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
/**
* 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]!));
});
}