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.
Truth-correctable, time-aware claims - implementation plan
Four parallel implementation lanes plus one integrator, structured over Variant 3's two sub-suites. Sub-suite A (tasks 1-10, lanes 1 and 2) delivers temporal truth: ledger validity fields with the succession channel, the windowed events operation, and grounded agent-stated ledger claims. Sub-suite B (tasks 11-19, lanes 3 and 4) delivers correction and recall: the correct verb with per-target end-state policy and fail-recorded sweep receipts, deepened traversal with width caps and direct-hit precedence, and the shared serve-with-correction coupling predicate across surfaces. Sub-suite B tasks start only after the contract modules they consume have landed (see Cross-lane contract and the dependency rule).
Lane ownership is disjoint: no two lanes edit the same file. Shared new modules exist only as contract items and are named in the Cross-lane contract. Every task is test-first: the named test files are written first, run, and must fail with the expected error before implementation.
| Lane | Name | Owns |
|---|---|---|
| 1 | ledger-core | src/core/brain/truth/** (except events-window.ts), src/core/brain/atomic-facts.ts, truth and census tests |
| 2 | recall-surfaces | src/mcp/brain/knowledge-tools.ts, src/mcp/brain/recall-tools.ts, src/mcp/brain/time-bounds.ts, src/core/brain/truth/events-window.ts, src/cli/brain/verbs/truth.ts, truth MCP/CLI tests |
| 3 | correction-coupling | src/core/brain/lifecycle/correction.ts, src/core/search/correction-coupling.ts, src/mcp/brain/lifecycle-tools.ts, src/cli/brain/verbs/lifecycle.ts, src/core/search/pipeline/post-rank.ts, src/core/brain/{query,context-pack,active,dream-scan}.ts, lifecycle/coupling/matrix tests |
| 4 | deep-traversal | src/core/search/{relational-fanout,fusion,ranker,retrieval-trail,index}.ts, src/core/search/pipeline/{relational-arm,attribution}.ts, src/core/search/store/entity-bridges.ts, relational search tests |
| D | docs | README.md, docs/architecture.md, regenerated plugins/codex/ mirrors |
| I | integrator | tests/contract/serve-with-correction.test.ts, full gates |
Cross-lane contract
The contract pins exactly the three genuinely cross-card decisions. Each item names its owning lane, its module, and the exact signatures every consumer implements against. A consumer lane codes against these signatures before the owning lane's commit lands; the poll rule in the dependency section covers the wait.
Contract item 1: the assertion-versus-validity axis rule (owner: lane 1, module src/core/brain/truth/validity.ts + src/core/brain/truth/succession.ts)
ClaimEvent,AppendClaimInputandClaimVersiongain optional presence-gatedvalidFrom?: stringandvalidUntil?: string(canonical ISO-8601 UTC, half-open[validFrom, validUntil)), serialized by conditional spread underTRUTH_SCHEMA_VERSION = 1.export interface ClaimWindow { readonly fromMs: number | null; readonly untilMs: number | null }andexport function claimWindow(event: ClaimEvent): ClaimWindow | null- null when the event carries no window; a missing bound is unbounded on that side.export function windowsIntersect(a: ClaimWindow, b: ClaimWindow): boolean- half-open intersection,a.fromMs < b.untilMs && b.fromMs < a.untilMswith null as plus/minus infinity.- Classification rule: a same-slot pair is succession if and only if both claims carry present windows and
windowsIntersectis false; every other pair keeps today's assertion-time contest behavior verbatim; an expired window never suppresses contestation on its own. - Windowed event shape:
ClaimEventRowis the storedClaimEventwith validity fields verbatim; the events operation'ssince/untilfilter assertiontsonly and are stated as such in the schema description. - Sibling consumers stay assertion-keyed:
collision.tsandgrounding.tsconstants gain a comment stating the axis choice; their code does not change.
Contract item 2: the correction end-state policy (owner: lane 1, module src/core/brain/truth/correction-policy.ts)
export type CorrectionEndState = "validity_close" | "tombstone";
export interface CorrectionEndStateInput {
/** The caller declares the prior claim was never true, not merely superseded. */
readonly flatlyWrong: boolean;
/** Explicit window end for a time-scoped correction (canonical ISO-8601 UTC). */
readonly windowEnd?: string;
}
export function correctionEndState(
input: CorrectionEndStateInput,
correctionTs: string,
): { endState: CorrectionEndState; validUntil: string | null };
// flatlyWrong -> { endState: "tombstone", validUntil: null }
// otherwise -> { endState: "validity_close", validUntil: windowEnd ?? correctionTs }
Consumers: lane 3's correct verb chooses per target through this function and records the choice in the bundle receipt with the existing reason codes (supersede for validity_close, tombstone for tombstone); lane 1's succession logic and lane 4's path-provenance annotation read the outcome through the ledger/frontmatter data (a validity-closed predecessor against its successor has non-overlapping present windows and classifies as succession under item 1).
Contract item 3: the serve-with-correction coupling predicate (owner: lane 3, module src/core/search/correction-coupling.ts)
export type CouplingVerdict =
| { readonly action: "serve_coupled"; readonly correctionPath: string }
| { readonly action: "drop" };
export interface CouplingInput {
/** Path of the retired-but-serveable row's page. */
readonly predecessorPath: string;
/** Chain-tip successor path from resolveChainTip/buildChainLookup, null when unresolved. */
readonly successorPath: string | null;
/** True when the successor page is readable at the caller's reach. */
readonly successorReadable: boolean;
}
export function couplingVerdict(input: CouplingInput): CouplingVerdict;
// resolved AND readable -> { action: "serve_coupled", correctionPath: successorPath }
// otherwise -> { action: "drop" }
Rule: a retired-but-serveable row is served only beside its chain-tip correction; otherwise it is dropped fail-closed (a withheld page stays indistinguishable from an absent one). Any correction content pulled in re-runs the full filter set: status, visibility scope, agent scope, reach. Every serving surface consumes this predicate: search post-rank, recall by topic, context-pack, active.md, dream scan. Tombstoned rows stay dropped by the status filter everywhere; the predicate governs the serveable-retired regime only. The guarantee is pinned by the integrator's cross-suite test tests/contract/serve-with-correction.test.ts, named here as part of the contract.
Dependency rule
- Lanes commit their pure modules first: lane 1 commits
validity.ts,succession.ts,correction-policy.ts(and their tests) before its store/surface wiring tasks; lane 3 commitscorrection-coupling.tsbefore its wiring tasks; lane 4 commits therelational-fanout.tsbudget changes before arm wiring. - A lane that consumes an upstream lane's module may poll
git log -- <file>for the upstream lane's commit at a 30 s interval, with a 12-minute cap; when the cap expires the consumer proceeds against the contract signatures above (they are exact and test-pinned, so drift surfaces as the consumer's failing test, which the integrator then reconciles). - Sub-suite B tasks (11-19) must not land before the contract item they consume has landed: lane 3's task 16 needs item 2, lane 4's tasks need no lane-1 module (they depend on item 1's annotation rule only through frontmatter data, so lane 4 may run fully in parallel), lane 3's tasks 18-19 need item 3 (their own module).
- Format and lint before every commit; each task is its own conventional commit on the feature branch.
Tasks
Task 1: Ledger validity fields and window parsing
- Lane: 1 (ledger-core)
- Files:
src/core/brain/truth/validity.ts(new),src/core/brain/truth/types.ts,src/core/brain/truth/store.ts,tests/core/brain/truth/validity.test.ts(new, written first),tests/core/brain/truth/store.test.ts,tests/core/architecture/visibility-surface-census.test.ts - Acceptance:
validity.test.tspasses: window parsing reuses thesearch/validity.tsdiscipline (bare dates day-snapped, datetimes, relative phrases rejected),claimWindowreturns null for windowless events,windowsIntersectimplements the half-open rule with infinity for missing bounds;store.test.tspasses: presence-gated serialization leaves windowless lines byte-identical,coerceClaimtolerates and validates the new optional fields under schema v1, the read/write matrix (old binary reads new lines, new binary reads old lines) is pinned; census rows exist for the new exported surfaces. - Depends on: none.
Task 2: Succession channel in the conflict policy layer
- Lane: 1 (ledger-core)
- Files:
src/core/brain/truth/succession.ts(new),src/core/brain/truth/conflicts.ts,src/core/brain/truth/types.ts,tests/core/brain/truth/succession.test.ts(new, written first),tests/core/brain/truth/conflicts.test.ts - Acceptance:
succession.test.tspasses: two same-slot claims with present non-overlapping windows classify asClaimSuccessionentries and never as conflicts; intersecting windows or any windowless claim falls through to the assertion-time contest rule verbatim; an expired window never suppresses contestation.conflicts.test.tspasses unchanged on its existing pins (base fold equality, bit-identical neutral default) andTruthState.successionsis absent (undefined, not[]) whenever empty;TruthConflictKindis unchanged; state file serialization spreadssuccessionsonly when present. - Depends on: Task 1.
Task 3: Ingest window defaults, frozen at ingest
- Lane: 1 (ledger-core)
- Files:
src/core/brain/truth/store.ts,src/core/brain/truth/validity.ts,tests/core/brain/truth/validity.test.ts - Acceptance:
validity.test.tswindow-default cases pass: explicitvalidFrom/validUntilinput wins outright; absent input, the resolver reads the source record's frontmattervalid_from/valid_untilwhen the source is readable at ingest and stores the frozen resolved value; an unreadable or windowless source stores a windowless event that is byte-identical to today's output; mtime is never used as a window source. - Depends on: Task 1.
Task 4: Grounded agent-stated claim core
- Lane: 1 (ledger-core)
- Files:
src/core/brain/truth/stated-claims.ts(new),src/core/brain/truth/ingest.ts,src/core/brain/truth/types.ts(optionalextractor?: "agent_stated"),src/core/brain/truth/store.ts,src/core/brain/atomic-facts.ts(export the occurrence-anchoring kernel as a pureanchorEntityForms),tests/core/brain/truth/stated-claims.test.ts(new, written first) - Acceptance:
stated-claims.test.tspasses: a stated claim{ subject, relation, object }withtextmaps to a ledger event (entity = normalized subject, aspect = relation token, value = object) withextractor: "agent_stated"; an unknown relation, missing text or missing source refuses the whole payload with nothing written (refuse-before-write at the boundary); anchoring verdicts are per claim - subject and object anchored via the quality-gated match forms commit, ungrounded claims are reported back with reasons; conflict detection is untouched (contestingValuesunchanged, conflict rows may annotate the tag but never re-rank or resolve). - Depends on: Task 1.
Task 5: Correction end-state policy (contract item 2)
- Lane: 1 (ledger-core)
- Files:
src/core/brain/truth/correction-policy.ts(new),tests/core/brain/truth/correction-policy.test.ts(new, written first) - Acceptance:
correction-policy.test.tspasses the exact signature and rule table:flatlyWrongyields tombstone with nullvalidUntil; any other input yields validity_close withwindowEndwhen time-scoped, else the correction instant; results are pure and deterministic. - Depends on: none. Must land before lane 3's Task 16 (sub-suite A before B).
Task 6: Events-window selection (pure)
- Lane: 2 (recall-surfaces)
- Files:
src/core/brain/truth/events-window.ts(new),tests/core/brain/truth/events-window.test.ts(new, written first) - Acceptance:
events-window.test.tspasses:selectClaimEvents(events, { entity, sinceMs, untilMs, limit })slices the already-ts-sorted event array with second-precision string compare (since floored, until ceiled to the second, matching the grammar's inclusive day-edge semantics), composes with the normalized-entity filter, appliesDEFAULT_EVENT_LIST_LIMIT = 200with hard capCLAIM_EVENT_MAX_LIST_LIMIT = 1000, and returns stable ascending rows withtotalandtruncated. - Depends on: none (codes against the
ClaimEventshape of contract item 1).
Task 7: Shared time-bounds wrapper
- Lane: 2 (recall-surfaces)
- Files:
src/mcp/brain/time-bounds.ts(new),src/mcp/brain/recall-tools.ts,tests/mcp/time-bounds.test.ts(new, written first) - Acceptance:
time-bounds.test.tspasses: the liftedresolveTimeBounds(since, before)resolves throughresolveTimeRangeand mapsSearchErrortoMCPError(INVALID_PARAMS);recall-tools.tsconsumes the shared wrapper for session-grep bounds with behavior unchanged (its existing tests stay green). - Depends on: none.
Task 8: brain_truth events operation and agent-stated claims operation
- Lane: 2 (recall-surfaces)
- Files:
src/mcp/brain/knowledge-tools.ts,tests/mcp/brain-truth.test.ts - Acceptance:
brain-truth.test.tsadditions pass:operation: "events"acceptsentity/since/until/limit(declared in the closed schema,additionalProperties: false), returns{ ok, operation, entity, events: ClaimEventRow[], total, withheld, truncated }with rows in stable ascending assertion-tsorder and validity fields verbatim; every row passes the same per-row visibility/reach gate asbrain_claims, dropped rows counted inwithheld; the slots and conflicts responses are byte-identical to before (theeventscount pin stays);operation: "state"accepts{ claims, text, source, agent? }, refuses unknown relations before any write, commits grounded claims withextractor: "agent_stated", and reports ungrounded claims back per claim with reasons. Schema descriptions state the ts-only filter and the half-open validity convention. - Depends on: Tasks 1, 2, 4, 6, 7 (polls lane 1 commits per the dependency rule).
Task 9: CLI truth surface
- Lane: 2 (recall-surfaces)
- Files:
src/cli/brain/verbs/truth.ts,tests/cli/brain-truth.test.ts - Acceptance:
brain-truth.test.tsCLI additions pass:o2b brain truth events [--entity E] [--since X] [--until Y] [--limit N]prints the same shape as the MCP events op;o2b brain truth ingestaccepts--valid-from/--valid-until;o2b brain truth state --subject S --relation R --object O --text T --source S [--agent N]prints the anchoring verdict (committed event or reported-back reasons); unparseable bounds fail with the INVALID_PARAMS-equivalent CLI error through the shared wrapper; the CLI/MCP op asymmetry is preserved (all ops present on both,sweepCLI-only). - Depends on: Tasks 3, 4, 6, 8.
Task 10: Sub-suite A integration checkpoint
- Lane: 2 (recall-surfaces)
- Files: none new (verification only)
- Acceptance: full truth-suite test files green together (
tests/core/brain/truth/,tests/mcp/brain-truth.test.ts,tests/cli/brain-truth.test.ts, census test); a windowed events call over events ingested with resolved windows returns rows carrying the frozen windows; the succession channel and the events surface agree on the axis rule from contract item 1. - Depends on: Tasks 1-9.
Task 11: Traversal budgets, hub skipping, deadline
- Lane: 4 (deep-traversal)
- Files:
src/core/search/relational-fanout.ts,src/core/search/index.ts,tests/core/search/relational-fanout.test.ts - Acceptance:
relational-fanout.test.tsadditions pass: seed capTRAVERSAL_MAX_SEEDS = 8, per-node capTRAVERSAL_MAX_EXPANSION_PER_NODE = 4, total-node capTRAVERSAL_MAX_TOTAL_NODES = 16, all overridable viaOPEN_SECOND_BRAIN_SEARCH_TRAVERSAL_*with theparseBool(envOrConfig(...))pattern; a node whose walked-edge degree exceedsTRAVERSAL_HUB_DEGREE_THRESHOLD = 12is reached but not expanded; a fired deadline abandons the frontier deterministically keeping already-reached nodes; the existing hop-dominance and determinism pins stay green; off state unchanged. - Depends on: none.
Task 12: Entity bridges from chunk_entities
- Lane: 4 (deep-traversal)
- Files:
src/core/search/store/entity-bridges.ts(new),src/core/search/relational-fanout.ts,tests/core/search/relational-fanout.test.ts - Acceptance:
relational-fanout.test.tsbridge cases pass:entityBridgesForDocumentsjoinschunk_entitiesinto deduplicated bridge edges labeledentity; bridges are walked only whenOPEN_SECOND_BRAIN_SEARCH_ENTITY_BRIDGESis true and the arm is enabled; with bridges off, fanout output equals the Task 11 output exactly; bridge edges count toward hub degree and node caps. - Depends on: Task 11.
Task 13: Ordered path provenance with per-node reach gating
- Lane: 4 (deep-traversal)
- Files:
src/core/search/pipeline/relational-arm.ts,src/core/search/pipeline/attribution.ts,src/core/search/retrieval-trail.ts,tests/core/search/relational-path.test.ts(new, written first),tests/core/search/relational-arm.test.ts - Acceptance:
relational-path.test.tspasses:RelationalReachcarries the ordered path of{ documentId, relation }steps; path nodes unreadable at the caller's reach are omitted and counted, and the attribution reason rendersrelational: via <types> (<n> hops, <k> nodes withheld); a readable path node that is a non-tip superseded predecessor with a closed validity window is annotatedsuperseded_by: <tip>from frontmatter only; the ordered path lands in the retrieval trail as a new stable typed code carrying readable document ids plus the withheld count; existing attribution tests stay green. - Depends on: Task 12.
Task 14: Structural direct-hit precedence
- Lane: 4 (deep-traversal)
- Files:
src/core/search/fusion.ts,src/core/search/ranker.ts,src/core/search/pipeline/relational-arm.ts,tests/core/search/fusion.test.ts - Acceptance:
fusion.test.tsprecedence pins pass: relational-only rows are admitted after the last organic row in the pre-rerank fused order; a relational-only row at relational-rank 1 never outranks a keyword direct hit; the tightened rerank pin holds (a relational-origin row may move within the relational block, never sinks below its pre-rerank position relative to other relational rows, and never crosses above an organic direct hit); with the arm disabled, fusion output is byte-identical. - Depends on: Task 11.
Task 15: Coupling predicate module (contract item 3)
- Lane: 3 (correction-coupling)
- Files:
src/core/search/correction-coupling.ts(new),tests/core/search/correction-coupling.test.ts(new, written first) - Acceptance:
correction-coupling.test.tspasses the exact signature and rule table: resolved and readable successor yieldsserve_coupledwith the correction path; unresolved, unreadable, or absent successor yieldsdrop; pure, deterministic, no I/O. - Depends on: none.
Task 16: Correct-verb sweep core
- Lane: 3 (correction-coupling)
- Files:
src/core/brain/lifecycle/correction.ts(new),tests/core/brain/lifecycle/correction.test.ts(new, written first) - Acceptance:
correction.test.tspasses: discovery gathers the affected set within the caller's reach (claim-graph closure viawhatReplaced/whatContests, match-only wikilink mention scan viaretargetWikilinkswithapply: false, same-entity/aspect ledger claims); dry-run writes nothing and returns the blast-radius report; the applied run retires each target throughcorrectionEndState(contract item 2), retargets mentions with per-write failure carry, appends ledger correction events from the successor's source (self-correction semantics, never a conflict), and emits per-record receipts withcorrection_bundle:<bundleId>inevidence_triggers; replay converges (no double tombstone, receipts reportappended: false, closed windows stay closed); Brain/log and receipt lines are never rewritten; every write passes the vault-identity guard. - Depends on: Task 5 (contract item 2; sub-suite A before B).
Task 17: brain_lifecycle correct action, CLI verb, matrix equality
- Lane: 3 (correction-coupling)
- Files:
src/mcp/brain/lifecycle-tools.ts,src/cli/brain/verbs/lifecycle.ts,tests/mcp/brain-lifecycle-correct.test.ts(new, written first),tests/mcp/agent-scope-matrix.test.ts - Acceptance:
brain-lifecycle-correct.test.tspasses:brain_lifecycleactioncorrectand CLIo2b brain lifecycle correctexpose the sweep withdry_rundefault true, aflatly_wrongflag, an optionalwindow_end, and reach-gated targets (a target the caller may not read is refused as missing before anything is written); the agent-scope-matrix equality is updated for the new action's recipes and stays an equality (tool count unchanged); receipt reason codes staysupersede/tombstone, name-aligned with the verb and action. - Depends on: Task 16.
Task 18: Search-pipeline coupling wiring
- Lane: 3 (correction-coupling)
- Files:
src/core/search/pipeline/post-rank.ts,tests/core/search/post-rank-coupling.test.ts(new, written first) - Acceptance:
post-rank-coupling.test.tspasses: the retired-row branch consumescouplingVerdict- a retired-but-serveable row is served only beside its resolved, readable chain-tip correction and is dropped otherwise; correction content pulled in re-runs the full filter set (status, visibility scope, agent scope, reach), closing the recorded gap where pulled successors bypassed visibility and agent scope; with no retired rows the pool is unchanged (byte-identical neutral path pinned); tombstoned rows remain dropped by the status filter before the predicate runs. - Depends on: Task 15.
Task 19: Cross-surface coupling
- Lane: 3 (correction-coupling)
- Files:
src/core/brain/query.ts,src/core/brain/context-pack.ts,src/core/brain/active.ts,src/core/brain/dream-scan.ts,tests/core/brain/coupling-surfaces.test.ts(new, written first) - Acceptance:
coupling-surfaces.test.tspasses: recall by topic, context-pack injection, the active.md digest and the dream scan all decide throughcouplingVerdict- a serveable retired row appears only with its correction, is dropped otherwise, and today's exclusion wiring keeps tombstoned rows hidden; each surface's non-retired output is unchanged. - Depends on: Task 15.
Task 20: Docs, matrix documentation, and plugin mirrors
- Lane: D (docs)
- Files:
README.md,docs/architecture.md, regenerated mirrors underplugins/codex/ - Acceptance: docs/architecture.md agent-scope-matrix section matches the implementation lane's test equality (same recipe rows for the
correctaction); README documents theeventsandstatetruth operations, thecorrectverb, the traversal budget flags and their defaults;bun run sync-plugin-mirrorshas been run and the generated mirror is committed in this lane's FIRST commit;bun run sync-plugin-mirrors:checkis clean afterwards. - Depends on: Tasks 10 and 17 (final shapes and matrix numbers; may be written against the contract in parallel and committed after they land).
Task 21: Integrator - contract pin and full gates
- Lane: I (integrator)
- Files:
tests/contract/serve-with-correction.test.ts(new, written first) - Acceptance: the cross-suite contract test passes: with sub-suite A's windows and sub-suite B's coupling wired together, a retired-but-serveable row served by any surface is always accompanied by its chain-tip correction, and is dropped when the successor is unresolved or out of reach - the guarantee named in contract item 3. Then the full gates in CI order: formatter, linter, full test suite,
bun run sync-plugin-mirrors:check, the architecture census and agent-scope-matrix equalities; any cross-lane drift against the contract is reconciled here. - Depends on: Tasks 10, 14, 19, 20.