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.
Variant 1: Extend continuity + metrics layers (reuse-first)
Approach: Treat both cards as additive surfaces on the infrastructure that already exists. Tracing becomes a new opt-in inbound continuity kind, generation_report, that the agent posts back after fulfilling any handoff (write-session submit, context-pack consume, dream proposal), carrying agent-reported usage (provider/model, real input/output/cached/total tokens, finish reason, latency) plus the local token estimate for comparison. Caching becomes a deterministic prefix-construction rule in the existing prompt builders plus a prompt_prefix metric surface that reports prefix-stability across repeated calls.
Trade-offs:
- Smallest blast radius: no new store, no new module, no new lifecycle. Both cards are pure additive surfaces under rules already audited (gate pattern,
safeContinuityPayload, content-hash dedup). - Memory <-> trace linkage falls out of
sourceRefs(paths/ids the kernel already knows); honest by construction, since the kernel never invents an LLM message id. - The asymmetry is surfaced cleanly: estimate is always present, real usage is present only when the inbound report arrives, and absent is reported as absent.
- Weaker uniformity: each of the three seams wires the inbound report itself, so there is mild duplication and no single "generation trace" abstraction to grow into later. Complexity: small Risk: low
Variant 2: Write-session engine as the canonical trace unit
Approach: Anchor both cards on the write-session lifecycle, the one seam that already has a durable record, audit event, attempts, and terminal transitions. Tracing extends the submit path with an opt-in agent-reported usage block and records latency/attempts into the existing write-session audit event, with session_id <-> target_path as the memory link. Caching adds a deterministic, separately hashed cache_prefix segment to the envelope plus advisory cache-control hints the agent may honour.
Trade-offs:
- Highest-fidelity trace where it matters most: the write-session already models open -> needs-llm-step -> submit -> terminal, so usage, attempts, and latency attach to a real state machine rather than a fresh log line.
- Reuses the existing chokepoint (
appendLogEvent), so audit ordering and the one-event-per-terminal-transition guarantee are preserved for free. - Coverage gap: context-pack and dream handoffs are not write-sessions, so they get little or no tracing and no shared prefix builder; the release covers one seam deeply and two shallowly.
- Modifying the submit path and envelope risks shape drift on a load-bearing record; needs careful flag-gating to keep default bytes identical. Complexity: medium Risk: medium
Variant 3: Dedicated generation-observability module
Approach: Introduce src/core/brain/generation/ as a unified seam that all three handoffs (write-session, context-pack, dream) describe themselves through, emitting one "generation handoff descriptor" and accepting one opt-in inbound "generation report" via a new CLI verb and MCP tool. The module owns a single deterministic prefix builder shared by all three seams and a prompt_prefix metric surface, giving one consistent trace ledger and one caching guarantee across the whole brain loop.
Trade-offs:
- Most coherent long-term shape: one abstraction, one reader, uniform linkage and prefix construction across every generation point.
- Best leverage for future handoff shapes, which only need to implement the descriptor rather than wire telemetry themselves.
- Largest change for a release the operator deliberately scoped to two minor, closely related tasks; it adds a new module, a new inbound path, and refactors three seams at once.
- Higher regression surface and review cost; risks introducing a parallel store/abstraction the brief explicitly cautions against, and front-loads design the two cards do not yet require. Complexity: large Risk: high
Recommended: Variant 1
Rationale: It satisfies every binding constraint with the least new surface area: opt-in, fail-open, payload-safe, additive-only, and byte-identical by default, all by reusing the continuity gate and the metrics layer rather than inventing a parallel store. It answers the key design question honestly: the traced unit is the agent's inbound generation report keyed by the paths/ids the kernel already owns, and caching is delivered structurally as a byte-stable prefix with a stability metric, never as a provider call. It covers all three handoff shapes without committing to a premature abstraction, which is the right altitude for a release deliberately scoped to two minor, closely related cards. Variant 2 leaves context-pack and dream under-covered, and Variant 3's uniformity is not yet earned and carries regression and parallel-store risk that this scope does not justify.