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.jsonindex 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.jsonindex 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.ymlindex 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@v5with:python-version: "3.11"@@ -55,5 +55,8 @@ jobs:- name: TypeScript test suiterun: bun test- - name: Python shim tests+ - name: Python plugin testsrun: python -m unittest discover -s tests/python -v++ - name: Python package compiles+ run: python -m compileall -q plugins/hermesdiff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 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@v5with: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 testsrun: 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/nullpython -m json.tool openclaw.plugin.json >/dev/nullpython -m json.tool package.json >/dev/null- python -m py_compile plugins/hermes/__init__.py+ python -m compileall -q plugins/hermesbash -n scripts/o2bbash -n scripts/vault-logbash -n scripts/_bun-precheck.shdiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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-01Hands-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.0diff --git a/README.md b/README.mdindex 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 runtimesdiff --git a/__init__.py b/__init__.pyindex 60f39f04..8caa5f64 100644--- a/__init__.py+++ b/__init__.py@@ -3,13 +3,77 @@Hermes installs Git plugins by cloning the repository and loading the repositoryroot as the plugin directory. The implementation lives in ``plugins/hermes`` soit 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 annotationstry:- 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 6diff --git a/docs/brainstorm/hermes-memory-provider/variants.md b/docs/brainstorm/hermes-memory-provider/variants.mdnew file mode 100644index 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.mdindex 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 froma 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```basho2b 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 restarto2b 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 offhermes plugins remove open-second-brain+o2b uninstall --apply-local --remove-clihermes 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.jsonindex 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.jsonindex 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.yamlindex 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+ - shutdowndiff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.jsonindex 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__.pyindex 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 annotationsimport os-import refrom pathlib import Pathfrom 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_NAMEdef 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 loadingpass+++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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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 0diff --git a/plugins/hermes/config.py b/plugins/hermes/config.pynew file mode 100644index 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.yamlindex 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+ - shutdowndiff --git a/plugins/hermes/provider.py b/plugins/hermes/provider.pynew file mode 100644index 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.tomlindex 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.pyindex 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 osimport sys-import tempfileimport unittestfrom 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: E402PLUGIN_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 therepository 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.pynew file mode 100644index 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()