Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
49.4 KB
Raw Blame
"""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()