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
21.2 KB
Raw Blame
/**
 * Canonical vault-relative layout of the Brain tree: every directory and
 * artefact filename under `<vault>/Brain/`, plus the two names of the
 * sibling derived-store directory that the snapshot family has to reach.
 *
 * Single source of truth. Every module that builds a path inside the
 * Brain layer imports these instead of repeating the literal. A future
 * rename ("Brain" → something else) is a one-line change here.
 *
 * A LEAF by construction — it imports nothing from the Brain layer. The
 * builders in `paths.ts` compose absolute paths from these names AND
 * carry the write-intent guard, so they depend on `vault-identity.ts`;
 * `vault-identity.ts` in turn only needs to know where the marker lives,
 * which is a name, not a builder. Keeping the names here is what lets
 * both sides reach them without pointing at each other. `paths.ts`
 * re-exports the whole module, so no importer changes.
 */

import { posix } from "node:path";

/** Vault-relative root of the Brain layer. */
export const BRAIN_ROOT_REL = "Brain";

/** Vault-relative Brain subdirectory names. */
export const BRAIN_INBOX_REL = posix.join(BRAIN_ROOT_REL, "inbox");
export const BRAIN_PROCESSED_REL = posix.join(BRAIN_INBOX_REL, "processed");
/**
 * Archive of inbox signals that can no longer become candidates: older than
 * `dream.contradiction_window_days` and never consumed by a preference. The
 * dream pass moves them here byte for byte; nothing is ever deleted.
 */
export const BRAIN_ARCHIVED_SIGNALS_REL = posix.join(BRAIN_INBOX_REL, "archived");
/** Write-approval staging area: `Brain/pending/sig-*.md` (A3, t_e540b093). */
export const BRAIN_PENDING_REL = posix.join(BRAIN_ROOT_REL, "pending");
export const BRAIN_PREFERENCES_REL = posix.join(BRAIN_ROOT_REL, "preferences");
export const BRAIN_RETIRED_REL = posix.join(BRAIN_ROOT_REL, "retired");
export const BRAIN_SKILL_PROPOSALS_REL = posix.join(BRAIN_ROOT_REL, "skill-proposals");
export const BRAIN_SKILL_PROPOSALS_PENDING_REL = posix.join(BRAIN_SKILL_PROPOSALS_REL, "pending");
export const BRAIN_SKILL_PROPOSALS_ACCEPTED_REL = posix.join(BRAIN_SKILL_PROPOSALS_REL, "accepted");
export const BRAIN_SKILL_PROPOSALS_REJECTED_REL = posix.join(BRAIN_SKILL_PROPOSALS_REL, "rejected");
/** Write-ahead journal of in-flight skill-proposal accepts (no-dead-ends, Unit I). */
export const BRAIN_SKILL_ACCEPT_JOURNAL_REL = posix.join(
  BRAIN_SKILL_PROPOSALS_REL,
  "accept-journal",
);
/**
 * Shard stem of the verifier-rejection JSONL ledger inside the proposals
 * root. Here rather than in `skill-proposals.ts` because the migration's
 * lane map needs it too, and that module's import graph reaches the dream
 * pass, which reads the lane map.
 */
export const VERIFIER_REJECTION_LEDGER_STEM = "verifier-rejections";
export const BRAIN_PROCEDURES_REL = posix.join(BRAIN_ROOT_REL, "procedures");
export const BRAIN_PROCEDURAL_MEMORY_REL = posix.join(BRAIN_ROOT_REL, "procedural-memory");
export const BRAIN_ATTENTION_REL = posix.join(BRAIN_ROOT_REL, "attention");
export const BRAIN_OBLIGATIONS_REL = posix.join(BRAIN_ROOT_REL, "obligations");
/**
 * One-off pledge pages: `Brain/pledges/<slug>.md` (dated-commitments wave).
 * A pledge is a promise made in prose with a due date, a cited source page
 * and evidence quotes verified against that source. `fulfill` stamps the
 * page in place - a fulfilled pledge stays in the active directory, so
 * listers filter on the stamp rather than assuming the page moved - and
 * `remove` retires it under `Brain/pledges/archive/`, beside the
 * recurring-obligation idiom.
 */
export const BRAIN_PLEDGES_REL = posix.join(BRAIN_ROOT_REL, "pledges");
/** Declared-thesis register pages: `Brain/theses/thesis-<slug>.md` (D3). */
export const BRAIN_THESES_REL = posix.join(BRAIN_ROOT_REL, "theses");
export const BRAIN_DECISIONS_REL = posix.join(BRAIN_ROOT_REL, "decisions");
/**
 * Knowledge-gap task notes: `Brain/gap-tasks/gap-<hash>.md` (A3 /
 * t_67d38036). Plain durable note files - never on the Hermes kanban board.
 */
export const BRAIN_GAP_TASKS_REL = posix.join(BRAIN_ROOT_REL, "gap-tasks");
/** Persisted contradiction (tension) notes: `Brain/tensions/tension-<slug>.md` (S2). */
export const BRAIN_TENSIONS_REL = posix.join(BRAIN_ROOT_REL, "tensions");
/**
 * Directory NAME of the Brain log, as a top-level `Brain/` entry. Named
 * beside the vault-relative path because a consumer comparing paths that
 * are relative to `Brain/` itself - the snapshot differ, which walks two
 * extracted trees with no vault around them - needs the segment rather
 * than the path.
 */
export const BRAIN_LOG_DIR = "log";
export const BRAIN_LOG_REL = posix.join(BRAIN_ROOT_REL, BRAIN_LOG_DIR);
/**
 * Inbound-capture staging + archive (Knowledge intake suite, seam 1,
 * t_f8f5ef6a). Mirrors the inbox-versus-processed distinction: a capture
 * lands in `Brain/captures/` (staging) and moves to
 * `Brain/captures/processed/` (archive) once drained. Kept in its own
 * subtree so the signal inbox and the dream pass stay untouched.
 */
export const BRAIN_CAPTURES_REL = posix.join(BRAIN_ROOT_REL, "captures");
export const BRAIN_CAPTURES_PROCESSED_REL = posix.join(BRAIN_CAPTURES_REL, "processed");
export const BRAIN_ENTITIES_REL = posix.join(BRAIN_ROOT_REL, "entities");
/**
 * Overwrite-only exact-state lane: `Brain/state/<aspect>.md` (t_b0c9d0a3).
 * A structured operational-state store keyed by aspect; each write replaces
 * the aspect's canonical value with no history. The lane is excluded from
 * the search index by the index-admission predicate so a stale "current"
 * value can never resurface through semantic recall.
 */
export const BRAIN_STATE_REL = posix.join(BRAIN_ROOT_REL, "state");
/**
 * Internal machinery lane: `Brain/.state/`. Distinct from
 * {@link BRAIN_STATE_REL} above despite the near-identical name, and the
 * two are not interchangeable: `Brain/state/` is OPERATOR-facing memory
 * content (one page per aspect, readable in Obsidian), while this
 * dot-directory holds the ledgers and markers this tool keeps for itself
 * - the session-lineage ledger, the anticipatory cache, the freeze
 * marker. Dot-prefixed so the vault walker excludes it from search and
 * indexing exactly as it excludes `.snapshots`.
 */
export const BRAIN_INTERNAL_STATE_DIR = ".state";
export const BRAIN_INTERNAL_STATE_REL = posix.join(BRAIN_ROOT_REL, BRAIN_INTERNAL_STATE_DIR);
/**
 * Anticipatory context cache: `Brain/.state/anticipatory/<key>.json`. One
 * entry per lineage root and enforced owner scope, refreshed on hook
 * events and pruned by age and count on write.
 */
export const BRAIN_ANTICIPATORY_DIR = "anticipatory";
export const BRAIN_ANTICIPATORY_REL = posix.join(BRAIN_INTERNAL_STATE_REL, BRAIN_ANTICIPATORY_DIR);
/** Obsidian Bases view definitions: `Brain/bases/<view>.base` (v1.15.0). */
export const BRAIN_BASES_REL = posix.join(BRAIN_ROOT_REL, "bases");
/** Ingested source summary pages: `Brain/sources/src-<slug>.md` (v1.7.0). */
export const BRAIN_SOURCES_REL = posix.join(BRAIN_ROOT_REL, "sources");
/** Cited research report pages: `Brain/reports/<date>-<slug>.md` (v1.7.0). */
export const BRAIN_REPORTS_REL = posix.join(BRAIN_ROOT_REL, "reports");
/** Source-distillation pages: `Brain/distillations/dist-<slug>.md` (t_2e2e959f). */
export const BRAIN_DISTILLATIONS_REL = posix.join(BRAIN_ROOT_REL, "distillations");
/** Directory NAME of the snapshot archive home, as a top-level `Brain/` entry. */
export const BRAIN_SNAPSHOTS_DIR = ".snapshots";
export const BRAIN_SNAPSHOTS_REL = posix.join(BRAIN_ROOT_REL, BRAIN_SNAPSHOTS_DIR);
/**
 * Ephemeral MCP tool-result artifacts (v0.18.0). Dot-directory so the
 * vault walker excludes it from search/indexing exactly like
 * `.snapshots`; never backed up, pruned by TTL on server startup.
 */
export const BRAIN_ARTIFACTS_DIR = ".artifacts";
export const BRAIN_ARTIFACTS_REL = posix.join(BRAIN_ROOT_REL, BRAIN_ARTIFACTS_DIR);

/**
 * Durable raw-source archive (answer trust): `Brain/.archives/<sha256>.txt`.
 * The ingest trusted-local branch persists the bytes a summary page's
 * knowledge was read from - redacted, content-addressed - so a source whose
 * file later decays can still be re-verified against what the page claimed.
 *
 * Dot-directory so the vault walker excludes it from search/indexing exactly
 * like `.snapshots` and `.artifacts`, and the index-admission predicate
 * refuses it by name besides (its entries are `.txt`, which the `.md` walkers
 * already skip - the stated rule keeps that from being an accident of the
 * extension). Deliberately NOT in {@link BRAIN_SNAPSHOT_EXCLUDED_ENTRIES},
 * unlike `.artifacts`: this is evidence rather than scratch, so a restore
 * must bring the bytes back - the same reading that keeps `.payloads` in the
 * snapshots. There is no TTL; retention is explicit operator pruning.
 */
export const BRAIN_ARCHIVES_DIR = ".archives";
export const BRAIN_ARCHIVES_REL = posix.join(BRAIN_ROOT_REL, BRAIN_ARCHIVES_DIR);

/**
 * Externalized oversized session content (payload registry, t_35440e83):
 * `Brain/.payloads/<sha256>.txt`. Session import moves data URIs, long
 * base64 runs and over-threshold turn text here and leaves a
 * `[payload: osb-payload://<sha256> chars=N]` placeholder in the
 * continuity row. Dot-directory so the vault walker never indexes it,
 * and deliberately NOT in {@link BRAIN_SNAPSHOT_EXCLUDED_ENTRIES}: a
 * restore must bring back the bytes the restored rows point at.
 */
export const BRAIN_PAYLOADS_DIR = ".payloads";
export const BRAIN_PAYLOADS_REL = posix.join(BRAIN_ROOT_REL, BRAIN_PAYLOADS_DIR);

/**
 * Content-addressed store of the bytes a note write replaced:
 * `Brain/.state/write-images/<sha256>` (who-wrote-what, Task A). One file
 * per distinct prior content, so repeated edits between two states cost
 * one file rather than one per write.
 */
export const BRAIN_WRITE_IMAGES_DIR = "write-images";
export const BRAIN_WRITE_IMAGES_REL = posix.join(BRAIN_INTERNAL_STATE_REL, BRAIN_WRITE_IMAGES_DIR);

/**
 * The top-level `Brain/` entries the snapshot family never touches:
 * never archived, never hashed into a manifest, and never removed by a
 * restore.
 *
 * `.snapshots` is excluded because archiving the archive home would
 * either explode the tar or let a rollback to an older state erase the
 * newer recovery points that are the operator's way forward.
 *
 * `.artifacts` is excluded because it is ephemeral tool output with a
 * TTL, documented above as never backed up. It was nevertheless archived
 * in every snapshot and hashed into every manifest, so churn in a cache
 * nobody wants restored tripped the rollback drift gate. One list, read
 * by the archiver, the manifest walker and the restore, is what keeps the
 * three from disagreeing again.
 */
export const BRAIN_SNAPSHOT_EXCLUDED_ENTRIES: ReadonlyArray<string> = Object.freeze([
  BRAIN_SNAPSHOTS_DIR,
  BRAIN_ARTIFACTS_DIR,
]);

/**
 * Name prefix of a restore's staging directory. It normally lives under
 * `.snapshots/`, but sits directly under `Brain/` when `.snapshots/` is on
 * another device, and a restore killed mid-swap leaves it there. Such a
 * top-level entry is restore plumbing, never Brain content: the archiver,
 * the manifest walker and the restore all skip it, like
 * {@link BRAIN_SNAPSHOT_EXCLUDED_ENTRIES}.
 */
export const BRAIN_RESTORE_STAGING_PREFIX = ".restore-staging-";

/**
 * The DERIVED store: `<vault>/.open-second-brain/brain.sqlite`.
 *
 * A sibling of `Brain/`, not a member of it, and the only file in that
 * directory the snapshot family may ever touch. The directory also holds
 * encrypted secrets, the install and protect lockfiles, a second SQLite
 * lease database and the ingest checkpoints - none of which belongs in a
 * recovery archive of the Markdown tree, which is why the constant names
 * the FILE and every caller joins the two rather than archiving the
 * directory.
 *
 * The literal used to be repeated at roughly a dozen sites behind four
 * private per-module constants. Naming it here does not make this module
 * know what a search index is: it knows a name, exactly as it does for
 * every `Brain/` entry above.
 */
export const DERIVED_STORE_DIR = ".open-second-brain";
export const DERIVED_STORE_FILE = "brain.sqlite";

/**
 * The bench-harness runs directory, vault-relative:
 * `<vault>/.open-second-brain/bench-runs/`.
 *
 * Named beside the derived store it sits in (t_206562ae) because the
 * `.gitignore` guard seeded at brain init covers the store with ONE
 * vault-root-anchored entry, and a consumer spelling the runs dir
 * independently of that store is exactly how a writer ends up outside
 * the covered directory. `tests/core/brain/gitignore-guard.test.ts`
 * reads both this constant and the bench verb's source to keep the two
 * from drifting; the CLI still resolves the value against the working
 * directory, so `--runs-dir` behaves exactly as before.
 */
export const BENCH_RUNS_REL = posix.join(DERIVED_STORE_DIR, "bench-runs");
/**
 * Where the runtime hooks append their one-line-per-decision audit trail,
 * one shard per ISO week.
 *
 * Named here (C1) because it stopped being only the hooks' business: it
 * is the readable install fact for the `hook` recall channel - the doctor
 * check that asks whether an enabled hook ever ran has nothing else to
 * look at. Six hook files used to spell the root as a raw three-argument
 * join beside a `DERIVED_STORE_DIR` that already existed; all six now go
 * through {@link hookAuditDir}, and `tests/hooks/audit-root.test.ts`
 * reads the hook sources to keep it that way. Five independent spellings
 * of a path a check depends on is a rename that succeeds once and looks
 * done.
 */
export const HOOK_AUDIT_DIR = "hook-audit";

/**
 * The extension every JSON Lines ledger writes, without the leading dot.
 *
 * Declared in this leaf rather than in `ledger-shards.ts` (which re-exports
 * it, so no importer changes) because the audit writer's week-grammar
 * constant reads it at module-evaluation time, and `ledger-shards.ts`
 * reaches back into `config.ts` for the device id - a cycle that TDZ-aborted
 * `audit.ts` whenever the shard grammar module was entered first. A name
 * this many ledgers share belongs beside the other Brain file names anyway.
 */
export const JSONL_LEDGER_EXT = "jsonl";

/** Brain-internal artefact filenames at the root of `Brain/`. */
export const BRAIN_CONFIG_FILE = "_brain.yaml";
export const BRAIN_MANUAL_FILE = "_BRAIN.md";
export const BRAIN_ACTIVE_FILE = "active.md";
export const BRAIN_LESSONS_FILE = "lessons.md";
/**
 * The compiled digest pages, vault-relative. Each is generated from records
 * (preferences, retired preferences, dead-ends) that may reserve themselves
 * against remote reads, yet the page carries no `visibility:` of its own, so
 * a generic page reader cannot measure it. The shared reach predicate
 * (`isPathReadableAtReach`) therefore withholds these pages at remote reach;
 * their dedicated readers (`brain_context`, `brain_pre_compress_pack`, and
 * the `osb://preferences/active` and `osb://lessons` resources) render the
 * digest per reader instead.
 */
export const BRAIN_COMPILED_DIGEST_RELS: ReadonlyArray<string> = Object.freeze([
  posix.join(BRAIN_ROOT_REL, BRAIN_ACTIVE_FILE),
  posix.join(BRAIN_ROOT_REL, BRAIN_LESSONS_FILE),
]);
/**
 * Operator-authored standing rules injected at the head of every session
 * preamble (silence-is-not-an-answer, U8).
 *
 * The DIRECTORY is most of the enforcement mechanism, and the reason the
 * name is a constant rather than a config key. Living under `Brain/` means
 * the note-target resolver already refuses it for the four caller-named
 * note-write tools; the label writer, which reaches a caller-named path
 * through the containment-only resolver, is refused by name in
 * `standing-rules.ts` instead. A configurable filename would be a second
 * thing to keep protected on both of those paths and would buy nothing the
 * operator cannot get by editing this file.
 */
export const BRAIN_STANDING_RULES_FILE = "standing-rules.md";
/**
 * Directory of operator-authored SCOPED standing rules, beside the
 * constitution file: `Brain/standing-rules/<axis>/<key>.md`, one file per
 * resolved project, harness or host value. Read by `scoped-rules.ts`,
 * refused to every write path by `assertStandingRulesNotTargeted`.
 */
export const BRAIN_SCOPED_RULES_DIR = "standing-rules";
export const BRAIN_PINNED_FILE = "pinned.md";
export const BRAIN_INDEX_FILE = "_INDEX.md";
/** Persisted claim-graph projection artifact (Belief lifecycle suite, A3). */
export const BRAIN_CLAIM_GRAPH_FILE = "claim-graph.json";
/** Persisted rollup-ladder counter ledger (knowledge-intake-and-consolidation, S3). */
export const BRAIN_ROLLUP_LEDGER_FILE = "rollup-ladder.json";
/**
 * Cross-topic rule promotion ledger (t_642bc2b8), beside the rollup
 * ladder ledger: the last date each owner token promoted, so a
 * budgeted-out dream pass plans nothing rather than re-promoting.
 */
export const BRAIN_CROSS_TOPIC_LEDGER_FILE = "cross-topic-rules.json";

/** Vault-relative path of the `o2b index` output file. */
export const BRAIN_INDEX_REL = posix.join(BRAIN_ROOT_REL, BRAIN_INDEX_FILE);

/**
 * The Brain page lanes: the directories under `Brain/` whose files are
 * content pages (one Markdown page per ingested source, distillation, or
 * cited report, built by `sourcePagePath` / `distillationPagePath` /
 * `reportPagePath`) rather than machinery the Brain's own writers own.
 * Every other path under `Brain/` - config, identity markers, standing
 * rules, preferences, logs, search state, snapshots - is machinery, and a
 * caller-named writer that is not the Brain itself must not reach it.
 */
export const BRAIN_PAGE_LANES_REL: ReadonlyArray<string> = Object.freeze([
  BRAIN_SOURCES_REL,
  BRAIN_REPORTS_REL,
  BRAIN_DISTILLATIONS_REL,
]);

/**
 * One path segment folded the way a case-insensitive filesystem reads it
 * (macOS APFS/HFS+ by default, NTFS): case-folded, with the trailing dots
 * and spaces Windows drops from a name removed. A wall that compares
 * segments must compare the folded forms, or `brain/`, `BRAIN/`, and
 * `Brain./` walk past a check that only knew `Brain/` while the
 * filesystem opens the same directory. Folding is conservative on a
 * case-sensitive filesystem - a user folder that differs from a Brain
 * directory only by case is refused too - which is the right side of the
 * trade for a machinery wall.
 */
function foldSegment(segment: string): string {
  return segment.replace(/[. ]+$/u, "").toLowerCase();
}

/**
 * The segments of a vault-relative path under the Brain root, or `null`
 * when the path does not land under `Brain/` at all.
 *
 * The path is read the way the filesystem will read it, not the way it
 * was spelled: `\` is a separator (Windows), `.` and `..` are collapsed
 * (`x/../Brain/a`, `./Brain/a`), leading separators are dropped (a join
 * onto the vault re-roots them), and the first segment is compared
 * case-insensitively (see {@link foldSegment}). A `..` that climbs above
 * the vault root collapses at the root rather than escaping, which reads
 * `../Brain/a` as Brain too - an over-refusal only for a path the vault
 * containment check refuses anyway.
 */
export function brainRootSegments(relPath: string): ReadonlyArray<string> | null {
  const normalized = posix.normalize(`/${relPath.replaceAll("\\", "/")}`);
  const segments = normalized.split("/").filter((s) => s.length > 0);
  const head = segments[0];
  if (head === undefined || foldSegment(head) !== foldSegment(BRAIN_ROOT_REL)) return null;
  return segments.slice(1);
}

/**
 * Does `relPath` name a compiled digest page ({@link BRAIN_COMPILED_DIGEST_RELS})
 * in any spelling the filesystem resolves to it? Read with the same
 * normalization and case-folding as {@link brainRootSegments}, so a leading
 * separator, a backslash, dot segments, a case variant or a trailing dot cannot
 * walk past a check that knew one spelling only.
 */
export function isCompiledDigestRel(relPath: string): boolean {
  const tail = brainRootSegments(relPath);
  if (tail === null || tail.length !== 1) return false;
  const name = foldSegment(tail[0]!);
  return [BRAIN_ACTIVE_FILE, BRAIN_LESSONS_FILE].some((file) => foldSegment(file) === name);
}

/**
 * Does `relPath` name a file under the Brain log ({@link BRAIN_LOG_REL}),
 * in any spelling the filesystem resolves to it? The daily log pages name
 * preference ids, retired ids and evidence artifacts in their event bodies
 * and carry no visibility of their own, so, like a compiled digest page,
 * they cannot say that a record they name is reserved. Read with the same
 * normalization and case-folding as {@link brainRootSegments}.
 */
export function isBrainLogRel(relPath: string): boolean {
  return isInBrainLane(relPath, [BRAIN_LOG_REL]);
}

/** Does `relPath` land at or under `Brain/`? See {@link brainRootSegments}. */
export function isUnderBrainRoot(relPath: string): boolean {
  return brainRootSegments(relPath) !== null;
}

/**
 * Does `relPath` name a file strictly inside one of `lanes` (each a
 * `Brain/<dir>` constant)? Read with the same normalization and
 * case-folding as {@link brainRootSegments}, so a lane admits exactly the
 * spellings the machinery wall would otherwise refuse.
 */
export function isInBrainLane(relPath: string, lanes: ReadonlyArray<string>): boolean {
  const tail = brainRootSegments(relPath);
  if (tail === null) return false;
  return lanes.some((lane) => {
    const laneTail = lane.split("/").slice(1);
    if (tail.length <= laneTail.length) return false;
    return laneTail.every((segment, i) => foldSegment(segment) === foldSegment(tail[i]!));
  });
}