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
Agent Write Contract Suite - implementation plan
Tasks
Task 1: write-session store and types
- Files:
src/core/brain/write-session/types.ts,src/core/brain/write-session/store.ts,tests/core/brain/write-session/store.test.ts - Acceptance: session records round-trip through
Brain/.sessions/write/<id>.json(snake_case on disk, camelCase in TS); id allocation is collision-safe; lazy TTL turns an expired record into terminalfailedwith reasonexpiredon read;sweepSessionsremoves terminal and expired files; corrupted session files read as a probe error, never throw. - Depends on: none
Task 2: artifact validation and target policy
- Files:
src/core/brain/write-session/validate.ts,tests/core/brain/write-session/validate.test.ts - Acceptance: target paths must resolve inside
Brain/(traversal and absolute escapes rejected); reserved namespaces (Brain/preferences/,Brain/log/,Brain/.sessions/,Brain/.payloads/,Brain/_brain.yaml) are denied with coded errors; artifacts validate frontmatter shape, declared schema-pack type/tag vocabulary, and size caps; every failure is{code, path, message}; a compact correction prompt is built from the error list. - Depends on: Task 1
Task 3: session engine - lifecycle, correction loop, collision guard, audit
- Files:
src/core/brain/write-session/engine.ts,tests/core/brain/write-session/engine.test.ts - Acceptance:
openArtifactSessionreturns aneeds-llm-stepenvelope with prompt and schema hints, andexistingmetadata (length, content hash, first heading) when the target exists;submitArtifactreturnsneeds-correctionwith errors and decrementedattempts_lefton validation failure, terminalfailedat the retry cap,needs-reviewwhen review is required, anddonewith an atomic commit otherwise; commits against an existing path require the session's explicitoverwriteormergeintent (merge appends a delimited section);approveSessioncommits a reviewed artifact;abandonSessionis terminal; every terminal transition appends onewrite_sessionevent viaappendLogEvent. - Depends on: Tasks 1, 2
Task 4: decision panel kind - personas, steps, synthesis, committed note
- Files:
src/core/brain/write-session/personas.ts,src/core/brain/write-session/panel.ts,tests/core/brain/write-session/panel.test.ts - Acceptance: personas load from
Brain/personas/*.md(frontmatterkind: persona,lens) with the built-in default set (technical, strategic, risk, user-experience) when the directory is absent;openPanelSessionwalks deterministic stepspersona:<slug>in order thensynthesis, each envelope carrying that step's prompt; per-step submits validate non-empty bounded text and reuse the kernel correction loop; the final commit rendersBrain/decisions/panels/panel-<date>-<topic-slug>.mdwith frontmatter, per-persona sections, and the synthesis; the panel adds no new envelope fields. - Depends on: Task 3
Task 5: memory-source backend boundary
- Files:
src/core/brain/agent-backend/types.ts,src/core/brain/agent-backend/registry.ts,src/core/brain/agent-backend/claude.ts,tests/core/brain/agent-backend.test.ts - Acceptance:
MemorySourceBackendprotocol (id,discoverMemoryPaths,parseMemories,renderPreference); frozen registry withclauderegistered;resolveMemoryBackendreads thememory_backendconfig key, defaults toclaude, and fails on unknown ids with the registered list in the message; the Claude adapter delegates to existingclaude-memory-*modules and its rendered output is byte-identical to calling them directly; the import flow resolves through the registry with unchanged default behavior. - Depends on: none
Task 6: cross-agent shared namespace mirror
- Files:
src/core/brain/shared-namespace.ts,tests/core/brain/shared-namespace.test.ts, mirror hooks insrc/mcp/brain-tools.ts(brain_feedback,brain_note) andsrc/cli/brain/verbs/feedback/note paths - Acceptance:
resolveSharedNamespacereads theshared_namespaceconfig key (missing/empty = off);mirrorSignal/mirrorNotewrite the same record into the shared vault withorigin_vaultattribution alongside the agent identity; any mirror failure is swallowed and reported asmirror: "failed"while the primary write result is untouched; default-off means byte-identical behavior for existing setups; tool and CLI results carrymirror: "ok" | "failed" | "off"only when the feature is configured; unconfigured setups stay silent. - Depends on: none
Task 7: CLI verbs - session and panel
- Files:
src/cli/brain/verbs/session.ts,src/cli/brain/verbs/panel.ts,src/cli/brain/verbs/index.ts,src/cli/brain.ts,src/cli/brain/help-text.ts,src/cli/command-manifest.ts,tests/cli/brain-session.test.ts,tests/cli/brain-panel.test.ts - Acceptance:
o2b brain session open|submit|approve|abandon|status|list|sweepando2b brain panel open|submit|statusdrive the kernel end-to-end with--jsonenvelopes; artifact bodies come from--fileor stdin; errors exit 1 with the envelope on stdout; help text and command manifest list both verbs. - Depends on: Tasks 3, 4
Task 8: MCP tool brain_write_session
- Files:
src/mcp/brain-tools.ts,src/mcp/tools.ts, contract tests asserting the advertised tool count,tests/mcp/brain-write-session.test.ts - Acceptance: one tool with
op(open|submit|approve|abandon|status|list) andkind(artifact|panel) discriminators returning the same envelopes as the CLI; advertised count moves 65 -> 66 in full scope and contract tests are updated deliberately; writer scope is unchanged. - Depends on: Tasks 3, 4
Task 9: end-to-end integration test
- Files:
tests/e2e/agent-write-contract.integration.test.ts - Acceptance: one flow per feature against a real tmp vault: artifact session open -> invalid submit -> correction envelope -> valid submit -> committed file plus audit event; panel open -> four persona submits -> synthesis -> committed decision note; backend registry resolves claude and renders a preference; shared namespace mirrors a signal and a note with attribution while a broken shared path degrades to
mirror: "failed"without harming the primary write. - Depends on: Tasks 3, 4, 5, 6
Task 10: docs
- Files:
README.md,CHANGELOG.md,docs/cli-reference.md,docs/how-it-works.md - Acceptance: CHANGELOG
[0.41.0]entry; README capability sentence; CLI reference section forbrain sessionandbrain panel; how-it-works section describing the write-session contract and the no-LLM-in-core rule it preserves. - Depends on: Tasks 1-9