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.
Answer trust: verified quotes, claim attribution, source archives, session identity - implementation plan
Feature branch: feat/answer-trust (checked out from origin/main at v1.80.0, a00fa3f5). TDD per task, one atomic conventional commit per task, bun run fmt + bun run lint green before every commit. Work is organized as five implementation lanes in separate worktrees with STRICTLY DISJOINT file ownership: a file is edited by exactly one lane. Within a lane, tasks are ordered substrate-first (pure modules and config before wiring and surfaces). There are NO cross-lane dependencies by design - the four cards and the repair lane land independently and assemble at merge time.
This wave adds NO new MCP tool, NO new CLI verb, and NO new continuity record kind. Every surface change is a field on an existing tool result, an op on an existing tool, a flag on an existing verb, or one registered doctor check, so the tool-name pins (tests/mcp/mcp.test.ts, tests/mcp/brain-tools-parity.test.ts, tests/mcp/agent-scope-matrix.test.ts, docs/mcp.md) do not move. Any census that must change for a lane to proceed is a design error and stops that lane.
House rules this wave:
- New verdict vocabularies (Lane A's five quote verdicts, Lane C's archive refusals if vocabulary-shaped): frozen object + companion member list + type guard, registered in
tests/core/architecture/verdict-vocabulary-census.test.ts. That file is SHARED-APPEND: each lane appends only its own vocabulary block; the census asserts membership per vocabulary, not a wave-global count, so appends never collide. - New durable Brain directory
Brain/.archives/: aSTATE_SURFACE_IDentry andSTATE_SURFACESrow insrc/core/state/surfaces.tsplus theDECLARED_SURFACE_COUNTbump intests/core/architecture/state-surface-census.test.ts(Lane C, Task C1). hooks/hooks.jsonis mirrored into the Codex plugin: after editing it, runbun run sync-plugin-mirrors(CI and the pre-commit hook gate onsync-plugin-mirrors:check; never hand-editplugins/codex/hooks/hooks.json). Every command must keep the resilient shape thetests/hooks/hooks-json-shape.test.tscensus pins:$CLAUDE_PLUGIN_ROOTwrapper, PATH fallback, trailingexit 0.- No identifier containing
secretbefore a quoted value anywhere in src or tests; the plugin scanner flags theconst secret = "..."form. Tests never depend on directory iteration order; every listing sorts deterministically.
Cross-lane contract (pinned)
| Owner | Files |
|---|---|
| Lane A | hooks/answer-quote-check.ts (new); hooks/hooks.json; src/core/brain/answer-quotes/check.ts (new); src/core/config.ts; tests/core/brain/answer-quotes/**; tests/hooks/answer-quote-check.test.ts (new); tests/core/config-answer-quote-check.test.ts (new); the tests/hooks/hooks-json-shape.test.ts Stop-order extension and A's verdict-vocabulary census block |
| Lane B | src/core/brain/truth/store.ts; src/core/brain/truth/stated-claims.ts; src/core/brain/truth/claim-provenance.ts (new); src/core/brain/context-receipts.ts (ContextReceiptFilter.receiptId field only); src/mcp/brain/knowledge-tools.ts; src/cli/brain/verbs/truth.ts; tests/core/brain/truth/**; tests/core/architecture/claim-attribution-census.test.ts (new); the existing truth and CLI truth suite extensions |
| Lane C | src/core/brain/provenance/source-archive.ts (new); src/core/brain/ingest/ingest.ts; src/mcp/brain/ingest-tools.ts; src/mcp/brain/hygiene-tools.ts; src/core/brain/hygiene/detectors/capture-scope.ts; src/core/brain/path-constants.ts; src/core/state/surfaces.ts; src/cli/brain/verbs/doctor.ts; tests/core/brain/provenance/source-archive.test.ts (new); tests/mcp/ingest-tool.test.ts; tests/mcp/hygiene-capture-scope-reach.test.ts; tests/cli/brain-hygiene.test.ts; the tests/core/architecture/state-surface-census.test.ts count and C's verdict-vocabulary census block; the index-admission walker-exclusion extension |
| Lane D | src/core/brain/session-recall.ts; src/core/brain/session-summary.ts; src/core/brain/idea-lineage.ts; src/core/brain/doctor/session-identity-check.ts (new); src/core/brain/doctor.ts; src/cli/brain/verbs/session-summary.ts; src/mcp/brain/synthesis-tools.ts (digest-shape sweep); tests/core/brain/session-identity-check.test.ts (new); the session-recall, session-summary and idea-lineage suite extensions |
| Lane R | src/core/search/property-pushdown.ts; src/core/search/store.ts; tests/core/search/kind-attributes-pushdown.test.ts; CHANGELOG.md (the two whitespace-damaged lines only) |
Shared files, collisions resolved by assignment:
src/core/config.ts- Lane A'squote_check.*resolvers own it; no other lane touches it (Lane C's ceilings are constants, not config).hooks/hooks.json- Lane A owns it (one Stop entry); the Codex mirror is regenerated, never hand-edited.src/core/brain/doctor.ts- Lane D owns theDOCTOR_CHECKSregistration edit. Lane C's archive findings ride the hygiene detector and the doctor CLI verb, never the registry.src/core/search/store.ts- Lane R owns it; Lanes B, C and D must not touch it (they read through existing store APIs without edits).tests/core/architecture/verdict-vocabulary-census.test.ts- shared-append as above; the only test file two lanes both append to.CHANGELOG.md- Lane R touches only the whitespace-damaged lines; the release entry itself belongs to the release phase after this plan.
Lane A config surface (pin - one vocabulary per key, no second reader)
| Key | Home | Values | Default | Resolver |
|---|---|---|---|---|
quote_check.recall |
Brain/_brain.yaml, quote_check block |
off | shadow | enforce |
shadow |
resolveAnswerQuoteCheckRecall(configPath?) |
quote_check.active |
Brain/_brain.yaml, quote_check block |
off | shadow | enforce |
shadow |
resolveAnswerQuoteCheckActive(configPath?) |
quote_check.subagent |
Brain/_brain.yaml, quote_check block |
off | shadow | enforce |
shadow |
resolveAnswerQuoteCheckSubagent(configPath?) |
Resolver semantics, pinned for all three: unknown or wrongly typed values are field-named config errors naming quote_check.<phase> (never silently off); unknown keys inside the quote_check block warn per the strict-block convention. The hook runs a phase's check only when BOTH hold: the phase's injection is enabled (recall requires recall_inject_enabled, src/core/config.ts:1185-1188; active and subagent their own injection gates) and the resolver returns more than off. shadow annotates only; enforce annotates and appends exactly one Brain-log event per turn.
Hook constants, pinned as named exports in hooks/answer-quote-check.ts: ANSWER_QUOTE_MAX_MESSAGES (last assistant messages read), ANSWER_QUOTE_MAX_CHARS (per-message char budget), ANSWER_QUOTE_BUDGET_MS (wall-clock budget) - the bounded, fail-open contract the wave requires on the hot path.
Tasks
Task A1: Quote verdict module (Lane A, substrate)
- Lane: A. Files: new
src/core/brain/answer-quotes/check.ts;tests/core/brain/answer-quotes/check.test.ts; A's block intests/core/architecture/verdict-vocabulary-census.test.ts. - Acceptance:
checkAnswerQuotes({spans, evidence})composesquoteHaystack/spanOccursInover the distill helpers imported in place (findQuoteSpans,normalizeForQuoteComparison,src/core/brain/distill/quote-spans.ts:410,466,486- no fork, no copy;checkClaimQuotesunextended) and returns exactly the five verdictsverified | not-in-note | source-truncated | note-unavailable | not-text, pinned table-style; the vocabulary is a frozen object + companion list + type guard, census-registered; the false-positive bar is the distill suite itself (tests/core/brain/distill/quote-check.test.ts): every span that suite verifies must verify here under the same evidence. - Depends on: none
Task A2: quote_check config resolvers (Lane A, substrate)
- Lane: A. Files:
src/core/config.ts;tests/core/config-answer-quote-check.test.ts. - Acceptance: the three resolvers land beside
resolveRecallInjectEnabled(src/core/config.ts:1185) with the exact semantics of the config surface table above: defaultshadowper phase,off|shadow|enforceaccepted, any other value a field-named error namingquote_check.<phase>, unknown block keys warning; resolvers are pure (configPathin, mode out) and read nothing else. - Depends on: none
Task A3: Stop-hook step and hooks.json entry (Lane A)
- Lane: A. Files: new
hooks/answer-quote-check.ts;hooks/hooks.json(one Stop entry, ordered afterstop-log-guardrail,hooks/hooks.json:112);tests/hooks/answer-quote-check.test.ts(synthetic transcript + injection ledger); thetests/hooks/hooks-json-shape.test.tsStop-order extension. - Acceptance: reads only the last assistant messages under the three named constants; finds quoted spans with
findQuoteSpans; resolves each span's cited note from the span context (wikilink or vault-relative path) else ledger membership acrossLEDGER_KEY_RECALL|ACTIVE|REGROUND|SUBAGENT_INJECT(hooks/lib/injection-ledger.ts:23-26); phase gating consults the injection gate AND the Task A2 resolver; emits exactly ONEhookSpecificOutput.additionalContextannotation listing unverified spans with their verdicts (thehooks/stop-log-guardrail.ts:10precedent); never blocks, never edits the transcript; any error exits 0 with exactly one stderr audit line;bun run sync-plugin-mirrorsrun and green. - Depends on: Tasks A1, A2
Task A4: Degradation matrix and the enforce trail (Lane A)
- Lane: A. Files:
src/core/brain/answer-quotes/check.ts(truncation and unavailability arms);hooks/answer-quote-check.ts(enforce log event); extensions of both A test suites. - Acceptance: the degradation matrix is pinned end-to-end - note unavailable yields
note-unavailablewith the annotation kept; a truncated source (ContextPackItem.trimmed,src/core/brain/context-pack.ts:156; receipttruncatedatsrc/core/brain/context-receipts.ts:336,447) is matched against the available prefix, a miss issource-truncated, and marks are never stripped on truncated evidence;shadowwrites nothing to the vault;enforceadditionally appends exactly one Brain-log event per turn viaappendLogEvent(src/core/brain/log.ts:289) and never more; the hook exits 0 in every arm. - Depends on: Task A3
Task B1: sample_id on the claim event (Lane B, substrate)
- Lane: B. Files:
src/core/brain/truth/store.ts; the truth store test suite. - Acceptance:
AppendClaimInputandClaimEvent(src/core/brain/truth/types.ts:50-71) carry optionalsample_id; omitted when absent, never invented; present values are stored verbatim and treated as opaque (privacy: receipts store hashes only, so the id discloses nothing); the schema version is unchanged and old ledgers read unchanged, exactly the optional-extractorforward-compatibility (src/core/brain/truth/types.ts:64-69); roundtrip pinned. - Depends on: none
Task B2: sampleId threading in stated claims (Lane B, substrate)
- Lane: B. Files:
src/core/brain/truth/stated-claims.ts; the stated-claims test suite. - Acceptance:
StatedClaimsPayloadgains optionalsampleId(src/core/brain/truth/stated-claims.ts:158-235is the append path); the value is trimmed and must be non-empty when present - an empty or whitespace-onlysampleIdis a named refusal, never coerced, never stored; threading reachesAppendClaimInput; the no-sampleId path is byte-identical to today. - Depends on: Task B1
Task B3: Read-only claim-provenance join (Lane B)
- Lane: B. Files: new
src/core/brain/truth/claim-provenance.ts;src/core/brain/context-receipts.ts(ContextReceiptFiltergainsreceiptId, matched before the limit,src/core/brain/context-receipts.ts:84-95,181);tests/core/brain/truth/claim-provenance.test.tsbesidetests/core/brain/context-pack-outcome.test.ts. - Acceptance: a claim's
sample_idresolves to{receipt items, outcome first_pass/evidence verdict}usinglistContextReceiptsby receipt id andlistContextPackOutcomesbysampleId(src/core/brain/context-pack-outcome.ts:108-118,293-305); asample_idwith a receipt but no outcome row renders "receipt known, outcome unknown" - absent, never invented; a claim timestamped before its claimed receipt'screated_atcarries an inversion flag; the module performs no vault writes (enforced by the Task B6 census); the join widens nothing the caller could not already read at its reach. - Depends on: Tasks B1, B2
Task B4: brain_truth state accepts sample_id and hydrates reads (Lane B)
- Lane: B. Files:
src/mcp/brain/knowledge-tools.ts; the knowledge tool test suite. - Acceptance:
brain_truth state(src/mcp/brain/knowledge-tools.ts:751-812) accepts optionalsample_idper claim and echoes it per-claim commit exactly as the claim committed; the read op hydrates committed claims throughclaim-provenance.tswhensample_idis present; claims withoutsample_idrender exactly as today; a missing outcome row renders the "receipt known, outcome unknown" marker, never a fabricated verdict. - Depends on: Task B3
Task B5: CLI truth --sample-id (Lane B)
- Lane: B. Files:
src/cli/brain/verbs/truth.ts; the CLI truth test suite. - Acceptance:
o2b brain truth state --sample-id <id>threads the id through Task B2's validation; claim reads hydrate provenance identically to the MCP read op; omitting the flag is byte-identical to today; the flag value is validated by the same named refusal as the MCP path. - Depends on: Task B4
Task B6: Attribution census (Lane B)
- Lane: B. Files: new
tests/core/architecture/claim-attribution-census.test.ts. - Acceptance: pins, as architecture invariants: (a) the continuity record-kind vocabulary is unchanged by the wave - the join reads existing
context_receiptandbrain_context_pack_outcomerows and introduces no new kind; (b) no recall-time writes - thetruth/modules andclaim-provenance.tsimport no continuity append path. Either invariant failing stops the lane. - Depends on: Task B3
Task C1: .archives path constants and state surface (Lane C, substrate)
- Lane: C. Files:
src/core/brain/path-constants.ts(BRAIN_ARCHIVES_DIR=".archives"+BRAIN_ARCHIVES_REL, with the dot-dir walker-exclusion doc following the.artifactsprecedent,src/core/brain/path-constants.ts:109-116);src/core/state/surfaces.ts(STATE_SURFACE_IDentry +STATE_SURFACESrow);tests/core/architecture/state-surface-census.test.ts(DECLARED_SURFACE_COUNT+1). - Acceptance: the surface row derives
Brain/.archives/,carries_memory: true, with a reason stating it is durable evidence - deleting it destroys re-verification ability, not current vault content (the deliberate contrast to the artifact store's prune,src/mcp/artifact-store.ts:110); the census count matches; nothing else in the tree builds the path by hand (the census's naive-path-builder sweep passes). - Depends on: none
Task C2: Source-archive store (Lane C, substrate)
- Lane: C. Files: new
src/core/brain/provenance/source-archive.ts;tests/core/brain/provenance/source-archive.test.ts; C's block intests/core/architecture/verdict-vocabulary-census.test.ts(if refusals are vocabulary-shaped). - Acceptance:
put(vault, bytes) -> sha256writesBrain/.archives/<sha256>.txt, content-addressed so identical bytes persist once (dedup pinned);ARCHIVE_MAX_BYTES = 1_048_576with refuse-not-truncate - a past-ceiling input raises the named error, never a truncated write (theCaptureExcerptErrorposture,src/core/brain/provenance/capture-scope.ts:243-248); redaction runs BEFORE persist viaredactRawOutput(src/core/redactor.ts:971), pinned by a test that a credential-shaped input never lands on disk;verify(vault, hash)re-hashes and reports match/mismatch;stats(vault)feeds the Task C6 doctor section. - Depends on: Task C1
Task C3: Ingest trusted-branch capture and page stamp (Lane C)
- Lane: C. Files:
src/core/brain/ingest/ingest.ts(trusted branch,src/core/brain/ingest/ingest.ts:390-396); the ingest suite andtests/mcp/ingest-tool.test.ts. - Acceptance: the trusted-local branch reads the source once,
readSourceOrigin-style (src/core/brain/intake/source-trust.ts:430-458- not the byte-discardingclassifySourceOrigin,:418-420), archives the bytes, and stampssource_archive_hash+source_archive_byteson the summary page ON SUCCESS ONLY; an archive failure leaves the page unstamped and never fails the ingest (absence still means exactly "not captured"); a source whose digest is refused to remote readers (src/core/brain/intake/extract-intake.ts:332-336) is never archived; an oversized source skips capture with the named refusal recorded; untrusted and non-local sources behave byte-identically to today. - Depends on: Task C2
Task C4: Ingest result field and delete-by-source cleanup (Lane C)
- Lane: C. Files:
src/mcp/brain/ingest-tools.ts;tests/mcp/ingest-tool.test.ts. - Acceptance: the
brain_ingest_sourceresult gainssource_archive_hashfollowing thecapture_scopefield pattern - always present, null when not captured (src/mcp/brain/ingest-tools.ts:148) so absence never reads as a missing key to a caller; delete-by-source cleanup (src/mcp/brain/ingest-tools.ts:218-260) gains an archive-entry kind so removing a source's last citing page removes its now-orphaned archive entry, reported as its own kind in the cleanup result. - Depends on: Task C3
Task C5: Hygiene detector missing/mismatched-archive finding (Lane C)
- Lane: C. Files:
src/core/brain/hygiene/detectors/capture-scope.ts;tests/mcp/hygiene-capture-scope-reach.test.ts;tests/cli/brain-hygiene.test.ts. - Acceptance: an ingest summary stamped
source_archive_hashwhose archive entry is absent or re-hashes differently yields the named finding (one per page,reviewproposed action, the detector's existing shape); a page with no stamp is unchanged - absence means not captured, never a finding; findings flow through the existing hygiene surfaces (brain_hygienetool,o2b brain hygiene scan, the Stop hygiene-digest hook) with no registry edits; reach rules hold - a caller who may not read the page learns nothing new from the finding. - Depends on: Tasks C2, C3
Task C6: Archive read surface and doctor section (Lane C)
- Lane: C. Files:
src/mcp/brain/hygiene-tools.ts(archive_getop);src/cli/brain/verbs/doctor.ts(informational archive section); the hygiene tool and doctor verb tests. - Acceptance:
archive_geton the existingbrain_hygienetool resolves a hash to the archived bytes, modeled onbrain_artifact_get's bounded-fetch posture and LOCAL reach only - a remote-reach caller gets the same answer an absent entry gives, never the bytes (the visibility rule the design pins); an unknown hash is a named miss; the doctor CLI section is count-only informational (entry count, total bytes, missing/mismatched count) with no fix verb; no new tool and no new verb, so the tool-name pins stay unmoved. - Depends on: Tasks C2, C5
Task D1: Explicit no-session semantics in recall (Lane D)
- Lane: D. Files:
src/core/brain/session-recall.ts; the session-recall test suite. - Acceptance: the read-path coercion at
src/core/brain/session-recall.ts:577treats a missing or non-stringsession_idas no-session explicitly (noString(... ?? "")); a record withoutsession_idis excluded from scoped recall and fromlineageScope; the lineage ledger's blank-id omission (:619-627) is pinned unchanged; unscoped reads still return the record; a non-string value (number, null) is excluded, not coerced. - Depends on: none
Task D2: Grouping sites and the digest shape sweep (Lane D)
- Lane: D. Files:
src/core/brain/session-summary.ts(the filter at:243, the scope compare at:339, the digest at:375);src/cli/brain/verbs/session-summary.ts;src/mcp/brain/synthesis-tools.ts; the session-summary test suite plus consumer rendering cases. - Acceptance: grouping at
:243and:339skips no-session records rather than matching them against""(the shared-bucket defect);SessionSummaryDigest.sessionIdbecomes presence-gated (key omitted when absent); the CLI verb and the synthesis surface render a no-session summary without crashing and without fabricating an id; a consumer that cannot tolerate the absent key stops the lane for a design check - no fallback to""is acceptable anywhere. - Depends on: none
Task D3: Idea-lineage no-session semantics (Lane D)
- Lane: D. Files:
src/core/brain/idea-lineage.ts(the turn index at:120, the source resolution at:198); the idea-lineage test suite. - Acceptance: the turn-index grouping skips no-session records rather than keying them by
""; the source resolution emits undefined rather than""for a record with no session; lineage output never merges two unrelated no-session records into one group (pinned by a two-record case). - Depends on: none
Task D4: blank-session-identity doctor check (Lane D)
- Lane: D. Files: new
src/core/brain/doctor/session-identity-check.ts;src/core/brain/doctor.ts(DOCTOR_CHECKSregistration adjacent toorphanSessionCheck,src/core/brain/doctor.ts:174-201);tests/core/brain/session-identity-check.test.ts. - Acceptance: count-only and fail-soft - one pass over
listContinuityRecords, one issue per affected record kind carrying the count, NOfixfield (repair belongs to t_6cc80627's backup-gated posture); an unreadable ledger yields the uncertain-stream outcome, mirroring the orphan-session patterns (src/core/brain/doctor/orphan-session-check.ts:37-40); the check runs ino2b brain doctorand thebrain_doctortool with zero config; no payload is ever rewritten. - Depends on: Task D1 (shares the no-session predicate's definition; reads only)
Task R1: Freshness gate on attribute narrowing (Lane R)
- Lane: R. Files:
src/core/search/property-pushdown.ts;src/core/search/store.ts;tests/core/search/kind-attributes-pushdown.test.ts. - Acceptance: the pinned case passes - a document indexed as
status: draft, edited tostatus: done, filteredstatus=done, is returned; stale candidates fall through to the live post-rank filter instead of being silently excluded by theEXISTS ... OR NOT EXISTSfragment (src/core/search/property-pushdown.ts:303-321, applied at:386); fresh candidates take the SQL path unchanged (the no-per-row-file-read case is pinned alongside); the advertised "narrow on the attribute snapshot, judged live" semantics (src/mcp/search-tools.ts:293) hold for every narrowed key. - Depends on: none
Task R2: CHANGELOG whitespace repair (Lane R)
- Lane: R. Files:
CHANGELOG.md(the damaged lines atCHANGELOG.md:264andCHANGELOG.md:2450only). - Acceptance: the missing spaces at
:264and the broken list indentation at:2450are repaired; the diff touches no other line; docs-only, no code paths, no behavior. - Depends on: none