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.
Agent Write Contract Suite - variants audit trail
Consultant: Claude Code (claude -p), primary, single run, no fallback needed.
Prompt: cli-output/prompt.md. Raw output: cli-output/claude.md (verbatim copy below).
Consultant output (verbatim)
Variant 1: Unified session kernel
- Approach: Build one generic, file-backed write-session state machine in
core/brain/session/(envelope withstatus/session_id/step, TTL + retry store, audit log) that is the literal deliverable of Task 1. Task 4's decision panel becomes a session kind (panel) riding the same kernel - OSB emits per-persona prompts as steps and validates the synthesis on submit - so it needs no parallel lifecycle. Task 2 stays a narrowAgentBackendboundary the session consults for render/validation strategy; Task 3 is an independent fail-soft mirror hooked at the existingsignal/note/preference-txnchokepoints. - Trade-offs:
- Pro: TTL, retry cap, collision metadata, and audit log are built exactly once and shared by both agent-facing flows.
- Pro: Task 4 collapses to persona-loading + a synthesis schema, since it inherits the correction loop and operator-gate (
needs-review) for free. - Pro: Fewer new MCP tools (one session surface with a
kinddiscriminator) keeps the 65-tool growth deliberate. - Con: Kernel must be generic enough on day one to serve both an artifact-write and a multi-step panel - some up-front design tax.
- Con: Couples panel and write-session evolution; a panel-specific need could leak into the shared envelope.
- Complexity: medium
- Risk: low
Variant 2: Four independent modules sharing only contracts
- Approach: Ship each task as a self-contained module sharing nothing but type contracts (
SchemaValidationResult, envelope types). Write-session, backend registry, shared-namespace mirror, and decision panel each own their store, surface, and tests; the panel calls the write-session as a library but persists to its own state. Each module maps one-to-one to a kanban task. - Trade-offs:
- Pro: Independently shippable, testable, and revertable - clean blast-radius isolation per task.
- Pro: Strongly additive; no module reshapes another's write path, fitting the "additive-only" and fail-closed/fail-soft split naturally.
- Pro: Lowest design risk - no premature generalization.
- Con: Session lifecycle, TTL, retry, and audit logic get duplicated (or near-duplicated) between Task 1 and the panel.
- Con: More MCP tools and two session-ish state machines that can drift apart over time.
- Complexity: medium
- Risk: low
Variant 3: Backend-protocol-first (everything is a backend capability)
- Approach: Make Task 2's
AgentBackendprotocol the central abstraction and route the write-session, persona panel, and shared-namespace mirroring through it as backend-dispatched capabilities. The Claude memory render becomes the first backend; selection is config-driven, and all agent-write behavior is expressed as capabilities a backend declares. - Trade-offs:
- Pro: Maximum extensibility - a future runtime gains write-session, panel, and mirror behavior through one seam.
- Pro: Single dispatch point for all agent-facing format concerns.
- Con: Over-abstraction when only one backend (Claude) exists; the deterministic-core rule means backends are format adapters, not generation engines, so the seam carries little real variation today.
- Con: Largest refactor - pulls the
claude-memory-*flow and core write paths under a new boundary, straining the "do not change existing public APIs / additive-only" constraint. - Con: High YAGNI risk; couples four independently-valuable tasks to one speculative abstraction.
- Complexity: large
- Risk: high
Recommended: Variant 1
Rationale: Task 4 is specified to run as a write-session, so a shared session kernel turns the panel into a thin persona-and-synthesis layer instead of a second state machine - the strongest reuse for the least surface, which directly serves the deliberate-MCP-growth and no-LLM-in-core constraints. It keeps Task 2 as a deliberately narrow render/validation boundary and Task 3 as a fail-soft hook at the existing chokepoints, avoiding both the duplication of Variant 2 and the premature, core-reshaping generalization of Variant 3.
Orchestrator decision
Variant 1 accepted, with two containment refinements against the consultant's literal text:
- The session kernel does not consult backends. The consultant suggested Task 2 as "a boundary the session consults for render/validation strategy" - that is speculative coupling with no consumer today. The backend boundary stays scoped to the memory-import flow (
claude-memory-*); the write-session validates against schema-pack contracts directly. If a real second runtime ever needs format-specific session validation, the seam can grow then. - Module path is
src/core/brain/write-session/, notcore/brain/session/. The repo already hassession-lifecycle.ts,session-recall.ts,session-scope.ts, andsessions/(import adapters); an unqualifiedsession/directory would collide with that vocabulary.
Variant 2 was the runner-up; its decisive flaw is the duplicated lifecycle between the artifact flow and the panel (two TTL/retry/audit implementations drifting apart). Variant 3 was rejected on YAGNI and on the additive-only constraint it admits to straining.