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
Native Hermes memory provider - implementation plan
Each task is one atomic conventional commit on feat/hermes-memory-provider.
TDD: write the failing test first, then implement. Run bun run fmt then
bun run lint before every commit. Python tests run with
python -m unittest discover -s tests/python -v.
Tasks
Task 1: Soft ABC base + shared config helpers
- Files:
plugins/hermes/_base.py(new),plugins/hermes/config.py(new),tests/python/test_memory_provider.py(new, partial) - Detail:
_base.pyimportsagent.memory_provider.MemoryProviderwhen available, else defines a minimal fallback base (lifecycle methods as no-ops accepting**kwargs).config.pyholdsconfig_path(),resolve_agent_name(),load_reminder_template(),render_reminder(agent)extracted from the current__init__.py(DRY - one source for both the provider and any legacy caller). - Acceptance: tests assert the fallback base is subclassable,
resolve_agent_name()honorsVAULT_AGENT_NAME/ config file /"agent"fallback, andrender_remindersubstitutes every{agent}placeholder. - Depends on: none
Task 2: BrainBridge abstraction + fake
- Files:
plugins/hermes/bridge.py(new),tests/python/test_memory_provider.py(extend) - Detail:
BrainBridgeProtocol withstart(),list_tools(),call_tool(name, args),stop().McpBrainBridgespawnso2b mcp --vault <vault>and implements the JSON-RPC handshake (initialize -> notifications/initialized -> tools/list) with timeouts and a single restart-on-crash.FakeBrainBridgereturns canned tool lists/results for tests. - Acceptance: tests drive
FakeBrainBridgethrough list/call;McpBrainBridgeJSON-RPC framing is unit-tested against an in-memory pipe stub (no real Bun). - Depends on: none
Task 3: Provider required surface
- Files:
plugins/hermes/provider.py(new),tests/python/test_memory_provider.py(extend) - Detail:
OpenSecondBrainMemoryProviderconstructor takes an optionalbridge(defaultMcpBrainBridge). Implementname,is_available()(config/vault present, no network),initialize(session_id, **kwargs)(capturehermes_home, resolve the vault from Open Second Brain config, start bridge),get_tool_schemas()(filterlist_tools()by the memory allowlist constant),handle_tool_call(name, args, **kwargs)(forward tocall_tool),get_config_schema()(fieldsvault,agent_name,timezone),save_config(values, hermes_home)(persist non-secret fields to the canonical Open Second Brain config the bridge and identity reminder both read). - Acceptance: tests assert tool-schema filtering against the allowlist, tool-call forwarding, config schema field shape, and
save_configwritesvault/agent_nameto the Open Second Brain config path (provider-local state, not the vault, is what lives underhermes_home). - Depends on: Task 1, Task 2
Task 4: Provider lifecycle hooks
- Files:
plugins/hermes/provider.py(extend),tests/python/test_memory_provider.py(extend) - Detail:
system_prompt_block()->brain_context(fail-soft to "").prefetch(query, *, session_id)->brain_recall_gatethenbrain_context_pack, append identity reminder.queue_prefetch()(cache last query).sync_turn(...)-> daemon thread, buffer turn underhermes_home.on_pre_compress(messages)/on_session_end(messages)-> flush buffer throughbrain_pre_compact_extract.on_memory_write(action, target, content)-> mirror to Brain viabrain_note/brain_pinned_context.shutdown()-> stop bridge, join threads. - Acceptance: tests assert prefetch returns reminder + recalled context, recall-gate "no" path returns reminder only, sync_turn never blocks and buffers, flush calls the extract tool, every hook is exception-safe.
- Depends on: Task 3
Task 5: register() + retire pre_llm_call
- Files:
plugins/hermes/__init__.py,tests/python/test_hermes_plugin.py - Detail:
register(ctx)registers the provider viaregister_memory_provider(best-effort across ctx shapes), keeps the health check, drops thepre_llm_callhook registration. Re-export provider/bridge/health. Retarget the shim tests: droppre_llm_callassertions, addregister_memory_providerassertions, keep template parity + health tests. - Acceptance:
registerattaches the provider on a ctx exposingregister_memory_provider; health check still attaches; nopre_llm_callregistration. - Depends on: Task 4
Task 6: Manifests - drop mcp_server, declare memory hooks
- Files:
plugins/hermes/plugin.yaml,plugin.yaml(root) - Detail: remove the
mcp_serverblock, replaceprovides_hooks: [pre_llm_call]with the implemented memory-hook list, bump description to "native memory provider". - Acceptance: YAML parses;
hookslist matches the implemented hooks; nomcp_serverkey. - Depends on: Task 5
Task 7: Optional CLI
- Files:
plugins/hermes/cli.py(new),tests/python/test_memory_provider.py(extend) - Detail:
register_cli(subparser)buildingstatus(provider availability + bridge ping) andconfig(effective config) subcommands; dispatch handler. - Acceptance: test invokes the argparse tree and asserts
status/configdispatch. - Depends on: Task 3
Task 8: CI compile + packaging
- Files:
.github/workflows/ci.yml,.github/workflows/release.yml,pyproject.toml(verify only) - Detail: change the
py_compile plugins/hermes/__init__.pystep tocompileall plugins/hermesso new submodules are compiled. Confirm setuptools still packagesplugins.hermes(submodules auto-included). - Acceptance: workflow YAML parses;
python -m compileall plugins/hermesis green locally. - Depends on: Task 5
Task 9: Docs (install, README, CHANGELOG)
- Files:
install/hermes.md,README.md,CHANGELOG.md - Detail: rewrite
install/hermes.mdaroundmemory.provider: open-second-brain/hermes memory setupinstead of the manualmcp_serversedit; add a README note that Hermes uses the native memory provider; add one CHANGELOG entry under the next version (version bumped in Phase 6). - Acceptance: docs describe the native provider flow; no stale
mcp_serversmanual-edit instruction remains for Hermes; no abbreviations, no AI-authorship markers, no exclamation marks. - Depends on: Task 6