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.
Variants - native Hermes memory provider
Consultant: Claude Code (claude -p), exit 0, 3 parseable variants. Codex
fallback not needed. Raw output preserved at cli-output/claude.md.
Variant 1: Embedded MCP client behind the provider
- Approach: The Python
MemoryProviderspawns a single long-livedo2b mcp --vault <hermes_home>/Brainstdio process duringinitialize()and holds an in-process JSON-RPC client to it.get_tool_schemas()returns the server'stools/list,handle_tool_call()forwards totools/call, and every lifecycle hook (prefetch,on_pre_compress,on_session_end) is just anothertools/callover the same channel. Themcp_serverblock leaves~/.hermes/config.yaml; the server becomes an internal implementation detail owned by the provider, so there is exactly one registration. - Trade-offs:
- Pro: Zero reimplementation - the battle-tested protocol and tool surface are reused verbatim; deterministic logic stays in TS.
- Pro: Tool-schema parity is automatic (schemas come from
tools/list), so no drift between a static manifest and the real server. - Pro: True consolidation - Hermes sees one provider, not an mcp_server plus a shim.
- Pro: Mockable in CI by swapping the JSON-RPC transport for a fake client; no live Bun needed.
- Con: Provider must manage subprocess lifecycle (boot, health,
shutdown(), hang/timeout handling, restart on crash). - Con:
sync_turnstill needs its own daemon thread to write the transcript without waiting on the RPC round-trip.
- Complexity: medium
- Risk: medium
Variant 2: Stateless per-call CLI bridge
- Approach: The provider holds no persistent process; each tool call and lifecycle hook shells out to a one-shot
o2bsubcommand (or a single-shot JSON-RPC invocation) and parses stdout.get_tool_schemas()returns a schema set generated once and cached, andsync_turnappends the raw turn to the transcript directly from Python (stdlib), invoking nothing. - Trade-offs:
- Pro: Simplest lifecycle - no long-lived process, no crash/restart logic, nothing to leak on
shutdown(). - Pro: Trivial to mock (replace the subprocess runner); robust in headless CI.
- Pro: Each call is isolated, so one failure cannot corrupt shared process state.
- Con: Process spawn + Bun startup cost on every call adds latency to hot paths like
prefetch. - Con: Schemas must be cached/snapshotted, reintroducing a drift risk between the snapshot and the real tool surface.
- Con: Needs stable one-shot CLI entrypoints, which may require adding
o2bsubcommands beyondo2b mcp.
- Pro: Simplest lifecycle - no long-lived process, no crash/restart logic, nothing to leak on
- Complexity: small
- Risk: low
Variant 3: Hybrid - Python-native light hooks + bridged tool surface
- Approach: Cheap, deterministic-free hooks (
sync_turn,on_memory_write,system_prompt_blockreadingBrain/active.md) are implemented directly in Python with stdlib file I/O scoped underhermes_home, while everything requiring deterministic logic (get_tool_schemas/handle_tool_call,prefetch,on_pre_compress) goes through a mockableBrainBridgeabstraction whose default backend is the TS core (persistent or per-call). This keeps the non-blocking, high-frequency paths off Bun entirely and reserves the bridge for genuine deterministic work. - Trade-offs:
- Pro: Hot paths (
sync_turn, prompt block, mirror writes) have no subprocess cost and no Bun dependency at all. - Pro: Clean
BrainBridgeseam makes the heavy paths independently mockable and lets the transport choice (Variant 1 vs 2) be swapped later. - Pro: Best worst-case latency and resilience for the non-blocking turn loop.
- Con: Two code paths and a partial Python file-format surface - real risk of subtly duplicating logic the constraints forbid reimplementing.
- Con: Most code to write, document, and keep in sync with the TS vault format as it evolves.
- Con: Harder to reason about "one mechanism" since some behavior lives in Python and some in TS.
- Pro: Hot paths (
- Complexity: large
- Risk: medium
Consultant recommendation: Variant 1
Rationale (consultant): satisfies the consolidation goal most directly - the MCP server becomes an internal detail owned by one native provider, collapsing the shim plus mcp_server block into a single registration - while reusing the exact, battle-tested tool surface so no deterministic logic is reimplemented in Python. Automatic schema parity via tools/list avoids the manifest-drift weakness of Variant 2, and abstracting the JSON-RPC transport keeps it fully mockable in CI without a live Bun runtime; the only real cost, subprocess lifecycle management, is a bounded, well-understood concern that Variant 3's dual-path duplication risk does not justify.
Orchestrator decision: Variant 1 (accept), with two refinements
I accept the consultant's recommendation. Variant 1 is the only one that fully delivers the stated goal (one mechanism, not two) without reintroducing schema drift (Variant 2) or Python-side duplication of the vault format the constraints explicitly forbid (Variant 3).
Two refinements borrowed from the other variants, justified by project context:
Borrow Variant 3's cheap
sync_turn. There is no "ingest one raw turn" MCP tool, and per-turn deterministic extraction is wasteful.sync_turnbuffers the turn (daemon thread, stdlib, scoped underhermes_home) and the deterministicbrain_pre_compact_extractruns only aton_pre_compress/on_session_endboundaries. This keeps the hot path off Bun (Variant 3's latency win) without duplicating any vault format (the extraction itself stays in TS).Borrow Variant 3's
BrainBridgeseam, keep Variant 1's persistent backend. The transport lives behind aBrainBridgeProtocol so the persistent MCP backend can be faked in CI and, if startup cost ever bites, swapped for Variant 2's per-call backend without touching the provider. This is pure Dependency Inversion and costs nothing now.
Everything requiring deterministic logic still goes through the single persistent o2b mcp channel, so the consolidation and "no reimplementation" guarantees hold.