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
/**
* The declared recovery story of every destructive site under
* `src/core/brain/` that does not route through the snapshot gate (R1b).
*
* `snapshot-gate.ts` promises that no destructive brain mutation runs
* without a recovery point on disk first, and it is reached by two
* modules. That is not a bug in the gate; it is what happens to any
* mechanism that has to be called by hand. Fixing the call sites fixes
* the call sites. What makes the NEXT unprotected removal impossible to
* add silently is this file plus
* `tests/core/architecture/destructive-site-census.test.ts`: the census
* sweeps the tree for removal calls and requires each site it finds to
* be routed through the gate or to appear below.
*
* ## What an entry is
*
* Facts, not conclusions. Each entry states the calls the site makes,
* what those calls put at risk (in the regions a snapshot archive is
* defined over), and whether anything archived them first. The verdict
* is DERIVED from those facts by the same pure classifier the gate uses,
* so the registry and the gate cannot come to different conclusions
* about the same shape of risk.
*
* The `reason` is what the facts alone do not say: for most of these
* sites it is the argument that the removal is safe by CONSTRUCTION -
* the destination landed and was re-confirmed before the source went, or
* the removed file's whole content was its existence, or a producer will
* emit it again on the next run. Those are real recovery stories; they
* are just not archives.
*
* ## What this module is not
*
* It imports nothing but the verdict vocabularies. A registry that must
* know about the modules it names is exactly where an import cycle
* appears, and a cycle here would be paid for by every module in the
* tree - so the sites are named by PATH, as strings, and the census is
* what proves those strings still resolve to real files.
*/
import {
classifyRecoverability,
type RecoverabilityFacts,
type RecoverabilityVerdict,
} from "./gates/recoverability.ts";
/**
* The calls that put existing bytes beyond reach: removal and
* displacement, in both the sync and the promise spelling. An atomic
* overwrite is deliberately absent - see the census header for the
* measurement behind that narrowing.
*/
export const REMOVAL_CALLS: ReadonlyArray<string> = Object.freeze([
// `node:fs`
"rmSync",
"unlinkSync",
"renameSync",
"rmdirSync",
// `node:fs/promises` twins. Nothing in `src/core/brain/` imports them
// today; they are here so the FIRST one is reported rather than
// admitted. The import gate in the census is what keeps a local helper
// named `rm` or `rename` from being miscounted as one of these.
"rm",
"unlink",
"rename",
"rmdir",
]);
/**
* What the census records when a module reaches an fs namespace through
* a COMPUTED member - `fs[call](path)`. Which call that is is a runtime
* fact, so the site is reported under this token rather than resolved to
* a name the census would be guessing at.
*
* Not a `node:fs` name, and deliberately unspellable as one: a site that
* needs it has to declare it, and the declaration is where the module
* says which calls that expression can actually reach.
*/
export const FS_UNRESOLVED_CALL = "fs[]";
/**
* Shortest reason the census accepts. Set where a real argument fits and
* a placeholder does not: "cleanup" and "not needed" are both under it.
*/
export const DESTRUCTIVE_SITE_MIN_REASON_LENGTH = 60;
/** One site's declaration. */
export interface DestructiveSiteDeclaration {
/** The removal calls this module makes directly, sorted. */
readonly calls: ReadonlyArray<string>;
/** What is at risk, and whether anything archived it first. */
readonly recovery: RecoverabilityFacts;
/** What the facts alone do not say. Never empty, never shared. */
readonly reason: string;
}
/** No archive behind it, and the bytes are inside the Brain tree. */
const UNARCHIVED_BRAIN: RecoverabilityFacts = Object.freeze({
recoveryPoint: false,
blastRadius: Object.freeze({ brainTopLevel: true }),
});
/** No archive behind it, and the bytes are outside the Brain tree. */
const UNARCHIVED_OUTSIDE: RecoverabilityFacts = Object.freeze({
recoveryPoint: false,
blastRadius: Object.freeze({ outsideBrainRoot: true }),
});
/**
* No archive behind it, and the bytes are in an entry no archive has
* ever contained: `Brain/.snapshots` or `Brain/.artifacts`.
*/
const UNARCHIVED_EXCLUDED: RecoverabilityFacts = Object.freeze({
recoveryPoint: false,
blastRadius: Object.freeze({ snapshotExcludedEntries: true }),
});
/**
* No archive behind it, and no bytes reachable at all: the call removes
* a directory entry that is empty by construction the moment it runs.
*/
const EMPTY_SHELL_ONLY: RecoverabilityFacts = Object.freeze({
recoveryPoint: false,
blastRadius: Object.freeze({}),
});
/**
* Every destructive site under `src/core/brain/` that is not routed
* through the destructive gate, with the argument for why the removal
* is accounted for anyway.
*
* Paths are repo-relative and POSIX-separated, matching the census's own
* enumeration.
*/
export const DESTRUCTIVE_SITES: Readonly<Record<string, DestructiveSiteDeclaration>> =
Object.freeze({
// --- Moves whose destination is proved before the source goes -------
// (`src/core/brain/pending.ts` stopped being a site when the
// multi-lane queue moved the engine into `pending/pending-lanes.ts`
// and the module became a pure delegation surface.)
"src/core/brain/pending/pending-lanes.ts": {
calls: ["unlinkSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"the multi-lane queue's apply and reject, generalized from the A3 applier: " +
"apply exclusive-creates the decoded publish target and throws on an occupied " +
"name BEFORE the staged copy is unlinked, so the document exists twice at that " +
"instant and never zero times; reject writes the retire-shaped render through " +
"`writeFrontmatterAtomic` and refuses an occupied retired name before the " +
"staged copy goes, preserving every original field beside the retire stamps.",
},
"src/core/brain/preference.ts": {
calls: ["unlinkSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"the retire re-renders into `retired/` through `writeFrontmatterAtomic` and " +
"then re-confirms the destination with `existsSync`, throwing if it is absent, " +
"before unlinking. Worth naming precisely: it RE-RENDERS rather than copies, so " +
"the record survives and the original prose does not.",
},
"src/core/brain/signal-retire.ts": {
calls: ["unlinkSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"the signal twin of the preference retire - shared-writer write, existence " +
"re-confirmed with a throw on absence, then the source unlinked - and the one " +
"of the pair that copies rather than re-renders, so no prose is lost.",
},
// --- Archival moves: the bytes change location, not existence -------
"src/core/brain/capture/capture-note.ts": {
calls: ["renameSync", "rmSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"moves a staged capture into `processed/`. The `rmSync` is the source half of " +
"the cross-device fallback and runs only after `atomicWriteText` has written " +
"the archived copy from bytes already read into memory.",
},
"src/core/brain/dream-apply.ts": {
calls: ["renameSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"moves each consumed signal from `inbox/` into its processed location. It runs " +
"inside the dream pass, whose pre-run archive covers the whole Brain tree - " +
"coverage this entry cannot claim itself, because the archive belongs to the " +
"caller and this module is reachable from tests without one.",
},
"src/core/brain/intentions.ts": {
calls: ["renameSync", "rmSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"archives an active intention into `history/` under a name a collision loop has " +
"already proved free, so an existing history entry can never be renamed over. " +
"The `rmSync` is the cross-device fallback's source half.",
},
"src/core/brain/recompile.ts": {
calls: ["renameSync", "rmSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"moves an orphaned GENERATED page into the cleanup directory under a suffixed " +
"free name. The page is reproducible from its inputs by definition, and the " +
"move is what lets an operator see what was orphaned rather than guess. Across " +
"volumes the move is a copy, then the source's removal.",
},
// --- Files whose whole content is their existence --------------------
"src/core/brain/exact-state.ts": {
calls: ["rmSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"clears one aspect's exact-state file. Absence IS the cleared state, so the " +
"removal is the state transition rather than a loss of one.",
},
"src/core/brain/skill-accept-journal.ts": {
calls: ["rmSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"clears a skill accept journal and its prior-content copy, device-local repair " +
"markers whose absence is the state 'no accept outstanding'; the transaction they " +
"recorded is resolved before they go.",
},
"src/core/brain/checkpoint-store.ts": {
calls: ["rmSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"clears one checkpoint - an ingest plan's or a session import's - once that run " +
"reached its terminal state. A checkpoint exists to let an interrupted run resume; " +
"after the run is done there is nothing it could resume into.",
},
"src/core/brain/lineage/identity.ts": {
calls: ["unlinkSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"clears a worktree identity marker and prunes the oldest past a fixed retain " +
"count, expired and undatable first. A marker carries no content beyond the " +
"fact that a worktree was seen, and the next run re-creates the live ones.",
},
"src/core/brain/git/ingest.ts": {
calls: ["rmSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"clears the git-ingest `state.json` watermark on a rescan that found no head, " +
"so the next run starts as an initial walk instead of inheriting a marker that " +
"points at a commit the repository no longer has.",
},
// --- Regenerable derivations -----------------------------------------
"src/core/brain/truth/store.ts": {
calls: ["rmSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"removes a claim-event shard only when compaction has filtered every line out " +
"of it, so the file removed is provably empty of surviving events at the moment " +
"it goes.",
},
// --- Bootstrap: a tree that did not exist a moment ago ---------------
"src/core/brain/init.ts": {
calls: ["renameSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"re-dates the starter bundle's own log filenames immediately after copying them " +
"into a destination the pre-check already proved empty. This is also the path " +
"that CREATES the tree, so it cannot be gated on anything the tree is about to " +
"contain.",
},
// --- The archive machinery itself ------------------------------------
"src/core/brain/snapshot.ts": {
calls: ["renameSync", "rmSync", "unlinkSync"],
recovery: UNARCHIVED_EXCLUDED,
reason:
"the module that MAKES recovery points: it prunes archives past the retention " +
"count, removes a partial store archive whose snapshot was refused, and swaps a " +
"decompressed database into place. Gating any of it on taking a snapshot would " +
"be circular, so `pruneSnapshots` carries a floor and a named refusal instead " +
"and `restoreSnapshot` takes a manual recovery point of the tree it discards.",
},
// --- Concurrency primitives ------------------------------------------
"src/core/brain/sync-lockfile.ts": {
calls: ["unlinkSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"the lock release and the process-exit sweep that releases any lock still held, " +
"each only while the lock file is still the one its holder created, and " +
"`removeStaleLockSync`, which removes an abandoned lock for the one contender whose " +
"exclusive takeover claim on that file won (the lineage gap-sidecar trim lock and " +
"the hook-state scope locks break theirs through it). A lock file's meaning comes " +
"entirely from its exclusive creation; removing one grants access rather than " +
"destroying anything.",
},
// --- Rewrites through a temp file ------------------------------------
"src/core/brain/freeze.ts": {
calls: ["unlinkSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"removes the freeze marker, whose whole content was its existence: the file carries " +
"no memory, `o2b brain freeze` writes an identical one in a single command, and the " +
"`unfreeze` log event records who lifted the freeze plus what the marker said before " +
"it went. Archiving it would preserve a fact the log already holds.",
},
"src/core/brain/maintenance/journal.ts": {
calls: ["renameSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"the tmp-plus-rename half of the journal cap sweep, which runs only while the " +
"maintenance lease is held. The rename is what makes the trim atomic - a reader " +
"sees either the full journal or the capped one, never a torn file.",
},
"src/core/brain/secrets/store.ts": {
calls: ["renameSync", "rmSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"the tmp-plus-rename half of a hand-rolled atomic write that must land at mode " +
"0600, which no shared writer expresses. The store holds encrypted secrets and " +
"is deliberately outside every snapshot archive, so its safety comes from the " +
"atomicity of the swap and not from a recovery point. The rmSync removes only " +
"this process's own staging copy of the vault-secrets adoption, whose source " +
"stays in the vault untouched.",
},
"src/core/brain/secrets/envelope.ts": {
calls: ["renameSync", "unlinkSync"],
recovery: UNARCHIVED_OUTSIDE,
reason:
"wraps the plaintext keyfile into a passphrase-verified envelope through a " +
"tmp-plus-rename swap that lands at mode 0600, and the unlink is only the tmp " +
"whose wrap failed, so the displaced bytes are the keyfile the envelope just " +
"replaced and the wrapping passphrase re-derives the key it protects - a lost " +
"passphrase is the documented, permanent loss. The custody state sits outside " +
"every snapshot archive by design.",
},
"src/core/brain/secrets/token-store.ts": {
calls: ["renameSync"],
recovery: UNARCHIVED_OUTSIDE,
reason:
"the tmp-plus-rename half of the per-agent MCP token store's write, which must " +
"land at mode 0600 at creation, so no shared writer serves it. The store is " +
"hash-at-rest by design: the bytes a rotation displaces are the previous hash " +
"and non-secret prefix, never a credential, and overwriting them is the rotate " +
"or revoke doing its job. Custody state sits outside every snapshot archive.",
},
// --- Two-phase accept with a journalled rollback ---------------------
"src/core/brain/skill-proposals.ts": {
calls: ["rmdirSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"the pending, accepted and materialised pages are removed through the lane " +
"page store (task 2.10 WP6), after the accepted copy landed and the journal " +
"recorded the commit phase, and only when the journal recorded that neither " +
"existed beforehand. The `rmdirSync` finishes that rollback for a `mature_page` " +
"accept, which creates a directory to hold its SKILL.md: `rmdirSync` refuses a " +
"non-empty directory, so only the empty shell this sequence made is removed. " +
"A `scored_rewrite` accept OVERWRITES an incumbent, so when the journal " +
"recorded that the artifact DID exist and carries a prior-content copy, the " +
"same rollback restores the incumbent bytes through `atomicWriteFileSync` " +
"instead of removing anything; a missing copy is a named refusal that keeps " +
"the journal on disk, because silently leaving the candidate body on an " +
"incumbent's path is the one outcome worse than the crash being recovered " +
"from.",
},
// --- Repair under an explicit apply ----------------------------------
"src/core/brain/watchdog.ts": {
calls: ["rmSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"under `--remediate` without `--dry-run` only: removes a non-directory " +
"occupying a path the Brain tree requires to be a directory, immediately before " +
"creating it. The plan naming that file is returned on every dry run, so the " +
"operator sees the exact removal before authorising it.",
},
// --- Reached from the gate, but not lexically inside it --------------
"src/core/brain/source-cleanup.ts": {
calls: ["rmSync"],
recovery: Object.freeze({
recoveryPoint: true,
blastRadius: Object.freeze({ brainTopLevel: true, outsideBrainRoot: true }),
}),
reason:
"`removeFile` is reached only from `runDeletion`, which `deleteBySource` hands to " +
"`withDestructiveSnapshot` BY NAME - so the archive exists before any removal, but the " +
"census sees a helper rather than a gated block and this entry is that claim written " +
"down. The one ungated call of `runDeletion` is the no-work branch, where the derived, " +
"originals and manifest lists are all empty and the loops remove nothing. Recovery is " +
"PARTIAL rather than covered because `--include-originals` removes the imported file " +
"outside `Brain/`, which no archive has ever held.",
},
"src/core/brain/anticipatory-prune.ts": {
calls: ["unlinkSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"prunes the anticipatory context cache under `Brain/.state/anticipatory/` by file age " +
"and a hard count cap, never the entry the calling refresh just wrote. Every entry is " +
"a derived context pack rebuilt from the vault it sits in, so removing one costs one " +
"recomputation on the next refresh or read and loses no content.",
},
"src/core/brain/notes/write-record.ts": {
calls: ["unlinkSync"],
recovery: UNARCHIVED_BRAIN,
reason:
"prunes before-images past a retention window measured from each file's own mtime, " +
"and an image whose age cannot be measured at all is kept rather than removed. Every " +
"image is a COPY of note content that still exists somewhere the snapshot region " +
"archives - either on disk as the note's current body or inside an earlier archive - " +
"so removing one loses no content; it only narrows how far back a revert can reach, " +
"and a revert that cannot reach its before-image refuses that target by name rather " +
"than discovering the absence silently.",
},
"src/core/brain/notes/lifecycle.ts": {
calls: ["renameSync", "unlinkSync"],
recovery: UNARCHIVED_OUTSIDE,
reason:
"the note MOVE, which is a relink and not a copy: `linkSync` attaches the inode to the " +
"destination name and the name is re-confirmed on disk before the source name is " +
"dropped, so the bytes are reachable under two names at that instant and under one at " +
"every other. The case-only rename cannot use that order - unlinking the source would " +
"remove the destination with it - so it stages a third private name for the same inode " +
"first. A note lives outside `Brain/` by construction, which is why no archive covers " +
"it and why the DELETE arm of the same module is behind the gate instead - including " +
"the `--delete-linked` cascade, whose extra unlinks all sit inside that one gate call " +
"and whose Brain-resident half the archive therefore does hold.",
},
"src/core/brain/notes/folder-lifecycle.ts": {
calls: ["rmdirSync", "unlinkSync"],
recovery: EMPTY_SHELL_ONLY,
reason:
"prunes the moved folder's own emptied directories after every file of the move set " +
"has relocated: `rmdirSync` refuses a non-empty directory, so a folder whose " +
"subtree still holds a failed file - or any file this surface does not address - " +
"keeps it, which is exactly where the report says the bytes are. The one " +
"`unlinkSync` drops a destination name a mid-set fault linked after the source " +
"name's own drop had already failed: the source name still holds that inode, so " +
"the bytes outlive the removal and the failure report's kept-path claim stays " +
"true. No file bytes are ever reached: both removals take names, never bytes.",
},
// --- Outside the vault entirely --------------------------------------
"src/core/brain/portability/pointer.ts": {
calls: ["rmSync"],
recovery: UNARCHIVED_OUTSIDE,
reason:
"the project-side pointer NAMING a vault lives outside that vault - " +
"`assertNotInsideVault` enforces it - so no archive could ever have covered it, " +
"and its whole content is one path an operator can write again.",
},
});
/**
* The verdict for one declared site, or `null` when the path carries no
* declaration (which for a real path means it routes through the gate).
*
* Derived rather than stored, so a registry entry cannot claim a state
* its own facts do not support.
*/
export function destructiveSiteRecoverability(path: string): RecoverabilityVerdict | null {
const entry = DESTRUCTIVE_SITES[path];
return entry === undefined ? null : classifyRecoverability(entry.recovery);
}