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
Integrity and control of the agent-facing memory surface - implementation plan
Tasks
Task 1: Shared unique-match resolver
- Files:
src/core/graph/unique-match.ts(new),tests/core/graph/unique-match.test.ts(new) - Acceptance:
resolveUniqueMatchreturns the typed three-status outcome (uniquewith the single target,ambiguouswith every candidate in a deterministic order,nonefor an empty candidate list); a repeated identical candidate is deduped before the decision so one page naming a term twice never reads as ambiguity. - Depends on: none
Task 2: Repair-lane unique-match mention-to-wikilink resolution (t_ec6b155d)
- Files:
src/core/brain/link-graph/repair-lane.ts,tests/core/brain/link-graph/repair-collect.test.ts,tests/core/brain/link-graph/repair-lane.test.ts - Acceptance: the explicit-reference collector pools title and
buildAliasIndexalias terms per corpus page; a mention term proposes a candidate only when exactly one corpus page key carries it; a term carried by two pages producesskip-ambiguousdecisions (newRepairActionmember) in the lane's decision list and no candidates; dry-run and apply behavior, ordering, confidence (explicit_reference), threshold, write cap and idempotent rerun are unchanged; an alias mention proposes the same 0.9-confidence candidate a title mention would. - Depends on: Task 1
Task 3: Pre-extract relative-import binding (t_2356dace)
- Files:
src/core/brain/ingest/pre-extract.ts,src/core/brain/ingest/ingest.ts,tests/core/brain/ingest/pre-extract.test.ts,tests/core/brain/ingest/ingest.test.ts - Acceptance:
preExtractCodeStructuretakes optional{ ingestedFiles }; a TS/JS./- or../-specifier and a Python leading-dotfrom .x importwhose probed candidates (joined path, each supported extension,/index+ each supported extension) contain exactly one ingested file carryresolvedTowith that canonical vault-relative path; zero or multiple ingested candidates, a bare package specifier, and a call withoutingestedFilesall leave seeds byte-identical to today;ingest.runPreExtractpasses the manifest's canonical path set. - Depends on: Task 1
Task 4: JSX component-usage edge kind (t_998aa4e6)
- Files:
src/core/brain/ingest/pre-extract.ts,tests/core/brain/ingest/pre-extract.test.ts - Acceptance: a .tsx/.jsx line whose opening tag matches the structural rule (name immediately after
<, preceding character not an identifier or., name in[A-Z_$][A-Za-z0-9_$]*) yields ausesedge from the source path to the component name;<div>,<nav>,<Nav.Item>and generic type arguments (Array<Foo>) produce nothing; the widened kind union dedupes and sorts deterministically through the existing kind-awareedgeKey. - Depends on: Task 3 (same file,
pre-extract.ts; theuseskind and the relative-import binding land on one coherent grammar)
Task 5: Write-batch client request ID and durable receipt (t_b34439d9)
- Files:
src/core/brain/write-batch.ts,src/mcp/brain/write-batch-tools.ts,tests/core/brain/write-batch.test.ts,tests/mcp/brain-write-batch.test.ts - Acceptance:
applyWriteBatchaccepts optionalrequestId; with no request ID behavior is byte-identical; a repeated ID with the same semantic payload returns the retained original result (ledgerref) marked as a duplicate receipt and writes nothing; a repeated ID with a different payload throwsIdempotencyPayloadMismatchError; a fresh ID records the key with the receipt inrefafter commit; the MCPbrain_write_batchacceptsrequest_idand returnsrequest_idplus the receipt status; invalid IDs (empty, over 256 chars) surface the ledger's own named error before any write. - Depends on: none
Task 6: brain_search when-to-search cue (t_cb1e9d3d)
- Files:
src/mcp/search-tools.ts, MCP search test coverage for the description - Acceptance: the
brain_searchdescription carries exactly one added sentence that namesbrain_recall_gateas the classifier to consult before widening recall; no fan-out counts, no parallel-search language, and the recall-inject header text is untouched. - Depends on: none
Task 7: Caller-selectable FTS match mode (t_c5326ece)
- Files:
src/core/search/fts.ts,src/core/search/types.ts,src/core/search/pipeline/request.ts,src/core/search/pipeline/keyword-lane.ts,src/core/search/search.ts,src/mcp/search-tools.ts,src/cli/search/verbs/query.ts,tests/core/search/fts.test.ts,tests/core/search/search.test.ts,tests/mcp/search-global.test.ts, CLI flag test coverage - Acceptance:
buildFtsMatchwithanyOR-joins the quoted tokens and still drops caller-typedAND/OR/NOT/NEARtokens; defaultalloutput is byte-identical to today, including empty-input and single-token cases; the mode threads fromSearchOptionsthrough the request resolution and keyword lane; MCPmatch_modevalidates the enum and rejects anything else; the CLI--match-modeflag mirrors it; expansion composition and the derived-term callers (second-pass.ts,evidence-verification.ts) are unchanged. - Depends on: none
Task 8: Per-device audit week files (t_774dea61, writer half)
- Files:
src/core/reliability/audit.ts,tests/core/reliability.test.ts - Acceptance:
appendAuditRecordnames its fileshardedFileName(isoWeekLabel(timestamp), resolveAppendShardId(), "jsonl"); two writes withO2B_DEVICE_ID=aand=bin one week produce<week>.a.jsonland<week>.b.jsonland no process writes the other device's file;O2B_DEVICE_ID=""(the test preload default) keeps the legacy<week>.jsonlname and byte-identical behavior; the returned path is the file actually written; redaction, timestamp validation and the fsync discipline are unchanged. - Depends on: none
Task 9: Audit-reader and probe conversion (t_774dea61, reader half)
- Files:
src/core/brain/schema-integrity.ts,src/core/state/surfaces.ts, plus their test suites - Acceptance:
readRecordedSchemaPackDigestlists the schema-mutation directory throughlistShardedFileswith the week grammar, so device shards merge (newest record still wins by its own timestamp) and*.sync-conflict-*copies are never parsed; the state inventory's reachability probe for a sharded fixed-name ledger reports the surface present when the legacy name or any shard of its grammar exists, and absent only when neither does; single-file vaults read exactly as before. - Depends on: Task 8 (same grammar), Task 10-11 for the probe's ledger set (landed together with them)
Task 10: Fixed-name ledgers in Brain/log/ (t_774dea61, items 7-10)
- Files:
src/core/brain/paths.ts,src/core/brain/query-demand.ts,src/core/brain/recurrence.ts,src/core/brain/capture/telegram-capture.ts,src/core/brain/skill-proposals.ts, plus their test suites - Acceptance: query-demand, recurrence-support, capture-decisions and verifier-rejections write
<base>[.<deviceId>].jsonlthrough the shard grammar;readQueryDemandreturns the union of all shards (and the legacy file) in its existing ts-sorted order; query-demand compaction caps only the shard just appended; two devices produce two files and a merged read sees both;O2B_DEVICE_ID=""keeps every name and byte identical. - Depends on: Task 8
Task 11: Remaining fixed-name ledgers (t_774dea61, items 11-13)
- Files:
src/core/brain/health/edit-history.ts,src/core/brain/git/store.ts,src/core/brain/maintenance/journal.ts, plus their test suites - Acceptance:
pref-<slug>.history, per-repocommitsandmaintenance-runswrite per-device shards;readEditHistory, the git record read (and its dedup-before-append) andlistJournal/consecutiveTaskFailuresmerge all shards deterministically with single-shard file order preserved;sweepJournalrewrites only the local device's shard to the cap; the git append lock moves to the device's own shard path; two-device tests cover each. - Depends on: Task 8
Task 12: Doctor conflict sweep extension and append guard (t_774dea61)
- Files:
src/core/brain/doctor/store-integrity.ts, plus the doctor test suite and a new source-layout guard suite - Acceptance:
LEDGER_DIRSalso sweepsBrain/log/{session-lifecycle,hygiene,schema-mutations,secret-custody,watchdog}, the hook-audit and watchdog-audit roots, the skill-proposal ledger directory, the per-repo git store directories andBrain/preferences/, reporting every*.sync-conflict-*copy with the existing merge instruction; a guard test fails when a source file appends viaappendFileSync/openSync(..., "a")without using the shard helpers, with a named allow-list (per-run-unique dream-run files and the doctor repair appending to them). - Depends on: Tasks 8-11
Task 13: Wave integration check
- Files: none (verification only)
- Acceptance:
bun run typecheck,bun run lint, and the touched test files all pass; the seven cards' behaviors coexist (a pre-extract result can carryusesedges withresolvedTobindings; a repair-lane dry run with alias terms; a batch retry returning a duplicate receipt; a two-device audit week read back merged) without interfering defaults. - Depends on: Tasks 1-7, 8-12