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
8.0 KB
Raw Blame
/**
 * The classification of every `_brain.yaml` key (design D14 item 3), a
 * leaf module: it imports nothing, so both the migration's settings import
 * (`../../store-migration/brain-settings.ts`, which re-exports it) and the
 * settings reader (`./settings-source.ts`) use one table without an import
 * cycle.
 *
 *  - `shared`: every machine must agree on it, so the migration writes it
 *    as a `setting-set` record in the `settings` stream of `shared`, under
 *    the setting key `brain.<block>.<field>` (`brain.<key>` for a scalar).
 *  - `device`: it is about one machine (its install, its host, its
 *    caches, snapshots and index). It lives in the machine config as
 *    `brain_<block>_<field>: <JSON value>`.
 *  - `drop`: not a setting (the file's own schema version).
 *
 * The classification is by block, with per-field overrides; the census
 * test (`tests/core/store-migration/brain-settings.test.ts`) fails when the
 * validator reads a key this table does not classify, or when the table
 * names a key the validator does not read.
 */

export type BrainKeyHome = "shared" | "device" | "drop";

export interface BrainKeyRule {
  readonly home: BrainKeyHome;
  readonly reason: string;
  /** Per-field homes that differ from the block's. */
  readonly fields?: Readonly<Record<string, BrainKeyHome>>;
}

const SHARED = (reason: string, fields?: BrainKeyRule["fields"]): BrainKeyRule => ({
  home: "shared",
  reason,
  ...(fields !== undefined ? { fields } : {}),
});
const DEVICE = (reason: string): BrainKeyRule => ({ home: "device", reason });

/** Every top-level `_brain.yaml` key, classified. */
export const BRAIN_YAML_KEYS: Readonly<Record<string, BrainKeyRule>> = Object.freeze({
  schema_version: { home: "drop", reason: "the version of the file's own format, not a setting" },
  primary_agent: SHARED("which agent owns the brain is one answer for every machine"),
  dream: SHARED("dream thresholds decide which rules exist, so every machine must agree"),
  retire: SHARED("retirement rules shape the shared preference fold"),
  confidence: SHARED("confidence bands label shared preferences"),
  rollup: SHARED("rollup thresholds decide shared consolidation"),
  cross_topic: SHARED("cross-topic promotion creates shared rules"),
  vault: SHARED("vault-relative ignore and include paths are the same in every copy"),
  active: SHARED("the injected digest budget is the same brain on every machine"),
  lessons: SHARED("the lessons digest is rendered from shared records"),
  guardrails: SHARED("promotion guardrails decide shared rules"),
  link_graph: SHARED("link-graph thresholds audit the shared vault"),
  temporal: SHARED("stale windows and week alignment describe the shared timeline"),
  notes: SHARED("note read paths are vault-relative, the same in every copy"),
  write_binding: SHARED("write binding prefixes are vault-relative, the same in every copy"),
  sessions: SHARED("capture boundaries decide what becomes a shared record"),
  health: SHARED("semantic-health thresholds judge the shared brain"),
  schema: SHARED("the record vocabulary must be one vocabulary"),
  feedback: SHARED("the default feedback scope labels shared signals"),
  recall: SHARED("recall degradation policy is one policy for the brain"),
  recall_inject: SHARED("which slices reach an agent is one policy for the brain"),
  context: SHARED("the context window budget is one budget for the brain"),
  integrity: SHARED("integrity policy guards shared records"),
  // Endpoints, providers, model names and key env names are machine
  // config; a vault only says which uses are enabled (and their
  // thresholds), which every machine must agree on.
  decision_model: {
    home: "device",
    reason: "decision-model endpoints, providers, models and key names belong to one machine",
    fields: { enabled: "shared" },
  },
  discipline_report: SHARED("the discipline report reads the shared timeline", {
    timezone: "device",
  }),
  hygiene: SHARED("deduplication thresholds decide shared records", { resolver_cmd: "device" }),
  install: DEVICE("hook timeouts and the tool profile belong to one machine's install"),
  maintenance: DEVICE("the host-pressure gate measures one machine"),
  snapshots: DEVICE("snapshots are device-local after the migration (design D14 item 9)"),
  storage: DEVICE("storage caps measure one machine's disk"),
  anticipatory: DEVICE("the anticipatory cache lives in one machine's state"),
  embeddings: DEVICE("the embedding index is device-local"),
});

/**
 * Shared settings that hold a safety or privacy boundary, so only the
 * operator (human authority, `o2b brain settings`) sets or unsets them; an
 * agent-authority write (`brain_settings`) is refused whether or not the
 * operator ever set the key, in both modes. Each named field lowers a
 * boundary when an agent could change it; the other fields of these
 * blocks (`guardrails.derived_fact_synthesis`, a field a later release
 * adds) stay agent-writable unless listed here. Only the `integrity`
 * block is operator-only as a whole (`OPERATOR_ONLY_BLOCKS`), so a field
 * it gains later fails closed; its fields are still listed for the census.
 *
 *  - `integrity.*`: the owner-scope delivery and write gates, the
 *    embedding ABI gate and the pack staleness window.
 *  - `notes.read_paths`: which user folders the agent may read.
 *  - `vault.ignore_paths` / `vault.include_paths`: what is indexed and so
 *    reaches search and recall.
 *  - `write_binding.path_prefixes`: where a caller-named write may land.
 *  - `sessions.*_patterns`: which sessions and messages the capture
 *    boundary keeps out of the brain.
 *  - `guardrails.*` (the seven named): the dream pass self-approval
 *    thresholds, the instruction-file ceiling and the trust and
 *    owner-scope toggles.
 *  - `decision_model.enabled`: the operator's opt-out of decision-model
 *    calls, a safety switch an agent must not turn back on.
 *
 * The census in `tests/core/brain/settings-operator-only.test.ts` names
 * the same list.
 */
export const OPERATOR_ONLY_SETTINGS: ReadonlySet<string> = new Set([
  "integrity.owner_scope_delivery",
  "integrity.owner_scope_writes",
  "integrity.embedding_abi",
  "integrity.pack_validity_seconds",
  "notes.read_paths",
  "vault.ignore_paths",
  "vault.include_paths",
  "write_binding.path_prefixes",
  "sessions.ignore_patterns",
  "sessions.stateless_patterns",
  "sessions.ignore_message_patterns",
  "guardrails.promotion_min_signals",
  "guardrails.promotion_min_distinct_agents",
  "guardrails.promotion_min_age_days",
  "guardrails.instruction_file_max_lines",
  "guardrails.untrusted_source_delimiting",
  "guardrails.provenance_trust_ordering",
  "guardrails.owner_scoped_facts",
  "decision_model.enabled",
]);

/** Blocks every field of which is operator-only, including fields a later release adds. */
const OPERATOR_ONLY_BLOCKS: ReadonlySet<string> = new Set(["integrity"]);

/** Whether `<block>.<field>` (or the scalar `block`) is operator-only. */
export function isOperatorOnlySetting(block: string, field?: string): boolean {
  if (OPERATOR_ONLY_BLOCKS.has(block)) return true;
  return OPERATOR_ONLY_SETTINGS.has(field === undefined ? block : `${block}.${field}`);
}

/** The setting key a shared field becomes. */
export function brainSettingKey(block: string, field?: string): string {
  return field === undefined ? `brain.${block}` : `brain.${block}.${field}`;
}

/** The machine-config key a device field maps to. */
export function brainConfigKey(block: string, field?: string): string {
  return field === undefined ? `brain_${block}` : `brain_${block}_${field}`;
}

/**
 * Where `block` (and `field` of it, when given) lives, or `undefined` for a
 * key the table does not classify. The settings reader
 * (`brain/policy/settings-source.ts`) asks the same question when it reads
 * these records back.
 */
export function brainKeyHome(block: string, field?: string): BrainKeyHome | undefined {
  if (!Object.hasOwn(BRAIN_YAML_KEYS, block)) return undefined;
  const rule = BRAIN_YAML_KEYS[block]!;
  return field !== undefined ? (rule.fields?.[field] ?? rule.home) : rule.home;
}