Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
"""Native Hermes ``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, ...)
and the optional readback hook ``get_status_config`` are added alongside.
"""
from __future__ import annotations
import atexit
import json
import logging
import os
import shutil
import threading
from collections.abc import Callable
from pathlib import Path
from typing import TYPE_CHECKING, Any, NamedTuple
if TYPE_CHECKING:
from collections.abc import Iterable, Mapping
from . import config
from ._base import MemoryProvider
from ._schemas import static_tool_schemas
from .bridge import BrainBridge, BridgeError, McpBrainBridge, resolve_request_timeout
logger = logging.getLogger(__name__)
# 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",
"brain_context_pack_outcome",
# continuity
"brain_pre_compact_extract",
)
class _ConfigField(NamedTuple):
"""One config field the setup wizard collects and this provider persists."""
#: Key as it appears in the Open Second Brain config file.
key: str
#: Wizard-facing explanation of what the field controls.
description: str
#: Whether the provider is unusable without it.
required: bool
#: How the value is resolved once written, used to verify the write took.
resolve: Callable[[], str | None]
#: Written value -> the effective value it should resolve to.
normalize: Callable[[str], str]
# The config surface, once. `get_config_schema()` and the write loop used to be
# the same three keys written out twice, so a fourth field could half-land: the
# wizard would collect it and the writer would drop it (or the reverse) with
# nothing failing. Both are derived from this tuple, in the order the wizard
# shows them.
_CONFIG_FIELDS: tuple[_ConfigField, ...] = (
_ConfigField(
key="vault",
description="Path to the Obsidian vault whose Brain/ subtree stores memory.",
required=True,
resolve=config.resolve_vault,
normalize=config.expand_tilde,
),
_ConfigField(
key="agent_name",
description="Agent identity recorded on every Brain write.",
required=False,
resolve=config.resolve_agent_name,
normalize=lambda value: value,
),
_ConfigField(
key="timezone",
description="IANA timezone for daily and scheduled Brain operations.",
required=False,
resolve=config.resolve_timezone,
normalize=lambda value: value,
),
)
_CONFIG_KEYS: tuple[str, ...] = tuple(field.key for field in _CONFIG_FIELDS)
def _resolved_config_values() -> dict[str, str]:
"""Every config field's effective value, keyed as the wizard names it.
This provider stores its config in the canonical Open Second Brain file
(see :meth:`OpenSecondBrainMemoryProvider.save_config`), which is outside
``hermes_home``. The host cannot read that file: it looks for provider
state in ``$HERMES_HOME/<name>.json``, ``$HERMES_HOME/<name>/config.json``
and the ``memory.<name>`` block of its own config, finds nothing for this
provider, and concludes the provider is unconfigured - permanently, since
a save writes the native file the host still cannot read. The dashboard
then refuses its own save with "not ready (needs config)".
The host's documented way for a provider to report a value it holds is the
schema field's ``default``, so this is what the two readback hooks -
:meth:`OpenSecondBrainMemoryProvider.get_config_schema` and
:meth:`OpenSecondBrainMemoryProvider.get_status_config` - report. No copy
of the config is written anywhere: one store stays the truth, and the host
is told what is in it rather than being asked to find it.
The EFFECTIVE value is reported, not the config file's line, because that
is what readiness means here - ``o2b mcp`` runs against the same
resolution chain, so a vault supplied by ``VAULT_DIR`` or a project
pointer is a configured provider.
A field whose config cannot be read contributes nothing: it renders as
unset, and the unreadable file is named by :meth:`is_available`, which
refuses instead of reporting the provider as merely unconfigured.
"""
resolved: dict[str, str] = {}
for field in _CONFIG_FIELDS:
try:
value = field.resolve()
except config.ConfigReadError:
continue
if value:
resolved[field.key] = value
return resolved
# Durable per-session transcript written under ``hermes_home``.
SESSION_TRANSCRIPT_FILENAME = "session-transcript.jsonl"
# Token budget for the recall slice fetched on each prefetch. Enforced
# SERVER-side by `brain_context_pack`, which estimates tokens against the
# bodies it emits; the provider never re-spends it as a character budget,
# because the four-bytes-per-token heuristic that would take is wrong by two
# to four times on Cyrillic and CJK vaults.
_PREFETCH_MAX_TOKENS = 1024
_PREFETCH_RECEIPT_HOST = "hermes"
# How `brain_context_pack` reads the turn: order the curated candidates by
# relevance rather than filtering them, so a natural-language turn spends the
# budget on what matters instead of substring-missing every page.
_PREFETCH_QUERY_MODE = "ranked"
# The ranked query limit counts Unicode codepoints; the gate counts UTF-16
# code units. At most 2,000 codepoints also fit the gate's 4,000-unit limit.
_PREFETCH_QUERY_MAX = 2000
_PREFETCH_QUERY_OMISSION = "\n...\n"
def _bounded_prefetch_query(query: str) -> str:
"""Keep both the opening context and the final question within the caps.
A non-string, or a turn that is blank after trimming, travels unchanged,
so the bridge refuses it as before; bounding a blank turn would leave
only the omission marker, a non-blank query with nothing to recall on.
"""
if not isinstance(query, str) or not query.strip() or len(query) <= _PREFETCH_QUERY_MAX:
return query
retained = _PREFETCH_QUERY_MAX - len(_PREFETCH_QUERY_OMISSION)
head = retained // 2
tail = retained - head
return query[:head] + _PREFETCH_QUERY_OMISSION + query[-tail:]
# A provider instance is created per AIAgent, but the MCP server is a gateway
# resource rather than a session resource. Keep one bridge per effective server
# configuration in this Python process. Cache eviction deliberately calls
# AIAgent.release_clients() without shutting down memory providers, so
# constructing one Bun child per provider leaks a child for every new session.
# The trailing tuple is the identity the child runs under on a multiplexed
# gateway (agent name, timezone, config path, request deadline); it is empty
# without multiplexing, where those are constant for the whole process.
_SharedBridgeKey = tuple[str | None, str | None, tuple[str, ...], str | None, tuple[Any, ...]]
_SHARED_BRIDGES: dict[_SharedBridgeKey, BrainBridge] = {}
_SHARED_BRIDGES_LOCK = threading.RLock()
def _shared_bridge_key(
vault: str | None,
repo_root: str | None,
command: tuple[str, ...],
env: Mapping[str, str] | None = None,
identity: tuple[Any, ...] = (),
) -> _SharedBridgeKey:
"""Identity of a bridge: what it runs, where, and the ``PATH`` it runs with.
``PATH`` is the only part of the overlay this provider ever rewrites, and
two children launched with different search paths are different servers -
sharing one bridge between them would hand the second caller a child that
resolved its runtime somewhere else.
``identity`` carries what a multiplexed gateway's profiles may differ in
besides the vault: two profiles sharing a vault under different agent
names must not share one child, or one of them writes as the other.
"""
return (
vault,
repo_root,
tuple(command),
None if env is None else env.get("PATH"),
tuple(identity),
)
def _get_shared_bridge(
*,
vault: str | None,
repo_root: str | None,
command: tuple[str, ...],
env: Mapping[str, str] | None = None,
identity: tuple[Any, ...] = (),
timeout: float | None = None,
) -> BrainBridge:
"""Return the one bridge for this gateway/configuration key.
``timeout`` is passed to the bridge only when given (a multiplexed
gateway); otherwise the bridge reads its deadline at start, as before.
"""
key = _shared_bridge_key(vault, repo_root, command, env, identity)
with _SHARED_BRIDGES_LOCK:
bridge = _SHARED_BRIDGES.get(key)
if bridge is None:
extra: dict[str, Any] = {} if timeout is None else {"timeout": timeout}
bridge = McpBrainBridge(
vault=vault,
repo_root=repo_root,
command=command,
env=env,
**extra,
)
_SHARED_BRIDGES[key] = bridge
return bridge
def _shutdown_shared_bridges() -> None:
"""Stop all gateway-owned bridges during normal interpreter shutdown."""
with _SHARED_BRIDGES_LOCK:
bridges = list(_SHARED_BRIDGES.values())
_SHARED_BRIDGES.clear()
for bridge in bridges:
try:
bridge.stop()
except Exception: # noqa: BLE001 - shutdown is best-effort
pass
_scope_degrade_warned = False
_scope_degrade_lock = threading.Lock()
def _warn_scope_degrade_once() -> None:
"""One WARNING per process when ``prefetch`` runs with no profile scope."""
global _scope_degrade_warned
with _scope_degrade_lock:
if _scope_degrade_warned:
return
_scope_degrade_warned = True
logger.warning(
"%s: no profile scope bound for this turn; the vault reminder is omitted",
OpenSecondBrainMemoryProvider.PROVIDER_NAME,
)
def _reset_scope_degrade_warning_for_tests() -> None:
"""Test-only: allow the prefetch degrade warning to fire again."""
global _scope_degrade_warned
with _scope_degrade_lock:
_scope_degrade_warned = False
def _reset_shared_bridges_for_tests() -> None:
"""Clear the process registry without exposing it as provider API."""
_shutdown_shared_bridges()
atexit.register(_shutdown_shared_bridges)
def _fallback_exe_dirs() -> tuple[Path, ...]:
"""Directories scanned for an executable when a tiny inherited ``PATH``
hides it from ``shutil.which``. Computed per call so it tracks the current
``$HOME`` (and stays patchable in tests)."""
home = Path.home()
return (
home / ".local" / "bin",
home / ".bun" / "bin",
home / ".hermes" / "node" / "bin",
Path("/opt/homebrew/bin"),
Path("/usr/local/bin"),
Path("/usr/bin"),
Path("/bin"),
)
def _path_with_dir_prepended(
directory: str, base: Mapping[str, str] | None = None
) -> dict[str, str]:
"""Copy of ``base`` (default ``os.environ``) with ``directory`` first on ``PATH``."""
env = dict(os.environ if base is None else base)
current = env.get("PATH", "")
env["PATH"] = f"{directory}{os.pathsep}{current}" if current else directory
return env
def _find_executable(name: str, search_dirs: Iterable[Path] | None = None) -> str | None:
"""Resolve ``name`` to an absolute executable path.
``shutil.which`` (which honours ``PATH``) wins when it can see the binary.
Hermes can start the provider from a process with a minimal inherited
``PATH``; then ``which`` returns nothing even though the executable exists
in a user-local bin, so fall back to scanning a curated directory set.
On Windows the scan appends ``PATHEXT`` suffixes (``.EXE``/``.CMD``/...) to
a bare name and does not gate on the POSIX execute bit, which has no meaning
there; on POSIX it matches the exact name and requires ``X_OK``.
"""
found = _which_not_in_cwd(name)
if found:
return found
dirs = tuple(search_dirs) if search_dirs is not None else _fallback_exe_dirs()
return _scan_dirs(name, dirs)
def _which_not_in_cwd(name: str) -> str | None:
"""``shutil.which``, minus the Windows current-directory lookup.
On Windows ``shutil.which`` looks in the current directory before
``PATH`` (Python 3.12+ skips that only when
``NoDefaultCurrentDirectoryInExePath`` is set), the same order cmd.exe
uses. Hermes runs in whatever project it was opened in, so a ``bun.cmd``
or ``o2b.cmd`` committed to that project would be the one started. A
hit in the current directory is therefore discarded, unless that
directory is itself on ``PATH``, and ``PATH`` is scanned instead.
"""
found = shutil.which(name)
if not found or os.name != "nt":
return found
cwd = os.path.normcase(os.path.abspath(os.getcwd()))
if os.path.normcase(os.path.dirname(os.path.abspath(found))) != cwd:
return found
path_dirs = [p for p in os.environ.get("PATH", "").split(os.pathsep) if p and os.path.isabs(p)]
if any(os.path.normcase(os.path.abspath(p)) == cwd for p in path_dirs):
return found
return _scan_dirs(name, path_dirs)
def _scan_dirs(name: str, dirs: Iterable[Path | str]) -> str | None:
"""The first ``name`` (with ``PATHEXT`` suffixes on Windows) in ``dirs``.
``os.path`` rather than ``pathlib``, so the scan does not depend on which
``Path`` flavour the platform instantiates."""
if os.name == "nt" and not os.path.splitext(name)[1]:
exts = [e for e in os.environ.get("PATHEXT", ".COM;.EXE;.BAT;.CMD").split(os.pathsep) if e]
candidate_names = [name + ext for ext in exts]
else:
candidate_names = [name]
for directory in dirs:
for candidate_name in candidate_names:
candidate = os.path.join(str(directory), candidate_name)
if not os.path.isfile(candidate):
continue
if os.name == "nt" or os.access(candidate, os.X_OK):
return candidate
return None
class OpenSecondBrainMemoryProvider(MemoryProvider):
"""Open Second Brain as a first-class Hermes memory provider."""
PROVIDER_NAME = config.PLUGIN_NAME
def __init__(self, bridge: BrainBridge | None = None) -> None:
self._bridge_override = bridge
self._bridge: BrainBridge | None = None
self._bridge_shared = False
self._bridge_start_error: Exception | 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.
A present-but-unreadable config is NOT answered here. The host renders
this boolean as a setup badge, and ``False`` on that badge means "you
have not configured this yet" - which is the exact false statement
GitHub #130 reported, and the reason a permissions fault on the config
file was indistinguishable from a plugin nobody had set up. There is no
third value in the host contract, so the only honest response to "I
cannot tell" is to refuse: :class:`config.ConfigReadError` is logged
with the file it names and re-raised, which reaches the gateway log
carrying its own remedy instead of vanishing into a wrong badge.
"""
try:
return config.resolve_vault() is not None
except config.ConfigReadError as exc:
logger.error("%s: cannot determine availability: %s", self.PROVIDER_NAME, exc)
raise
def initialize(self, session_id: str, **kwargs: Any) -> None:
"""Start the bridge to the TS core.
Fail-soft about the BRIDGE - a gateway boot must survive an ``o2b mcp``
that will not start - but not silent about it: the failure is logged
with a traceback and remembered, so a later tool call names it instead
of returning ``None`` forever with nothing anywhere saying why.
A configuration the resolver cannot read is a different matter and
propagates, for the reason :meth:`is_available` gives.
"""
self._session_id = session_id or ""
self._hermes_home = kwargs.get("hermes_home")
self._bridge_start_error = None
old_bridge = self._bridge
old_bridge_shared = self._bridge_shared
self._bridge = None
self._bridge_shared = False
if old_bridge is not None and not old_bridge_shared:
# Re-initialization (a new session on a reused instance) must not
# leak an injected/test bridge's subprocess. Gateway bridges are
# shared and intentionally remain alive for the gateway lifetime.
try:
old_bridge.stop()
except Exception: # noqa: BLE001 - a stale child must not block re-init
logger.warning(
"%s: could not stop the previous bridge", self.PROVIDER_NAME, exc_info=True
)
if self._bridge_override is not None:
self._bridge = self._bridge_override
else:
vault = config.resolve_vault()
repo_root = self._repo_root()
command = self._resolve_command()
env = self._resolve_env()
if config.is_multiplexed():
# Resolved here, once, where Hermes has bound this profile's
# scope: the child and every restart of it must not consult
# the gateway's environment, which is the launch profile's.
env, identity, timeout = self._scoped_child(env)
self._bridge = _get_shared_bridge(
vault=vault,
repo_root=repo_root,
command=command,
env=env,
identity=identity,
timeout=timeout,
)
else:
self._bridge = _get_shared_bridge(
vault=vault,
repo_root=repo_root,
command=command,
env=env,
)
self._bridge_shared = True
try:
assert self._bridge is not None
self._bridge.start()
except Exception as exc: # noqa: BLE001 - boot survives; the failure is recorded
self._bridge_start_error = exc
logger.error(
"%s: bridge to the Open Second Brain core failed to start; "
"memory tool calls will be refused until it does",
self.PROVIDER_NAME,
exc_info=True,
)
@staticmethod
def _repo_root() -> str | None:
"""Plugin checkout root that ships ``skills/`` (provider lives at
``<root>/plugins/hermes/provider.py``). Passed as ``--repo`` so the TS
core's ``repoRoot`` resolves and in-repo skills become discoverable;
without it ``skill_auto_attach`` returns an empty list."""
root = Path(__file__).resolve().parents[2]
return str(root) if (root / "skills").is_dir() else None
@staticmethod
def _scoped_child(
base: Mapping[str, str] | None,
) -> tuple[dict[str, str], tuple[Any, ...], float]:
"""Child environment, bridge identity and deadline for this profile.
Multiplexed gateways only. The child inherits the gateway's
environment, and the TypeScript core reads the agent name, timezone
and config path from it - so every profile-scoped name is removed and
the scope's own non-empty values are set in its place; a name the
scope leaves unset is resolved by the child from the config file, as
the plugin resolves it. The config directories
(:data:`config.SCOPE_FIRST_ENV`) are overridden only when the scope
sets them, so the child looks for the same config file the plugin
resolved. The deadline is fixed here (``0.0`` when
disabled) so a restart never reads the scope from a thread that has
none.
:raises config.ProfileScopeError: when no profile scope is bound.
"""
env = dict(os.environ if base is None else base)
for name in config.PROFILE_SCOPED_ENV:
env.pop(name, None)
for name in config.PROFILE_SCOPED_ENV:
value = config.env_setting(name)
if value:
env[name] = value
for name in config.SCOPE_FIRST_ENV:
value = config.scope_first_setting(name)
if value:
env[name] = value
deadline = resolve_request_timeout()
timeout = 0.0 if deadline is None else deadline
identity = (
config.resolve_agent_name(),
config.resolve_timezone(),
str(config.config_path()),
timeout,
# The core derives its config, data and state directories from
# these, so two profiles that differ only here need two children.
*(env.get(name) for name in config.SCOPE_FIRST_ENV),
)
return env, identity, timeout
@staticmethod
def _resolve_env() -> dict[str, str] | None:
"""Environment for the MCP child, or ``None`` to inherit this process's.
Resolving an absolute ``o2b`` is only half the job: the wrapper is a
bash script that runs ``command -v bun`` against its own ``PATH``, and
a Hermes gateway can hand the provider a ``PATH`` with no Bun on it -
so the wrapper exits 127 and the handshake dies at EOF. When Bun was
found only by the fallback scan, put its directory on the child's
``PATH`` so every branch of :meth:`_resolve_command` launches into an
environment where Bun resolves.
``None`` when ``PATH`` already resolves Bun (nothing to add) or when no
Bun exists to point at, which keeps the common case inheriting exactly
what it inherits today.
"""
if _which_not_in_cwd("bun"):
return None
bun = _find_executable("bun")
if not bun:
return None
return _path_with_dir_prepended(str(Path(bun).parent))
@classmethod
def _resolve_command(cls) -> tuple[str, ...]:
"""Determine the right argv prefix for the ``o2b mcp`` subprocess.
Hermes memory providers can run with a tiny inherited ``PATH``, so
resolve absolute executable paths via :func:`_find_executable` (which
scans user-local and system bins when ``PATH`` hides the binary) before
falling back to a bare command name.
On Windows the ``scripts/o2b`` bash wrapper is not directly executable
by ``subprocess.Popen``, so the o2b branch is POSIX-only; the
cross-platform path is the repo-local TypeScript entry point via
``bun run``.
"""
# The o2b wrapper is preferred - it also sources the macOS sqlite-vec
# shim, which the bare entry point does not - but it is a bash script
# whose first act is to check its own PATH for Bun. Preferring it when
# no Bun exists anywhere buys a command that can only exit 127, so the
# branch is gated on a Bun the child will be able to see: found here,
# and put on the child's PATH by :meth:`_resolve_env`.
bun = _find_executable("bun")
if os.name != "nt" and bun:
o2b = _find_executable("o2b")
if o2b:
return (o2b, "mcp")
# Resolve via repo-local TypeScript entry point + bun.
root = cls._repo_root()
if root and bun:
entry = Path(root) / "src" / "cli" / "main.ts"
if entry.is_file():
return (bun, "run", str(entry), "mcp")
# Last resort: hope o2b is reachable (e.g. npm global install on
# Windows created an o2b.cmd shim, or the user's shell can run it).
# On Windows resolve it to an absolute path first: CreateProcess only
# appends ``.exe`` to a bare name, so ``Popen(["o2b", ...])`` cannot
# start an ``o2b.cmd`` launcher even when it is on PATH.
if os.name == "nt":
o2b = _find_executable("o2b")
if o2b:
return (o2b, "mcp")
return ("o2b", "mcp")
def get_tool_schemas(self) -> list[dict[str, Any]]:
"""Return the memory-relevant subset of the server's advertised tools.
Hermes builds its tool routing table from this method at provider
registration time, BEFORE ``initialize()`` starts the bridge. The
vendored static schemas cover that window (and a failed live listing),
so the provider never registers with zero tools; once the bridge is
up, live schemas from ``tools/list`` win.
"""
if self._bridge is None:
return static_tool_schemas()
try:
tools = self._bridge.list_tools()
except Exception: # noqa: BLE001 - static fallback rather than a crash
# The fallback is right (Hermes needs a tool table now, and the
# vendored schemas are generated from the live ones), but it looks
# identical to a healthy listing. Say so, or a dead bridge hides
# behind a plausible tool list for the life of the gateway.
logger.warning(
"%s: live tools/list failed; serving vendored static schemas instead",
self.PROVIDER_NAME,
exc_info=True,
)
return static_tool_schemas()
filtered = []
for t in tools:
if t.get("name") not in MEMORY_TOOLS:
continue
# MCP uses "inputSchema"; Hermes adapters expect "parameters"
if "inputSchema" in t and "parameters" not in t:
t = dict(t)
t["parameters"] = t.pop("inputSchema")
filtered.append(t)
return filtered
def handle_tool_call(self, tool_name: str, args: dict[str, Any], **_kwargs: Any) -> str:
"""Forward an agent tool invocation to the TS core over the bridge.
Hermes feeds the return value back to the model as tool-message
content, and the chat-completions contract requires that content to
be a string. The bridge yields the MCP ``tools/call`` result dict, so
it is serialized here. Lenient providers (Anthropic) tolerate a raw
dict, which is why this leaked undetected; strict ones (DeepSeek)
reject it with HTTP 400. Coercing at this boundary - not in the
caller - is what makes the provider portable across both.
"""
if self._bridge is None:
raise BridgeError("memory provider not initialized")
if self._bridge_start_error is not None:
raise BridgeError(
"memory bridge failed to start: "
f"{type(self._bridge_start_error).__name__}: {self._bridge_start_error}"
)
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}")
forward_args = dict(args or {})
# Correlation defaults for the outcome POST only. `host` and
# `session_id` are also READ filters on list/summary, so supplying
# them there would narrow an agent's query to this host's rows
# without ever telling it - the "narrowed without saying so" failure
# the architecture notes call out by name.
if tool_name == "brain_context_pack_outcome" and forward_args.get("operation") == "post":
forward_args.setdefault("host", _PREFETCH_RECEIPT_HOST)
if self._session_id:
forward_args.setdefault("session_id", self._session_id)
return self._as_tool_content(self._bridge.call_tool(tool_name, forward_args))
def get_config_schema(self) -> list[dict[str, Any]]:
"""The wizard's field list, derived from :data:`_CONFIG_FIELDS`.
Each field carries the value this provider currently resolves as its
``default``, which is how a host that cannot read the native store
learns the provider is configured; :func:`_resolved_config_values`
explains what that closes. The wizard and the dashboard both render a
default as the field's current value, so a re-run pre-fills what is in
force rather than asking for it again.
"""
current = _resolved_config_values()
return [
{
"key": field.key,
"description": field.description,
"required": field.required,
"default": current.get(field.key, ""),
}
for field in _CONFIG_FIELDS
]
def get_status_config(self, provider_config: dict[str, Any]) -> dict[str, Any]:
"""What ``hermes memory status`` prints under ``<name> config:``.
The host passes its own ``memory.<name>`` block, which is empty for
this provider by design - nothing writes it, and duplicating the vault
path there is exactly what step 4 of ``install/hermes.md`` promises not
to do. Reporting it verbatim printed an empty block for a provider that
was fully configured, so the resolved values are reported instead,
alongside the file they come from: the confusion this closes is an
operator looking for provider state in the Hermes config.
"""
del provider_config # the host's own store holds nothing for us
status: dict[str, Any] = dict(_resolved_config_values())
try:
status["config_file"] = str(config.config_path())
except config.ConfigReadError:
# A multiplexed gateway with no profile scope bound: the path
# cannot be resolved, so the field is skipped like any other
# unreadable value rather than failing the status call.
pass
return status
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). The host
reads none of it back; :func:`_resolved_config_values` is how it is
told what this file holds.
Three rules, each replacing a way this used to lie about what it did:
- A key the wizard did not send is left alone; a key it sent EMPTY is
unset. Skipping every falsy value meant a field the operator cleared
kept its old value and the wizard reported success.
- The write is verified by re-resolving. Writing ``vault`` into a file
that ``VAULT_DIR`` (or a project pointer, or an active profile)
shadows leaves the operator with a config they can read and a vault
they are not using; :class:`config.ConfigEffectError` names the
shadowing source instead.
- Values that cannot survive the read-back are refused, not encoded.
This used to JSON-encode them, which made a Windows path round-trip
through the plugin and read back as a DIFFERENT path in ``o2b``.
:raises config.ConfigReadError: the existing config cannot be read, so
a write would clobber content nothing has seen.
:raises config.ConfigValueError: a value cannot survive the read-back.
:raises config.ConfigEffectError: the write landed but does not take.
"""
pending: dict[str, str | None] = {}
for field in _CONFIG_FIELDS:
if field.key not in values:
continue
raw = values[field.key]
pending[field.key] = str(raw) if raw else None
if not pending:
return
path = config.set_config_values(pending)
self._verify_saved(pending, path)
@staticmethod
def _verify_saved(pending: dict[str, str | None], path: Path) -> None:
"""Refuse loudly when a written key does not resolve to what was written."""
stored = config.parse_simple_yaml(path.read_text(encoding="utf-8"))
for field in _CONFIG_FIELDS:
if field.key not in pending:
continue
written = pending[field.key]
if not written:
if stored.get(field.key):
raise config.ConfigEffectError(
field.key, "", stored[field.key], "the key survived the unset"
)
continue
effective = field.resolve()
expected = field.normalize(written)
if effective != expected:
raise config.ConfigEffectError(
field.key,
written,
effective,
config.shadowing_source(field.key)
or "something ahead of the config file in the resolution chain wins",
)
# -- lifecycle hooks -----------------------------------------------------
@staticmethod
def _receipt_id(pack: Any) -> str | None:
"""Return the server-issued opaque receipt id, if this pack has one."""
structured = OpenSecondBrainMemoryProvider._structured(pack)
receipt_id = structured.get("receipt_id")
return str(receipt_id) if receipt_id else None
def _log_pack_warnings(self, pack: Any) -> None:
"""Surface the pack's own warnings; a degraded recall must name itself.
`brain_context_pack` reports injection-time tension warnings and the
owner-scope observation. They describe the material about to enter the
prompt - a memory that is the subject of an unresolved contradiction,
for one - and are for the operator, not the model, so they go to the
log rather than into the injected text.
"""
warnings = self._structured(pack).get("warnings")
if not isinstance(warnings, list):
return
for warning in warnings:
text = str(warning).strip()
if text:
logger.warning("%s: brain_context_pack: %s", self.PROVIDER_NAME, text)
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.
Recall has exactly ONE lane, ``brain_context_pack``, and the turn's
query rides it in ranked mode. That lane is where the prompt-injection
guard, the curated preference pool, the tombstone and supersession-tip
filters, owner-scope delivery, the enforced token budget, and the
server-issued receipt live; a raw ``brain_search`` recall would have
query-awareness and none of them. There is no second lane and no
fallback: a lane that fails says so through ``_safe_call`` and this
turn is injected nothing.
"""
parts: list[str] = []
sid = session_id or self._session_id
turn_id = str(_kwargs.get("turn_id") or "")
recall_query = _bounded_prefetch_query(query)
if recall_query != query:
logger.info(
"%s: prefetch recall query reduced to %d codepoints (original %d)",
self.PROVIDER_NAME, len(recall_query), len(query),
)
gate_args: dict[str, Any] = {
"prompt": recall_query,
"telemetry_host": _PREFETCH_RECEIPT_HOST,
}
if sid:
gate_args["session_id"] = sid
if turn_id:
gate_args["turn_id"] = turn_id
gate = self._structured(self._safe_call("brain_recall_gate", gate_args))
if gate.get("retrieve"):
pack_args: dict[str, Any] = {
"max_tokens": _PREFETCH_MAX_TOKENS,
"receipt": True,
"receipt_host": _PREFETCH_RECEIPT_HOST,
"telemetry": True,
"telemetry_host": _PREFETCH_RECEIPT_HOST,
}
# Ranked mode ORDERS the curated candidates by relevance to this
# turn and excludes none, so the budget decides what is dropped.
# The server refuses a mode with no query, so both travel or
# neither does.
if recall_query.strip():
pack_args["query"] = recall_query
pack_args["query_mode"] = _PREFETCH_QUERY_MODE
if sid:
pack_args["session_id"] = sid
if turn_id:
pack_args["turn_id"] = turn_id
pack = self._safe_call("brain_context_pack", pack_args)
self._log_pack_warnings(pack)
recalled = self._context_pack_text(pack)
if recalled:
parts.append(recalled)
receipt_id = self._receipt_id(pack)
if receipt_id:
parts.append(
"[O2B context-pack metadata] "
+ json.dumps(
{
"sample_id": receipt_id,
"outcome": "unknown_until_explicit_tool_call",
"tool": "brain_context_pack_outcome",
},
ensure_ascii=False,
)
)
else:
# A gated turn that recalls nothing is a fact worth stating:
# on an empty vault it is normal, and after a failed bridge
# call it is the second half of the warning `_safe_call`
# already emitted. Either way it is not a silent no-op.
logger.info(
"%s: brain_context_pack returned no recall for a gated turn",
self.PROVIDER_NAME,
)
# Skill auto-attach (Agent Surface Suite): the TS side gates on the
# skill_auto_attach config key and returns an empty block when off,
# so the default injection stays byte-identical. Fail-soft like every
# other lifecycle bridge call.
attach = self._structured(self._safe_call("skills_attach", {"query": query}))
skills_block = str(attach.get("block", "") or "")
if attach.get("enabled") and skills_block:
parts.append(skills_block)
try:
reminder = config.build_reminder()
except config.ProfileScopeError:
# Degrade like `_safe_call`: a turn with no bound profile scope
# cannot know whose identity to remind of, and failing the turn
# over a reminder would be worse than omitting it.
_warn_scope_degrade_once()
reminder = None
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
logger.warning(
"%s: capturing a turn failed; it is lost", self.PROVIDER_NAME, exc_info=True
)
# 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, *, interrupted: bool = False, **_kwargs: Any) -> None:
"""Flush any remaining buffered turns at session close.
Hermes now fires this hook on an interrupted close too
(SIGHUP/SIGTERM/force-quit/restart-drain, #50004/#50003/#50312),
passing ``interrupted=True`` alongside the flushed in-flight transcript.
Surfacing the flag onto the flush payload lets the TS core record an
interrupted capture honestly; the flush itself already drains the same
buffered turns whether the close was clean or interrupted, so no turn is
lost. Python makes no capture decision - it only forwards the flag.
"""
self._drain_captures()
self._flush_buffer(interrupted=bool(interrupted))
def on_memory_write(
self,
action: str,
target: str,
content: str,
metadata: dict[str, Any] | None = None,
**_kwargs: Any,
) -> None:
"""Persist a Hermes built-in memory write into the Brain vault.
Verified host contract (Hermes c253b0738): the manager dispatches one
call per write with ``action`` in {add, replace} (``remove`` is filtered
out host-side and never arrives) and ``target`` in {memory, user};
batches are decomposed host-side, so a provider never receives an array.
``metadata`` carries structured provenance (write_origin, session_id,
tool_name, ...).
This is a thin adapter: it forwards the payload to the host-bridge tool,
which is the single authority that validates the contract and persists a
durable ``host_memory_write`` continuity record via the shared substrate.
``_safe_call`` degrades to a no-op (the bridge's own rejection of an
unsupported payload, or a missing bridge, never breaks a turn) — matching
Hermes' own fail-soft hook contract.
"""
args: dict[str, Any] = {"action": action, "target": target, "content": content}
if isinstance(metadata, dict) and metadata:
args["metadata"] = metadata
self._safe_call("brain_memory_bridge", args)
def shutdown(self) -> None:
"""Drain captures, flush, and stop owned test bridges. Never raises."""
self._drain_captures()
self._flush_buffer()
bridge = self._bridge
bridge_shared = self._bridge_shared
self._bridge = None
self._bridge_shared = False
# Shared production bridges belong to the gateway, not an evictable
# session. The process registry/atexit hook owns their final stop.
if bridge is not None and not bridge_shared:
try:
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:
logger.debug("%s: %s skipped, no bridge", self.PROVIDER_NAME, name)
return None
try:
return self._bridge.call_tool(name, args)
except Exception: # noqa: BLE001 - lifecycle hooks must not raise into Hermes
logger.warning("%s: %s failed; degrading to no recall", self.PROVIDER_NAME, name)
return None
@staticmethod
def _as_tool_content(result: Any) -> str:
"""Coerce a bridge result into tool-message content (always a string).
The Hermes memory contract types ``handle_tool_call`` as ``-> str``,
but the bridge yields an MCP result dict. Serialize losslessly so the
model still sees both the ``content`` and ``structuredContent``
envelopes. ``default=str`` keeps non-JSON-native values (datetimes,
Paths) from raising at the boundary; an already-string result passes
through untouched.
"""
if isinstance(result, str):
return result
return json.dumps(result, ensure_ascii=False, default=str)
@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 ""
@staticmethod
def _context_pack_text(result: Any) -> str:
"""Recall text from ``brain_context_pack``: prefer structured bodies.
Structured item bodies are the budgeted recall payload; using them also
bypasses the MCP transport's preview envelope. ``content[0].text`` is
the fallback for older servers that only expose legacy text.
A server that answered with an ``items`` key has spoken the structured
contract, so its answer stands even when it is empty: an empty pack
means there was nothing to recall, and dropping to the text channel
there would inject the raw pack JSON - vault paths and all - or the
preview envelope into the prompt. Only a result with no ``items`` key
at all is treated as legacy.
"""
structured = OpenSecondBrainMemoryProvider._structured(result)
if "items" in structured:
return "\n\n".join(
str(item.get("body"))
for item in (structured.get("items") or [])
if isinstance(item, dict) and str(item.get("body") or "").strip()
)
return OpenSecondBrainMemoryProvider._text(result)
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) / config.PLUGIN_NAME / SESSION_TRANSCRIPT_FILENAME
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:
logger.warning(
"%s: could not append the session transcript at %s",
self.PROVIDER_NAME,
path,
exc_info=True,
)
def _flush_buffer(self, interrupted: bool = False) -> None:
"""Hand buffered turns to deterministic extraction, then clear the buffer.
``interrupted`` is forwarded to the extractor only when set, so a clean
close emits a byte-identical payload (the field is absent by default).
"""
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)
# Turn bounds are turn *ids* on the server contract, so they go over as
# strings — the tool reads them with `requiredStringArg`, which does not
# coerce, and `_safe_call` swallows the `-32602` it raises. Sending ints
# here loses the whole flushed segment with nothing on either side
# saying so. Matches the sibling Aider bracket, which also sends "0".
args: dict[str, Any] = {
"session_id": self._session_id or "hermes",
"turn_start": "0",
"turn_end": str(len(turns)),
"text": text,
}
if interrupted:
args["interrupted"] = True
self._safe_call("brain_pre_compact_extract", args)
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()