Skip to content

The agent that grows with you

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.py
new file mode 100644
index 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 _run
diff --git a/agent/memory_manager.py b/agent/memory_manager.py
index 817145fe9e0..f0ec422710d 100644
--- a/agent/memory_manager.py
+++ b/agent/memory_manager.py
@@ -18,6 +18,7 @@ from typing import Any, Callable, Dict, List, Optional
from agent.redact import redact_for_egress
+from agent.memory_caller_scope import caller_scope, claim_instance, in_owner_home, refused_tool_message
from agent.memory_provider import MemoryProvider, PRE_COMPRESS_CHECKPOINT_API_VERSION, ctx_bound, spawn_context_thread
from agent.skill_commands import extract_user_instruction_from_skill_message
from 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]] = None
def _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"):
return
clean_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"):
return
clean_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 its
durability class. Runs under the caller's contextvars (``ctx_bound``). If the executor is
unavailable 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_executor
if 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_call
try:
@@ -556,6 +577,8 @@ class MemoryManager:
return result
def on_turn_start(self, turn_number: int, message: str, **kwargs) -> None:
+ if not self._owner_allows("on_turn_start"):
+ return
message = _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"):
+ return
messages = _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 inline
execution — the pre-#16454 synchronous behavior, slow but correct.
"""
- if not self._providers:
+ if not self._providers or not self._owner_allows("session_boundary"):
return
snapshot = 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"):
return
if rewound: # forward only when set so it never pollutes providers' **kwargs
kwargs["rewound"] = True
@@ -640,6 +665,10 @@ class MemoryManager:
only to checkpoint (v2+) providers. With ``require_checkpoint`` at least one checkpoint provider
must 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 = False
messages, 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"):
+ return
content, 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"):
+ return
task, 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_home
kwargs["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.py
index 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__.py
index 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, 0
Path(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__.py
index 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 background
diff --git a/tests/agent/test_memory_provider.py b/tests/agent/test_memory_provider.py
index 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 = text
mgr = MemoryManager()
mgr.add_provider(provider)
+ mgr.initialize_all(session_id="s") # bound to this scope's profile, as agents are
managers[home] = mgr
mgr = 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 = text
assert fresh.prefetch_all("recall", session_id="fresh") == text
assert not (a / "recall" / "fresh").exists()
diff --git a/tests/agent/test_memory_provider_caller_profile.py b/tests/agent/test_memory_provider_caller_profile.py
new file mode 100644
index 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.py
index 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.py
new file mode 100644
index 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, errors
diff --git a/website/docs/developer-guide/memory-provider-plugin.md b/website/docs/developer-guide/memory-provider-plugin.md
index 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 profiles
data_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.
+
## Testing
See `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.