Skip to content

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
5.0 KB
Raw Blame

Variant 1

Approach: Introduce one shared per-item annotation envelope early on the branch — a RetrievalAnnotations extension threaded through context-pack.ts/context-receipts.ts and the reader tail — and have every card attach its field to that single struct (A: rerank score, C: epistemic status + evidence_refs, D: adequacy verdict, E: satisfaction signal). Cards land in sequence, each extending the same envelope rather than opening a new output seam. B folds its outcome tag onto the same annotation vocabulary. Trade-offs:

  • Cleanest composition: C→D and A→enrich share one growth point, so the C/D output-shape collision and the A/rerank-tail collision collapse into "extend the struct."
  • Broad blast radius on the shared type; a defect in the envelope touches all five read paths at once.
  • Per-card bit-identity is harder to verify: each card mutates a struct other cards also read, so the off-branch proof is no longer a single guarded call site but "this field defaults absent and nothing consumes it."
  • Front-loads an abstraction before the second consumer exists, risking speculative shape. Complexity: large Risk: medium

Variant 2

Approach: Keep each card a self-contained stage with its own module, its own default-off config key, and one guarded call site, minimizing shared types. Resolve the real collisions purely by ordering so the later card extends an already-merged seam: A → C → D → E → B. A appends after the existing heuristic reranks in the reader tail; C adds the epistemic field to context items; D extends C's now-merged item shape with the verdict and reads gate-telemetry/coverage; E instruments the recall path D already touched; B lands last as the capstone assembly over a fully-merged branch. Trade-offs:

  • Maximal per-card bit-identity: every off-branch is a single guarded call site whose unchanged output is trivially verifiable.
  • Smallest blast radius per card; a regression is isolated to one stage.
  • Directly mirrors invariant #6 and the demonstrated one-PR-many-cards cadence — no up-front shared abstraction to design or defend.
  • Mild duplication: C's status and D's verdict are emitted as adjacent-but-separate fields; B and E each own their persistence (Brain/lessons/* vs Brain/demand-log/*) with no shared writer. Complexity: medium Risk: low

Variant 3

Approach: Land the two persistence substrates and a shared recall-event record first — B's outcome-tagged lessons corpus and E's demand log both emitted as continuity/gate_telemetry-style records — then rebuild the read-side cards (A, C, D) as consumers of that common event stream. D and E share one recall-event emission; B and E share the record substrate; the dream pass folds everything. Trade-offs:

  • Resolves the B/E persistence collision and the D/E recall-instrumentation collision via one shared emission point.
  • Inverts the natural read→write flow, forcing the persistence/event layer to be designed before its consumers exist.
  • Centralized emission on the hot path stresses the fail-open telemetry contract and Syncthing determinism, and makes the off-branch bit-identity proof depend on the whole bus being inert, not a local call site.
  • Largest blast radius and the weakest fit with driving cards one at a time — the first card carries most of the risk for cards that land later. Complexity: large Risk: high

Recommended: Variant 2

Variant 2 is the only option whose off-branch state is provable the way invariant #2 asks for it — a single guarded call site per card, each off-branch byte-identical to today — because it refuses a shared mutable struct or a shared emission bus that would make bit-identity a whole-subsystem property. The ordering A → C → D → E → B is exactly invariant #6 in practice: A is pure search-side with no vault writes and lowest blast radius, so it seeds the cross-encoder-provider pattern first (mirroring embeddings/registry.ts) without touching any other card; C then establishes the epistemic field on context items so D extends an already-merged shape rather than colliding on context-pack.ts/context-receipts.ts; D reuses C's status plus the existing gate-telemetry/coverage scores as a thin verdict+action layer (honoring its "do not build a separate attention organ" guardrail); E appends its demand log at the recall seam D has already opened, reusing coverage.ts's IDF score as the satisfaction axis; and B lands last as the heaviest assembly, unifying dead-ends.ts/preference.ts under the usage-signal.ts decay scorer and the dream pass over a fully-merged branch. This maximizes reuse of existing scoring/telemetry/coverage primitives, keeps every decision in-kernel deterministic (the cross-encoder stays an opt-in external call, graceful no-op when unset), and matches the repository's proven multi-card-suite cadence. Variant 1's shared envelope and Variant 3's event bus both trade that per-card verifiability and small blast radius for a composition elegance the suite does not need — and both raise, rather than lower, the risk to the load-bearing bit-identity and fail-open invariants.