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
"""Two-mode settings for the Hermes plugin on a multiplexed gateway.
A Hermes gateway with ``multiplex_profiles`` serves several profiles from one
process, and the process environment belongs to the launch profile. Under
multiplexing every profile-scoped setting must therefore come from the turn's
profile scope (``agent.secret_scope``), never from ``os.environ``; without
multiplexing the plugin must answer exactly as it always has.
Hermes is not installed in CI, so a fake ``agent.secret_scope`` is injected
through ``sys.modules``. ``config.py`` imports it lazily per call, so the stub
takes effect without reloading anything.
"""
from __future__ import annotations
import contextlib
import io
import json
import os
import sys
import tempfile
import threading
import types
import unittest
from pathlib import Path
from unittest.mock import patch
ROOT = Path(__file__).resolve().parents[2]
if str(ROOT) not in sys.path:
sys.path.insert(0, str(ROOT))
from plugins.hermes import bridge as bridge_module # noqa: E402
from plugins.hermes import config as cfg # noqa: E402
from plugins.hermes import provider as provider_module # noqa: E402
from plugins.hermes.bridge import FakeBrainBridge, McpBrainBridge # noqa: E402
from plugins.hermes.provider import OpenSecondBrainMemoryProvider # noqa: E402
# Process-environment values that belong to the LAUNCH profile. None of them
# may surface under multiplexing, in a result or in a message.
LAUNCH_VALUES = {
"VAULT_DIR": "launch-vault-dir-value",
"VAULT_AGENT_NAME": "launch-agent-value",
"VAULT_TIMEZONE": "Launch/Zone",
"OPEN_SECOND_BRAIN_CONFIG": "launch-config-path-value.yaml",
"OPEN_SECOND_BRAIN_MCP_TIMEOUT": "4242",
}
_ISOLATED_ENV = (*LAUNCH_VALUES.keys(), cfg.XDG_CONFIG_HOME_ENV)
class FakeUnscopedError(RuntimeError):
"""Stands in for Hermes's ``UnscopedSecretError``."""
def make_fake_scope(*, multiplexed: bool, values: dict | None = None, unbound: bool = False):
"""A fake ``agent`` package and ``agent.secret_scope`` module.
``reads`` records every name the plugin asked the scope for, so a test can
prove the scope was (or was not) consulted.
"""
pkg = types.ModuleType("agent")
pkg.__path__ = []
fake = types.ModuleType("agent.secret_scope")
scoped_values = dict(values or {})
reads: list[str] = []
def is_multiplex_active() -> bool:
return multiplexed
def get_secret(name, default=None):
reads.append(name)
if unbound:
raise FakeUnscopedError(f"{name} has no bound profile scope")
return scoped_values.get(name, default)
fake.is_multiplex_active = is_multiplex_active
fake.get_secret = get_secret
fake.UnscopedSecretError = FakeUnscopedError
fake.reads = reads
pkg.secret_scope = fake
return pkg, fake
class ScopeTestCase(unittest.TestCase):
"""Isolates every scoped name and the XDG directory per test."""
def setUp(self):
self._saved = {k: os.environ.pop(k, None) for k in _ISOLATED_ENV}
self._tmp = tempfile.TemporaryDirectory()
self.tmp = Path(self._tmp.name)
reset = getattr(cfg, "_reset_scope_warnings_for_tests", None)
if reset is not None:
reset()
def tearDown(self):
for k in _ISOLATED_ENV:
os.environ.pop(k, None)
if self._saved[k] is not None:
os.environ[k] = self._saved[k]
self._tmp.cleanup()
reset = getattr(cfg, "_reset_scope_warnings_for_tests", None)
if reset is not None:
reset()
def install(self, fake_pair):
pkg, fake = fake_pair
return patch.dict(sys.modules, {"agent": pkg, "agent.secret_scope": fake})
def no_hermes(self):
# A ``None`` entry makes the import raise ImportError, whatever is on
# the machine running the suite.
return patch.dict(sys.modules, {"agent": None, "agent.secret_scope": None})
def set_launch_env(self):
os.environ.update(LAUNCH_VALUES)
def write_xdg_config(self, body: str) -> Path:
xdg = self.tmp / "xdg"
path = xdg / cfg.PLUGIN_NAME / cfg.CONFIG_FILENAME
path.parent.mkdir(parents=True)
path.write_text(body, encoding="utf-8")
os.environ[cfg.XDG_CONFIG_HOME_ENV] = str(xdg)
return path
class ContractTests(unittest.TestCase):
def test_scoped_names_are_the_five_profile_settings(self):
self.assertEqual(
cfg.PROFILE_SCOPED_ENV,
(
"VAULT_DIR",
"VAULT_AGENT_NAME",
"VAULT_TIMEZONE",
"OPEN_SECOND_BRAIN_CONFIG",
"OPEN_SECOND_BRAIN_MCP_TIMEOUT",
),
)
self.assertEqual(cfg.REQUEST_TIMEOUT_ENV, "OPEN_SECOND_BRAIN_MCP_TIMEOUT")
def test_os_level_variables_are_not_scoped(self):
for name in ("XDG_CONFIG_HOME", "LOCALAPPDATA", "PATH", "PATHEXT", "HOME"):
self.assertNotIn(name, cfg.PROFILE_SCOPED_ENV)
def test_config_directories_are_scope_first(self):
self.assertEqual(cfg.SCOPE_FIRST_ENV, ("XDG_CONFIG_HOME", "LOCALAPPDATA"))
class WithoutHermesTests(ScopeTestCase):
"""(a) No ``agent.secret_scope``: today's answers."""
def test_not_multiplexed_and_process_environment_answers(self):
self.set_launch_env()
with self.no_hermes():
self.assertFalse(cfg.is_multiplexed())
self.assertEqual(cfg.resolve_agent_name(), "launch-agent-value")
self.assertEqual(cfg.resolve_vault(str(self.tmp)), "launch-vault-dir-value")
self.assertEqual(cfg.resolve_timezone(), "Launch/Zone")
self.assertEqual(cfg.config_path(), Path("launch-config-path-value.yaml"))
self.assertEqual(cfg.env_setting("VAULT_AGENT_NAME"), "launch-agent-value")
def test_empty_value_counts_as_unset(self):
os.environ["VAULT_AGENT_NAME"] = ""
with self.no_hermes():
self.assertIsNone(cfg.env_setting("VAULT_AGENT_NAME"))
class BrokenScopeModuleTests(ScopeTestCase):
"""A Hermes scope module that is present but fails to import fails closed."""
def _hermes_on_path(self, secret_scope_source: str | None):
"""A real ``agent`` package on ``sys.path``; ``None`` omits ``secret_scope``."""
root = Path(tempfile.mkdtemp(prefix="hermes-src-", dir=self.tmp))
package = root / "agent"
package.mkdir(parents=True)
(package / "__init__.py").write_text("", encoding="utf-8")
if secret_scope_source is not None:
(package / "secret_scope.py").write_text(secret_scope_source, encoding="utf-8")
stack = contextlib.ExitStack()
stack.enter_context(patch.object(sys, "path", [str(root), *sys.path]))
stack.enter_context(patch.dict(sys.modules))
for name in ("agent", "agent.secret_scope"):
sys.modules.pop(name, None)
return stack
def test_a_failing_import_refuses_scoped_reads_and_warns_once_by_type(self):
self.set_launch_env()
failures = {
"RuntimeError": "raise RuntimeError('launch-vault-dir-value')\n",
"ModuleNotFoundError": "import o2b_hermes_dependency_that_is_absent\n",
}
for type_name, source in failures.items():
with self.subTest(failure=type_name):
cfg._reset_scope_warnings_for_tests()
with (
self._hermes_on_path(source),
self.assertLogs("plugins.hermes.config", "WARNING") as logs,
):
self.assertTrue(cfg.is_multiplexed())
with self.assertRaises(cfg.ProfileScopeError):
cfg.resolve_agent_name()
with self.assertRaises(cfg.ProfileScopeError):
cfg.config_path()
self.assertEqual(cfg.env_setting("PATH"), os.environ.get("PATH") or None)
failed = [
r.getMessage() for r in logs.records if "failed to import" in r.getMessage()
]
self.assertEqual(len(failed), 1)
self.assertIn(type_name, failed[0])
for value in LAUNCH_VALUES.values():
self.assertNotIn(value, failed[0])
def test_a_failed_import_is_tried_once_until_reset(self):
calls = []
def failing_import(name, *args, **kwargs):
calls.append(name)
raise ImportError("scope module is broken")
with (
patch.object(cfg.importlib, "import_module", side_effect=failing_import),
self.assertLogs("plugins.hermes.config", "WARNING"),
):
for _ in range(2):
with self.assertRaises(cfg.ProfileScopeError):
cfg.env_setting("VAULT_AGENT_NAME")
self.assertEqual(calls, [cfg._SCOPE_MODULE_NAME])
cfg._reset_scope_warnings_for_tests()
with self.assertRaises(cfg.ProfileScopeError):
cfg.env_setting("VAULT_AGENT_NAME")
self.assertEqual(len(calls), 2)
def test_a_hermes_without_the_scope_module_reads_the_process_environment(self):
self.set_launch_env()
with self._hermes_on_path(None), self.assertNoLogs("plugins.hermes.config", "WARNING"):
self.assertFalse(cfg.is_multiplexed())
self.assertEqual(cfg.resolve_agent_name(), "launch-agent-value")
class MultiplexOffTests(ScopeTestCase):
"""(b) Hermes present, multiplexing off: the process environment wins."""
def test_process_environment_answers_and_the_scope_is_never_read(self):
self.set_launch_env()
pair = make_fake_scope(multiplexed=False, values={"VAULT_AGENT_NAME": "scoped-agent"})
with self.install(pair):
self.assertFalse(cfg.is_multiplexed())
self.assertEqual(cfg.resolve_agent_name(), "launch-agent-value")
self.assertEqual(cfg.resolve_vault(str(self.tmp)), "launch-vault-dir-value")
self.assertEqual(cfg.resolve_timezone(), "Launch/Zone")
self.assertEqual(cfg.config_path(), Path("launch-config-path-value.yaml"))
self.assertEqual(pair[1].reads, [])
class MultiplexedScopeTests(ScopeTestCase):
"""(c) Multiplexed with a bound scope: scoped values beat the launch env."""
def test_scoped_values_beat_conflicting_process_values(self):
self.set_launch_env()
scoped_config = self.tmp / "scoped.yaml"
pair = make_fake_scope(
multiplexed=True,
values={
"VAULT_DIR": "scoped-vault",
"VAULT_AGENT_NAME": "scoped-agent",
"VAULT_TIMEZONE": "Europe/Paris",
"OPEN_SECOND_BRAIN_CONFIG": str(scoped_config),
"OPEN_SECOND_BRAIN_MCP_TIMEOUT": "7",
},
)
with self.install(pair):
self.assertTrue(cfg.is_multiplexed())
self.assertEqual(cfg.resolve_vault(str(self.tmp)), "scoped-vault")
self.assertEqual(cfg.resolve_agent_name(), "scoped-agent")
self.assertEqual(cfg.resolve_timezone(), "Europe/Paris")
self.assertEqual(cfg.config_path(), scoped_config)
self.assertEqual(cfg.env_setting("OPEN_SECOND_BRAIN_MCP_TIMEOUT"), "7")
def test_config_directories_fall_back_to_the_process_when_the_scope_has_none(self):
xdg = self.tmp / "xdg"
os.environ[cfg.XDG_CONFIG_HOME_ENV] = str(xdg)
pair = make_fake_scope(multiplexed=True)
with self.install(pair):
self.assertEqual(cfg.config_path(), xdg / cfg.PLUGIN_NAME / cfg.CONFIG_FILENAME)
self.assertIn(cfg.XDG_CONFIG_HOME_ENV, pair[1].reads)
def test_the_scope_config_directory_beats_the_process_one(self):
os.environ[cfg.XDG_CONFIG_HOME_ENV] = str(self.tmp / "launch-xdg")
scoped = self.tmp / "profile-xdg"
pair = make_fake_scope(multiplexed=True, values={"XDG_CONFIG_HOME": str(scoped)})
with self.install(pair):
self.assertEqual(cfg.config_path(), scoped / cfg.PLUGIN_NAME / cfg.CONFIG_FILENAME)
def test_the_scope_local_app_data_beats_the_process_one(self):
scoped = self.tmp / "profile-local"
with patch.dict(os.environ, {"LOCALAPPDATA": str(self.tmp / "launch-local")}):
pair = make_fake_scope(multiplexed=True, values={"LOCALAPPDATA": str(scoped)})
with self.install(pair):
self.assertEqual(cfg._windows_local_app_data(), scoped)
empty = make_fake_scope(multiplexed=True)
with self.install(empty):
self.assertEqual(cfg._windows_local_app_data(), self.tmp / "launch-local")
off = make_fake_scope(multiplexed=False, values={"LOCALAPPDATA": str(scoped)})
with self.install(off):
self.assertEqual(cfg._windows_local_app_data(), self.tmp / "launch-local")
self.assertEqual(off[1].reads, [])
def test_unbound_scope_refuses_the_config_directories(self):
pair = make_fake_scope(multiplexed=True, unbound=True)
with self.install(pair):
for name in cfg.SCOPE_FIRST_ENV:
with self.subTest(name=name), self.assertRaises(cfg.ProfileScopeError):
cfg.scope_first_setting(name)
class MultiplexedEmptyScopeTests(ScopeTestCase):
"""(d) Multiplexed, empty scope: the config chain answers, never os.environ."""
def test_falls_through_to_the_config_file(self):
self.set_launch_env()
self.write_xdg_config(
'vault: "config-vault"\nagent_name: "config-agent"\ntimezone: "Asia/Tokyo"\n'
)
pair = make_fake_scope(multiplexed=True, values={"VAULT_AGENT_NAME": ""})
with self.install(pair):
self.assertEqual(cfg.resolve_vault(str(self.tmp)), "config-vault")
self.assertEqual(cfg.resolve_agent_name(), "config-agent")
self.assertEqual(cfg.resolve_timezone(), "Asia/Tokyo")
def test_falls_through_to_the_defaults(self):
self.set_launch_env()
os.environ[cfg.XDG_CONFIG_HOME_ENV] = str(self.tmp / "absent")
pair = make_fake_scope(multiplexed=True)
with self.install(pair):
self.assertIsNone(cfg.resolve_vault(str(self.tmp)))
self.assertEqual(cfg.resolve_agent_name(), cfg.DEFAULT_AGENT)
self.assertIsNone(cfg.resolve_timezone())
self.assertIsNone(cfg.env_setting("OPEN_SECOND_BRAIN_MCP_TIMEOUT"))
class UnboundScopeTests(ScopeTestCase):
"""(e) Multiplexed with no scope bound: a named, value-free refusal."""
def test_resolvers_raise_profile_scope_error(self):
self.set_launch_env()
pair = make_fake_scope(multiplexed=True, unbound=True)
for resolver in (lambda: cfg.resolve_vault(str(self.tmp)), cfg.resolve_agent_name):
with self.subTest(resolver=resolver), self.install(pair):
with self.assertRaises(cfg.ProfileScopeError) as caught:
resolver()
exc = caught.exception
self.assertIsInstance(exc, cfg.ConfigReadError)
self.assertIsInstance(exc.__cause__, FakeUnscopedError)
self.assertEqual(exc.path, "")
self.assertEqual(exc.reason, "no profile scope bound")
self.assertIn(exc.name, cfg.PROFILE_SCOPED_ENV)
message = str(exc)
for value in LAUNCH_VALUES.values():
self.assertNotIn(value, message)
def test_message_names_the_setting_and_the_remedy(self):
exc = cfg.ProfileScopeError("VAULT_AGENT_NAME")
self.assertEqual(exc.name, "VAULT_AGENT_NAME")
self.assertEqual(
str(exc),
"VAULT_AGENT_NAME cannot be resolved: this multiplexed Hermes gateway bound no "
"profile scope for the call, and Open Second Brain does not fall back to the "
"gateway's process environment, which belongs to the launch profile. Restart the "
"gateway (hermes gateway restart); if it persists, report it.",
)
class IgnoredProcessValueWarningTests(ScopeTestCase):
"""(c') and (g): one value-free WARNING per ignored name, once per process."""
def test_one_warning_per_ignored_name_without_its_value(self):
self.set_launch_env()
pair = make_fake_scope(multiplexed=True, values={"VAULT_AGENT_NAME": "scoped-agent"})
with self.install(pair), self.assertLogs("plugins.hermes.config", "WARNING") as logs:
cfg.resolve_agent_name()
cfg.resolve_timezone()
messages = [record.getMessage() for record in logs.records]
self.assertTrue(any("VAULT_AGENT_NAME" in m for m in messages))
self.assertTrue(any("VAULT_TIMEZONE" in m for m in messages))
for message in messages:
self.assertIn("multiplexed gateway", message)
for value in LAUNCH_VALUES.values():
self.assertNotIn(value, message)
def test_repeated_reads_warn_once(self):
os.environ["VAULT_AGENT_NAME"] = LAUNCH_VALUES["VAULT_AGENT_NAME"]
os.environ[cfg.XDG_CONFIG_HOME_ENV] = str(self.tmp / "absent")
pair = make_fake_scope(multiplexed=True, values={"VAULT_AGENT_NAME": "scoped-agent"})
with self.install(pair), self.assertLogs("plugins.hermes.config", "WARNING") as logs:
for _ in range(3):
cfg.resolve_agent_name()
named = [r for r in logs.records if "VAULT_AGENT_NAME" in r.getMessage()]
self.assertEqual(len(named), 1)
def test_no_warning_without_multiplexing_or_without_a_process_value(self):
pair = make_fake_scope(multiplexed=True, values={"VAULT_AGENT_NAME": "scoped-agent"})
with self.install(pair), self.assertNoLogs("plugins.hermes.config", "WARNING"):
cfg.resolve_agent_name()
os.environ["VAULT_AGENT_NAME"] = "launch-agent-value"
off = make_fake_scope(multiplexed=False)
with self.install(off), self.assertNoLogs("plugins.hermes.config", "WARNING"):
cfg.resolve_agent_name()
class ShadowingSourceTests(ScopeTestCase):
def test_multiplexed_names_the_profile_env_file(self):
pair = make_fake_scope(multiplexed=True, values={"VAULT_AGENT_NAME": "scoped-agent"})
with self.install(pair):
self.assertEqual(
cfg.shadowing_source("agent_name"),
"the VAULT_AGENT_NAME setting in this Hermes profile's .env overrides the "
"config file",
)
def test_multiplexed_ignores_the_process_environment(self):
self.set_launch_env()
os.environ[cfg.XDG_CONFIG_HOME_ENV] = str(self.tmp / "absent")
pair = make_fake_scope(multiplexed=True)
with self.install(pair):
self.assertIsNone(cfg.shadowing_source("agent_name"))
def test_without_multiplexing_the_text_is_unchanged(self):
os.environ["VAULT_AGENT_NAME"] = "launch-agent-value"
with self.no_hermes():
self.assertEqual(
cfg.shadowing_source("agent_name"),
"the VAULT_AGENT_NAME environment variable overrides the config file",
)
class ConfigCommandSourceTests(ScopeTestCase):
def _run_config(self):
from plugins.hermes import cli
out, err = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
rc = cli._config()
return rc, out.getvalue(), err.getvalue()
def test_first_line_names_the_process_environment(self):
os.environ[cfg.XDG_CONFIG_HOME_ENV] = str(self.tmp / "absent")
with self.no_hermes():
rc, out, _ = self._run_config()
self.assertEqual(rc, 0)
self.assertEqual(
out.splitlines()[0],
"settings_source: process environment (this command; a gateway with "
"gateway.multiplex_profiles reads each profile's .env)",
)
self.assertTrue(out.splitlines()[1].startswith("config_path:"))
def test_first_line_names_the_profile_scope(self):
os.environ[cfg.XDG_CONFIG_HOME_ENV] = str(self.tmp / "absent")
pair = make_fake_scope(multiplexed=True, values={"VAULT_AGENT_NAME": "scoped-agent"})
with self.install(pair):
rc, out, _ = self._run_config()
self.assertEqual(rc, 0)
lines = out.splitlines()
self.assertEqual(lines[0], "settings_source: profile scope (multiplexed gateway)")
self.assertIn("scoped-agent", out)
def test_unbound_scope_prints_the_named_error_and_exits_2(self):
self.set_launch_env()
pair = make_fake_scope(multiplexed=True, unbound=True)
with self.install(pair):
rc, out, err = self._run_config()
self.assertEqual(rc, 2)
self.assertEqual(out.splitlines()[0], "settings_source: profile scope (multiplexed gateway)")
self.assertIn("OPEN_SECOND_BRAIN_CONFIG cannot be resolved", err)
for value in LAUNCH_VALUES.values():
self.assertNotIn(value, out + err)
class StatusConfigScopeTests(ScopeTestCase):
def test_unbound_scope_skips_the_config_file_field(self):
self.set_launch_env()
pair = make_fake_scope(multiplexed=True, unbound=True)
with self.install(pair):
status = OpenSecondBrainMemoryProvider(bridge=FakeBrainBridge()).get_status_config({})
self.assertNotIn("config_file", status)
for value in LAUNCH_VALUES.values():
self.assertNotIn(value, json.dumps(status))
def test_bound_scope_reports_the_config_file(self):
scoped_config = self.tmp / "scoped.yaml"
pair = make_fake_scope(
multiplexed=True, values={"OPEN_SECOND_BRAIN_CONFIG": str(scoped_config)}
)
with self.install(pair):
status = OpenSecondBrainMemoryProvider(bridge=FakeBrainBridge()).get_status_config({})
self.assertEqual(status["config_file"], str(scoped_config))
class _HandshakeProcess:
"""A child that answers ``initialize`` and ``tools/list`` and nothing else."""
def __init__(self):
frames = [
{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2025-06-18"}},
{"jsonrpc": "2.0", "id": 2, "result": {"tools": []}},
]
self.stdin = io.BytesIO()
self.stdout = io.BytesIO(b"".join(json.dumps(f).encode() + b"\n" for f in frames))
self.stderr = None
self.pid = 4242
def poll(self):
return None
def terminate(self):
pass
def kill(self):
pass
def wait(self, timeout=None):
return 0
class ScopedChildEnvironmentTests(ScopeTestCase):
"""(f) Under multiplexing each profile gets its own MCP child identity."""
def tearDown(self):
provider_module._reset_shared_bridges_for_tests()
super().tearDown()
def _initialize(self, pair, factory, overlay=None):
with (
self.install(pair),
patch("plugins.hermes.provider.McpBrainBridge", side_effect=factory),
patch.object(OpenSecondBrainMemoryProvider, "_repo_root", return_value="/repo"),
patch.object(
OpenSecondBrainMemoryProvider, "_resolve_command", return_value=("o2b", "mcp")
),
patch.object(OpenSecondBrainMemoryProvider, "_resolve_env", return_value=overlay),
):
OpenSecondBrainMemoryProvider().initialize("session", hermes_home=str(self.tmp))
def test_child_env_carries_the_scoped_identity_only(self):
self.set_launch_env()
os.environ[cfg.XDG_CONFIG_HOME_ENV] = str(self.tmp / "absent")
built = []
pair = make_fake_scope(
multiplexed=True,
values={"VAULT_DIR": "shared-vault", "VAULT_AGENT_NAME": "scoped-agent"},
)
self._initialize(pair, lambda **kw: built.append(kw) or FakeBrainBridge())
self.assertEqual(len(built), 1)
env = built[0]["env"]
self.assertEqual(env["VAULT_AGENT_NAME"], "scoped-agent")
self.assertEqual(env["VAULT_DIR"], "shared-vault")
for name in ("VAULT_TIMEZONE", "OPEN_SECOND_BRAIN_CONFIG", "OPEN_SECOND_BRAIN_MCP_TIMEOUT"):
self.assertNotIn(name, env)
for value in LAUNCH_VALUES.values():
self.assertNotIn(value, env.values())
# The bridge never reads the deadline itself on this gateway.
self.assertEqual(built[0]["timeout"], bridge_module.DEFAULT_REQUEST_TIMEOUT_SECONDS)
def test_child_env_carries_the_scope_config_directory(self):
os.environ[cfg.XDG_CONFIG_HOME_ENV] = str(self.tmp / "launch-xdg")
scoped = str(self.tmp / "profile-xdg")
built = []
pair = make_fake_scope(
multiplexed=True, values={"VAULT_DIR": "v", "XDG_CONFIG_HOME": scoped}
)
self._initialize(pair, lambda **kw: built.append(kw) or FakeBrainBridge())
self.assertEqual(built[0]["env"]["XDG_CONFIG_HOME"], scoped)
def test_child_env_keeps_the_process_config_directory_the_scope_lacks(self):
launch = str(self.tmp / "launch-xdg")
os.environ[cfg.XDG_CONFIG_HOME_ENV] = launch
built = []
pair = make_fake_scope(multiplexed=True, values={"VAULT_DIR": "v"})
self._initialize(pair, lambda **kw: built.append(kw) or FakeBrainBridge())
self.assertEqual(built[0]["env"]["XDG_CONFIG_HOME"], launch)
def test_overlay_path_survives_the_scoping(self):
os.environ[cfg.XDG_CONFIG_HOME_ENV] = str(self.tmp / "absent")
built = []
pair = make_fake_scope(multiplexed=True, values={"VAULT_DIR": "v"})
overlay = {"PATH": "/opt/bun/bin", "VAULT_AGENT_NAME": "launch-agent-value"}
self._initialize(pair, lambda **kw: built.append(kw) or FakeBrainBridge(), overlay)
self.assertEqual(built[0]["env"]["PATH"], "/opt/bun/bin")
self.assertNotIn("VAULT_AGENT_NAME", built[0]["env"])
def test_scoped_timeout_reaches_the_bridge(self):
os.environ[cfg.XDG_CONFIG_HOME_ENV] = str(self.tmp / "absent")
built = []
for raw, expected in (("7", 7.0), ("0", 0.0)):
with self.subTest(raw=raw):
provider_module._reset_shared_bridges_for_tests()
built.clear()
pair = make_fake_scope(
multiplexed=True,
values={"VAULT_DIR": "v", "OPEN_SECOND_BRAIN_MCP_TIMEOUT": raw},
)
self._initialize(pair, lambda **kw: built.append(kw) or FakeBrainBridge())
self.assertEqual(built[0]["timeout"], expected)
def test_same_vault_different_agents_get_two_bridges(self):
os.environ[cfg.XDG_CONFIG_HOME_ENV] = str(self.tmp / "absent")
built = []
for agent in ("agent-one", "agent-two", "agent-one"):
pair = make_fake_scope(
multiplexed=True,
values={"VAULT_DIR": "shared-vault", "VAULT_AGENT_NAME": agent},
)
self._initialize(pair, lambda **kw: built.append(kw) or FakeBrainBridge())
self.assertEqual(
[kw["env"]["VAULT_AGENT_NAME"] for kw in built], ["agent-one", "agent-two"]
)
def test_same_config_different_config_directories_get_two_bridges(self):
shared = str(self.tmp / "shared-config.yaml")
built = []
for xdg in ("profile-one-xdg", "profile-two-xdg", "profile-one-xdg"):
pair = make_fake_scope(
multiplexed=True,
values={
"VAULT_DIR": "shared-vault",
"VAULT_AGENT_NAME": "same-agent",
"OPEN_SECOND_BRAIN_CONFIG": shared,
"XDG_CONFIG_HOME": str(self.tmp / xdg),
},
)
self._initialize(pair, lambda **kw: built.append(kw) or FakeBrainBridge())
self.assertEqual(
[kw["env"]["XDG_CONFIG_HOME"] for kw in built],
[str(self.tmp / "profile-one-xdg"), str(self.tmp / "profile-two-xdg")],
)
self.assertEqual(len(provider_module._SHARED_BRIDGES), 2)
def test_without_multiplexing_env_and_sharing_are_unchanged(self):
os.environ["VAULT_DIR"] = "launch-vault"
os.environ["VAULT_AGENT_NAME"] = "launch-agent-value"
built = []
off = make_fake_scope(multiplexed=False)
for _ in range(2):
self._initialize(off, lambda **kw: built.append(kw) or FakeBrainBridge())
self.assertEqual(len(built), 1)
self.assertIsNone(built[0]["env"])
self.assertNotIn("timeout", built[0])
self.assertEqual(off[1].reads, [])
class BridgeTimeoutFixedAtConstructionTests(ScopeTestCase):
"""(h) A restart from a plugin-owned thread never reads the scope."""
def test_fixed_timeout_restart_never_reads_the_scope(self):
pair = make_fake_scope(multiplexed=True, unbound=True)
bridge = McpBrainBridge(vault="v", spawn=lambda argv: _HandshakeProcess(), timeout=7.0)
errors = []
def restart():
try:
bridge.start()
except Exception as exc: # noqa: BLE001 - recorded for the assertion
errors.append(exc)
with self.install(pair):
thread = threading.Thread(target=restart)
thread.start()
thread.join(5)
self.assertEqual(errors, [])
self.assertEqual(pair[1].reads, [])
self.assertEqual(bridge._client._timeout, 7.0)
def test_non_positive_timeout_disables_the_deadline(self):
bridge = McpBrainBridge(vault="v", spawn=lambda argv: _HandshakeProcess(), timeout=0.0)
bridge.start()
self.assertIsNone(bridge._client._timeout)
def test_no_timeout_argument_keeps_reading_the_environment(self):
os.environ["OPEN_SECOND_BRAIN_MCP_TIMEOUT"] = "45"
with self.no_hermes():
bridge = McpBrainBridge(vault="v", spawn=lambda argv: _HandshakeProcess())
bridge.start()
self.assertEqual(bridge._client._timeout, 45.0)
def test_multiplexed_timeout_reads_the_scope(self):
os.environ["OPEN_SECOND_BRAIN_MCP_TIMEOUT"] = "4242"
pair = make_fake_scope(multiplexed=True, values={"OPEN_SECOND_BRAIN_MCP_TIMEOUT": "9"})
with self.install(pair):
self.assertEqual(bridge_module.resolve_request_timeout(), 9.0)
class RequestTimeoutValueTests(ScopeTestCase):
"""A timeout value that is not a finite number never becomes a deadline."""
def _resolve(self, raw):
os.environ["OPEN_SECOND_BRAIN_MCP_TIMEOUT"] = raw
with self.no_hermes():
return bridge_module.resolve_request_timeout()
def test_nan_falls_back_to_the_default_with_a_warning(self):
for raw in ("nan", "NaN", "-nan"):
with self.subTest(raw=raw), self.assertLogs("plugins.hermes.bridge", "WARNING") as logs:
self.assertEqual(self._resolve(raw), bridge_module.DEFAULT_REQUEST_TIMEOUT_SECONDS)
self.assertEqual(len(logs.records), 1)
def test_infinity_disables_the_deadline(self):
for raw in ("inf", "Infinity", "-inf"):
with self.subTest(raw=raw), self.assertNoLogs("plugins.hermes.bridge", "WARNING"):
self.assertIsNone(self._resolve(raw))
def test_malformed_value_warning_never_carries_the_value(self):
for raw in ("launch-timeout-value", "nan"):
with self.subTest(raw=raw), self.assertLogs("plugins.hermes.bridge", "WARNING") as logs:
self._resolve(raw)
message = logs.records[0].getMessage()
self.assertIn("OPEN_SECOND_BRAIN_MCP_TIMEOUT", message)
self.assertNotIn(raw, message)
def test_nan_scoped_timeouts_share_one_bridge(self):
os.environ[cfg.XDG_CONFIG_HOME_ENV] = str(self.tmp / "absent")
built = []
try:
for _ in range(2):
pair = make_fake_scope(
multiplexed=True,
values={"VAULT_DIR": "v", "OPEN_SECOND_BRAIN_MCP_TIMEOUT": "nan"},
)
with (
self.install(pair),
patch(
"plugins.hermes.provider.McpBrainBridge",
side_effect=lambda **kw: built.append(kw) or FakeBrainBridge(),
),
patch.object(OpenSecondBrainMemoryProvider, "_repo_root", return_value="/repo"),
patch.object(
OpenSecondBrainMemoryProvider,
"_resolve_command",
return_value=("o2b", "mcp"),
),
patch.object(OpenSecondBrainMemoryProvider, "_resolve_env", return_value=None),
):
OpenSecondBrainMemoryProvider().initialize("session", hermes_home=str(self.tmp))
finally:
provider_module._reset_shared_bridges_for_tests()
self.assertEqual(len(built), 1)
self.assertEqual(built[0]["timeout"], bridge_module.DEFAULT_REQUEST_TIMEOUT_SECONDS)
class PrefetchDegradeTests(ScopeTestCase):
"""(h) ``prefetch`` with no scope bound omits the reminder for the turn."""
def test_prefetch_degrades_and_warns_once(self):
# Recall the turn can still serve, so "omit the reminder" is told
# apart from "drop the whole turn".
bridge = FakeBrainBridge(
results={
"brain_recall_gate": {"structuredContent": {"retrieve": True, "reason": "hit"}},
"brain_context_pack": {
"structuredContent": {"generated_at": "2026-08-22"},
"content": [{"type": "text", "text": "SCOPED TURN RECALL"}],
},
}
)
provider = OpenSecondBrainMemoryProvider(bridge=bridge)
provider.initialize("session", hermes_home=str(self.tmp))
provider_module._reset_scope_degrade_warning_for_tests()
pair = make_fake_scope(multiplexed=True, unbound=True)
with self.install(pair), self.assertLogs("plugins.hermes.provider", "WARNING") as logs:
first = provider.prefetch("hello")
second = provider.prefetch("hello again")
self.assertIn("SCOPED TURN RECALL", first)
self.assertIn("SCOPED TURN RECALL", second)
degraded = [
r for r in logs.records if "no profile scope bound for this turn" in r.getMessage()
]
self.assertEqual(len(degraded), 1)
self.assertEqual(
degraded[0].getMessage(),
"open-second-brain: no profile scope bound for this turn; the vault reminder is "
"omitted",
)
if __name__ == "__main__":
unittest.main()