The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(memory): serve a memory provider only to the profile it was initialized for
unsupportedpastels419e6627aaed
diff --git a/agent/memory_caller_scope.py b/agent/memory_caller_scope.pynew file mode 100644index 00000000000..0a9eaaca13a--- /dev/null+++ b/agent/memory_caller_scope.py@@ -0,0 +1,145 @@+"""Which profile a memory-provider call or hook belongs to (#140058).++On a multiplexed gateway every served profile's turns run in one process. Each agent's manager owns+its own provider instance, bound by ``initialize_all`` to one profile home; the provider-side half of+the rule is the multiplexing contract in ``agent/memory_provider.py``. The manager's half lives here:++- a tool call or lifecycle hook runs only when the caller explicitly names the profile the manager was+ initialized for (the context's HERMES_HOME override, or the home its secret scope was built for).+ On a multiplexed process a caller that names no profile is refused, never resolved to the process's+ own profile; a single-profile process falls back to its home as before;+- one provider instance serves one profile: a plugin that hands several agents the same instance is+ refused for every profile after the first, instead of being rebound to it.++Refusals log the check's code and both homes; the model/chat only ever sees a generic refusal.+"""++from __future__ import annotations++import logging+import threading+import weakref+from typing import Any, Callable, Optional++logger = logging.getLogger(__name__)++CALLER_PROFILE_REFUSAL = "memory_caller_profile_unresolved"+SHARED_INSTANCE_REFUSAL = "memory_provider_instance_shared"++# id(provider) -> (weak reference to that very instance, profile home key). Keyed by identity, never+# by the provider's own __hash__/__eq__: an unhashable or value-equal provider is still tracked.+_claims: dict[int, tuple[weakref.ref, str]] = {}+_claims_lock = threading.RLock() # reentrant: a weakref callback can fire from GC inside the lock+++def refused_tool_message(tool_name: str) -> str:+ """What the model/chat sees for a refused memory tool call: no check name, no home paths."""+ return f"Memory tool '{tool_name}' refused. Ask the operator to check gateway.log."+++def _home_key(home: Any) -> Optional[str]:+ if not home:+ return None+ from hermes_constants import hermes_home_key+ try:+ return hermes_home_key(home)+ except (OSError, RuntimeError, ValueError): # unresolvable path: no key, so the call is refused+ return None+++def _explicit_caller_home() -> Optional[str]:+ """The profile the caller's context names: its HERMES_HOME override, else the home its secret+ scope was built for. None when the context names no profile (``get_hermes_home()`` would only fall+ back to the process home, which proves nothing on a multiplexed process)."""+ from agent.secret_scope import current_secret_scope_home+ from hermes_constants import get_hermes_home_override+ return get_hermes_home_override() or current_secret_scope_home()+++def _refuse(label: str, reason: str, caller_home: Any, bound_home: Any, multiplexed: bool) -> None:+ logger.warning("Memory %s refused (%s): %s; caller profile home %r, provider bound to %r, multiplexed=%s",+ label, CALLER_PROFILE_REFUSAL, reason, caller_home, bound_home, multiplexed)+++def caller_scope(bound: Optional[dict[str, Any]], label: str) -> Optional[dict[str, Any]]:+ """Provider kwargs naming the calling profile, or None when the call/hook must be refused.++ ``bound`` is what ``initialize_all`` recorded (``hermes_home``, ``agent_identity``); ``label``+ names the call in the log (``tool <name>`` / ``hook <name>``)."""+ from agent.secret_scope import is_multiplex_active+ bound = bound or {}+ bound_home = bound.get("hermes_home")+ multiplexed = is_multiplex_active()+ caller_home = _explicit_caller_home()+ if caller_home is None:+ if multiplexed:+ _refuse(label, "the caller names no profile on a process serving several", None, bound_home, multiplexed)+ return None+ from hermes_constants import get_hermes_home+ caller_home = str(get_hermes_home()) # single-profile process: its own home is the only one+ if not bound_home:+ if multiplexed:+ _refuse(label, "the memory manager recorded no profile", caller_home, None, multiplexed)+ return None+ return {"hermes_home": str(caller_home)}+ caller_key = _home_key(caller_home)+ if caller_key is None or caller_key != _home_key(bound_home):+ _refuse(label, "the caller's profile is not the one its provider was initialized for",+ caller_home, bound_home, multiplexed)+ return None+ scope: dict[str, Any] = {"hermes_home": str(bound_home)}+ if bound.get("agent_identity"):+ scope["agent_identity"] = bound["agent_identity"]+ return scope+++def _forget(pid: int, ref: weakref.ref) -> None:+ with _claims_lock:+ if _claims.get(pid, (None,))[0] is ref:+ del _claims[pid]+++def claim_instance(provider: Any, home: Any) -> bool:+ """Record that ``provider`` (the instance) is bound to ``home``. False on a multiplexed process+ when another profile already bound this same instance (initializing it again would rebind the+ other profile's store), or when the instance can't be tracked at all (no weak reference)."""+ from agent.secret_scope import is_multiplex_active+ key = _home_key(home) or str(home)+ multiplexed = is_multiplex_active()+ pid = id(provider)+ with _claims_lock:+ entry = _claims.get(pid)+ owner = entry[1] if entry is not None and entry[0]() is provider else None+ if owner is not None and owner != key and multiplexed:+ logger.warning("Memory provider '%s' refused for profile home %r (%s): this same provider instance "+ "is already bound to %r; a provider must give every agent its own instance",+ getattr(provider, "name", "?"), str(home), SHARED_INSTANCE_REFUSAL, owner)+ return False+ try:+ ref = weakref.ref(provider, lambda dead, pid=pid: _forget(pid, dead))+ except TypeError:+ if multiplexed:+ logger.warning("Memory provider '%s' refused for profile home %r (%s): the instance can't be "+ "tracked (no weak reference support), so sharing it can't be ruled out",+ getattr(provider, "name", "?"), str(home), SHARED_INSTANCE_REFUSAL)+ return False+ return True+ _claims[pid] = (ref, key)+ return True+++def in_owner_home(bound: Optional[dict[str, Any]], fn: Callable[[], Any]) -> Callable[[], Any]:+ """``fn`` run under the owning profile's HERMES_HOME override, set explicitly: a background+ worker must not depend on the submitter's context having carried it."""+ home = (bound or {}).get("hermes_home")+ if not home:+ return fn++ def _run() -> Any:+ from hermes_constants import reset_hermes_home_override, set_hermes_home_override+ token = set_hermes_home_override(str(home))+ try:+ return fn()+ finally:+ reset_hermes_home_override(token)+ return _rundiff --git a/agent/memory_manager.py b/agent/memory_manager.pyindex 817145fe9e0..f0ec422710d 100644--- a/agent/memory_manager.py+++ b/agent/memory_manager.py@@ -18,6 +18,7 @@ from typing import Any, Callable, Dict, List, Optionalfrom agent.redact import redact_for_egress+from agent.memory_caller_scope import caller_scope, claim_instance, in_owner_home, refused_tool_messagefrom agent.memory_provider import MemoryProvider, PRE_COMPRESS_CHECKPOINT_API_VERSION, ctx_bound, spawn_context_threadfrom agent.skill_commands import extract_user_instruction_from_skill_messagefrom tools.hook_output_spill import get_spill_config, spill_if_oversized@@ -245,6 +246,8 @@ class MemoryManager:self._shutdown_drain_state: dict[str, Any] = {"status": "not_started", "abandoned_writes": 0, "abandoned_prefetches": 0, "active_tasks": 0,}+ # The profile ``initialize_all`` bound the providers to; tool calls must come from it (#140058).+ self._bound_scope: Optional[dict[str, Any]] = Nonedef _each_provider(self, label: str, call: Callable[[MemoryProvider], Any], *, level: int = logging.DEBUG,providers: Optional[list[MemoryProvider]] = None, exc_info: bool = False) -> list[Any]:@@ -258,6 +261,16 @@ class MemoryManager:logger.log(level, "Memory provider '%s' %s: %s", provider.name, label, e, exc_info=exc_info)return results+ def _owner_allows(self, hook: str) -> bool:+ """Whether a lifecycle hook may reach the providers: only from the profile they were initialized+ for (#140058; see ``agent/memory_caller_scope.py``). Nothing to reach, nothing to refuse."""+ return not self._providers or caller_scope(self._bound_scope, f"hook {hook}") is not None++ def _drop_provider(self, provider: MemoryProvider) -> None:+ self._providers = [p for p in self._providers if p is not provider]+ self._tool_to_provider = {t: p for t, p in self._tool_to_provider.items() if p is not provider}+ self._has_external = any(p.name != "builtin" for p in self._providers)+def add_provider(self, provider: MemoryProvider) -> None:"""Register a provider; builtin always accepted, only ONE external allowed."""if provider.name != "builtin" and self._has_external:@@ -338,7 +351,7 @@ class MemoryManager:def prefetch_all(self, query: str, *, session_id: str = "") -> str:"""Merge non-empty prefetch context from all providers (failures are non-fatal)."""clean_query = self._strip_skill_scaffolding(query)- if not clean_query:+ if not clean_query or not self._owner_allows("prefetch"):return ""clean_query = _redact_for_provider(clean_query)parts = self._each_provider(@@ -409,7 +422,7 @@ class MemoryManager:"""Queue background prefetch on all providers for the next turn (see ``sync_all``)."""providers = list(self._providers)clean_query = self._strip_skill_scaffolding(query) if providers else None- if not clean_query:+ if not clean_query or not self._owner_allows("queue_prefetch"):returnclean_query = _redact_for_provider(clean_query)self._submit_background(lambda: self._each_provider(@@ -438,7 +451,7 @@ class MemoryManager:"""providers = list(self._providers)clean_user_content = self._strip_skill_scaffolding(user_content) if providers else None- if not clean_user_content:+ if not clean_user_content or not self._owner_allows("sync_turn"):returnclean_user_content, assistant_content, redacted_messages = _redact_for_provider(clean_user_content, assistant_content, messages)@@ -459,7 +472,7 @@ class MemoryManager:"""Queue ``fn`` on the serialized worker (created lazily; None once shutting down) and track itsdurability class. Runs under the caller's contextvars (``ctx_bound``). If the executor isunavailable outside shutdown, run inline — the historical fail-safe."""- fn = ctx_bound(fn)+ fn = ctx_bound(in_owner_home(self._bound_scope, fn))executor = None if self._shutting_down else self._sync_executorif executor is None and not self._shutting_down:with self._sync_executor_lock:@@ -544,6 +557,14 @@ class MemoryManager:provider = self._tool_to_provider.get(tool_name)if provider is None:return tool_error(f"No memory provider handles tool '{tool_name}'")+ scope = caller_scope(self._bound_scope, f"tool {tool_name}")+ if scope is None:+ return tool_error(refused_tool_message(tool_name))+ kwargs = {**kwargs, **scope}+ # A provider written against ``handle_tool_call(tool_name, args)`` gets only what it declares.+ params = _signature_params(provider.handle_tool_call)+ if params is not None and not _has_var_kwargs(params):+ kwargs = {k: v for k, v in kwargs.items() if k in params}args = _redact_for_provider(args)from hermes_cli.observability.shared_metrics_loop import record_provider_memory_calltry:@@ -556,6 +577,8 @@ class MemoryManager:return resultdef on_turn_start(self, turn_number: int, message: str, **kwargs) -> None:+ if not self._owner_allows("on_turn_start"):+ returnmessage = _redact_for_provider(message)def _tick(p: MemoryProvider) -> None:@@ -567,6 +590,8 @@ class MemoryManager:self._each_provider("on_turn_start failed", _tick)def on_session_end(self, messages: list[dict[str, Any]]) -> None:+ if not self._owner_allows("on_session_end"):+ returnmessages = _redact_messages_for_egress(messages or [])self._each_provider("on_session_end failed", lambda p: p.on_session_end(messages), level=logging.WARNING,exc_info=True)@@ -588,7 +613,7 @@ class MemoryManager:share the same worker. If the executor is unavailable, ``_submit_background`` degrades to inlineexecution — the pre-#16454 synchronous behavior, slow but correct."""- if not self._providers:+ if not self._providers or not self._owner_allows("session_boundary"):returnsnapshot = list(messages or [])@@ -609,7 +634,7 @@ class MemoryManager:"""Notify providers that ``AIAgent.session_id`` rotated without teardown(``/resume``, ``/branch``, ``/reset``, ``/new``, compression). ``rewound=True``(``/undo``): same id, truncated transcript."""- if not new_session_id:+ if not new_session_id or not self._owner_allows("on_session_switch"):returnif rewound: # forward only when set so it never pollutes providers' **kwargskwargs["rewound"] = True@@ -640,6 +665,10 @@ class MemoryManager:only to checkpoint (v2+) providers. With ``require_checkpoint`` at least one checkpoint providermust succeed — its exception propagates so the caller keeps the uncompressed transcript."""+ if not self._owner_allows("on_pre_compress"):+ if require_checkpoint: # the caller keeps the uncompressed transcript+ raise RuntimeError("Memory pre-compress checkpoint refused; see gateway.log")+ return ""parts = []checkpoint_succeeded = Falsemessages, evidence_messages = _redact_for_provider(messages or [], evidence_messages)@@ -681,6 +710,8 @@ class MemoryManager:def on_memory_write(self, action: str, target: str, content: str,metadata: Optional[dict[str, Any]] = None) -> None:"""Notify external providers when the built-in memory tool writes (skips builtin, the source)."""+ if not self._owner_allows("on_memory_write"):+ returncontent, metadata = _redact_for_provider(content, dict(metadata or {}))def _notify(provider: MemoryProvider) -> None:@@ -762,6 +793,8 @@ class MemoryManager:logger.debug("notify_memory_tool_write failed for op %s: %s", action, e)def on_delegation(self, task: str, result: str, *, child_session_id: str = "", **kwargs) -> None:+ if not self._owner_allows("on_delegation"):+ returntask, result = _redact_for_provider(task, result)self._each_provider("on_delegation failed",@@ -821,5 +854,10 @@ class MemoryManager:if "hermes_home" not in kwargs:from hermes_constants import get_hermes_homekwargs["hermes_home"] = str(get_hermes_home())+ self._bound_scope = {key: kwargs.get(key) for key in ("hermes_home", "agent_identity")}+ # One instance, one profile: never rebind an instance another profile's manager bound (#140058).+ for provider in [p for p in self._providers if p.name != "builtin"]:+ if not claim_instance(provider, kwargs["hermes_home"]):+ self._drop_provider(provider)self._each_provider("initialize failed", lambda p: p.initialize(session_id=session_id, **kwargs),level=logging.WARNING)diff --git a/agent/memory_provider.py b/agent/memory_provider.pyindex 8641636b4c5..c9970466082 100644--- a/agent/memory_provider.py+++ b/agent/memory_provider.py@@ -82,7 +82,25 @@ def is_trivial_prompt(text: Optional[str]) -> bool:class MemoryProvider(ABC):- """Abstract base class for memory providers."""+ """Abstract base class for memory providers.++ Multiplexing contract (#140058). One gateway process can serve several profiles, and each agent's+ ``MemoryManager`` owns its own provider instance, initialized for one profile. A provider must:++ - hand every load a NEW instance (``register(ctx)`` / the loader constructs one per agent). The+ manager refuses an instance another profile's manager already bound, rather than rebinding it;+ - bind every store, path, client, bank or tenant from ``initialize()``'s ``hermes_home`` (and+ scoped secrets read during ``initialize``) and keep that binding on the instance;+ - keep no profile-specific mutable state at module or class level, and never "rebind" a shared+ binding per call: two profiles' calls interleave on different threads.++ The manager runs tool calls and lifecycle hooks only from the profile the instance was initialized+ for (refusing callers that name another profile, or none on a multiplexed process), runs its+ background hooks under that profile's ``HERMES_HOME``, and passes ``hermes_home`` /+ ``agent_identity`` / ``caller_gsk`` to ``handle_tool_call`` when it accepts ``**kwargs``. Those+ keywords name the same profile the instance is bound to; they are not a reason to rebind. Core+ cannot see inside a provider: one that keeps a process-wide binding still breaks this contract.+ """# Providers that durably checkpoint every successful on_pre_compress() set this to# PRE_COMPRESS_CHECKPOINT_API_VERSION; 1 = best-effort legacy.diff --git a/plugins/memory/byterover/__init__.py b/plugins/memory/byterover/__init__.pyindex 18bc35ca0d3..8a3bd35be44 100644--- a/plugins/memory/byterover/__init__.py+++ b/plugins/memory/byterover/__init__.py@@ -172,7 +172,10 @@ class ByteRoverMemoryProvider(MemoryProvider):]def initialize(self, session_id: str, **kwargs) -> None:- self._cwd, self._session_id, self._turn_count = str(_get_brv_cwd()), session_id, 0+ # Bind to the profile the manager names, not the ambient one (multiplexing contract, MemoryProvider).+ home = kwargs.get("hermes_home")+ cwd = Path(home) / "byterover" if home else _get_brv_cwd()+ self._cwd, self._session_id, self._turn_count = str(cwd), session_id, 0Path(self._cwd).mkdir(parents=True, exist_ok=True)def system_prompt_block(self) -> str:diff --git a/plugins/memory/retaindb/__init__.py b/plugins/memory/retaindb/__init__.pyindex 22685adaa78..fde208da1d8 100644--- a/plugins/memory/retaindb/__init__.py+++ b/plugins/memory/retaindb/__init__.py@@ -340,8 +340,9 @@ class RetainDBMemoryProvider(MemoryProvider):self._client = _Client(get_secret("RETAINDB_API_KEY", "") or "", base_url, project)self._session_id, self._user_id = session_id, kwargs.get("user_id", "default") or "default"self._agent_id = kwargs.get("agent_id", "hermes") or "hermes"+ # Bind to the profile the manager names, not the ambient one (multiplexing contract, MemoryProvider).from hermes_constants import get_hermes_home- home = get_hermes_home()+ home = Path(kwargs["hermes_home"]) if kwargs.get("hermes_home") else get_hermes_home()self._queue = _WriteQueue(self._client, home / "retaindb_queue.db")soul = (home / "SOUL.md").read_text(encoding="utf-8-sig", errors="replace").strip() if (home / "SOUL.md").exists() else ""if soul: # seed agent identity from SOUL.md in backgrounddiff --git a/tests/agent/test_memory_provider.py b/tests/agent/test_memory_provider.pyindex cd9ad12fc8b..a6da59e632d 100644--- a/tests/agent/test_memory_provider.py+++ b/tests/agent/test_memory_provider.py@@ -304,6 +304,7 @@ class TestMemoryManager:provider._prefetch_result = textmgr = MemoryManager()mgr.add_provider(provider)+ mgr.initialize_all(session_id="s") # bound to this scope's profile, as agents aremanagers[home] = mgrmgr = managers[home]if home == b:@@ -329,6 +330,7 @@ class TestMemoryManager:try:fresh = MemoryManager()fresh.add_provider(provider := FakeMemoryProvider("external"))+ fresh.initialize_all(session_id="fresh")provider._prefetch_result = textassert fresh.prefetch_all("recall", session_id="fresh") == textassert not (a / "recall" / "fresh").exists()diff --git a/tests/agent/test_memory_provider_caller_profile.py b/tests/agent/test_memory_provider_caller_profile.pynew file mode 100644index 00000000000..52d33157166--- /dev/null+++ b/tests/agent/test_memory_provider_caller_profile.py@@ -0,0 +1,457 @@+"""PLG-11 (#140058): a memory-provider tool call belongs to the calling turn's profile.++On a multiplexed gateway every served profile's turns run in one process, so anything a provider+module keeps at module or class level is shared by all of them. These tests drive the real+sequential and concurrent dispatch helpers with real ``MemoryManager`` instances.+"""+import json+import threading+from types import SimpleNamespace++import pytest++from agent.inline_tool_executors import resolve_invoke_tool_executor+from agent.memory_manager import MemoryManager+from agent.memory_provider import MemoryProvider, ctx_bound+from agent.secret_scope import is_multiplex_active+from agent.tool_executor import _resolve_sequential_dispatch, _ToolCallRef+from hermes_constants import reset_hermes_home_override, set_hermes_home_override++_TOOL = "pw_remember"+++class _ProcessWideProvider(MemoryProvider):+ """The reported provider's shape: one store binding per PROCESS, set by whichever profile+ initialized last. A call that names its caller's home rebinds; one that doesn't writes wherever+ the binding points."""++ binding = None+ stores: dict = {}+ calls: list = []++ @property+ def name(self):+ return "processwide"++ def is_available(self):+ return True++ def initialize(self, session_id, **kwargs):+ type(self).binding = kwargs["hermes_home"]++ def get_tool_schemas(self):+ return [{"name": _TOOL, "description": "remember", "parameters": {"type": "object", "properties": {}}}]++ def handle_tool_call(self, tool_name, args, **kwargs):+ type(self).calls.append(kwargs)+ home = kwargs.get("hermes_home") or type(self).binding+ type(self).stores.setdefault(home, []).append(args["content"])+ return json.dumps({"ok": True})+++class _BareSignatureProvider(_ProcessWideProvider):+ """A provider written against the two-argument ``handle_tool_call`` shape."""++ def handle_tool_call(self, tool_name, args):+ type(self).stores.setdefault("bare", []).append(args["content"])+ return json.dumps({"ok": True})++[email protected](autouse=True)+def _fresh_provider_state():+ _ProcessWideProvider.binding = None+ _ProcessWideProvider.stores = {}+ _ProcessWideProvider.calls = []+ yield+++class _Scope:+ def __init__(self, home):+ self.home = home++ def __enter__(self):+ self.token = set_hermes_home_override(str(self.home))++ def __exit__(self, *exc):+ reset_hermes_home_override(self.token)+++def _agent(home, gsk, provider_cls=_ProcessWideProvider, *, initialize=True):+ manager = MemoryManager()+ with _Scope(home):+ manager.add_provider(provider_cls())+ if initialize:+ manager.initialize_all(session_id=f"s-{home.name}", platform="api_server", hermes_home=str(home))+ return SimpleNamespace(+ _memory_manager=manager, _context_engine_tool_names=set(), _gateway_session_key=gsk,+ _should_emit_quiet_tool_messages=lambda: False, _should_start_quiet_spinner=lambda: False,+ )+++def _sequential(agent, content):+ ref = _ToolCallRef(name=_TOOL, args={"content": content}, task_id="t", call_id="c", trace=[])+ return _resolve_sequential_dispatch(agent, ref, []).execute({"content": content})+++def _concurrent(agent, content):+ executor = resolve_invoke_tool_executor(agent, _TOOL)+ assert executor is not None+ return executor(agent, {"content": content}, SimpleNamespace())+++def homes(tmp_path):+ root = tmp_path / ".hermes"+ alpha, beta = root / "profiles" / "alpha", root / "profiles" / "beta"+ for home in (alpha, beta):+ home.mkdir(parents=True)+ return alpha, beta+++def test_interleaved_turns_of_two_profiles_write_to_their_own_stores(homes):+ alpha_home, beta_home = homes+ alpha = _agent(alpha_home, "agent:alpha:api_server:dm:1")+ beta = _agent(beta_home, "agent:beta:api_server:dm:2") # initialized last: owns the process-wide binding+ barrier, errors = threading.Barrier(2), []++ def turn(agent, home, label):+ try:+ with _Scope(home):+ barrier.wait(timeout=5)+ for i in range(20):+ result = (_sequential if i % 2 else _concurrent)(agent, f"{label}-{i}")+ assert json.loads(result) == {"ok": True}, result+ except Exception as exc: # surfaced below; a thread can't fail the test itself+ errors.append(exc)++ threads = [threading.Thread(target=turn, args=(alpha, alpha_home, "alpha")),+ threading.Thread(target=turn, args=(beta, beta_home, "beta"))]+ for thread in threads:+ thread.start()+ for thread in threads:+ thread.join(timeout=10)+ assert not errors, errors+ stores = _ProcessWideProvider.stores+ assert sorted(stores.get(str(alpha_home), [])) == sorted(f"alpha-{i}" for i in range(20)), stores+ assert sorted(stores.get(str(beta_home), [])) == sorted(f"beta-{i}" for i in range(20)), stores+ # The caller's gateway session key still travels with each call.+ assert {call["caller_gsk"] for call in _ProcessWideProvider.calls} == {+ "agent:alpha:api_server:dm:1", "agent:beta:api_server:dm:2"}+++_REFUSAL_CODE = "memory_caller_profile_unresolved"+++def _assert_generic_refusal(result, caplog, *homes):+ """The model/chat sees a generic refusal; gateway.log keeps the check's code and the homes."""+ error = result.get("error", "")+ assert "refused" in error and "gateway.log" in error, result+ assert _REFUSAL_CODE not in error and not any(str(home) in error for home in homes), result+ logged = "\n".join(r.getMessage() for r in caplog.records if r.name == "agent.memory_caller_scope")+ assert _REFUSAL_CODE in logged, logged+ assert all(str(home) in logged for home in homes), logged+++def multiplexed():+ from agent.secret_scope import reset_multiplex_context, set_multiplex_context+ token = set_multiplex_context(True)+ yield+ reset_multiplex_context(token)++[email protected]("dispatch", [_sequential, _concurrent])+def test_call_from_another_profiles_scope_is_refused(homes, dispatch, caplog):+ alpha_home, beta_home = homes+ alpha = _agent(alpha_home, "agent:alpha:api_server:dm:1")+ with _Scope(beta_home): # the turn's scope names a profile this manager never served+ result = json.loads(dispatch(alpha, "stray"))+ _assert_generic_refusal(result, caplog, alpha_home, beta_home)+ assert _ProcessWideProvider.stores == {}+++def test_multiplexed_call_with_no_known_profile_is_refused(homes, multiplexed, caplog):+ alpha_home, _ = homes+ agent = _agent(alpha_home, "", initialize=False)+ with _Scope(alpha_home):+ result = json.loads(_sequential(agent, "orphan"))+ _assert_generic_refusal(result, caplog, alpha_home)+ assert _ProcessWideProvider.stores == {}++[email protected]("dispatch", [_sequential, _concurrent])+def test_multiplexed_call_without_a_caller_scope_is_refused_even_for_the_process_profile(+ homes, dispatch, multiplexed, monkeypatch, caplog):+ # The manager serves the process's own (launch) profile, but on a multiplexed process a call that+ # names no profile is not proof it came from that profile's turn.+ alpha_home, _ = homes+ monkeypatch.setenv("HERMES_HOME", str(alpha_home))+ alpha = _agent(alpha_home, "agent:alpha:api_server:dm:1")+ token = set_hermes_home_override(None)+ try:+ result = json.loads(dispatch(alpha, "unscoped"))+ finally:+ reset_hermes_home_override(token)+ _assert_generic_refusal(result, caplog, alpha_home)+ assert _ProcessWideProvider.stores == {}+++def test_single_profile_process_keeps_working_without_initialize(homes):+ alpha_home, _ = homes+ agent = _agent(alpha_home, "", initialize=False)+ with _Scope(alpha_home):+ assert json.loads(_sequential(agent, "plain")) == {"ok": True}+++def test_two_argument_provider_signature_still_receives_its_calls(homes):+ alpha_home, _ = homes+ agent = _agent(alpha_home, "agent:alpha:api_server:dm:1", _BareSignatureProvider)+ with _Scope(alpha_home):+ assert json.loads(_sequential(agent, "one")) == {"ok": True}+ assert json.loads(_concurrent(agent, "two")) == {"ok": True}+ assert _ProcessWideProvider.stores == {"bare": ["one", "two"]}+++# -- Provider-side contract and lifecycle hooks --------------------------------------------------------++_HOOK_TOOL = "ct_remember"+++class _InstanceScopedProvider(MemoryProvider):+ """A provider that meets the multiplexing contract: its store binding lives on the instance, set+ from ``initialize``'s ``hermes_home``. Records which binding, and which ambient home, every call+ and hook ran under."""++ events: list = []++ def __init__(self):+ self._home = None++ @property+ def name(self):+ return "instancescoped"++ def is_available(self):+ return True++ def initialize(self, session_id, **kwargs):+ self._home = kwargs["hermes_home"]++ def _record(self, what):+ from hermes_constants import get_hermes_home+ type(self).events.append((what, self._home, str(get_hermes_home())))++ def get_tool_schemas(self):+ return [{"name": _HOOK_TOOL, "description": "remember", "parameters": {"type": "object", "properties": {}}}]++ def handle_tool_call(self, tool_name, args, **kwargs):+ assert kwargs["hermes_home"] == self._home, (kwargs, self._home)+ self._record("tool")+ return json.dumps({"ok": True})++ def prefetch(self, query, *, session_id=""):+ self._record("prefetch")+ return ""++ def queue_prefetch(self, query, *, session_id=""):+ self._record("queue_prefetch")++ def sync_turn(self, user_content, assistant_content, *, session_id=""):+ self._record("sync_turn")++ def on_turn_start(self, turn_number, message, **kwargs):+ self._record("on_turn_start")++ def on_session_end(self, messages):+ self._record("on_session_end")++ def on_session_switch(self, new_session_id, **kwargs):+ self._record("on_session_switch")++ def on_pre_compress(self, messages):+ self._record("on_pre_compress")+ return ""++ def on_memory_write(self, action, target, content, metadata=None):+ self._record("on_memory_write")++ def on_delegation(self, task, result, *, child_session_id="", **kwargs):+ self._record("on_delegation")++[email protected](autouse=True)+def _fresh_events():+ _InstanceScopedProvider.events = []+ yield+++def _manager(home, provider=None):+ manager = MemoryManager()+ with _Scope(home):+ manager.add_provider(provider or _InstanceScopedProvider())+ manager.initialize_all(session_id=f"s-{home.name}", platform="api_server", hermes_home=str(home))+ return manager+++def _drain(manager):+ assert manager.flush_pending(timeout=5)+++# hook name -> drives it through the manager the way the agent does (background ones are drained)+_HOOKS = {+ "sync_turn": lambda m: (m.sync_all("what did we decide", "the plan", session_id="s"), _drain(m)),+ "queue_prefetch": lambda m: (m.queue_prefetch_all("what did we decide", session_id="s"), _drain(m)),+ "prefetch": lambda m: m.prefetch_all("what did we decide", session_id="s"),+ "on_turn_start": lambda m: m.on_turn_start(1, "what did we decide"),+ "on_session_end": lambda m: m.on_session_end([]),+ "on_session_switch": lambda m: m.on_session_switch("s2"),+ "session_boundary": lambda m: (m.commit_session_boundary_async([], new_session_id="s3"), _drain(m)),+ "on_pre_compress": lambda m: m.on_pre_compress([{"role": "user", "content": "x"}]),+ "on_memory_write": lambda m: m.on_memory_write("add", "memory", "a fact"),+ "on_delegation": lambda m: m.on_delegation("task", "result"),+}++[email protected]("hook", sorted(_HOOKS))+def test_lifecycle_hook_from_another_profiles_scope_is_refused(homes, hook, caplog):+ alpha_home, beta_home = homes+ alpha = _manager(alpha_home)+ with _Scope(beta_home):+ _HOOKS[hook](alpha)+ assert _InstanceScopedProvider.events == []+ logged = "\n".join(r.getMessage() for r in caplog.records if r.name == "agent.memory_caller_scope")+ assert _REFUSAL_CODE in logged and str(beta_home) in logged, logged++[email protected]("hook", sorted(_HOOKS))+def test_multiplexed_lifecycle_hook_without_a_caller_scope_is_refused(homes, hook, multiplexed, monkeypatch):+ alpha_home, _ = homes+ monkeypatch.setenv("HERMES_HOME", str(alpha_home))+ alpha = _manager(alpha_home)+ _HOOKS[hook](alpha)+ assert _InstanceScopedProvider.events == []+++def test_refused_checkpoint_compression_fails_closed(homes):+ alpha_home, beta_home = homes+ alpha = _manager(alpha_home)+ with _Scope(beta_home), pytest.raises(RuntimeError):+ alpha.on_pre_compress([{"role": "user", "content": "x"}], require_checkpoint=True)+++def test_background_hook_runs_under_the_owning_profile_explicitly(homes, multiplexed):+ # The turn proves its profile through the secret scope alone (no HERMES_HOME override): the+ # background worker must still run the provider under the owner's home, not the process's.+ from agent.secret_scope import reset_secret_scope, set_secret_scope+ alpha_home, _ = homes+ alpha = _manager(alpha_home)+ token = set_secret_scope({}, profile_home=str(alpha_home))+ try:+ alpha.sync_all("what did we decide", "the plan", session_id="s")+ _drain(alpha)+ finally:+ reset_secret_scope(token)+ assert _InstanceScopedProvider.events == [("sync_turn", str(alpha_home), str(alpha_home))]+++def test_two_profiles_interleaving_tool_calls_and_hooks_stay_in_their_own_stores(homes, multiplexed):+ alpha_home, beta_home = homes+ managers = {alpha_home: _manager(alpha_home), beta_home: _manager(beta_home)}+ barrier, errors = threading.Barrier(2), []++ def turns(home):+ manager = managers[home]+ agent = SimpleNamespace(+ _memory_manager=manager, _context_engine_tool_names=set(), _gateway_session_key=f"agent:{home.name}:dm",+ _should_emit_quiet_tool_messages=lambda: False, _should_start_quiet_spinner=lambda: False)+ try:+ assert is_multiplex_active(), "the worker lost the multiplexed mode"+ with _Scope(home):+ barrier.wait(timeout=5)+ for i in range(10):+ ref = _ToolCallRef(name=_HOOK_TOOL, args={}, task_id="t", call_id="c", trace=[])+ if i % 2:+ assert json.loads(_resolve_sequential_dispatch(agent, ref, []).execute({})) == {"ok": True}+ else:+ assert json.loads(resolve_invoke_tool_executor(agent, _HOOK_TOOL)(agent, {}, SimpleNamespace())) == {"ok": True}+ for hook in sorted(_HOOKS):+ _HOOKS[hook](manager)+ except Exception as exc: # surfaced below+ errors.append(exc)++ # Each worker runs under its own copy of this context, so it inherits the multiplexed mode.+ threads = [threading.Thread(target=ctx_bound(turns), args=(home,)) for home in managers]+ for thread in threads:+ thread.start()+ for thread in threads:+ thread.join(timeout=30)+ assert not errors, errors+ events = _InstanceScopedProvider.events+ for home in managers:+ mine = [e for e in events if e[1] == str(home)]+ assert {e[0] for e in mine} >= {"tool", *{h for h in _HOOKS if h != "session_boundary"}}, mine+ assert all(ambient == str(home) for _, _, ambient in mine), mine+ assert len(events) == sum(1 for e in events if e[1] in {str(alpha_home), str(beta_home)})+++def test_one_provider_instance_is_never_served_to_a_second_profile(homes, multiplexed, caplog):+ # A plugin that hands every agent the SAME instance keeps one binding for the whole process.+ # It stays with the profile that initialized it; another profile's manager refuses it.+ alpha_home, beta_home = homes+ shared = _InstanceScopedProvider()+ alpha = _manager(alpha_home, shared)+ beta = _manager(beta_home, shared)+ assert shared._home == str(alpha_home)+ assert not beta.has_tool(_HOOK_TOOL) and beta.providers == []+ with _Scope(alpha_home):+ assert json.loads(alpha.handle_tool_call(_HOOK_TOOL, {})) == {"ok": True}+ assert [e[1] for e in _InstanceScopedProvider.events] == [str(alpha_home)]+ logged = "\n".join(r.getMessage() for r in caplog.records if r.name == "agent.memory_caller_scope")+ assert "memory_provider_instance_shared" in logged and str(beta_home) in logged, logged+++class _UnhashableProvider(_InstanceScopedProvider):+ __hash__ = None+++class _ValueEqualProvider(_InstanceScopedProvider):+ """Every instance compares (and hashes) equal to every other: equality is not identity."""++ def __eq__(self, other):+ return isinstance(other, _ValueEqualProvider)++ def __hash__(self):+ return 0+++def test_unhashable_shared_provider_is_refused_for_a_second_profile(homes, multiplexed):+ alpha_home, beta_home = homes+ shared = _UnhashableProvider()+ alpha = _manager(alpha_home, shared)+ beta = _manager(beta_home, shared)+ assert shared._home == str(alpha_home)+ assert alpha.providers and beta.providers == []+++def test_value_equal_distinct_instances_are_each_served(homes, multiplexed):+ alpha_home, beta_home = homes+ first, second = _ValueEqualProvider(), _ValueEqualProvider()+ alpha, beta = _manager(alpha_home, first), _manager(beta_home, second)+ assert (first._home, second._home) == (str(alpha_home), str(beta_home))+ assert alpha.providers == [first] and beta.providers == [second]+++def test_untrackable_provider_instance_fails_closed_only_when_multiplexed(homes):+ from agent.memory_caller_scope import claim_instance+ from agent.secret_scope import reset_multiplex_context, set_multiplex_context++ class _NoWeakref:+ __slots__ = ("name",)++ alpha_home, _ = homes+ assert claim_instance(_NoWeakref(), alpha_home)+ token = set_multiplex_context(True)+ try:+ assert not claim_instance(_NoWeakref(), alpha_home)+ finally:+ reset_multiplex_context(token)diff --git a/tests/agent/test_run_agent.py b/tests/agent/test_run_agent.pyindex 4014f9eff15..131befb7080 100644--- a/tests/agent/test_run_agent.py+++ b/tests/agent/test_run_agent.py@@ -1592,41 +1592,6 @@ class TestExecuteToolCalls:assert metadata["tool_call_id"] == "mem-1"assert messages[-1]["tool_call_id"] == "mem-1"- def test_memory_provider_tool_receives_gateway_session_key(self, agent):- """Regression for #140058: multiplexed provider calls retain their caller identity."""- provider_call = MagicMock(return_value="{}")- agent._gateway_session_key = "agent:profile-a:telegram:dm:42"- agent._memory_manager = SimpleNamespace(- has_tool=lambda name: name == "external_memory_tool",- handle_tool_call=provider_call,- )- tc = _mock_tool_call(name="external_memory_tool", arguments="{}", call_id="memory-1")-- agent._execute_tool_calls_sequential(_mock_assistant_msg(content="", tool_calls=[tc]), [], "task-1")-- provider_call.assert_called_once_with(- "external_memory_tool", {}, caller_gsk="agent:profile-a:telegram:dm:42",- )-- def test_concurrent_memory_provider_tool_receives_gateway_session_key(self, agent):- """The concurrent dispatch helper preserves the same provider identity contract."""- from agent.inline_tool_executors import resolve_invoke_tool_executor-- provider_call = MagicMock(return_value="{}")- agent._gateway_session_key = "agent:profile-b:discord:dm:7"- agent._memory_manager = SimpleNamespace(- has_tool=lambda name: name == "external_memory_tool",- handle_tool_call=provider_call,- )-- executor = resolve_invoke_tool_executor(agent, "external_memory_tool")-- assert executor is not None- executor(agent, {}, SimpleNamespace())- provider_call.assert_called_once_with(- "external_memory_tool", {}, caller_gsk="agent:profile-b:discord:dm:7",- )-def test_interrupt_skips_remaining(self, agent, monkeypatch):tc1 = _mock_tool_call(name="web_search", arguments="{}", call_id="c1")tc2 = _mock_tool_call(name="web_search", arguments="{}", call_id="c2")diff --git a/tests/plugins/memory/test_provider_multiplex_contract.py b/tests/plugins/memory/test_provider_multiplex_contract.pynew file mode 100644index 00000000000..e70a909f1da--- /dev/null+++ b/tests/plugins/memory/test_provider_multiplex_contract.py@@ -0,0 +1,169 @@+"""PLG-11 (#140058): the in-repo memory providers meet the multiplexing contract.++On a multiplexed gateway every profile's agents share one process. Each agent's manager owns its own+provider instance, and the contract (``agent/memory_provider.py``) is that the instance binds its+store from the ``hermes_home`` ``initialize`` receives, keeps that binding on the instance, and+never rebinds a module/class-level one per call. These tests drive the real providers through real+managers with two profiles interleaving on threads, with only the network/CLI backend faked.+"""+from __future__ import annotations++import json+import threading+from pathlib import Path++import pytest++from agent.memory_manager import MemoryManager+from hermes_constants import reset_hermes_home_override, set_hermes_home_override+from tests.waiting import wait_until+++def homes(tmp_path, monkeypatch):+ root = tmp_path / ".hermes"+ alpha, beta = root / "profiles" / "alpha", root / "profiles" / "beta"+ for home in (alpha, beta):+ home.mkdir(parents=True)+ monkeypatch.setenv("HERMES_HOME", str(root)) # the launch profile: neither alpha nor beta+ return alpha, beta+++class _Scope:+ def __init__(self, home):+ self.home = home++ def __enter__(self):+ self.token = set_hermes_home_override(str(self.home))++ def __exit__(self, *exc):+ reset_hermes_home_override(self.token)+++# -- ByteRover ---------------------------------------------------------------------------------------++def test_byterover_binds_the_home_initialize_receives(homes):+ from plugins.memory.byterover import ByteRoverMemoryProvider+ alpha, _ = homes+ provider = ByteRoverMemoryProvider({})+ provider.initialize("s", hermes_home=str(alpha)) # no context override: the ambient home is the root+ assert Path(provider._cwd) == alpha / "byterover"+++def test_byterover_two_profiles_interleaving_stay_in_their_own_trees(homes, monkeypatch):+ from plugins.memory import byterover+ calls: list = []+ lock = threading.Lock()++ def fake_run_brv(args, timeout=0, cwd=None):+ with lock:+ calls.append((args[0], args[-1], cwd))+ return {"success": True, "output": "x" * 40}++ monkeypatch.setattr(byterover, "_run_brv", fake_run_brv)+ monkeypatch.setattr(byterover, "_resolve_brv_path", lambda: "/bin/true")+ managers = {}+ for home in homes:+ manager = MemoryManager()+ with _Scope(home):+ manager.add_provider(byterover.ByteRoverMemoryProvider({}))+ manager.initialize_all(session_id=f"s-{home.name}", platform="api_server", hermes_home=str(home))+ managers[home] = manager+ _run_interleaved(managers, "brv_curate", {"content": None})+ wait_until(lambda: len(calls) >= 2 * 3 * 5, what="every brv call from both profiles")+ for home in homes:+ mine = [c for c in calls if c[1].endswith(f"{home.name}-content") or f"{home.name}-" in c[1]]+ assert mine and all(Path(cwd) == home / "byterover" for _, _, cwd in mine), mine+++# -- RetainDB ----------------------------------------------------------------------------------------++class _FakeClient:+ calls: list = []+ lock = threading.Lock()++ def __init__(self, api_key, base_url, project):+ self.project = project++ def _record(self, what, content):+ with self.lock:+ type(self).calls.append((what, self.project, content))++ def add_memory(self, user_id, session_id, content, **kwargs):+ self._record("add_memory", content)+ return {"ok": True}++ def ingest_session(self, user_id, session_id, messages, timeout=15.0):+ self._record("ingest_session", messages[0]["content"])+ return {"ok": True}+++def fake_retaindb(monkeypatch):+ from plugins.memory import retaindb+ _FakeClient.calls = []+ monkeypatch.setattr(retaindb, "_Client", _FakeClient)+ monkeypatch.setattr(retaindb, "get_secret", lambda name, default=None: "rdb-key" if name == "RETAINDB_API_KEY" else default)+ monkeypatch.setattr(retaindb, "_load_retaindb_config", dict)+ return retaindb+++def test_retaindb_binds_the_home_initialize_receives(homes, fake_retaindb):+ alpha, _ = homes+ provider = fake_retaindb.RetainDBMemoryProvider()+ provider.initialize("s", hermes_home=str(alpha)) # no context override: the ambient home is the root+ try:+ assert provider._queue._db_path == alpha / "retaindb_queue.db"+ assert provider._client.project == "hermes-alpha"+ finally:+ provider.shutdown()+++def test_retaindb_two_profiles_interleaving_stay_in_their_own_projects(homes, fake_retaindb):+ managers = {}+ for home in homes:+ manager = MemoryManager()+ with _Scope(home):+ manager.add_provider(fake_retaindb.RetainDBMemoryProvider())+ manager.initialize_all(session_id=f"s-{home.name}", platform="api_server", hermes_home=str(home))+ managers[home] = manager+ try:+ _run_interleaved(managers, "retaindb_remember", {"content": None})+ wait_until(lambda: len(_FakeClient.calls) >= 2 * 3 * 5, what="every RetainDB write from both profiles")+ finally:+ for manager in managers.values():+ manager.shutdown_all()+ for home in homes:+ mine = [c for c in _FakeClient.calls if f"{home.name}-" in c[2]]+ assert {c[0] for c in mine} == {"add_memory", "ingest_session"}, mine+ assert all(project == f"hermes-{home.name}" for _, project, _ in mine), mine+ assert (home / "retaindb_queue.db").exists()+++# -- shared driver -----------------------------------------------------------------------------------++def _run_interleaved(managers, tool, args_template, rounds=5):+ """Each profile's turn, on its own thread and scope: a tool call, a turn sync and a built-in+ memory-write mirror per round, all carrying that profile's name in their content."""+ barrier, errors = threading.Barrier(len(managers)), []++ def turns(home, manager):+ try:+ with _Scope(home):+ barrier.wait(timeout=5)+ for i in range(rounds):+ args = {k: (v if v is not None else f"{home.name}-tool-{i}") for k, v in args_template.items()}+ result = json.loads(manager.handle_tool_call(tool, args))+ assert "error" not in result, result+ manager.sync_all(f"{home.name}-turn-{i} what did we decide", "the plan", session_id="s")+ manager.on_memory_write("add", "memory", f"{home.name}-write-{i}")+ assert manager.flush_pending(timeout=10)+ except Exception as exc: # surfaced below+ errors.append(exc)++ threads = [threading.Thread(target=turns, args=item) for item in managers.items()]+ for thread in threads:+ thread.start()+ for thread in threads:+ thread.join(timeout=30)+ assert not errors, errorsdiff --git a/website/docs/developer-guide/memory-provider-plugin.md b/website/docs/developer-guide/memory-provider-plugin.mdindex e307a615a37..8cc94659144 100644--- a/website/docs/developer-guide/memory-provider-plugin.md+++ b/website/docs/developer-guide/memory-provider-plugin.md@@ -428,14 +428,26 @@ workspace data.All storage paths **must** use the `hermes_home` kwarg from `initialize()`, not hardcoded `~/.hermes`:```python-# CORRECT — profile-scoped-from hermes_constants import get_hermes_home-data_dir = get_hermes_home() / "my-provider"+# CORRECT — profile-scoped, bound on the instance+def initialize(self, session_id, **kwargs):+ self._data_dir = Path(kwargs["hermes_home"]) / "my-provider"# WRONG — shared across all profilesdata_dir = Path("~/.hermes/my-provider").expanduser()```+### Multiplexed gateways++One gateway process can serve several profiles at once, and their turns run concurrently on different threads. Each agent gets its own `MemoryManager` and its own provider instance, initialized for one profile. Your provider must:++- **Return a new instance per load.** `register(ctx)` should construct the provider (`ctx.register_memory_provider(MyProvider())`), not hand back a module-level singleton. The manager refuses to initialize an instance that another profile's manager already bound, and logs `memory_provider_instance_shared`.+- **Bind from `initialize()`.** Derive every store, path, client, bank and tenant from the `hermes_home` keyword (and secrets read through `get_secret()` during `initialize`), and keep that binding on `self`.+- **Keep nothing profile-specific at module or class level.** No global "current store", and no rebinding a shared binding on each call. Two profiles' calls interleave, so a per-call rebind races.++The manager enforces the other half. It runs tool calls and every lifecycle hook (`prefetch`, `queue_prefetch`, `sync_turn`, `on_memory_write`, `on_session_end`, …) only from the profile the instance was initialized for. On a multiplexed gateway a caller that names no profile is refused, and the refusal is logged in `gateway.log` as `memory_caller_profile_unresolved`. Background hooks run under the owning profile's `HERMES_HOME`. `handle_tool_call(..., **kwargs)` also receives `hermes_home`, `agent_identity` and `caller_gsk`. They name the profile your instance is already bound to, so you can assert on them, but don't rebind from them.++Hermes can't verify a provider's internals. A provider that keeps a process-wide binding still mixes profiles' memories, even with these checks in place.+## TestingSee `tests/agent/test_memory_provider.py` and adjacent memory tests (`tests/agent/test_memory_session_switch.py`, `tests/agent/test_memory_user_id.py`, `tests/agent/test_memory_provider_init.py`) for end-to-end patterns.