Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
10.2 KB
Raw Blame
/**
 * Turn a parsed `_brain.yaml` object into a typed {@link BrainConfig}.
 *
 * One reason to change: which blocks exist and in what order they are
 * read. Every block's own rules live in `./blocks/`; this module owns
 * only the sequence, the mandatory `schema_version` check, and the
 * forward-compat sweep that must run after every block has registered
 * itself.
 */

import type { BrainConfig } from "../types.ts";
import { BrainConfigError, type BrainConfigLoadWarning } from "./errors.ts";
import {
  KeyIndexCollector,
  type BlockParseContext,
  type BrainConfigKeyIndex,
} from "./key-index.ts";
import { BRAIN_CONFIG_SUPPORTED_VERSIONS, DEFAULT_BRAIN_CONFIG } from "./defaults.ts";
import { parsePrimaryAgent } from "./primary-agent.ts";
import {
  parseConfidenceBlock,
  parseDreamBlock,
  parseRetireBlock,
  parseSnapshotsBlock,
} from "./blocks/lifecycle.ts";
import { parseVaultBlock } from "./blocks/vault-scope.ts";
import { parseActiveBlock } from "./blocks/active.ts";
import { parseRecallInjectBlock } from "./blocks/recall-inject.ts";
import { parseLessonsBlock } from "./blocks/lessons.ts";
import { parseMaintenanceBlock } from "./blocks/maintenance.ts";
import { parseInstallBlock } from "./blocks/install.ts";
import { parseDisciplineReportBlock } from "./blocks/discipline-report.ts";
import { parseGuardrailsBlock } from "./blocks/guardrails.ts";
import { parseRollupBlock } from "./blocks/rollup.ts";
import { parseLinkGraphBlock } from "./blocks/link-graph.ts";
import { parseTemporalBlock } from "./blocks/temporal.ts";
import { parseEmbeddingsBlock } from "./blocks/embeddings.ts";
import { parseHealthBlock } from "./blocks/health.ts";
import { parseIntegrityBlock } from "./blocks/integrity.ts";
import { parseNotesBlock } from "./blocks/notes.ts";
import { parseWriteBindingBlock } from "./blocks/write-binding.ts";
import { parseSessionsBlock } from "./blocks/sessions.ts";
import { parseSchemaBlock } from "./blocks/schema.ts";
import {
  parseAnticipatoryBlock,
  parseHygieneBlock,
  parseRecallBlock,
} from "./blocks/continuity-hygiene.ts";
import { parseContextBlock, parseCrossTopicBlock } from "./blocks/context.ts";
import { parseFeedbackBlock } from "./blocks/feedback.ts";
import { parseDecisionModelBlock } from "./blocks/decision-model.ts";
import { parseStorageBlock } from "./blocks/storage.ts";

export interface ValidateResult {
  readonly config: BrainConfig;
  readonly warnings: ReadonlyArray<BrainConfigLoadWarning>;
  /**
   * Every key this validation run branched on, top-level and per-block.
   * Recorded by construction (see `KeyIndexCollector`) rather than from a
   * hand-maintained list, so it can never disagree with what the
   * validator actually understands. Consumed by the configuration-template
   * ratchet.
   */
  readonly knownKeys: BrainConfigKeyIndex;
}

/**
 * Pure validator. Accepts a parsed object (typically from
 * `parseBrainYaml`) and returns a typed {@link BrainConfig}, or
 * throws {@link BrainConfigError} naming the offending field.
 *
 * `source` is rendered into error messages; pass the config file path or
 * a synthetic label like `"<test fixture>"` so the failure points at
 * something useful.
 */
export function validateBrainConfig(parsed: unknown, source: string | null = null): BrainConfig {
  return validateBrainConfigDetailed(parsed, source).config;
}

export function validateBrainConfigDetailed(
  parsed: unknown,
  source: string | null = null,
): ValidateResult {
  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
    throw new BrainConfigError("config root must be a map of keys", null, source);
  }
  const ctx: BlockParseContext = {
    obj: parsed as Record<string, unknown>,
    source,
    warnings: [],
    keys: new KeyIndexCollector(),
  };
  // `schema_version` is seeded directly because `readSchemaVersion`
  // checks its presence with an inverted `in` test rather than through
  // `hasBlock`, so nothing else would register it.
  ctx.keys.addTop("schema_version");
  const schemaVersion = readSchemaVersion(ctx);
  const primaryAgent = parsePrimaryAgent(ctx);

  // Each block is optional; a missing block inherits its default. The
  // lifecycle blocks merge field-by-field so a user can override one
  // threshold without having to re-state the rest.
  const dream = parseDreamBlock(ctx);
  const retire = parseRetireBlock(ctx);
  const confidence = parseConfidenceBlock(ctx);
  const snapshots = parseSnapshotsBlock(ctx);

  const vault = parseVaultBlock(ctx);
  const active = parseActiveBlock(ctx);
  const recallInject = parseRecallInjectBlock(ctx);
  const lessons = parseLessonsBlock(ctx);
  const maintenance = parseMaintenanceBlock(ctx);
  const install = parseInstallBlock(ctx);
  const disciplineReport = parseDisciplineReportBlock(ctx);
  const guardrails = parseGuardrailsBlock(ctx);
  const rollup = parseRollupBlock(ctx);
  const linkGraph = parseLinkGraphBlock(ctx);
  const temporal = parseTemporalBlock(ctx);
  const health = parseHealthBlock(ctx);
  const embeddings = parseEmbeddingsBlock(ctx);
  const integrity = parseIntegrityBlock(ctx);
  const notes = parseNotesBlock(ctx);
  const writeBinding = parseWriteBindingBlock(ctx);
  const sessions = parseSessionsBlock(ctx);
  const schema = parseSchemaBlock(ctx);
  const hygiene = parseHygieneBlock(ctx);
  const anticipatory = parseAnticipatoryBlock(ctx);
  const recall = parseRecallBlock(ctx);
  const feedback = parseFeedbackBlock(ctx);
  const decisionModel = parseDecisionModelBlock(ctx);
  const storage = parseStorageBlock(ctx);
  const crossTopic = parseCrossTopicBlock(ctx);
  const context = parseContextBlock(ctx);

  warnUnknownTopLevelKeys(ctx);

  const config: BrainConfig = {
    schema_version: schemaVersion,
    primary_agent: primaryAgent,
    dream,
    retire,
    confidence,
    snapshots,
    ...(vault !== undefined ? { vault } : {}),
    ...(active !== undefined ? { active } : {}),
    ...(lessons !== undefined ? { lessons } : {}),
    ...(maintenance !== undefined ? { maintenance } : {}),
    ...(install !== undefined ? { install } : {}),
    ...(disciplineReport !== undefined ? { discipline_report: disciplineReport } : {}),
    ...(rollup !== undefined ? { rollup } : {}),
    ...(guardrails !== undefined ? { guardrails } : {}),
    ...(linkGraph !== undefined ? { link_graph: linkGraph } : {}),
    ...(temporal !== undefined ? { temporal } : {}),
    ...(notes !== undefined ? { notes } : {}),
    ...(writeBinding !== undefined ? { write_binding: writeBinding } : {}),
    ...(sessions !== undefined ? { sessions } : {}),
    ...(health !== undefined ? { health } : {}),
    ...(embeddings !== undefined ? { embeddings } : {}),
    ...(integrity !== undefined ? { integrity } : {}),
    ...(schema !== undefined ? { schema } : {}),
    ...(hygiene !== undefined ? { hygiene } : {}),
    ...(anticipatory !== undefined ? { anticipatory } : {}),
    ...(recall !== undefined ? { recall } : {}),
    ...(recallInject !== undefined ? { recall_inject: recallInject } : {}),
    ...(feedback !== undefined ? { feedback } : {}),
    ...(decisionModel !== undefined ? { decision_model: decisionModel } : {}),
    ...(storage !== undefined ? { storage } : {}),
    ...(crossTopic !== undefined ? { cross_topic: crossTopic } : {}),
    ...(context !== undefined ? { context } : {}),
  };

  return { config, warnings: ctx.warnings, knownKeys: ctx.keys };
}

/** Mandatory, and must be in the supported set. */
function readSchemaVersion(ctx: BlockParseContext): number {
  if (!("schema_version" in ctx.obj)) {
    throw new BrainConfigError(
      "missing required field; expected a positive integer in the supported set " +
        `(${BRAIN_CONFIG_SUPPORTED_VERSIONS.join(", ")})`,
      "schema_version",
      ctx.source,
    );
  }
  const value = ctx.obj["schema_version"];
  if (
    typeof value !== "number" ||
    !Number.isInteger(value) ||
    !BRAIN_CONFIG_SUPPORTED_VERSIONS.includes(value)
  ) {
    throw new BrainConfigError(
      `unsupported value ${JSON.stringify(value)}; expected one of ` +
        BRAIN_CONFIG_SUPPORTED_VERSIONS.join(", "),
      "schema_version",
      ctx.source,
    );
  }
  return value;
}

/**
 * Forward-compat: unknown top-level keys → warning, not error. Runs after
 * every block has had a chance to register itself, so a block can never be
 * parsed-but-not-yet-known at the point this check reads the set. Uses its
 * own message format (distinct from `warnUnknownKeys`'s `block.key: …`
 * shape), pinned by an existing test.
 */
function warnUnknownTopLevelKeys(ctx: BlockParseContext): void {
  for (const key of Object.keys(ctx.obj)) {
    if (!ctx.keys.topLevel.has(key)) {
      ctx.warnings.push({
        path: ctx.source ?? "<config>",
        message: `unknown top-level field '${key}' ignored (forward-compat)`,
      });
    }
  }
}

/**
 * Probe source label used by {@link brainConfigKnownKeys}. Never reaches
 * a user-visible surface: the probe discards its warnings.
 */
const KEY_INDEX_PROBE_SOURCE = "<brain-config-key-index>";

/**
 * Every configuration key {@link validateBrainConfigDetailed} branches
 * on, enumerated by running the validator rather than by reading a list.
 *
 * Two passes are needed because a block's sub-key vocabulary is only
 * declared inside the branch that parses the block: pass one discovers
 * the top-level keys against a minimal config, pass two re-runs with
 * every discovered block present but empty so each block's sub-key
 * registration executes. Scalar top-level keys keep their default value
 * in pass two - handing `primary_agent` an empty map would (correctly)
 * be rejected.
 */
export function brainConfigKnownKeys(): BrainConfigKeyIndex {
  const minimal: Record<string, unknown> = {
    schema_version: BRAIN_CONFIG_SUPPORTED_VERSIONS[0],
  };
  const firstPass = validateBrainConfigDetailed(minimal, KEY_INDEX_PROBE_SOURCE).knownKeys;
  const defaults = DEFAULT_BRAIN_CONFIG as unknown as Record<string, unknown>;
  const probe: Record<string, unknown> = { ...minimal };
  for (const key of firstPass.topLevel) {
    if (key in minimal) continue;
    const fallback = defaults[key];
    const isScalar = key in defaults && (fallback === null || typeof fallback !== "object");
    probe[key] = isScalar ? fallback : {};
  }
  return validateBrainConfigDetailed(probe, KEY_INDEX_PROBE_SOURCE).knownKeys;
}