Skip to content

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

feat: become a native Hermes memory provider (#62)

Sol Aitken0952dfcde8a0
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 8c59ead8..a6b53061 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.31.2",
+ "version": "0.32.0",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": {
"name": "Open Second Brain contributors"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 2b737c31..7a393256 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.31.2",
+ "version": "0.32.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"skills": "./skills",
"hooks": "./hooks/hooks.json",
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6c6f863d..15dda1c5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
with:
bun-version: latest
- - name: Set up Python (Hermes shim test only)
+ - name: Set up Python (Hermes plugin tests)
uses: actions/setup-python@v5
with:
python-version: "3.11"
@@ -55,5 +55,8 @@ jobs:
- name: TypeScript test suite
run: bun test
- - name: Python shim tests
+ - name: Python plugin tests
run: python -m unittest discover -s tests/python -v
+
+ - name: Python package compiles
+ run: python -m compileall -q plugins/hermes
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 07ff1097..7dba84a9 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -36,7 +36,7 @@ jobs:
with:
bun-version: latest
- - name: Set up Python (Hermes shim test only)
+ - name: Set up Python (Hermes plugin tests)
uses: actions/setup-python@v5
with:
python-version: "3.11"
@@ -53,7 +53,7 @@ jobs:
- name: Run TypeScript test suite (bun:test)
run: bun test
- - name: Run Python shim tests
+ - name: Run Python plugin tests
run: python -m unittest discover -s tests/python -v
- name: Validate manifests and CLI scripts
@@ -64,7 +64,7 @@ jobs:
python -m json.tool .codex-plugin/plugin.json >/dev/null
python -m json.tool openclaw.plugin.json >/dev/null
python -m json.tool package.json >/dev/null
- python -m py_compile plugins/hermes/__init__.py
+ python -m compileall -q plugins/hermes
bash -n scripts/o2b
bash -n scripts/vault-log
bash -n scripts/_bun-precheck.sh
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a083eb84..dc0107c2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,62 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.32.0] - 2026-06-01
+
+Open Second Brain is now a native Hermes memory provider. The Hermes
+integration is consolidated into one mechanism: a Python `MemoryProvider` that
+bridges to the existing `o2b mcp` server over JSON-RPC, replacing the separate
+`pre_llm_call` shim and the standalone `mcp_servers` registration. Claude Code
+and Codex are unchanged - their canonical path is still MCP plus hooks.
+
+### Added
+
+- `plugins/hermes` memory provider (`provider.py`, `bridge.py`, `config.py`,
+ `_base.py`, `cli.py`): implements the Hermes `MemoryProvider` contract -
+ `get_tool_schemas`/`handle_tool_call` over a curated `brain_*` subset,
+ `system_prompt_block` from `Brain/active.md`, `prefetch` (recall gate plus the
+ per-turn identity reminder), non-blocking `sync_turn` buffering, deterministic
+ `on_pre_compress`/`on_session_end` flush via `brain_pre_compact_extract`,
+ `on_memory_write` mirroring of Hermes `MEMORY.md`/`USER.md` into `Brain/`, and
+ `shutdown`.
+- `hermes open-second-brain status` / `config` diagnostics CLI (`cli.py`).
+ Surfacing is gated on an upstream Hermes loader fix - see Notes.
+
+### Changed
+
+- `register(ctx)` now wires the memory provider via `register_memory_provider`
+ alongside the health check.
+- Both Hermes manifests declare the memory provider and the lifecycle hooks it
+ implements instead of `provides_hooks: [pre_llm_call]` and an `mcp_server`
+ block. They no longer set `kind: standalone`, so Hermes auto-routes the plugin
+ to its memory-provider path; the repo-root `__init__.py` re-exports the
+ provider so Hermes' provider discovery detects it.
+- `install/hermes.md` documents the activation lifecycle: activate with
+ `hermes memory setup open-second-brain`, deactivate with `hermes memory off`;
+ `memory.provider` persists across `hermes plugins update` (no re-activation).
+
+### Removed
+
+- The Hermes-only `pre_llm_call` hook: its per-turn identity reminder is now
+ carried by the provider's `prefetch`.
+
+### Notes
+
+- The bridge restarts the `o2b mcp` subprocess only on a transport failure
+ (EOF / broken pipe); a JSON-RPC error response (e.g. invalid tool arguments)
+ propagates unchanged. Behaviour is locked by `tests/python/test_memory_provider.py`
+ and `tests/python/test_hermes_plugin.py`.
+- **Temporary loader workaround.** Hermes' external memory-provider loader
+ imports a plugin under a synthetic package (`_hermes_user_memory.<name>`)
+ without registering that parent namespace, so an external provider's relative
+ imports raise `ModuleNotFoundError: No module named '_hermes_user_memory'`
+ (a flat single-directory layout hits this too). The repo-root `__init__.py`
+ carries a file-path fallback to load the implementation, marked for removal
+ once the upstream loader registers the parent namespace
+ (`NousResearch/hermes-agent`). The same limitation gates the
+ `hermes open-second-brain` CLI subcommand; it needs no further changes here
+ and surfaces automatically when the upstream fix ships.
+
## [0.31.2] - 2026-06-01
Hands-off post-upgrade migration. After an update, the plugin now brings an
@@ -3779,6 +3835,7 @@ plugin config (vault field)`, and exits with a clear
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
+[0.32.0]: https://github.com/itechmeat/open-second-brain/compare/v0.31.2...v0.32.0
[0.31.2]: https://github.com/itechmeat/open-second-brain/compare/v0.31.1...v0.31.2
[0.31.1]: https://github.com/itechmeat/open-second-brain/compare/v0.31.0...v0.31.1
[0.30.0]: https://github.com/itechmeat/open-second-brain/compare/v0.29.0...v0.30.0
diff --git a/README.md b/README.md
index e5e1c552..0f3cae22 100644
--- a/README.md
+++ b/README.md
@@ -60,7 +60,7 @@ o2b brain init --vault /path/to/your-vault --primary-agent <agent-name>
o2b doctor --vault /path/to/your-vault
```
-Register the MCP server in `~/.hermes/config.yaml` and restart the gateway one more time - the agent now reads `Brain/active.md` on every session start and writes signals through `brain_feedback`. Full step-by-step including MCP wiring: [`install/hermes.md`](install/hermes.md).
+Enable Open Second Brain as the memory provider in `~/.hermes/config.yaml` (`memory.provider: open-second-brain`) and restart the gateway one more time - the agent now injects `Brain/active.md` into its system prompt, recalls context before each turn, and writes signals through `brain_feedback`, all through the one native provider. Full step-by-step: [`install/hermes.md`](install/hermes.md).
## Other runtimes
diff --git a/__init__.py b/__init__.py
index 60f39f04..8caa5f64 100644
--- a/__init__.py
+++ b/__init__.py
@@ -3,13 +3,77 @@
Hermes installs Git plugins by cloning the repository and loading the repository
root as the plugin directory. The implementation lives in ``plugins/hermes`` so
it can also be used directly by runtimes that expect an adapter subdirectory.
+
+TEMPORARY WORKAROUND (third import branch below)
+------------------------------------------------
+Hermes' external memory-provider loader (``plugins/memory/_load_provider_from_dir``)
+imports this file under a synthetic package name ``_hermes_user_memory.<plugin>``
+but never registers that parent namespace package. As a result ANY relative
+import in an external (user-installed) provider fails with
+``ModuleNotFoundError: No module named '_hermes_user_memory'`` β€” this affects a
+flat single-directory layout too, not just our ``plugins/`` subpackage. Bundled
+providers escape it only because they load as ``plugins.memory.<name>`` (that
+parent IS registered). The file-path fallback below sidesteps the broken parent
+chain so the provider loads.
+
+This is a Hermes-core limitation, not a plugin bug. The correct fix is upstream
+(``NousResearch/hermes-agent``): have the loader register the
+``_hermes_user_memory`` parent namespace. REMOVE the third ``except`` branch once
+that ships β€” the first two import branches are the real, native ones. The same
+limitation blocks the ``hermes open-second-brain`` diagnostic CLI subcommand;
+it will start working from the same upstream fix with no further changes here.
"""
from __future__ import annotations
try:
- from .plugins.hermes import check_health, health, register
+ # Normal package import: adapter-subdir runtimes and Hermes' general
+ # plugin manager load the repo root as a package, so the implementation
+ # subpackage resolves relatively.
+ from .plugins.hermes import (
+ OpenSecondBrainMemoryProvider,
+ check_health,
+ health,
+ register,
+ )
except ImportError:
- from plugins.hermes import check_health, health, register
+ try:
+ from plugins.hermes import (
+ OpenSecondBrainMemoryProvider,
+ check_health,
+ health,
+ register,
+ )
+ except ImportError:
+ # === TEMPORARY WORKAROUND β€” remove with upstream Hermes loader fix ===
+ # See the module docstring. Hermes' memory loader imports this file as
+ # ``_hermes_user_memory.<plugin>`` without registering that parent
+ # namespace, so the relative/absolute imports above raise
+ # ``ModuleNotFoundError: No module named '_hermes_user_memory'``. Load
+ # the implementation by file path under a collision-free package name;
+ # ``submodule_search_locations`` lets its own relative imports
+ # (``.provider``, ``._base``, …) resolve.
+ import importlib.util as _ilu
+ import os as _os
+ import sys as _sys
+
+ _impl_dir = _os.path.join(
+ _os.path.dirname(_os.path.abspath(__file__)), "plugins", "hermes"
+ )
+ _pkg = "_osb_hermes_impl"
+ _mod = _sys.modules.get(_pkg)
+ if _mod is None:
+ _spec = _ilu.spec_from_file_location(
+ _pkg,
+ _os.path.join(_impl_dir, "__init__.py"),
+ submodule_search_locations=[_impl_dir],
+ )
+ _mod = _ilu.module_from_spec(_spec)
+ _sys.modules[_pkg] = _mod
+ _spec.loader.exec_module(_mod)
+ OpenSecondBrainMemoryProvider = _mod.OpenSecondBrainMemoryProvider
+ check_health = _mod.check_health
+ health = _mod.health
+ register = _mod.register
-__all__ = ["check_health", "health", "register"]
+__all__ = ["OpenSecondBrainMemoryProvider", "check_health", "health", "register"]
diff --git a/docs/brainstorm/hermes-memory-provider/cli-output/claude.md b/docs/brainstorm/hermes-memory-provider/cli-output/claude.md
new file mode 100644
index 00000000..11ec2e79
--- /dev/null
+++ b/docs/brainstorm/hermes-memory-provider/cli-output/claude.md
@@ -0,0 +1,38 @@
+### Variant 1: Embedded MCP client behind the provider
+- **Approach**: The Python `MemoryProvider` spawns a single long-lived `o2b mcp --vault <hermes_home>/Brain` stdio process during `initialize()` and holds an in-process JSON-RPC client to it. `get_tool_schemas()` returns the server's `tools/list`, `handle_tool_call()` forwards to `tools/call`, and every lifecycle hook (`prefetch`, `on_pre_compress`, `on_session_end`) is just another `tools/call` over the same channel. The `mcp_server` block 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_turn` still 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 `o2b` subcommand (or a single-shot JSON-RPC invocation) and parses stdout. `get_tool_schemas()` returns a schema set generated once and cached, and `sync_turn` appends 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 `o2b` subcommands beyond `o2b mcp`.
+- **Complexity**: small
+- **Risk**: low
+
+### Variant 3: Hybrid β€” Python-native light hooks + bridged tool surface
+- **Approach**: Cheap, non-deterministic-free hooks (`sync_turn`, `on_memory_write`, `system_prompt_block` reading `Brain/active.md`) are implemented directly in Python with stdlib file I/O scoped under `hermes_home`, while everything requiring deterministic logic (`get_tool_schemas`/`handle_tool_call`, `prefetch`, `on_pre_compress`) goes through a mockable `BrainBridge` abstraction 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 `BrainBridge` seam 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.
+- **Complexity**: large
+- **Risk**: medium
+
+### Recommended: Variant 1
+**Rationale**: It satisfies the core 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.
diff --git a/docs/brainstorm/hermes-memory-provider/cli-output/prompt.md b/docs/brainstorm/hermes-memory-provider/cli-output/prompt.md
new file mode 100644
index 00000000..890ab6c7
--- /dev/null
+++ b/docs/brainstorm/hermes-memory-provider/cli-output/prompt.md
@@ -0,0 +1,87 @@
+You are brainstorming architectural variants for the following task. Do not write code. Do not write a final design. Only produce variants and a recommendation.
+
+# Task
+
+Become a native Hermes memory provider (consolidate Hermes integration).
+
+Goal: Implement Open Second Brain as a first-class Hermes `MemoryProvider` (the canonical, supported integration) and consolidate the current Hermes wiring so there is ONE mechanism for one goal instead of two.
+
+Ref: https://hermes-agent.nousresearch.com/docs/developer-guide/memory-provider-plugin
+
+Hermes contract (MemoryProvider ABC in `agent/memory_provider.py`):
+- Required: `name` (property), `is_available()` (no network), `initialize(session_id, **kwargs)` (kwargs always includes `hermes_home`), `get_tool_schemas()`, `handle_tool_call(tool_name, args, **kwargs)`, `get_config_schema()`, `save_config(values, hermes_home)`.
+- Optional lifecycle hooks: `system_prompt_block()`, `prefetch(query, *, session_id)`, `queue_prefetch(query)`, `sync_turn(user, assistant, *, session_id, messages)` (MUST be non-blocking), `on_session_end(messages)`, `on_pre_compress(messages)`, `on_memory_write(action, target, content)`, `shutdown()`.
+- Registration: `register(ctx)` -> `ctx.register_memory_provider(...)`. Plugin layout `plugins/memory/<provider>/` with `__init__.py`, `plugin.yaml` (lists implemented hooks), optional `cli.py` (`register_cli(subparser)`).
+- Built-in Hermes memory is MEMORY.md/USER.md; Hermes mirrors writes to the active provider via `on_memory_write`. Only ONE external provider can be active at a time (`memory.provider` in `~/.hermes/config.yaml`).
+- All storage paths must be scoped under `hermes_home` from `initialize()`. `sync_turn` must use a daemon thread so it never blocks the turn.
+
+Current state in this repo (what to consolidate / replace, Hermes only):
+1. `plugins/hermes/__init__.py` β€” a Python shim that provides ONLY a `pre_llm_call` hook (per-turn identity reminder, reads `agent_name` from `~/.config/open-second-brain/config.yaml`, fills `templates/identity-reminder.hermes.txt`) plus a `health()`/`check_health()` data-only readiness check and a best-effort `register(ctx)`.
+2. The `o2b mcp` stdio server registered via `plugin.yaml` `mcp_server` block / `~/.hermes/config.yaml` `mcp_servers` β€” the actual brain_* tool surface.
+Neither is the native MemoryProvider. We want to replace both with one native provider.
+
+Hermes memory hooks the provider should map to existing Open Second Brain capabilities:
+- get_tool_schemas / handle_tool_call -> the brain_* tools (brain_feedback, brain_apply_evidence, brain_note, brain_query, brain_search, brain_recall_gate, brain_context_pack, brain_pre_compact_extract, etc.)
+- prefetch(query) -> brain_recall_gate + brain_query/brain_context_pack
+- system_prompt_block() -> Brain/active.md
+- on_pre_compress -> brain_pre_compress_pack / brain_pre_compact_extract
+- on_session_end -> session flush / dream candidate
+- on_memory_write -> mirror Hermes MEMORY.md/USER.md into Brain/
+- sync_turn -> append raw turn to a session transcript for the deterministic `dream` pass (no LLM extraction in the loop, per project philosophy)
+
+# Project context
+
+Project: Open Second Brain. An Obsidian-compatible Markdown "second brain" / memory layer for AI agents. Core runtime is TypeScript on Bun (CLI `o2b`, MCP stdio server, OpenClaw plugin). A thin Python package (`plugins/hermes/`, root `__init__.py`, `pyproject.toml`) exists ONLY as the Hermes in-process shim. Memory learning is deterministic: a `dream` pass turns repeat signals into rules β€” NO LLM inside the algorithm.
+
+Recent commits:
+6fbab0b feat: hands-off post-upgrade migration (v0.31.2) (#61)
+496dd2d fix: make plugin updates self-healing (v0.31.1) (#60)
+09c0592 chore(release): v0.31.0 (#59)
+b81335c Feat/procedural attention suite (#58)
+1f3a218 Feat/self learning skill proposals (#57)
+0162d13 feat(brain): add context continuity and receipts suite (#56)
+3b7b3a5 feat(brain): add safety governance foundations (#55)
+794ee45 feat(search): ship recall control and trust surfaces (#54)
+
+Related files:
+- plugins/hermes/__init__.py (current shim)
+- plugins/hermes/plugin.yaml, plugin.yaml (root) β€” Hermes manifests with mcp_server block + provides_hooks: [pre_llm_call]
+- src/mcp/server.ts, src/mcp/stdio.ts, src/mcp/index.ts, src/mcp/tools.ts β€” JSON-RPC 2.0 stdio MCP server (protocol 2025-06-18; lifecycle initialize / notifications/initialized / tools/list / tools/call; scope `full` | `writer`)
+- scripts/o2b β€” bash entry: `exec bun run src/cli/main.ts "$@"`; `o2b mcp --vault <path> [--scope writer]`
+- templates/identity-reminder.hermes.txt β€” per-turn reminder template
+- install/hermes.md β€” current install doc (manual mcp_servers edit)
+- pyproject.toml, __init__.py β€” Python packaging for the Hermes shim
+- tests/ β€” Bun test suite
+
+Conventions:
+- TypeScript core on Bun; Python only for the Hermes in-process plugin (no runtime Python deps today; `dependencies = []`).
+- The MCP server is the existing, battle-tested tool surface. Deterministic logic (dream, recall, search) lives in TypeScript and must NOT be reimplemented in Python.
+- Plain Markdown vault under `Brain/`; agent identity resolved from `~/.config/open-second-brain/config.yaml` (`agent_name`) or `VAULT_AGENT_NAME`.
+- Public artifacts use the full name "Open Second Brain" (no abbreviation), no exclamation marks in docs, no AI-authorship markers.
+- `register(ctx)` must be defensive: unknown ctx shapes are ignored without raising so minimal/test contexts do not break plugin loading.
+
+Constraints:
+- Provider MUST be Python (Hermes loads it in-process).
+- Do NOT break Claude Code or Codex integrations β€” those use `.mcp.json` / `.claude-plugin` / `.codex-plugin` + hooks and have NO formal memory-provider interface; their files must stay untouched. Shared assets (`scripts/o2b`, `templates/`) are reused, not changed destructively.
+- Do NOT reimplement the deterministic dream/recall/search logic in Python.
+- Avoid adding heavy external Python dependencies; prefer stdlib (the project ships `dependencies = []`).
+- `sync_turn` must be non-blocking (daemon thread).
+- All provider storage must be scoped under `hermes_home`.
+- Must remain testable without a live Bun runtime in CI (the bridge to the TS core must be mockable).
+
+# Required output format
+
+Produce exactly 3 distinct architectural variants. For each variant:
+
+### Variant N: <short name>
+- **Approach**: 2-3 sentences describing the variant.
+- **Trade-offs**: bullet list of pros and cons.
+- **Complexity**: small | medium | large
+- **Risk**: low | medium | high
+
+After the three variants, add exactly one recommendation:
+
+### Recommended: Variant N
+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.
+
+Output nothing outside of these sections.
diff --git a/docs/brainstorm/hermes-memory-provider/design.md b/docs/brainstorm/hermes-memory-provider/design.md
new file mode 100644
index 00000000..d2ddf480
--- /dev/null
+++ b/docs/brainstorm/hermes-memory-provider/design.md
@@ -0,0 +1,67 @@
+# Native Hermes memory provider - consolidate Hermes integration
+
+**Status:** draft
+**Author:** feature-release-playbook
+**Audience:** implementation
+
+## Problem statement
+
+Open Second Brain integrates with Hermes today through two overlapping mechanisms: a Python `pre_llm_call` shim (`plugins/hermes/__init__.py`) that injects a per-turn identity reminder, and the `o2b mcp` stdio server registered as a Hermes `mcp_server`. Neither is the native `MemoryProvider` interface Hermes exposes for memory layers. The result is two registrations for one goal and no access to Hermes memory lifecycle hooks (prefetch, pre-compress, memory mirroring). This task makes Open Second Brain a first-class Hermes memory provider and collapses the two mechanisms into one.
+
+## Scope
+
+- A native Hermes memory provider implemented in the existing `plugins/hermes` Python package, subclassing the `MemoryProvider` ABC.
+- Required surface: `name`, `is_available()`, `initialize()`, `get_tool_schemas()`, `handle_tool_call()`, `get_config_schema()`, `save_config()`.
+- Lifecycle hooks: `system_prompt_block()`, `prefetch()` (absorbs the retired per-turn identity reminder), `queue_prefetch()`, `sync_turn()` (non-blocking), `on_pre_compress()`, `on_session_end()`, `on_memory_write()`, `shutdown()`.
+- A `BrainBridge` abstraction whose default backend spawns one long-lived `o2b mcp` process and speaks MCP JSON-RPC (initialize / tools/list / tools/call) over stdio. The bridge is the only seam that touches the TypeScript core.
+- `register(ctx)` calls `ctx.register_memory_provider(...)` and keeps the existing health check; the `pre_llm_call` hook registration is retired.
+- `plugin.yaml` (root + `plugins/hermes`): drop the `mcp_server` block and the `pre_llm_call` hook; declare the implemented memory hooks.
+- Optional `cli.py` exposing `hermes open-second-brain status|config`.
+- Migrate the Python test suite from the shim contract to the provider + bridge contract, keeping the identity-reminder template parity tests.
+- Update `install/hermes.md`, `README.md`, `CHANGELOG.md`, and the CI `py_compile` step.
+
+## Out of scope
+
+- Any change to Claude Code or Codex integration. Those runtimes have no formal memory-provider interface; their canonical path (`.mcp.json`, `.claude-plugin`, `.codex-plugin`, `hooks/hooks.json`) is already correct and stays untouched. Shared assets (`scripts/o2b`, `templates/`) are reused, not modified destructively.
+- Reimplementing any deterministic logic (dream, recall, search, extraction) in Python. All of it stays in the TypeScript core, reached through the bridge.
+- The optional Codex `~/.codex/memories` mirroring enhancement (separate future task).
+
+## Chosen approach
+
+Variant 1 - Embedded MCP client behind the provider. The provider owns a single long-lived `o2b mcp --vault <vault>` subprocess started in `initialize()`. `get_tool_schemas()` returns a memory-relevant subset of the server's `tools/list`; `handle_tool_call()` forwards to `tools/call`; and the deterministic lifecycle hooks (`prefetch`, `on_pre_compress`, `on_session_end`, `system_prompt_block`) are each a `tools/call` over the same channel. The Hermes `mcp_server` registration goes away because the server becomes an internal implementation detail of the one provider, satisfying the consolidation goal. The JSON-RPC transport sits behind a `BrainBridge` Protocol so tests inject a fake and never need a live Bun runtime.
+
+## Design decisions
+
+- **Bridge as an abstraction (Dependency Inversion).** The provider depends on a `BrainBridge` Protocol, not on subprocess details. Default `McpBrainBridge` spawns `o2b mcp`; tests pass a `FakeBrainBridge`. This keeps the provider unit-testable without Bun and isolates subprocess lifecycle handling in one class.
+- **Soft import of the ABC.** `agent.memory_provider.MemoryProvider` is only importable inside a Hermes install. A `_base.py` module imports it when present and otherwise defines a minimal local fallback base, so the package imports and tests run in this repo's CI. This mirrors the existing defensive `register(ctx)` pattern.
+- **Identity reminder moves into `prefetch`.** The retired `pre_llm_call` returned `{"context": reminder}` every turn. `prefetch()` is the provider-native per-turn injection point; it returns the recall context (when `brain_recall_gate` says retrieve) with the identity reminder appended. The reminder template loading is reused verbatim from the current shim (no text drift, parity tests preserved).
+- **`sync_turn` stays cheap; extraction happens at boundaries.** There is no dedicated "ingest one raw turn" MCP tool, and per-turn deterministic extraction would be wasteful. `sync_turn` (daemon thread, non-blocking) buffers the turn in memory; `on_pre_compress` and `on_session_end` flush the buffer through `brain_pre_compact_extract` (deterministic, no LLM). This honors the project's "no LLM inside the algorithm" rule and the non-blocking contract.
+- **Curated tool subset.** `get_tool_schemas()` filters `tools/list` to a single explicit allowlist of memory-relevant tools (writer set plus recall/query/context tools). Schemas come from the real server (no schema drift); only the name allowlist is maintained locally. This respects the documented MCP token-economy concern without exposing all 60+ tools.
+- **Vault vs `hermes_home` are distinct paths.** The Open Second Brain vault (an Obsidian vault whose `Brain/` subtree the server reads and writes) is resolved from Open Second Brain config (`~/.config/open-second-brain/config.yaml` or the `vault` field of `save_config`) and passed to `o2b mcp --vault <vault>`. `hermes_home` from `initialize()` scopes only provider-local state - the `sync_turn` transcript buffer and any cache - never the vault, and never a hardcoded path, per the profile-isolation requirement.
+- **Fail-soft everywhere the agent turn depends on us.** `prefetch`, `system_prompt_block`, `sync_turn`, and `on_memory_write` never raise into the turn loop; a bridge error degrades to empty context, matching the current shim's "never leak, never block" behavior.
+- **Single Hermes plugin package.** Rather than create a parallel hyphenated `plugins/memory/open-second-brain/` directory (not a valid Python import path), evolve the existing `plugins/hermes` package. The repo already loads its `register` via the root `__init__.py`, and the existing tests already import `plugins.hermes` - keeping one package is the DRY/KISS choice.
+
+## File changes
+
+New files:
+- `plugins/hermes/_base.py` - soft MemoryProvider import + fallback base.
+- `plugins/hermes/config.py` - agent-name / config-path / reminder-template helpers (extracted from `__init__.py`, shared).
+- `plugins/hermes/bridge.py` - `BrainBridge` Protocol, `McpBrainBridge` (subprocess JSON-RPC), `FakeBrainBridge` (tests).
+- `plugins/hermes/provider.py` - `OpenSecondBrainMemoryProvider(MemoryProvider)`.
+- `plugins/hermes/cli.py` - `register_cli(subparser)` for `status` / `config`.
+- `tests/python/test_memory_provider.py` - provider + bridge unit tests with the fake bridge.
+
+Modified files:
+- `plugins/hermes/__init__.py` - `register(ctx)` registers the provider + health check; retire `pre_llm_call`; re-export provider/bridge.
+- `plugins/hermes/plugin.yaml`, `plugin.yaml` (root) - drop `mcp_server`, declare memory hooks.
+- `tests/python/test_hermes_plugin.py` - retarget to the new contract; keep template parity tests.
+- `install/hermes.md` - rewrite around `memory.provider: open-second-brain`.
+- `README.md`, `CHANGELOG.md` - document the native provider.
+- `.github/workflows/ci.yml`, `.github/workflows/release.yml` - compile the whole `plugins/hermes` package, not just `__init__.py`.
+
+## Risks and open questions
+
+- **MemoryProvider ABC signature drift.** The exact method signatures come from the published Hermes docs. The fallback base and provider must match the real ABC; if Hermes changes the contract the fallback hides it. Mitigation: keep the fallback minimal and rely on `**kwargs` for forward compatibility on lifecycle hooks.
+- **`hermes memory setup` config keys.** `get_config_schema()` field names (`vault`, `agent_name`, `timezone`) drive the setup wizard. They reuse the existing `~/.config/open-second-brain/config.yaml` keys; verify against a real wizard run during QA where possible.
+- **Subprocess startup cost.** The first `prefetch` after `initialize` pays Bun startup. Mitigation: spawn in `initialize()` (not lazily) and warm `tools/list` once.
+- **Single-provider rule.** Enabling Open Second Brain as `memory.provider` excludes other external providers by Hermes design. This is expected and documented for the operator.
diff --git a/docs/brainstorm/hermes-memory-provider/plan.md b/docs/brainstorm/hermes-memory-provider/plan.md
new file mode 100644
index 00000000..9cc6cb35
--- /dev/null
+++ b/docs/brainstorm/hermes-memory-provider/plan.md
@@ -0,0 +1,62 @@
+# 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.py` imports `agent.memory_provider.MemoryProvider` when available, else defines a minimal fallback base (lifecycle methods as no-ops accepting `**kwargs`). `config.py` holds `config_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()` honors `VAULT_AGENT_NAME` / config file / `"agent"` fallback, and `render_reminder` substitutes 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**: `BrainBridge` Protocol with `start()`, `list_tools()`, `call_tool(name, args)`, `stop()`. `McpBrainBridge` spawns `o2b mcp --vault <vault>` and implements the JSON-RPC handshake (initialize -> notifications/initialized -> tools/list) with timeouts and a single restart-on-crash. `FakeBrainBridge` returns canned tool lists/results for tests.
+- **Acceptance**: tests drive `FakeBrainBridge` through list/call; `McpBrainBridge` JSON-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**: `OpenSecondBrainMemoryProvider` constructor takes an optional `bridge` (default `McpBrainBridge`). Implement `name`, `is_available()` (config/vault present, no network), `initialize(session_id, **kwargs)` (capture `hermes_home`, resolve the vault from Open Second Brain config, start bridge), `get_tool_schemas()` (filter `list_tools()` by the memory allowlist constant), `handle_tool_call(name, args, **kwargs)` (forward to `call_tool`), `get_config_schema()` (fields `vault`, `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_config` writes `vault`/`agent_name` to the Open Second Brain config path (provider-local state, not the vault, is what lives under `hermes_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_gate` then `brain_context_pack`, append identity reminder. `queue_prefetch()` (cache last query). `sync_turn(...)` -> daemon thread, buffer turn under `hermes_home`. `on_pre_compress(messages)` / `on_session_end(messages)` -> flush buffer through `brain_pre_compact_extract`. `on_memory_write(action, target, content)` -> mirror to Brain via `brain_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 via `register_memory_provider` (best-effort across ctx shapes), keeps the health check, drops the `pre_llm_call` hook registration. Re-export provider/bridge/health. Retarget the shim tests: drop `pre_llm_call` assertions, add `register_memory_provider` assertions, keep template parity + health tests.
+- **Acceptance**: `register` attaches the provider on a ctx exposing `register_memory_provider`; health check still attaches; no `pre_llm_call` registration.
+- **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_server` block, replace `provides_hooks: [pre_llm_call]` with the implemented memory-hook list, bump description to "native memory provider".
+- **Acceptance**: YAML parses; `hooks` list matches the implemented hooks; no `mcp_server` key.
+- **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)` building `status` (provider availability + bridge ping) and `config` (effective config) subcommands; dispatch handler.
+- **Acceptance**: test invokes the argparse tree and asserts `status`/`config` dispatch.
+- **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__.py` step to `compileall plugins/hermes` so new submodules are compiled. Confirm setuptools still packages `plugins.hermes` (submodules auto-included).
+- **Acceptance**: workflow YAML parses; `python -m compileall plugins/hermes` is green locally.
+- **Depends on**: Task 5
+
+### Task 9: Docs (install, README, CHANGELOG)
+- **Files**: `install/hermes.md`, `README.md`, `CHANGELOG.md`
+- **Detail**: rewrite `install/hermes.md` around `memory.provider: open-second-brain` / `hermes memory setup` instead of the manual `mcp_servers` edit; 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_servers` manual-edit instruction remains for Hermes; no abbreviations, no AI-authorship markers, no exclamation marks.
+- **Depends on**: Task 6
diff --git a/docs/brainstorm/hermes-memory-provider/variants.md b/docs/brainstorm/hermes-memory-provider/variants.md
new file mode 100644
index 00000000..42b7d3fc
--- /dev/null
+++ b/docs/brainstorm/hermes-memory-provider/variants.md
@@ -0,0 +1,55 @@
+# 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 `MemoryProvider` spawns a single long-lived `o2b mcp --vault <hermes_home>/Brain` stdio process during `initialize()` and holds an in-process JSON-RPC client to it. `get_tool_schemas()` returns the server's `tools/list`, `handle_tool_call()` forwards to `tools/call`, and every lifecycle hook (`prefetch`, `on_pre_compress`, `on_session_end`) is just another `tools/call` over the same channel. The `mcp_server` block 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_turn` still 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 `o2b` subcommand (or a single-shot JSON-RPC invocation) and parses stdout. `get_tool_schemas()` returns a schema set generated once and cached, and `sync_turn` appends 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 `o2b` subcommands beyond `o2b mcp`.
+- **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_block` reading `Brain/active.md`) are implemented directly in Python with stdlib file I/O scoped under `hermes_home`, while everything requiring deterministic logic (`get_tool_schemas`/`handle_tool_call`, `prefetch`, `on_pre_compress`) goes through a mockable `BrainBridge` abstraction 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 `BrainBridge` seam 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.
+- **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:
+
+1. **Borrow Variant 3's cheap `sync_turn`.** There is no "ingest one raw turn" MCP tool, and per-turn deterministic extraction is wasteful. `sync_turn` buffers the turn (daemon thread, stdlib, scoped under `hermes_home`) and the deterministic `brain_pre_compact_extract` runs only at `on_pre_compress` / `on_session_end` boundaries. This keeps the hot path off Bun (Variant 3's latency win) without duplicating any vault format (the extraction itself stays in TS).
+
+2. **Borrow Variant 3's `BrainBridge` seam, keep Variant 1's persistent backend.** The transport lives behind a `BrainBridge` Protocol 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.
diff --git a/install/hermes.md b/install/hermes.md
index f59e502c..ea205910 100644
--- a/install/hermes.md
+++ b/install/hermes.md
@@ -1,8 +1,15 @@
# Hermes
-Hermes installs OSB through its native plugin / MCP machinery,
-not through `o2b install --target hermes`. The flow below assumes
-a working Hermes Agent with `hermes` on PATH.
+Hermes installs Open Second Brain through its native plugin and
+memory-provider machinery, not through `o2b install --target hermes`.
+The flow below assumes a working Hermes Agent with `hermes` on PATH.
+
+Open Second Brain registers as a native Hermes **memory provider**:
+one mechanism that injects `Brain/active.md` into the system prompt,
+recalls context before each turn, captures turns for the deterministic
+`dream` pass, mirrors Hermes built-in memory writes into `Brain/`, and
+exposes the `brain_*` tools - all over a single internal `o2b mcp`
+bridge. There is no separate `mcp_servers` entry to maintain.
## 1. Install the plugin
@@ -12,9 +19,8 @@ hermes gateway restart
```
Or paste `https://github.com/itechmeat/open-second-brain` into the
-Hermes Dashboard β†’ Plugins β†’ Install from GitHub URL. Do not pin
-a tag β€” the CLI resolves to the latest released version on its
-own.
+Hermes Dashboard -> Plugins -> Install from GitHub URL. Do not pin
+a tag - the CLI resolves to the latest released version on its own.
## 2. Publish the `o2b` CLI on PATH
@@ -38,18 +44,19 @@ o2b brain init --vault /path/to/vault \
dream-running host. Multi-device setups (Syncthing) benefit from
a single dream-runner.
-## 4. Register the MCP server
+## 4. Enable the memory provider
+
+Run the setup wizard and choose `open-second-brain`:
-Edit `~/.hermes/config.yaml`:
+```bash
+hermes memory setup
+```
+
+Or set it directly in `~/.hermes/config.yaml`:
```yaml
-mcp_servers:
- open-second-brain:
- command: o2b
- args: [mcp, --vault, /path/to/vault]
- env:
- VAULT_AGENT_NAME: <chosen-agent-name>
- enabled: true
+memory:
+ provider: open-second-brain
```
Then restart the gateway:
@@ -58,13 +65,41 @@ Then restart the gateway:
hermes gateway restart
```
+Only one external memory provider can be active at a time; selecting
+`open-second-brain` makes it the active provider. The provider reads
+the vault, agent name, and timezone from the Open Second Brain config
+written in step 3 (`~/.config/open-second-brain/config.yaml`), so no
+vault path is duplicated in the Hermes config.
+
+### Activation lifecycle
+
+Hermes activates memory providers through the `memory.provider` config
+key, not at install time β€” `hermes plugins install` only makes the
+provider *available*. This is by design (exactly one provider is active
+at a time), so activation is one explicit command:
+
+| Action | What happens | What you run |
+|---|---|---|
+| First install | Not auto β€” install only makes it available | `hermes memory setup open-second-brain` |
+| Plugin update | **Automatic** β€” `memory.provider` persists in `config.yaml` | nothing |
+| Deactivate / uninstall | Not auto | `hermes memory off` (reverts to built-in) |
+
## 5. Verify
```bash
o2b doctor --vault /path/to/vault --repo .
+hermes memory status
```
-Run the daily-identity check described in `install/prerequisites.md`.
+`hermes memory status` shows `Provider: open-second-brain` with
+`available βœ“` once active. Run the daily-identity check described in
+`install/prerequisites.md`.
+
+> The dedicated `hermes open-second-brain status/config` subcommand is
+> not yet available: Hermes' loader cannot import an external provider's
+> `cli.py` (the same parent-namespace limitation noted in the root
+> `__init__.py`). It lights up automatically once that upstream fix
+> ships. Until then, use `hermes memory status` and `o2b doctor`.
## Update
@@ -74,13 +109,20 @@ hermes gateway restart
o2b doctor --vault /path/to/vault --repo .
```
+`memory.provider` persists across updates, so the provider stays active
+with no re-activation step.
+
## Uninstall
+Deactivate first (reverts to built-in memory), then remove:
+
```bash
-hermes mcp remove open-second-brain
-o2b uninstall --apply-local --remove-cli
+hermes memory off
hermes plugins remove open-second-brain
+o2b uninstall --apply-local --remove-cli
hermes gateway restart
```
-The vault and its Markdown files are never deleted.
+`hermes memory off` is the native way to switch back to built-in memory
+(or use `hermes memory setup` to pick a different provider). The vault
+and its Markdown files are never deleted.
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index 73251c6a..13423404 100644
--- a/openclaw.plugin.json
+++ b/openclaw.plugin.json
@@ -2,7 +2,7 @@
"id": "open-second-brain",
"name": "Open Second Brain",
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",
- "version": "0.31.2",
+ "version": "0.32.0",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index 70e94d4e..d7610345 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.31.2",
+ "version": "0.32.0",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
"keywords": [
diff --git a/plugin.yaml b/plugin.yaml
index 326d209b..419f3cf6 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,12 +1,13 @@
name: open-second-brain
-version: "0.31.2"
-description: "Hermes plugin entrypoint for OpenSecondBrain vault health checks and the optional MCP tool server."
-author: "OpenSecondBrain contributors"
-kind: standalone
-provides_hooks:
- - pre_llm_call
-mcp_server:
- command: scripts/o2b
- args: ["mcp"]
- description: "Optional stdio MCP server. Add to ~/.hermes/config.yaml mcp_servers if MCP tool routing is desired."
- protocol_version: "2025-06-18"
+version: "0.32.0"
+description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
+author: "Open Second Brain contributors"
+memory_provider: true
+hooks:
+ - system_prompt_block
+ - prefetch
+ - sync_turn
+ - on_pre_compress
+ - on_session_end
+ - on_memory_write
+ - shutdown
diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json
index 290215d4..b18bad5a 100644
--- a/plugins/codex/.codex-plugin/plugin.json
+++ b/plugins/codex/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.31.2",
+ "version": "0.32.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"author": {
"name": "Open Second Brain contributors",
diff --git a/plugins/hermes/__init__.py b/plugins/hermes/__init__.py
index 8c70c45a..7eb9cacf 100644
--- a/plugins/hermes/__init__.py
+++ b/plugins/hermes/__init__.py
@@ -1,134 +1,39 @@
-"""Hermes Python shim for Open Second Brain.
-
-Most of Open Second Brain runs as a Bun-based MCP server on stdio (registered
-via ``hermes mcp_servers`` in ``~/.hermes/config.yaml``). MCP carries every
-agent-facing tool surface (``second_brain_status``, ``second_brain_query``,
-``vault_health``, plus the Brain writer surface: ``brain_feedback``,
-``brain_apply_evidence``, ``brain_note``); Β§32 (v0.10.8) retires the legacy
-``event_log_append`` tool from every runtime, including this one.
-
-This file exists for one Hermes-specific feature that MCP cannot replicate:
-the per-turn ``pre_llm_call`` hook, which appends a short identity reminder
-to the user message of every turn. Doing it server-side (in MCP
-``initialize.instructions``) only fires once per session, not per turn β€” long
-sessions drift away from the reminder.
-
-The shim has no dependency on the TypeScript core. It reads ``agent_name``
-from the same plugin config the TS code writes (``~/.config/open-second-brain/config.yaml``).
+"""Hermes plugin package for Open Second Brain.
+
+Open Second Brain integrates with Hermes as a native memory provider. Hermes
+loads this package in-process and calls ``register``, which wires two things
+into the gateway:
+
+- the ``OpenSecondBrainMemoryProvider`` (``provider.py``), a first-class Hermes
+ memory provider backed by an ``o2b mcp`` bridge (``bridge.py``); and
+- a small data-only health check.
+
+The provider's ``prefetch`` carries the per-turn identity reminder that the
+retired ``pre_llm_call`` hook used to inject, so there is one mechanism, not
+two. Shared config and reminder helpers live in ``config.py``.
"""
from __future__ import annotations
import os
-import re
from pathlib import Path
from typing import Any
-PLUGIN_NAME = "open-second-brain"
-
-_REPO_ROOT = Path(__file__).resolve().parents[2]
-_TEMPLATES_DIR = _REPO_ROOT / "templates"
-_COMMON_TEMPLATE_PATH = _TEMPLATES_DIR / "identity-reminder.txt"
-# This shim runs inside Hermes, so the target is fixed at the call site
-# rather than threaded through an env var β€” mirrors the TypeScript
-# behaviour where the OpenClaw plugin passes its own target literal.
-_TARGET = "hermes"
-_TARGET_TEMPLATE_PATH = _TEMPLATES_DIR / f"identity-reminder.{_TARGET}.txt"
-
-_AGENT_LINE_RE = re.compile(r"^\s*(agent_name|agentName)\s*:\s*['\"]?([^'\"\n]+?)['\"]?\s*$", re.MULTILINE)
-
-_template_cache: str | None = None
+from . import config
+from .bridge import BrainBridge, FakeBrainBridge, McpBrainBridge
+from .cli import register_cli
+from .provider import OpenSecondBrainMemoryProvider
-
-def _load_reminder_template() -> str:
- """Read the Hermes reminder template, falling back to the common file.
-
- This shim is hermes-only β€” it does not honour ``O2B_TARGET``. The
- TypeScript ``buildReminder`` has a three-step resolver (explicit
- target -> env -> common); the Python equivalent collapses to
- ``hermes`` -> common because Hermes always runs the Hermes target.
- Both languages read the same templates on disk and a fixture-pinned
- test catches text drift.
-
- The body is cached after the first call. Hermes' ``pre_llm_call``
- hook fires every turn; templates are installation-time artifacts
- that do not change at runtime, so a single read per process is
- enough. A gateway restart (every plugin update) flushes the cache.
- """
- global _template_cache
- if _template_cache is not None:
- return _template_cache
- if _TARGET_TEMPLATE_PATH.is_file():
- _template_cache = _TARGET_TEMPLATE_PATH.read_text(encoding="utf-8").rstrip()
- else:
- _template_cache = _COMMON_TEMPLATE_PATH.read_text(encoding="utf-8").rstrip()
- return _template_cache
-
-
-def _reset_template_cache_for_tests() -> None:
- """Test-only: drop the cached body so a fixture rewrite is visible."""
- global _template_cache
- _template_cache = None
-
-
-def _config_path() -> Path:
- override = os.environ.get("OPEN_SECOND_BRAIN_CONFIG")
- if override:
- return Path(override).expanduser()
- xdg = os.environ.get("XDG_CONFIG_HOME")
- if xdg:
- return Path(xdg).expanduser() / "open-second-brain" / "config.yaml"
- return Path.home() / ".config" / "open-second-brain" / "config.yaml"
-
-
-def _resolve_agent_name() -> str:
- """Resolve the agent identity used by ``pre_llm_call``.
-
- Order: ``VAULT_AGENT_NAME`` env, ``agent_name``/``agentName`` in plugin
- config, then the literal placeholder ``"agent"``. Mirrors
- ``resolveAgentName`` in ``src/core/config.ts``.
- """
- env_value = os.environ.get("VAULT_AGENT_NAME")
- if env_value:
- return env_value
- path = _config_path()
- if not path.is_file():
- return "agent"
- try:
- text = path.read_text(encoding="utf-8")
- except OSError:
- return "agent"
- match = _AGENT_LINE_RE.search(text)
- if match:
- value = match.group(2).strip()
- if value:
- return value
- return "agent"
-
-
-def on_pre_llm_call(**_kwargs: Any) -> dict[str, str] | None:
- """Inject identity context into the current turn's user message.
-
- Hermes ``pre_llm_call`` contract: callbacks receive turn metadata and may
- return ``{"context": "..."}`` β€” Hermes appends the value to the user
- message of this turn (system prompt left untouched, so the cache prefix
- is preserved). Returns ``None`` when no identity is configured, to avoid
- leaking the literal ``@agent`` placeholder into Daily.
- """
- agent = _resolve_agent_name()
- if agent == "agent":
- return None
- template = _load_reminder_template()
- return {"context": template.replace("{agent}", agent)}
+PLUGIN_NAME = config.PLUGIN_NAME
def health(repo_root: str | Path | None = None) -> dict[str, Any]:
"""Minimal data-only readiness check.
- Verifies the artifacts Hermes itself depends on (the runner script and
- the OpenClaw bundle that the same repo produces). The TypeScript ``o2b
- doctor`` covers everything else; runtimes that want the full suite
- should call it via the MCP ``vault_health`` tool.
+ Verifies the artifacts Hermes itself depends on (the runner script and the
+ OpenClaw bundle that the same repo produces). The TypeScript ``o2b doctor``
+ covers everything else; runtimes that want the full suite call it via the
+ MCP ``vault_health`` tool.
"""
root = Path(repo_root) if repo_root is not None else Path(__file__).resolve().parents[2]
checks = {
@@ -154,12 +59,7 @@ def _check_file(path: Path, *, executable: bool = False) -> dict[str, Any]:
return {"ok": ok, "path": str(path), "message": message}
-def register(ctx: Any) -> None:
- """Best-effort registration of the health check and the pre_llm_call hook.
-
- Unsupported context shapes are ignored without raising so a minimal /
- test ``ctx`` won't break plugin loading.
- """
+def _register_health_check(ctx: Any) -> None:
for method_name in ("register_health_check", "add_health_check", "register_check"):
method = getattr(ctx, method_name, None)
if callable(method):
@@ -167,17 +67,41 @@ def register(ctx: Any) -> None:
method(PLUGIN_NAME, check_health)
except TypeError:
method(check_health)
- break
- else:
- health_checks = getattr(ctx, "health_checks", None)
- if isinstance(health_checks, dict):
- health_checks[PLUGIN_NAME] = check_health
- elif isinstance(health_checks, list):
- health_checks.append((PLUGIN_NAME, check_health))
-
- register_hook = getattr(ctx, "register_hook", None)
- if callable(register_hook):
+ return
+ health_checks = getattr(ctx, "health_checks", None)
+ if isinstance(health_checks, dict):
+ health_checks[PLUGIN_NAME] = check_health
+ elif isinstance(health_checks, list):
+ health_checks.append((PLUGIN_NAME, check_health))
+
+
+def _register_memory_provider(ctx: Any) -> None:
+ method = getattr(ctx, "register_memory_provider", None)
+ if callable(method):
try:
- register_hook("pre_llm_call", on_pre_llm_call)
- except Exception:
+ method(OpenSecondBrainMemoryProvider())
+ except Exception: # noqa: BLE001 - never break plugin loading
pass
+
+
+def register(ctx: Any) -> None:
+ """Register the memory provider and health check.
+
+ Unsupported context shapes are ignored without raising so a minimal / test
+ ``ctx`` won't break plugin loading.
+ """
+ _register_health_check(ctx)
+ _register_memory_provider(ctx)
+
+
+__all__ = [
+ "PLUGIN_NAME",
+ "health",
+ "check_health",
+ "register",
+ "register_cli",
+ "OpenSecondBrainMemoryProvider",
+ "BrainBridge",
+ "McpBrainBridge",
+ "FakeBrainBridge",
+]
diff --git a/plugins/hermes/_base.py b/plugins/hermes/_base.py
new file mode 100644
index 00000000..a86b32e7
--- /dev/null
+++ b/plugins/hermes/_base.py
@@ -0,0 +1,68 @@
+"""Soft import of the Hermes ``MemoryProvider`` ABC with a local fallback.
+
+``agent.memory_provider.MemoryProvider`` only exists inside a Hermes install.
+This repository's CI (and any non-Hermes runtime) has no such module, so the
+provider must still import and be testable. We import the real ABC when it is
+present and otherwise expose a minimal stand-in base with no-op optional hooks,
+mirroring the defensive pattern the rest of the Hermes shim already uses.
+
+The stand-in deliberately does not enforce the abstract surface: the concrete
+provider overrides every required method, and a faithful no-op base keeps the
+provider importable and unit-testable without Hermes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+try: # pragma: no cover - exercised only inside a Hermes install
+ from agent.memory_provider import MemoryProvider as _HermesMemoryProvider
+
+ MemoryProvider: type = _HermesMemoryProvider
+ HAS_HERMES_ABC = True
+except Exception: # noqa: BLE001 - any import failure means "not in Hermes"
+ HAS_HERMES_ABC = False
+
+ class MemoryProvider: # type: ignore[no-redef]
+ """Minimal fallback base used when the Hermes ABC is unavailable.
+
+ Optional lifecycle hooks default to no-ops so a subclass that does not
+ override one can still be driven by a Hermes-shaped harness without
+ raising. Required methods are intentionally absent here; the concrete
+ provider supplies them.
+ """
+
+ def system_prompt_block(self) -> str:
+ return ""
+
+ def prefetch(self, query: str, *, session_id: str = "", **_kwargs: Any) -> str:
+ return ""
+
+ def queue_prefetch(self, query: str, **_kwargs: Any) -> None:
+ return None
+
+ def sync_turn(
+ self,
+ user: str,
+ assistant: str,
+ *,
+ session_id: str = "",
+ messages: list | None = None,
+ **_kwargs: Any,
+ ) -> None:
+ return None
+
+ def on_session_end(self, messages: list, **_kwargs: Any) -> None:
+ return None
+
+ def on_pre_compress(self, messages: list, **_kwargs: Any) -> None:
+ return None
+
+ def on_memory_write(self, action: str, target: str, content: str, **_kwargs: Any) -> None:
+ return None
+
+ def shutdown(self) -> None:
+ return None
+
+
+__all__ = ["MemoryProvider", "HAS_HERMES_ABC"]
diff --git a/plugins/hermes/bridge.py b/plugins/hermes/bridge.py
new file mode 100644
index 00000000..7a52509f
--- /dev/null
+++ b/plugins/hermes/bridge.py
@@ -0,0 +1,257 @@
+"""Bridge from the Python memory provider to the Open Second Brain TS core.
+
+The provider never reimplements deterministic memory logic; it forwards work
+to the existing ``o2b mcp`` stdio server over MCP JSON-RPC. ``BrainBridge`` is
+the seam: ``McpBrainBridge`` is the production backend that owns a long-lived
+``o2b mcp`` subprocess, and ``FakeBrainBridge`` lets tests exercise the
+provider with no live Bun runtime.
+
+Splitting ``JsonRpcStdioClient`` (pure framing) from ``McpBrainBridge`` (process
+lifecycle) keeps each class single-responsibility and lets the framing be
+unit-tested against in-memory streams.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import Any, Protocol, runtime_checkable
+
+PROTOCOL_VERSION = "2025-06-18"
+CLIENT_NAME = "open-second-brain-hermes-provider"
+
+
+class BridgeError(RuntimeError):
+ """Base error: a JSON-RPC error response or a transport failure."""
+
+
+class BridgeTransportError(BridgeError):
+ """The channel itself failed (EOF, broken pipe). Worth one restart.
+
+ Distinct from a plain ``BridgeError``, which signals a JSON-RPC error
+ response (e.g. invalid tool arguments) - a server-level rejection that a
+ restart would only repeat, so it must propagate unchanged.
+ """
+
+
+@runtime_checkable
+class BrainBridge(Protocol):
+ """Minimal contract the provider depends on (Dependency Inversion)."""
+
+ def start(self) -> None: ...
+
+ def list_tools(self) -> list[dict[str, Any]]: ...
+
+ def call_tool(self, name: str, args: dict[str, Any]) -> dict[str, Any]: ...
+
+ def stop(self) -> None: ...
+
+
+class JsonRpcStdioClient:
+ """Newline-delimited JSON-RPC 2.0 client over a writer/reader pair.
+
+ ``writer`` needs ``write`` (and optionally ``flush``); ``reader`` needs
+ ``readline`` returning ``str`` (``""`` at EOF). Responses are correlated by
+ id; notifications and stale ids are skipped.
+ """
+
+ def __init__(self, writer: Any, reader: Any) -> None:
+ self._writer = writer
+ self._reader = reader
+ self._id = 0
+
+ def notify(self, method: str, params: dict[str, Any] | None = None) -> None:
+ frame: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+ if params is not None:
+ frame["params"] = params
+ self._write(frame)
+
+ def request(self, method: str, params: dict[str, Any] | None = None) -> Any:
+ self._id += 1
+ rid = self._id
+ frame: dict[str, Any] = {"jsonrpc": "2.0", "id": rid, "method": method}
+ if params is not None:
+ frame["params"] = params
+ self._write(frame)
+ return self._read_response(rid)
+
+ def _write(self, frame: dict[str, Any]) -> None:
+ try:
+ self._writer.write(json.dumps(frame) + "\n")
+ flush = getattr(self._writer, "flush", None)
+ if callable(flush):
+ flush()
+ except (BrokenPipeError, ValueError, OSError) as exc:
+ raise BridgeTransportError(f"write failed: {exc}") from exc
+
+ def _read_response(self, rid: int) -> Any:
+ while True:
+ line = self._reader.readline()
+ if line == "":
+ raise BridgeTransportError("unexpected EOF from MCP server")
+ line = line.strip()
+ if not line:
+ continue
+ try:
+ message = json.loads(line)
+ except json.JSONDecodeError:
+ # stdout carries only JSON-RPC frames; ignore stray noise.
+ continue
+ if not isinstance(message, dict) or message.get("id") != rid:
+ continue
+ if "error" in message:
+ raise BridgeError(str(message["error"]))
+ return message.get("result")
+
+
+class McpBrainBridge:
+ """Owns one ``o2b mcp`` subprocess and speaks MCP JSON-RPC to it.
+
+ ``spawn`` is injectable so tests substitute a fake process and never need a
+ live Bun runtime. A crashed channel is restarted once on the next call.
+ """
+
+ def __init__(
+ self,
+ *,
+ vault: str | None,
+ command: tuple[str, ...] = ("o2b", "mcp"),
+ spawn: Any = None,
+ cwd: str | None = None,
+ ) -> None:
+ self._vault = vault
+ self._command = command
+ self._spawn = spawn or self._default_spawn
+ self._cwd = cwd
+ self._proc: Any = None
+ self._client: JsonRpcStdioClient | None = None
+ self._tools: list[dict[str, Any]] = []
+ self._started = False
+
+ def _argv(self) -> list[str]:
+ argv = list(self._command)
+ if self._vault:
+ argv += ["--vault", self._vault]
+ return argv
+
+ def _default_spawn(self, argv: list[str]) -> Any:
+ return subprocess.Popen( # noqa: S603 - argv is a fixed command + config path
+ argv,
+ stdin=subprocess.PIPE,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.DEVNULL,
+ text=True,
+ bufsize=1,
+ cwd=self._cwd,
+ )
+
+ def start(self) -> None:
+ if self._started:
+ return
+ self._proc = self._spawn(self._argv())
+ self._client = JsonRpcStdioClient(self._proc.stdin, self._proc.stdout)
+ try:
+ self._client.request(
+ "initialize",
+ {
+ "protocolVersion": PROTOCOL_VERSION,
+ "capabilities": {},
+ "clientInfo": {"name": CLIENT_NAME, "version": "1"},
+ },
+ )
+ self._client.notify("notifications/initialized")
+ result = self._client.request("tools/list", {})
+ except BaseException:
+ # A failed handshake must not leak the spawned process.
+ self.stop()
+ raise
+ self._tools = list((result or {}).get("tools", []))
+ self._started = True
+
+ def list_tools(self) -> list[dict[str, Any]]:
+ self._ensure_started()
+ return self._tools
+
+ def call_tool(self, name: str, args: dict[str, Any]) -> dict[str, Any]:
+ self._ensure_started()
+ assert self._client is not None
+ try:
+ result = self._client.request("tools/call", {"name": name, "arguments": args})
+ except BridgeTransportError:
+ # The channel died: restart once and retry. A JSON-RPC error
+ # (plain BridgeError, e.g. invalid arguments) is a server-level
+ # rejection and propagates unchanged - restarting would only repeat it.
+ self._restart()
+ assert self._client is not None
+ result = self._client.request("tools/call", {"name": name, "arguments": args})
+ return result or {}
+
+ def stop(self) -> None:
+ proc = self._proc
+ self._started = False
+ self._client = None
+ self._proc = None
+ if proc is None:
+ return
+ try:
+ proc.terminate()
+ proc.wait(timeout=5)
+ except Exception: # noqa: BLE001 - never raise on shutdown
+ kill = getattr(proc, "kill", None)
+ if callable(kill):
+ kill()
+ # Reap the killed child so it cannot linger as a zombie.
+ try:
+ proc.wait(timeout=5)
+ except Exception: # noqa: BLE001
+ pass
+
+ def _ensure_started(self) -> None:
+ if not self._started:
+ self.start()
+
+ def _restart(self) -> None:
+ self.stop()
+ self.start()
+
+
+class FakeBrainBridge:
+ """In-memory ``BrainBridge`` for tests: records calls, returns canned data."""
+
+ def __init__(
+ self,
+ tools: list[dict[str, Any]] | None = None,
+ results: dict[str, Any] | None = None,
+ ) -> None:
+ self._tools = tools or []
+ self._results = results or {}
+ self.calls: list[tuple[str, dict[str, Any]]] = []
+ self.started = False
+ self.stopped = False
+
+ def start(self) -> None:
+ self.started = True
+
+ def list_tools(self) -> list[dict[str, Any]]:
+ return list(self._tools)
+
+ def call_tool(self, name: str, args: dict[str, Any]) -> dict[str, Any]:
+ self.calls.append((name, args))
+ result = self._results.get(name)
+ if callable(result):
+ return result(args)
+ return result if result is not None else {}
+
+ def stop(self) -> None:
+ self.stopped = True
+
+
+__all__ = [
+ "BridgeError",
+ "BridgeTransportError",
+ "BrainBridge",
+ "JsonRpcStdioClient",
+ "McpBrainBridge",
+ "FakeBrainBridge",
+ "PROTOCOL_VERSION",
+]
diff --git a/plugins/hermes/cli.py b/plugins/hermes/cli.py
new file mode 100644
index 00000000..4ad2864c
--- /dev/null
+++ b/plugins/hermes/cli.py
@@ -0,0 +1,49 @@
+"""Optional ``hermes open-second-brain`` CLI subtree.
+
+Hermes discovers ``register_cli`` by convention and only surfaces these
+commands when the provider is active. They are read-only diagnostics over the
+same config and provider the gateway uses - no deterministic logic here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import config
+from .provider import OpenSecondBrainMemoryProvider
+
+
+def register_cli(subparser: Any) -> None:
+ """Build the ``status`` / ``config`` argparse subtree."""
+ subs = subparser.add_subparsers(dest="osb_command")
+ subs.add_parser("status", help="Show the Open Second Brain memory provider status.")
+ subs.add_parser("config", help="Show the effective Open Second Brain configuration.")
+ subparser.set_defaults(func=run)
+
+
+def run(args: Any) -> int:
+ """Dispatch the selected subcommand. Returns a process exit code."""
+ command = getattr(args, "osb_command", None)
+ if command == "status":
+ return _status()
+ if command == "config":
+ return _config()
+ print("usage: hermes open-second-brain {status,config}")
+ return 0
+
+
+def _status() -> int:
+ provider = OpenSecondBrainMemoryProvider()
+ available = provider.is_available()
+ print(f"provider: {provider.name}")
+ print(f"available: {available}")
+ print(f"vault: {config.resolve_vault() or '(unset)'}")
+ return 0 if available else 1
+
+
+def _config() -> int:
+ print(f"config_path: {config.config_path()}")
+ print(f"vault: {config.resolve_vault() or '(unset)'}")
+ print(f"agent_name: {config.resolve_agent_name()}")
+ print(f"timezone: {config.resolve_timezone() or '(unset)'}")
+ return 0
diff --git a/plugins/hermes/config.py b/plugins/hermes/config.py
new file mode 100644
index 00000000..00ea9b16
--- /dev/null
+++ b/plugins/hermes/config.py
@@ -0,0 +1,145 @@
+"""Shared configuration and identity-reminder helpers for the Hermes plugin.
+
+These helpers read the same plugin config the TypeScript core writes
+(``~/.config/open-second-brain/config.yaml``) without a YAML dependency, and
+load the per-turn identity-reminder template. They are the single source of
+truth for both the native memory provider (``provider.py``) and the legacy
+``register``/health surface in ``__init__.py`` so the two never drift.
+
+Resolution order mirrors ``src/core/config.ts`` exactly:
+- agent name: ``VAULT_AGENT_NAME`` env -> ``agent_name``/``agentName`` -> ``"agent"``
+- vault: ``VAULT_DIR`` env -> ``vault`` field -> ``None``
+- timezone: ``timezone`` field -> ``None``
+"""
+
+from __future__ import annotations
+
+import os
+import json
+import re
+from pathlib import Path
+
+PLUGIN_NAME = "open-second-brain"
+DEFAULT_AGENT = "agent"
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+_TEMPLATES_DIR = _REPO_ROOT / "templates"
+_COMMON_TEMPLATE_PATH = _TEMPLATES_DIR / "identity-reminder.txt"
+# This package runs inside Hermes, so the reminder target is fixed at the call
+# site (mirrors the TypeScript behaviour where each runtime passes its own
+# target literal). The Python side collapses to hermes -> common.
+_TARGET = "hermes"
+_TARGET_TEMPLATE_PATH = _TEMPLATES_DIR / f"identity-reminder.{_TARGET}.txt"
+
+_template_cache: str | None = None
+
+
+def config_path() -> Path:
+ """Resolve the plugin config path (``OPEN_SECOND_BRAIN_CONFIG`` -> XDG -> ~)."""
+ override = os.environ.get("OPEN_SECOND_BRAIN_CONFIG")
+ if override:
+ return Path(override).expanduser()
+ xdg = os.environ.get("XDG_CONFIG_HOME")
+ if xdg:
+ return Path(xdg).expanduser() / "open-second-brain" / "config.yaml"
+ return Path.home() / ".config" / "open-second-brain" / "config.yaml"
+
+
+def _config_text() -> str | None:
+ path = config_path()
+ if not path.is_file():
+ return None
+ try:
+ return path.read_text(encoding="utf-8")
+ except OSError:
+ return None
+
+
+def _config_value(*keys: str) -> str | None:
+ """Read the first matching ``key: value`` line for any of ``keys``.
+
+ Deliberately tiny: the plugin config is a flat key/value YAML written by
+ the TypeScript core, so a per-key line regex avoids a YAML dependency
+ (the project ships ``dependencies = []``).
+ """
+ text = _config_text()
+ if text is None:
+ return None
+ alternation = "|".join(re.escape(k) for k in keys)
+ pattern = re.compile(rf"^\s*(?:{alternation})\s*:\s*(.+?)\s*$", re.MULTILINE)
+ match = pattern.search(text)
+ if not match:
+ return None
+ raw = match.group(1).strip()
+ if not raw:
+ return None
+ # `save_config` writes a JSON-encoded double-quoted scalar (valid YAML), so
+ # decode that form to recover embedded quotes / backslashes; fall back to a
+ # bare or single-quoted scalar for hand-written or TypeScript-written config.
+ if raw.startswith('"'):
+ try:
+ return json.loads(raw) or None
+ except json.JSONDecodeError:
+ return raw.strip('"') or None
+ return raw.strip("'") or None
+
+
+def resolve_agent_name() -> str:
+ """Resolve the agent identity, mirroring ``resolveAgentName`` in TypeScript."""
+ env_value = os.environ.get("VAULT_AGENT_NAME")
+ if env_value:
+ return env_value
+ return _config_value("agent_name", "agentName") or DEFAULT_AGENT
+
+
+def resolve_vault() -> str | None:
+ """Resolve the vault path, mirroring ``resolveVault`` in TypeScript."""
+ env_value = os.environ.get("VAULT_DIR")
+ if env_value:
+ return env_value
+ return _config_value("vault")
+
+
+def resolve_timezone() -> str | None:
+ """Resolve the configured timezone, or ``None`` when unset."""
+ return _config_value("timezone")
+
+
+def load_reminder_template() -> str:
+ """Read the Hermes reminder template, falling back to the common file.
+
+ Cached after the first call: the template is an installation-time artifact
+ that does not change at runtime, and a gateway restart (every plugin
+ update) flushes the cache by starting a fresh process.
+ """
+ global _template_cache
+ if _template_cache is not None:
+ return _template_cache
+ if _TARGET_TEMPLATE_PATH.is_file():
+ _template_cache = _TARGET_TEMPLATE_PATH.read_text(encoding="utf-8").rstrip()
+ else:
+ _template_cache = _COMMON_TEMPLATE_PATH.read_text(encoding="utf-8").rstrip()
+ return _template_cache
+
+
+def _reset_template_cache_for_tests() -> None:
+ """Test-only: drop the cached body so a fixture rewrite is visible."""
+ global _template_cache
+ _template_cache = None
+
+
+def render_reminder(agent: str) -> str:
+ """Substitute every ``{agent}`` placeholder in the reminder template."""
+ return load_reminder_template().replace("{agent}", agent)
+
+
+def build_reminder() -> str | None:
+ """Render the identity reminder for the configured agent.
+
+ Returns ``None`` when no identity is configured, so the literal ``@agent``
+ placeholder never leaks into a user-facing turn.
+ """
+ agent = resolve_agent_name()
+ if agent == DEFAULT_AGENT:
+ return None
+ return render_reminder(agent)
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index 99d1bde2..419f3cf6 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,12 +1,13 @@
name: open-second-brain
-version: "0.31.2"
-description: "Hermes adapter for OpenSecondBrain vault health checks and optional MCP tool server."
-author: "OpenSecondBrain contributors"
-kind: standalone
-provides_hooks:
- - pre_llm_call
-mcp_server:
- command: scripts/o2b
- args: ["mcp"]
- description: "Optional stdio MCP server. Add to ~/.hermes/config.yaml mcp_servers if MCP tool routing is desired."
- protocol_version: "2025-06-18"
+version: "0.32.0"
+description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
+author: "Open Second Brain contributors"
+memory_provider: true
+hooks:
+ - system_prompt_block
+ - prefetch
+ - sync_turn
+ - on_pre_compress
+ - on_session_end
+ - on_memory_write
+ - shutdown
diff --git a/plugins/hermes/provider.py b/plugins/hermes/provider.py
new file mode 100644
index 00000000..0e775af3
--- /dev/null
+++ b/plugins/hermes/provider.py
@@ -0,0 +1,312 @@
+"""Native Hermes ``MemoryProvider`` for Open Second Brain.
+
+The provider is a thin orchestrator: it owns a ``BrainBridge`` to the
+deterministic TypeScript core and maps the Hermes memory contract onto the
+existing ``brain_*`` MCP tools. No deterministic memory logic lives here.
+
+Required surface (this module): ``name``, ``is_available``, ``initialize``,
+``get_tool_schemas``, ``handle_tool_call``, ``get_config_schema``,
+``save_config``. Lifecycle hooks (prefetch, sync_turn, on_pre_compress, ...)
+are added alongside.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import threading
+from pathlib import Path
+from typing import Any
+
+from . import config
+from ._base import MemoryProvider
+from .bridge import BrainBridge, BridgeError, McpBrainBridge
+
+# Curated, memory-relevant subset of the full MCP tool surface. Schemas still
+# come from the live server's `tools/list`; only this name allowlist is kept
+# locally, which keeps the agent's tool context small (the full server
+# advertises 60+ tools) without risking schema drift.
+MEMORY_TOOLS: tuple[str, ...] = (
+ # writers
+ "brain_feedback",
+ "brain_apply_evidence",
+ "brain_note",
+ "brain_pinned_context",
+ # recall / query / context
+ "brain_query",
+ "brain_search",
+ "brain_recall_gate",
+ "brain_context",
+ "brain_context_pack",
+ # continuity
+ "brain_pre_compact_extract",
+)
+
+# Config fields this provider owns, in the order the setup wizard shows them.
+_CONFIG_KEYS: tuple[str, ...] = ("vault", "agent_name", "timezone")
+
+# Token budget for the recall slice fetched on each prefetch.
+_PREFETCH_MAX_TOKENS = 1024
+# Upper bound on a single mirrored built-in-memory note.
+_MIRROR_CHAR_LIMIT = 2000
+
+
+class OpenSecondBrainMemoryProvider(MemoryProvider):
+ """Open Second Brain as a first-class Hermes memory provider."""
+
+ PROVIDER_NAME = "open-second-brain"
+
+ def __init__(self, bridge: BrainBridge | None = None) -> None:
+ self._bridge_override = bridge
+ self._bridge: BrainBridge | None = None
+ self._hermes_home: str | None = None
+ self._session_id: str = ""
+ self._buffer: list[tuple[str, str]] = []
+ self._lock = threading.Lock()
+ self._sync_threads: list[threading.Thread] = []
+ self._queued_query: str = ""
+
+ # -- required surface ----------------------------------------------------
+
+ @property
+ def name(self) -> str:
+ return self.PROVIDER_NAME
+
+ def is_available(self) -> bool:
+ """Activation eligibility without network calls: a vault is configured."""
+ return config.resolve_vault() is not None
+
+ def initialize(self, session_id: str, **kwargs: Any) -> None:
+ """Start the bridge to the TS core. Fail-soft: never break gateway boot."""
+ self._session_id = session_id or ""
+ self._hermes_home = kwargs.get("hermes_home")
+ if self._bridge is not None:
+ # Re-initialization (a new session on a reused instance) must not
+ # leak the previous bridge's subprocess.
+ try:
+ self._bridge.stop()
+ except Exception: # noqa: BLE001
+ pass
+ self._bridge = self._bridge_override or McpBrainBridge(vault=config.resolve_vault())
+ try:
+ self._bridge.start()
+ except Exception: # noqa: BLE001 - degrade to inert; tool calls surface errors
+ pass
+
+ def get_tool_schemas(self) -> list[dict[str, Any]]:
+ """Return the memory-relevant subset of the server's advertised tools."""
+ if self._bridge is None:
+ return []
+ try:
+ tools = self._bridge.list_tools()
+ except Exception: # noqa: BLE001 - no tools rather than a crash
+ return []
+ return [t for t in tools if t.get("name") in MEMORY_TOOLS]
+
+ def handle_tool_call(self, tool_name: str, args: dict[str, Any], **_kwargs: Any) -> Any:
+ """Forward an agent tool invocation to the TS core over the bridge."""
+ if self._bridge is None:
+ raise BridgeError("memory provider not initialized")
+ if tool_name not in MEMORY_TOOLS:
+ # Enforce the curated surface at execution time, not just discovery.
+ raise BridgeError(f"unsupported memory tool: {tool_name}")
+ return self._bridge.call_tool(tool_name, args or {})
+
+ def get_config_schema(self) -> list[dict[str, Any]]:
+ return [
+ {
+ "key": "vault",
+ "description": "Path to the Obsidian vault whose Brain/ subtree stores memory.",
+ "required": True,
+ },
+ {
+ "key": "agent_name",
+ "description": "Agent identity recorded on every Brain write.",
+ },
+ {
+ "key": "timezone",
+ "description": "IANA timezone for daily and scheduled Brain operations.",
+ },
+ ]
+
+ def save_config(self, values: dict[str, Any], hermes_home: str) -> None:
+ """Persist non-secret config to the canonical Open Second Brain config.
+
+ The bridge spawns ``o2b mcp``, which resolves the vault from this same
+ file, so the provider's config must land here rather than under
+ ``hermes_home`` (which scopes only provider-local state).
+ """
+ path = config.config_path()
+ path.parent.mkdir(parents=True, exist_ok=True)
+ existing = path.read_text(encoding="utf-8") if path.is_file() else ""
+ lines = existing.splitlines()
+ for key in _CONFIG_KEYS:
+ value = values.get(key)
+ if not value:
+ continue
+ # Serialize as a JSON scalar (valid YAML) so quotes, backslashes
+ # (Windows paths), and newlines cannot corrupt the shared config.
+ new_line = f"{key}: {json.dumps(str(value), ensure_ascii=False)}"
+ key_re = re.compile(rf"^\s*{re.escape(key)}\s*:")
+ for i, line in enumerate(lines):
+ if key_re.match(line):
+ lines[i] = new_line
+ break
+ else:
+ lines.append(new_line)
+ path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+ # -- lifecycle hooks -----------------------------------------------------
+
+ def system_prompt_block(self) -> str:
+ """Static provider context: the current active-preferences body."""
+ result = self._safe_call("brain_context", {})
+ return str(self._structured(result).get("content", "") or "")
+
+ def prefetch(self, query: str, *, session_id: str = "", **_kwargs: Any) -> str:
+ """Recall context before an API call, plus the per-turn identity reminder.
+
+ The recall gate decides whether a retrieval runs; the identity reminder
+ (the behaviour the retired ``pre_llm_call`` hook used to provide) is
+ always appended when an agent identity is configured.
+ """
+ parts: list[str] = []
+ gate = self._structured(self._safe_call("brain_recall_gate", {"prompt": query}))
+ if gate.get("retrieve"):
+ pack = self._safe_call("brain_context_pack", {"max_tokens": _PREFETCH_MAX_TOKENS})
+ recalled = self._text(pack)
+ if recalled:
+ parts.append(recalled)
+ reminder = config.build_reminder()
+ if reminder:
+ parts.append(reminder)
+ return "\n\n".join(parts)
+
+ def queue_prefetch(self, query: str, **_kwargs: Any) -> None:
+ """Remember the next turn's query so a later prefetch can warm it."""
+ self._queued_query = query or ""
+
+ def sync_turn(
+ self,
+ user: str,
+ assistant: str,
+ *,
+ session_id: str = "",
+ messages: list | None = None,
+ **_kwargs: Any,
+ ) -> None:
+ """Buffer the completed turn off the hot path (non-blocking, daemon thread)."""
+ sid = session_id or self._session_id
+
+ def _work() -> None:
+ try:
+ self._append_turn(user, assistant, sid)
+ except Exception: # noqa: BLE001 - a turn must never fail on capture
+ pass
+
+ # Drop references to finished capture threads so the list cannot grow
+ # unbounded across a long-lived session.
+ self._sync_threads = [t for t in self._sync_threads if t.is_alive()]
+ thread = threading.Thread(target=_work, daemon=True)
+ self._sync_threads.append(thread)
+ thread.start()
+
+ def on_pre_compress(self, messages: list, **_kwargs: Any) -> None:
+ """Flush buffered turns into deterministic continuity storage before compaction."""
+ self._drain_captures()
+ self._flush_buffer()
+
+ def on_session_end(self, messages: list, **_kwargs: Any) -> None:
+ """Flush any remaining buffered turns at session close."""
+ self._drain_captures()
+ self._flush_buffer()
+
+ def on_memory_write(self, action: str, target: str, content: str, **_kwargs: Any) -> None:
+ """Mirror a Hermes built-in memory write (MEMORY.md / USER.md) into Brain."""
+ text = f"Hermes built-in memory {action} on {target}: {content}"[:_MIRROR_CHAR_LIMIT]
+ self._safe_call("brain_note", {"text": text})
+
+ def shutdown(self) -> None:
+ """Drain captures, flush, and stop the bridge. Never raises."""
+ self._drain_captures()
+ self._flush_buffer()
+ if self._bridge is not None:
+ try:
+ self._bridge.stop()
+ except Exception: # noqa: BLE001 - shutdown is best-effort
+ pass
+
+ # -- internals -----------------------------------------------------------
+
+ def _safe_call(self, name: str, args: dict[str, Any]) -> Any:
+ """Bridge call that degrades to ``None`` instead of breaking a turn."""
+ if self._bridge is None:
+ return None
+ try:
+ return self._bridge.call_tool(name, args)
+ except Exception: # noqa: BLE001 - lifecycle hooks must not raise into Hermes
+ return None
+
+ @staticmethod
+ def _structured(result: Any) -> dict[str, Any]:
+ if isinstance(result, dict) and isinstance(result.get("structuredContent"), dict):
+ return result["structuredContent"]
+ return {}
+
+ @staticmethod
+ def _text(result: Any) -> str:
+ if not isinstance(result, dict):
+ return ""
+ content = result.get("content")
+ if isinstance(content, list) and content:
+ first = content[0]
+ if isinstance(first, dict) and isinstance(first.get("text"), str):
+ return first["text"]
+ return ""
+
+ def _append_turn(self, user: str, assistant: str, session_id: str) -> None:
+ with self._lock:
+ self._buffer.append((user, assistant))
+ self._persist_turn(user, assistant, session_id)
+
+ def _persist_turn(self, user: str, assistant: str, session_id: str) -> None:
+ """Append the raw turn to a transcript under hermes_home for durability."""
+ if not self._hermes_home:
+ return
+ path = Path(self._hermes_home) / "open-second-brain" / "session-transcript.jsonl"
+ record = json.dumps(
+ {"session_id": session_id, "user": user, "assistant": assistant},
+ ensure_ascii=False,
+ )
+ try:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ with path.open("a", encoding="utf-8") as handle:
+ handle.write(record + "\n")
+ except OSError:
+ pass
+
+ def _flush_buffer(self) -> None:
+ """Hand buffered turns to deterministic extraction, then clear the buffer."""
+ with self._lock:
+ turns = list(self._buffer)
+ self._buffer.clear()
+ if not turns:
+ return
+ text = "\n\n".join(f"User: {u}\nAssistant: {a}" for u, a in turns)
+ self._safe_call(
+ "brain_pre_compact_extract",
+ {
+ "session_id": self._session_id or "hermes",
+ "turn_start": 0,
+ "turn_end": len(turns),
+ "text": text,
+ },
+ )
+
+ def _drain_captures(self) -> None:
+ """Join outstanding capture threads so a turn buffered just before a
+ flush still reaches storage. Safe to call any time; used by the
+ lifecycle hooks and by tests for determinism."""
+ for thread in list(self._sync_threads):
+ thread.join(timeout=5)
+ self._sync_threads.clear()
diff --git a/pyproject.toml b/pyproject.toml
index a8bfa93e..7800c04d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"
# CLI entry points (those moved to `package.json` `bin`).
[project]
name = "open-second-brain"
-version = "0.31.2"
+version = "0.32.0"
description = "Hermes Python shim for Open Second Brain. Most of the project (CLI, MCP server, OpenClaw plugin) is TypeScript on Bun; see package.json."
readme = "README.md"
requires-python = ">=3.11"
diff --git a/tests/python/test_hermes_plugin.py b/tests/python/test_hermes_plugin.py
index f6f83330..1e89f767 100644
--- a/tests/python/test_hermes_plugin.py
+++ b/tests/python/test_hermes_plugin.py
@@ -1,36 +1,24 @@
-"""Tests for the slim Hermes Python shim.
+"""Tests for the Hermes plugin package surface.
-The shim only handles the per-turn ``pre_llm_call`` injection and a small
-data-only health report; everything else lives in the TypeScript core
-exposed through the MCP server. These tests pin the contract Hermes
-relies on.
+The package now registers a native memory provider and a data-only health
+check; the legacy per-turn ``pre_llm_call`` hook is retired (its identity
+reminder moved into the provider's ``prefetch``). These tests pin the package
+contract Hermes relies on: ``register`` wiring, the health report, the root
+entrypoint re-export, and the identity-reminder template source of truth.
"""
import importlib.util
-import os
import sys
-import tempfile
import unittest
from pathlib import Path
-# Ensure ``plugins.hermes`` is importable regardless of which directory the
-# test runner is invoked from. Pytest with rootdir at the repo root works
-# out of the box; running ``python -m unittest tests.python.test_hermes_plugin``
-# from the repo root also works because ``plugins/hermes/__init__.py`` is on
-# the path. The legacy invocation ``python -m unittest discover -s tests``
-# would not find ``plugins`` without the explicit insert; the shim's
-# import is small enough that we keep it self-contained.
ROOT = Path(__file__).resolve().parents[2]
if str(ROOT) not in sys.path:
sys.path.insert(0, str(ROOT))
-from plugins.hermes import ( # noqa: E402
- _load_reminder_template,
- check_health,
- health,
- on_pre_llm_call,
- register,
-)
+from plugins.hermes import check_health, health, register, register_cli # noqa: E402
+from plugins.hermes import config as cfg # noqa: E402
+from plugins.hermes.provider import OpenSecondBrainMemoryProvider # noqa: E402
PLUGIN_NAME = "open-second-brain"
@@ -50,8 +38,8 @@ class HealthReportTests(unittest.TestCase):
class RootPluginEntrypointTests(unittest.TestCase):
"""Hermes installs Git plugins by cloning the repo and loading the
repository root as the plugin directory. The root ``__init__.py`` is
- therefore the entry the gateway sees first; it must re-export the
- same callable names this shim exposes.
+ therefore the entry the gateway sees first; it must re-export the same
+ callable names this package exposes.
"""
def test_root_init_exposes_check_health(self):
@@ -92,93 +80,89 @@ class RegisterTests(unittest.TestCase):
register(ctx)
self.assertIn(PLUGIN_NAME, ctx.health_checks)
- def test_register_hook_called_for_pre_llm_call(self):
- registered: list[tuple[str, object]] = []
+ def test_registers_memory_provider(self):
+ registered: list[object] = []
class Context:
- def register_hook(self, name, callback):
- registered.append((name, callback))
+ def register_memory_provider(self, provider):
+ registered.append(provider)
register(Context())
self.assertEqual(len(registered), 1)
- name, callback = registered[0]
- self.assertEqual(name, "pre_llm_call")
- self.assertIs(callback, on_pre_llm_call)
+ self.assertIsInstance(registered[0], OpenSecondBrainMemoryProvider)
+ self.assertEqual(registered[0].name, PLUGIN_NAME)
-class PreLlmCallTests(unittest.TestCase):
- """The hook fires every turn and must:
+class LoaderFallbackTests(unittest.TestCase):
+ """Guards the TEMPORARY file-path fallback in the root ``__init__.py``.
- - return ``{"context": "..."}`` when identity is configured
- - return ``None`` (no injection) when identity is unresolved
- - never raise
+ Hermes' external memory-provider loader imports a plugin under a synthetic
+ package name without registering its parent namespace, breaking the
+ relative/absolute imports the root entrypoint tries first. The fallback
+ loads ``plugins/hermes`` directly by file path with
+ ``submodule_search_locations`` so its own relative imports still resolve.
+ This locks that mechanism: if it ever stops yielding the provider (e.g. the
+ fallback is removed before the upstream Hermes fix lands), this fails.
"""
- def setUp(self):
- self._prev_env = os.environ.pop("VAULT_AGENT_NAME", None)
- self._prev_cfg = os.environ.pop("OPEN_SECOND_BRAIN_CONFIG", None)
-
- def tearDown(self):
- os.environ.pop("VAULT_AGENT_NAME", None)
- os.environ.pop("OPEN_SECOND_BRAIN_CONFIG", None)
- if self._prev_env is not None:
- os.environ["VAULT_AGENT_NAME"] = self._prev_env
- if self._prev_cfg is not None:
- os.environ["OPEN_SECOND_BRAIN_CONFIG"] = self._prev_cfg
-
- def test_returns_context_when_env_identity_set(self):
- os.environ["VAULT_AGENT_NAME"] = "hermes-vps-agent"
- result = on_pre_llm_call(
- session_id="test",
- user_message="hello",
- conversation_history=[],
- is_first_turn=True,
- model="combo",
- platform="cli",
- sender_id="",
+ def test_filepath_load_of_impl_yields_provider(self):
+ impl_dir = ROOT / "plugins" / "hermes"
+ spec = importlib.util.spec_from_file_location(
+ "_osb_hermes_impl_test",
+ impl_dir / "__init__.py",
+ submodule_search_locations=[str(impl_dir)],
)
- self.assertIsInstance(result, dict)
- self.assertIn("context", result)
- ctx = result["context"]
- self.assertIn("@hermes-vps-agent", ctx)
- # Β§32 (v0.10.8): the Hermes reminder now points at the three
- # Brain writer tools; event_log_append is retired.
- self.assertIn("brain_feedback", ctx)
- self.assertIn("brain_apply_evidence", ctx)
- self.assertIn("brain_note", ctx)
- self.assertNotIn("event_log_append", ctx)
-
- def test_returns_context_from_persisted_config(self):
- with tempfile.TemporaryDirectory() as tmp:
- cfg = Path(tmp) / "config.yaml"
- cfg.write_text('agent_name: "openclaw-main"\n', encoding="utf-8")
- os.environ["OPEN_SECOND_BRAIN_CONFIG"] = str(cfg)
- result = on_pre_llm_call()
- self.assertIsInstance(result, dict)
- self.assertIn("@openclaw-main", result["context"])
-
- def test_returns_context_with_camelcase_config_key(self):
- with tempfile.TemporaryDirectory() as tmp:
- cfg = Path(tmp) / "config.yaml"
- cfg.write_text('agentName: "codex-vps-agent"\n', encoding="utf-8")
- os.environ["OPEN_SECOND_BRAIN_CONFIG"] = str(cfg)
- result = on_pre_llm_call()
- self.assertIsInstance(result, dict)
- self.assertIn("@codex-vps-agent", result["context"])
-
- def test_returns_none_when_identity_unresolved(self):
- with tempfile.TemporaryDirectory() as tmp:
- os.environ["OPEN_SECOND_BRAIN_CONFIG"] = str(Path(tmp) / "missing.yaml")
- result = on_pre_llm_call()
- self.assertIsNone(result)
+ self.assertIsNotNone(spec)
+ module = importlib.util.module_from_spec(spec)
+ sys.modules[spec.name] = module
+ try:
+ spec.loader.exec_module(module)
+ provider = module.OpenSecondBrainMemoryProvider()
+ self.assertEqual(provider.name, PLUGIN_NAME)
+ self.assertTrue(callable(module.register))
+ finally:
+ for name in list(sys.modules):
+ if name == spec.name or name.startswith(spec.name + "."):
+ sys.modules.pop(name, None)
+
+ def test_register_does_not_raise_on_minimal_context(self):
+ class Context:
+ pass
+
+ # A ctx exposing neither hook must be ignored, not fatal.
+ register(Context())
+
+ def test_register_cli_is_reexported(self):
+ # Hermes may discover CLI registration at package level; keep it exported.
+ self.assertTrue(callable(register_cli))
+
+ def test_no_pre_llm_call_hook_registered(self):
+ registered: list[str] = []
+
+ class Context:
+ def register_hook(self, name, callback):
+ registered.append(name)
+
+ def register_memory_provider(self, provider):
+ pass
+
+ register(Context())
+ self.assertNotIn("pre_llm_call", registered)
class TemplateSourceOfTruthTests(unittest.TestCase):
- """The reminder text lives in `templates/identity-reminder.txt` so the
- Python shim and the TypeScript core do not drift apart. These tests
- pin the file's location and shape; both runtimes must keep loading it.
+ """The reminder text lives in ``templates/identity-reminder*.txt`` so the
+ Python provider and the TypeScript core do not drift apart. These tests
+ pin the file's location, shape, and per-target parity with the shared
+ fixture asserted on the TypeScript side.
"""
+ def setUp(self):
+ cfg._reset_template_cache_for_tests()
+
+ def tearDown(self):
+ cfg._reset_template_cache_for_tests()
+
def test_template_file_exists_at_canonical_path(self):
path = ROOT / "templates" / "identity-reminder.txt"
self.assertTrue(path.is_file(), f"missing canonical reminder template: {path}")
@@ -188,35 +172,22 @@ class TemplateSourceOfTruthTests(unittest.TestCase):
text = path.read_text(encoding="utf-8")
self.assertGreaterEqual(text.count("{agent}"), 2)
- def test_pre_llm_call_substitutes_every_placeholder(self):
- os.environ["VAULT_AGENT_NAME"] = "parity-agent"
- try:
- result = on_pre_llm_call()
- finally:
- os.environ.pop("VAULT_AGENT_NAME", None)
- self.assertIsNotNone(result)
- self.assertIn("@parity-agent", result["context"])
- self.assertNotIn("{agent}", result["context"])
-
-
-class PerTargetParityTests(unittest.TestCase):
- """Python and TypeScript must produce the same bytes for the Hermes
- target. The shared fixture at
- ``tests/fixtures/identity-reminder/hermes.txt`` is asserted by the
- TS resolver test; this test asserts the Python shim against the same
- bytes. If the two drift, both languages' CI fails.
- """
+ def test_render_reminder_substitutes_every_placeholder(self):
+ rendered = cfg.render_reminder("parity-agent")
+ self.assertIn("@parity-agent", rendered)
+ self.assertNotIn("{agent}", rendered)
def test_hermes_template_matches_shared_fixture(self):
fixture = (
- ROOT / "tests" / "fixtures" / "identity-reminder" / "hermes.txt"
- ).read_text(encoding="utf-8").rstrip()
- rendered = _load_reminder_template().replace("{agent}", "test-agent")
+ (ROOT / "tests" / "fixtures" / "identity-reminder" / "hermes.txt")
+ .read_text(encoding="utf-8")
+ .rstrip()
+ )
+ rendered = cfg.load_reminder_template().replace("{agent}", "test-agent")
self.assertEqual(rendered, fixture)
def test_hermes_template_prefers_per_target_over_common(self):
- body = _load_reminder_template()
- self.assertIn("Hermes turns are short", body)
+ self.assertIn("Hermes turns are short", cfg.load_reminder_template())
if __name__ == "__main__":
diff --git a/tests/python/test_memory_provider.py b/tests/python/test_memory_provider.py
new file mode 100644
index 00000000..2e939ebf
--- /dev/null
+++ b/tests/python/test_memory_provider.py
@@ -0,0 +1,569 @@
+"""Tests for the native Hermes memory provider and its bridge.
+
+The provider subclasses the Hermes ``MemoryProvider`` ABC when running inside
+a Hermes install, and a local fallback base otherwise (so this repo's CI can
+exercise it without Hermes present). All deterministic work is delegated to
+the TypeScript core through a ``BrainBridge`` seam, which tests replace with a
+fake so no live Bun runtime is needed.
+"""
+
+import io
+import json
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+ sys.path.insert(0, str(ROOT))
+
+from plugins.hermes import config as cfg # noqa: E402
+from plugins.hermes._base import MemoryProvider # noqa: E402
+from plugins.hermes.bridge import ( # noqa: E402
+ BridgeError,
+ BridgeTransportError,
+ FakeBrainBridge,
+ JsonRpcStdioClient,
+ McpBrainBridge,
+)
+from plugins.hermes.provider import ( # noqa: E402
+ MEMORY_TOOLS,
+ OpenSecondBrainMemoryProvider,
+)
+from plugins.hermes.cli import register_cli # noqa: E402
+
+
+class ConfigHelperTests(unittest.TestCase):
+ _ENV_KEYS = ("VAULT_AGENT_NAME", "VAULT_DIR", "OPEN_SECOND_BRAIN_CONFIG")
+
+ def setUp(self):
+ self._saved = {k: os.environ.pop(k, None) for k in self._ENV_KEYS}
+ cfg._reset_template_cache_for_tests()
+
+ def tearDown(self):
+ for k in self._ENV_KEYS:
+ os.environ.pop(k, None)
+ if self._saved[k] is not None:
+ os.environ[k] = self._saved[k]
+ cfg._reset_template_cache_for_tests()
+
+ def _write_config(self, tmp, body):
+ path = Path(tmp) / "config.yaml"
+ path.write_text(body, encoding="utf-8")
+ os.environ["OPEN_SECOND_BRAIN_CONFIG"] = str(path)
+ return path
+
+ def test_resolve_agent_name_prefers_env(self):
+ os.environ["VAULT_AGENT_NAME"] = "env-agent"
+ self.assertEqual(cfg.resolve_agent_name(), "env-agent")
+
+ def test_resolve_agent_name_from_config_snake_and_camel(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ self._write_config(tmp, 'agent_name: "snake-agent"\n')
+ self.assertEqual(cfg.resolve_agent_name(), "snake-agent")
+ with tempfile.TemporaryDirectory() as tmp:
+ self._write_config(tmp, 'agentName: "camel-agent"\n')
+ self.assertEqual(cfg.resolve_agent_name(), "camel-agent")
+
+ def test_resolve_agent_name_default_when_unresolved(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ os.environ["OPEN_SECOND_BRAIN_CONFIG"] = str(Path(tmp) / "missing.yaml")
+ self.assertEqual(cfg.resolve_agent_name(), cfg.DEFAULT_AGENT)
+
+ def test_resolve_vault_prefers_env(self):
+ os.environ["VAULT_DIR"] = "/tmp/env-vault"
+ self.assertEqual(cfg.resolve_vault(), "/tmp/env-vault")
+
+ def test_resolve_vault_from_config(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ self._write_config(tmp, 'vault: "/tmp/cfg-vault"\nagent_name: "x"\n')
+ self.assertEqual(cfg.resolve_vault(), "/tmp/cfg-vault")
+
+ def test_resolve_vault_none_when_unset(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ self._write_config(tmp, 'agent_name: "x"\n')
+ self.assertIsNone(cfg.resolve_vault())
+
+ def test_render_reminder_substitutes_every_placeholder(self):
+ rendered = cfg.render_reminder("zed")
+ self.assertIn("@zed", rendered)
+ self.assertNotIn("{agent}", rendered)
+
+ def test_build_reminder_none_when_unresolved(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ os.environ["OPEN_SECOND_BRAIN_CONFIG"] = str(Path(tmp) / "missing.yaml")
+ self.assertIsNone(cfg.build_reminder())
+
+ def test_build_reminder_string_when_identity_set(self):
+ os.environ["VAULT_AGENT_NAME"] = "build-agent"
+ reminder = cfg.build_reminder()
+ self.assertIsNotNone(reminder)
+ self.assertIn("@build-agent", reminder)
+
+
+class FallbackBaseTests(unittest.TestCase):
+ def test_memory_provider_is_subclassable(self):
+ class Demo(MemoryProvider):
+ @property
+ def name(self):
+ return "demo"
+
+ demo = Demo()
+ self.assertEqual(demo.name, "demo")
+
+ def test_optional_hooks_are_noop_on_base(self):
+ class Demo(MemoryProvider):
+ @property
+ def name(self):
+ return "demo"
+
+ demo = Demo()
+ # Optional lifecycle hooks the provider may not override must not raise.
+ self.assertIsNone(demo.queue_prefetch("q"))
+ self.assertIsNone(demo.on_session_end([]))
+ self.assertIsNone(demo.shutdown())
+
+
+class ProviderRequiredSurfaceTests(unittest.TestCase):
+ _ENV_KEYS = ("VAULT_AGENT_NAME", "VAULT_DIR", "OPEN_SECOND_BRAIN_CONFIG")
+
+ def setUp(self):
+ self._saved = {k: os.environ.pop(k, None) for k in self._ENV_KEYS}
+
+ def tearDown(self):
+ for k in self._ENV_KEYS:
+ os.environ.pop(k, None)
+ if self._saved[k] is not None:
+ os.environ[k] = self._saved[k]
+
+ def _provider(self, bridge):
+ return OpenSecondBrainMemoryProvider(bridge=bridge)
+
+ def test_name(self):
+ self.assertEqual(self._provider(FakeBrainBridge()).name, "open-second-brain")
+
+ def test_is_available_true_when_vault_configured(self):
+ os.environ["VAULT_DIR"] = "/tmp/vault"
+ self.assertTrue(self._provider(FakeBrainBridge()).is_available())
+
+ def test_is_available_false_when_no_vault(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ os.environ["OPEN_SECOND_BRAIN_CONFIG"] = str(Path(tmp) / "missing.yaml")
+ self.assertFalse(self._provider(FakeBrainBridge()).is_available())
+
+ def test_initialize_starts_bridge(self):
+ bridge = FakeBrainBridge()
+ provider = self._provider(bridge)
+ provider.initialize("sess-1", hermes_home="/tmp/hh")
+ self.assertTrue(bridge.started)
+
+ def test_get_tool_schemas_filters_to_allowlist(self):
+ bridge = FakeBrainBridge(
+ tools=[
+ {"name": "brain_query"},
+ {"name": "brain_note"},
+ {"name": "vault_health"},
+ {"name": "second_brain_status"},
+ ]
+ )
+ provider = self._provider(bridge)
+ provider.initialize("s", hermes_home="/tmp/hh")
+ names = {t["name"] for t in provider.get_tool_schemas()}
+ self.assertEqual(names, {"brain_query", "brain_note"})
+ self.assertTrue(names.issubset(set(MEMORY_TOOLS)))
+
+ def test_handle_tool_call_forwards_to_bridge(self):
+ bridge = FakeBrainBridge(results={"brain_note": {"ok": True}})
+ provider = self._provider(bridge)
+ provider.initialize("s", hermes_home="/tmp/hh")
+ result = provider.handle_tool_call("brain_note", {"text": "hi"})
+ self.assertEqual(result, {"ok": True})
+ self.assertEqual(bridge.calls, [("brain_note", {"text": "hi"})])
+
+ def test_get_config_schema_shape(self):
+ schema = self._provider(FakeBrainBridge()).get_config_schema()
+ by_key = {f["key"]: f for f in schema}
+ self.assertEqual(set(by_key), {"vault", "agent_name", "timezone"})
+ self.assertTrue(by_key["vault"].get("required"))
+
+ def test_save_config_writes_to_osb_config_and_preserves_others(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ cfg_path = Path(tmp) / "config.yaml"
+ cfg_path.write_text('existing_key: "keep"\n', encoding="utf-8")
+ os.environ["OPEN_SECOND_BRAIN_CONFIG"] = str(cfg_path)
+ provider = self._provider(FakeBrainBridge())
+ provider.save_config(
+ {"vault": "/v", "agent_name": "a", "timezone": "UTC"}, tmp
+ )
+ text = cfg_path.read_text(encoding="utf-8")
+ self.assertIn('vault: "/v"', text)
+ self.assertIn('agent_name: "a"', text)
+ self.assertIn('timezone: "UTC"', text)
+ self.assertIn('existing_key: "keep"', text)
+
+ def test_handle_tool_call_rejects_non_allowlisted_tool(self):
+ bridge = FakeBrainBridge(results={"brain_dream": {"ok": True}})
+ provider = self._provider(bridge)
+ provider.initialize("s", hermes_home="/tmp/hh")
+ with self.assertRaises(BridgeError):
+ provider.handle_tool_call("brain_dream", {})
+ self.assertEqual(bridge.calls, []) # never reached the bridge
+
+ def test_save_config_encodes_windows_path_safely(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ cfg_path = Path(tmp) / "config.yaml"
+ os.environ["OPEN_SECOND_BRAIN_CONFIG"] = str(cfg_path)
+ provider = self._provider(FakeBrainBridge())
+ win = 'C:\\Users\\me\\My "Special" Vault'
+ provider.save_config({"vault": win}, tmp)
+ # Round-trips through the writer (JSON scalar) and the reader, even
+ # with backslashes and embedded quotes that would corrupt a raw
+ # interpolation. Asserted inside the tempdir so the file still exists.
+ self.assertEqual(cfg.resolve_vault(), win)
+
+
+class CliTests(unittest.TestCase):
+ _ENV_KEYS = ("VAULT_AGENT_NAME", "VAULT_DIR", "OPEN_SECOND_BRAIN_CONFIG")
+
+ def setUp(self):
+ self._saved = {k: os.environ.pop(k, None) for k in self._ENV_KEYS}
+
+ def tearDown(self):
+ for k in self._ENV_KEYS:
+ os.environ.pop(k, None)
+ if self._saved[k] is not None:
+ os.environ[k] = self._saved[k]
+
+ def _run(self, argv):
+ import argparse
+ import contextlib
+
+ parser = argparse.ArgumentParser()
+ subparsers = parser.add_subparsers(dest="cmd")
+ osb = subparsers.add_parser("open-second-brain")
+ register_cli(osb)
+ args = parser.parse_args(["open-second-brain", *argv])
+ buf = io.StringIO()
+ with contextlib.redirect_stdout(buf):
+ rc = args.func(args)
+ return rc, buf.getvalue()
+
+ def test_status_reports_provider_and_availability(self):
+ os.environ["VAULT_DIR"] = "/tmp/cli-vault"
+ rc, out = self._run(["status"])
+ self.assertEqual(rc, 0)
+ self.assertIn("open-second-brain", out)
+ self.assertIn("/tmp/cli-vault", out)
+
+ def test_status_nonzero_when_unavailable(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ os.environ["OPEN_SECOND_BRAIN_CONFIG"] = str(Path(tmp) / "missing.yaml")
+ rc, _ = self._run(["status"])
+ self.assertEqual(rc, 1)
+
+ def test_config_reports_effective_values(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ cfg_path = Path(tmp) / "config.yaml"
+ cfg_path.write_text('vault: "/v"\nagent_name: "cli-agent"\n', encoding="utf-8")
+ os.environ["OPEN_SECOND_BRAIN_CONFIG"] = str(cfg_path)
+ rc, out = self._run(["config"])
+ self.assertEqual(rc, 0)
+ self.assertIn("/v", out)
+ self.assertIn("cli-agent", out)
+
+
+class _RaisingBridge(FakeBrainBridge):
+ """Bridge whose tool calls always fail, to prove hooks are exception-safe."""
+
+ def call_tool(self, name, args):
+ raise BridgeError("boom")
+
+
+class ProviderLifecycleTests(unittest.TestCase):
+ _ENV_KEYS = ("VAULT_AGENT_NAME", "VAULT_DIR", "OPEN_SECOND_BRAIN_CONFIG")
+
+ def setUp(self):
+ self._saved = {k: os.environ.pop(k, None) for k in self._ENV_KEYS}
+
+ def tearDown(self):
+ for k in self._ENV_KEYS:
+ os.environ.pop(k, None)
+ if self._saved[k] is not None:
+ os.environ[k] = self._saved[k]
+
+ def _init(self, bridge, **kwargs):
+ provider = OpenSecondBrainMemoryProvider(bridge=bridge)
+ provider.initialize("sess-1", **kwargs)
+ return provider
+
+ def test_system_prompt_block_returns_active_content(self):
+ bridge = FakeBrainBridge(
+ results={"brain_context": {"structuredContent": {"content": "ACTIVE PREFS"}}}
+ )
+ provider = self._init(bridge, hermes_home="/tmp/hh")
+ self.assertEqual(provider.system_prompt_block(), "ACTIVE PREFS")
+
+ def test_prefetch_returns_recall_and_reminder_when_gate_retrieves(self):
+ os.environ["VAULT_AGENT_NAME"] = "pf-agent"
+ bridge = FakeBrainBridge(
+ results={
+ "brain_recall_gate": {"structuredContent": {"retrieve": True, "reason": "hit"}},
+ "brain_context_pack": {"content": [{"type": "text", "text": "RECALLED"}]},
+ }
+ )
+ provider = self._init(bridge, hermes_home="/tmp/hh")
+ out = provider.prefetch("what did we decide", session_id="sess-1")
+ self.assertIn("RECALLED", out)
+ self.assertIn("@pf-agent", out)
+
+ def test_prefetch_reminder_only_when_gate_declines(self):
+ os.environ["VAULT_AGENT_NAME"] = "pf-agent"
+ bridge = FakeBrainBridge(
+ results={"brain_recall_gate": {"structuredContent": {"retrieve": False}}}
+ )
+ provider = self._init(bridge, hermes_home="/tmp/hh")
+ out = provider.prefetch("hello", session_id="sess-1")
+ self.assertIn("@pf-agent", out)
+ self.assertNotIn("RECALLED", out)
+ called = [name for name, _ in bridge.calls]
+ self.assertNotIn("brain_context_pack", called)
+
+ def test_prefetch_empty_when_no_identity_and_no_recall(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ os.environ["OPEN_SECOND_BRAIN_CONFIG"] = str(Path(tmp) / "missing.yaml")
+ bridge = FakeBrainBridge(
+ results={"brain_recall_gate": {"structuredContent": {"retrieve": False}}}
+ )
+ provider = self._init(bridge, hermes_home="/tmp/hh")
+ self.assertEqual(provider.prefetch("hi"), "")
+
+ def test_sync_turn_buffers_and_pre_compress_flushes_through_extract(self):
+ bridge = FakeBrainBridge(results={"brain_pre_compact_extract": {"structuredContent": {}}})
+ provider = self._init(bridge, hermes_home="/tmp/hh")
+ provider.sync_turn("u1", "a1", session_id="sess-1")
+ provider.sync_turn("u2", "a2", session_id="sess-1")
+ provider._drain_captures()
+ provider.on_pre_compress([])
+ extract_calls = [a for n, a in bridge.calls if n == "brain_pre_compact_extract"]
+ self.assertEqual(len(extract_calls), 1)
+ self.assertIn("u1", extract_calls[0]["text"])
+ self.assertIn("a2", extract_calls[0]["text"])
+ # Buffer cleared: a second flush makes no further extract call.
+ provider.on_session_end([])
+ self.assertEqual(
+ len([1 for n, _ in bridge.calls if n == "brain_pre_compact_extract"]), 1
+ )
+
+ def test_on_memory_write_mirrors_to_brain_note(self):
+ bridge = FakeBrainBridge(results={"brain_note": {"structuredContent": {}}})
+ provider = self._init(bridge, hermes_home="/tmp/hh")
+ provider.on_memory_write("update", "MEMORY.md", "remember the vault path")
+ note_calls = [a for n, a in bridge.calls if n == "brain_note"]
+ self.assertEqual(len(note_calls), 1)
+ self.assertIn("MEMORY.md", note_calls[0]["text"])
+ self.assertIn("remember the vault path", note_calls[0]["text"])
+
+ def test_shutdown_stops_bridge(self):
+ bridge = FakeBrainBridge()
+ provider = self._init(bridge, hermes_home="/tmp/hh")
+ provider.shutdown()
+ self.assertTrue(bridge.stopped)
+
+ def test_hooks_are_exception_safe(self):
+ os.environ["VAULT_AGENT_NAME"] = "safe-agent"
+ provider = self._init(_RaisingBridge(), hermes_home="/tmp/hh")
+ # None of these may raise even though every bridge call fails.
+ self.assertEqual(provider.system_prompt_block(), "")
+ self.assertIn("@safe-agent", provider.prefetch("q"))
+ provider.sync_turn("u", "a")
+ provider._drain_captures()
+ provider.on_pre_compress([])
+ provider.on_session_end([])
+ provider.on_memory_write("update", "USER.md", "x")
+ provider.shutdown()
+
+
+class _ScriptedReader:
+ """Readline source that yields pre-built JSON-RPC frames in order."""
+
+ def __init__(self, frames):
+ self._lines = [json.dumps(f) + "\n" for f in frames]
+ self._i = 0
+
+ def readline(self):
+ if self._i >= len(self._lines):
+ return ""
+ line = self._lines[self._i]
+ self._i += 1
+ return line
+
+
+class _FakeProcess:
+ """Minimal Popen stand-in: captures stdin writes, scripts stdout reads."""
+
+ def __init__(self, responses):
+ self.stdin = io.StringIO()
+ self.stdout = _ScriptedReader(responses)
+ self.terminated = False
+ self._returncode = None
+
+ def poll(self):
+ return self._returncode
+
+ def terminate(self):
+ self.terminated = True
+ self._returncode = 0
+
+ def wait(self, timeout=None):
+ self._returncode = 0
+ return 0
+
+ def kill(self):
+ self._returncode = -9
+
+
+class JsonRpcStdioClientTests(unittest.TestCase):
+ def test_request_correlates_by_id_and_skips_noise(self):
+ writer = io.StringIO()
+ # A notification (no id) and a mismatched id must be skipped before
+ # the matching response is returned.
+ reader = _ScriptedReader(
+ [
+ {"jsonrpc": "2.0", "method": "notifications/progress"},
+ {"jsonrpc": "2.0", "id": 999, "result": {"stale": True}},
+ {"jsonrpc": "2.0", "id": 1, "result": {"ok": True}},
+ ]
+ )
+ client = JsonRpcStdioClient(writer, reader)
+ result = client.request("ping", {})
+ self.assertEqual(result, {"ok": True})
+ sent = json.loads(writer.getvalue().strip().splitlines()[0])
+ self.assertEqual(sent["method"], "ping")
+ self.assertEqual(sent["id"], 1)
+
+ def test_error_response_raises(self):
+ reader = _ScriptedReader(
+ [{"jsonrpc": "2.0", "id": 1, "error": {"code": -32601, "message": "nope"}}]
+ )
+ client = JsonRpcStdioClient(io.StringIO(), reader)
+ with self.assertRaises(BridgeError):
+ client.request("missing", {})
+
+ def test_eof_raises(self):
+ client = JsonRpcStdioClient(io.StringIO(), _ScriptedReader([]))
+ with self.assertRaises(BridgeError):
+ client.request("ping", {})
+
+
+class McpBrainBridgeTests(unittest.TestCase):
+ def _handshake_frames(self, extra=None):
+ frames = [
+ {"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2025-06-18"}},
+ {
+ "jsonrpc": "2.0",
+ "id": 2,
+ "result": {"tools": [{"name": "brain_query"}, {"name": "brain_note"}]},
+ },
+ ]
+ if extra:
+ frames.extend(extra)
+ return frames
+
+ def test_start_runs_handshake_and_lists_tools(self):
+ proc = _FakeProcess(self._handshake_frames())
+ bridge = McpBrainBridge(vault="/v", spawn=lambda argv: proc)
+ bridge.start()
+ names = [t["name"] for t in bridge.list_tools()]
+ self.assertEqual(names, ["brain_query", "brain_note"])
+ # initialize then tools/list were written; argv carried the vault.
+ methods = [json.loads(line)["method"] for line in proc.stdin.getvalue().splitlines()]
+ self.assertEqual(methods[0], "initialize")
+ self.assertIn("notifications/initialized", methods)
+ self.assertIn("tools/list", methods)
+
+ def test_call_tool_forwards_name_and_arguments(self):
+ extra = [{"jsonrpc": "2.0", "id": 3, "result": {"content": "ok"}}]
+ proc = _FakeProcess(self._handshake_frames(extra))
+ bridge = McpBrainBridge(vault="/v", spawn=lambda argv: proc)
+ bridge.start()
+ result = bridge.call_tool("brain_query", {"q": "x"})
+ self.assertEqual(result, {"content": "ok"})
+ last = json.loads(proc.stdin.getvalue().splitlines()[-1])
+ self.assertEqual(last["method"], "tools/call")
+ self.assertEqual(last["params"], {"name": "brain_query", "arguments": {"q": "x"}})
+
+ def test_argv_includes_vault(self):
+ captured = {}
+
+ def spy(argv):
+ captured["argv"] = argv
+ return _FakeProcess(self._handshake_frames())
+
+ McpBrainBridge(vault="/my/vault", spawn=spy).start()
+ self.assertIn("--vault", captured["argv"])
+ self.assertIn("/my/vault", captured["argv"])
+
+ def test_stop_terminates_process(self):
+ proc = _FakeProcess(self._handshake_frames())
+ bridge = McpBrainBridge(vault="/v", spawn=lambda argv: proc)
+ bridge.start()
+ bridge.stop()
+ self.assertTrue(proc.terminated)
+
+ def _counting_spawn(self, *procs):
+ it = iter(procs)
+ state = {"n": 0}
+
+ def spawn(argv):
+ state["n"] += 1
+ return next(it)
+
+ spawn.state = state
+ return spawn
+
+ def test_tool_error_response_propagates_without_restart(self):
+ # A JSON-RPC error (e.g. invalid arguments) is a server rejection, not
+ # a dead channel: it must propagate and must not respawn the process.
+ err = [{"jsonrpc": "2.0", "id": 3, "error": {"code": -32602, "message": "bad args"}}]
+ spawn = self._counting_spawn(_FakeProcess(self._handshake_frames(err)))
+ bridge = McpBrainBridge(vault="/v", spawn=spawn)
+ bridge.start()
+ with self.assertRaises(BridgeError) as ctx:
+ bridge.call_tool("brain_query", {})
+ self.assertNotIsInstance(ctx.exception, BridgeTransportError)
+ self.assertEqual(spawn.state["n"], 1)
+
+ def test_transport_error_restarts_once_and_retries(self):
+ # First process dies mid-call (EOF); the bridge restarts once and the
+ # second process answers.
+ dead = _FakeProcess(self._handshake_frames()) # no id-3 frame -> EOF
+ good = _FakeProcess(
+ self._handshake_frames([{"jsonrpc": "2.0", "id": 3, "result": {"ok": True}}])
+ )
+ spawn = self._counting_spawn(dead, good)
+ bridge = McpBrainBridge(vault="/v", spawn=spawn)
+ bridge.start()
+ result = bridge.call_tool("brain_query", {"topic": "x"})
+ self.assertEqual(result, {"ok": True})
+ self.assertEqual(spawn.state["n"], 2)
+
+
+class FakeBrainBridgeTests(unittest.TestCase):
+ def test_records_calls_and_returns_canned_results(self):
+ bridge = FakeBrainBridge(
+ tools=[{"name": "brain_query"}],
+ results={"brain_query": {"items": []}},
+ )
+ bridge.start()
+ self.assertTrue(bridge.started)
+ self.assertEqual(bridge.list_tools(), [{"name": "brain_query"}])
+ self.assertEqual(bridge.call_tool("brain_query", {"q": "x"}), {"items": []})
+ self.assertEqual(bridge.calls, [("brain_query", {"q": "x"})])
+ bridge.stop()
+ self.assertTrue(bridge.stopped)
+
+
+if __name__ == "__main__":
+ unittest.main()