Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix: B6 — memory injection moves to live-zone user-tail

chopratejas2ee05774b92d
diff --git a/headroom/proxy/handlers/gemini.py b/headroom/proxy/handlers/gemini.py
index 427314f3f..03bbd5208 100644
--- a/headroom/proxy/handlers/gemini.py
+++ b/headroom/proxy/handlers/gemini.py
@@ -321,7 +321,14 @@ class GeminiHandlerMixin:
tokens_saved = original_tokens - optimized_tokens
optimization_latency = (time.time() - start_time) * 1000
- # Memory: inject context for Gemini requests
+ # Memory: inject context for Gemini requests.
+ #
+ # PR-B6: memory context auto-injects to the live-zone tail (the
+ # latest user message) — never to the system / systemInstruction
+ # field. The cache hot zone is sacrosanct (invariant I2). When
+ # the memory handler is in ``MemoryMode.TOOL`` its
+ # ``search_and_format_context`` returns ``None`` so nothing flows
+ # in here.
if self.memory_handler and memory_user_id:
try:
if self.memory_handler.config.inject_context:
@@ -329,15 +336,24 @@ class GeminiHandlerMixin:
memory_user_id, optimized_messages
)
if memory_context:
- # Prepend as system message (will become systemInstruction in Gemini format)
- optimized_messages = [
- {"role": "system", "content": memory_context},
- *optimized_messages,
- ]
- logger.info(
- f"[{request_id}] Memory: Injected {len(memory_context)} chars "
- f"of context for user {memory_user_id} (gemini)"
+ new_messages, bytes_appended = (
+ self.memory_handler._append_to_latest_user_tail(
+ optimized_messages,
+ memory_context,
+ provider="openai",
+ )
)
+ if bytes_appended > 0:
+ optimized_messages = new_messages
+ logger.info(
+ f"[{request_id}] Memory: Injected {bytes_appended} chars "
+ f"into latest user message tail for user {memory_user_id} (gemini)"
+ )
+ else:
+ logger.debug(
+ f"[{request_id}] Memory: no eligible user message; "
+ "skipped tail injection (gemini)"
+ )
except Exception as e:
logger.warning(f"[{request_id}] Memory injection failed (gemini): {e}")
diff --git a/headroom/proxy/memory_handler.py b/headroom/proxy/memory_handler.py
index e8e0d2b74..f6b82020e 100644
--- a/headroom/proxy/memory_handler.py
+++ b/headroom/proxy/memory_handler.py
@@ -25,6 +25,7 @@ Usage:
from __future__ import annotations
import asyncio
+import enum
import inspect
import json
import logging
@@ -40,6 +41,27 @@ if TYPE_CHECKING:
logger = logging.getLogger(__name__)
+
+class MemoryMode(str, enum.Enum):
+ """Memory injection mode (PR-B6).
+
+ AUTO_TAIL (default): Memory retrieval runs at request entry; results are
+ appended to the latest user message tail (the live zone). The cache hot
+ zone (system prompt / instructions / frozen prefix) is never mutated —
+ invariant I2 from PR-A2.
+
+ TOOL: Auto-injection is disabled entirely. The model calls the
+ ``memory_search`` tool explicitly when it wants memory; retrieval runs in
+ the tool execution path, not the prompt-construction path. Memory becomes
+ opt-in (and visible to the model) rather than implicit.
+
+ See REALIGNMENT/04-phase-B-live-zone.md PR-B6 for the rationale.
+ """
+
+ AUTO_TAIL = "auto_tail"
+ TOOL = "tool"
+
+
# Memory tool names for detection (Headroom's custom tools)
MEMORY_TOOL_NAMES = {"memory_save", "memory_search", "memory_update", "memory_delete"}
@@ -75,6 +97,11 @@ class MemoryConfig:
inject_context: bool = True
top_k: int = 10
min_similarity: float = 0.3
+ # PR-B6: Memory injection mode. AUTO_TAIL (default) auto-appends retrieved
+ # memory to the latest user message tail. TOOL disables auto-injection;
+ # the model must call ``memory_search`` to retrieve. Configurable per
+ # deployment via ``ProxyConfig.memory_mode``.
+ mode: MemoryMode = MemoryMode.AUTO_TAIL
# Native memory tool (Anthropic's built-in memory_20250818)
use_native_tool: bool = False
native_memory_dir: str = "" # Directory for native memory files (default: ~/.headroom/memories)
@@ -494,10 +521,27 @@ class MemoryHandler:
Returns:
Formatted context string, or None if no relevant memories.
+
+ PR-B6: When ``self.config.mode == MemoryMode.TOOL``, this method
+ returns ``None`` unconditionally so the proxy never auto-injects.
+ The model must call ``memory_search`` explicitly to retrieve. This
+ is the single chokepoint that gates auto-injection across all
+ provider handlers (Anthropic /v1/messages, OpenAI /v1/chat/completions,
+ OpenAI /v1/responses).
"""
if not self.config.inject_context:
return None
+ # PR-B6: Tool mode disables auto-injection. The model calls
+ # ``memory_search`` to retrieve when it wants to. Log the skip
+ # decision so cache-affecting routing remains observable.
+ if self.config.mode == MemoryMode.TOOL:
+ logger.info(
+ "event=memory_mode_skip mode=tool user_id=%s reason=tool_mode_no_auto_injection",
+ user_id,
+ )
+ return None
+
await self._ensure_initialized()
if not self._backend:
return None
@@ -560,6 +604,69 @@ Use this context to provide personalized and contextually relevant responses."""
)
return context
+ @staticmethod
+ def _append_to_latest_user_tail(
+ messages: list[dict[str, Any]],
+ context_text: str,
+ *,
+ provider: Literal["anthropic", "openai"] = "anthropic",
+ frozen_message_count: int = 0,
+ ) -> tuple[list[dict[str, Any]], int]:
+ """Append memory context to the live-zone tail (latest user message).
+
+ PR-B6 canonical entry point for memory tail injection. Replaces the
+ retired ``_inject_to_system_or_instructions`` path (deleted in PR-A2).
+ The cache hot zone — system / instructions / frozen prefix — is never
+ mutated by this helper.
+
+ Args:
+ messages: Provider-shaped message list. For Anthropic this is the
+ Messages API ``messages`` array. For OpenAI Chat Completions
+ this is ``body["messages"]``.
+ context_text: Pre-formatted memory context block. Empty/missing
+ returns the input unchanged.
+ provider: ``"anthropic"`` or ``"openai"``. Selects the correct
+ tail-append helper for the provider's content shape.
+ frozen_message_count: For Anthropic: the cache-frozen prefix
+ length. The latest user message must lie outside this prefix
+ to be eligible for mutation. Ignored for OpenAI Chat
+ Completions (which does not have a frozen-prefix concept on
+ this path).
+
+ Returns:
+ ``(new_messages, bytes_appended)``. ``bytes_appended == 0`` means
+ no eligible user text block was found; the message list is
+ returned unchanged.
+
+ Determinism: the bytes appended are byte-identical for the same
+ ``context_text`` across runs. The caller is responsible for ensuring
+ ``context_text`` itself is deterministic (i.e. that the upstream
+ vector search produced the same results in the same order).
+ """
+ if not messages or not context_text:
+ return messages, 0
+
+ if provider == "anthropic":
+ # Late import to avoid circular: AnthropicHandlerMixin lives in
+ # headroom.proxy.handlers.anthropic which imports MemoryHandler.
+ from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin
+
+ new_messages = AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
+ messages,
+ context_text,
+ frozen_message_count=frozen_message_count,
+ )
+ if new_messages is messages:
+ return messages, 0
+ return new_messages, len(context_text)
+
+ if provider == "openai":
+ from headroom.proxy.helpers import append_text_to_latest_user_chat_message
+
+ return append_text_to_latest_user_chat_message(messages, context_text)
+
+ raise ValueError(f"Unknown provider {provider!r}; expected 'anthropic' or 'openai'")
+
def _extract_user_query(self, messages: list[dict[str, Any]]) -> str:
"""Extract the user query from the last user message."""
for msg in reversed(messages):
diff --git a/headroom/proxy/models.py b/headroom/proxy/models.py
index a4aa0641e..76c2b610c 100644
--- a/headroom/proxy/models.py
+++ b/headroom/proxy/models.py
@@ -205,6 +205,12 @@ class ProxyConfig:
memory_inject_context: bool = True
memory_top_k: int = 10
memory_min_similarity: float = 0.3
+ # PR-B6: Memory injection mode. ``"auto_tail"`` (default) auto-appends
+ # retrieved memory to the latest user message tail (live zone).
+ # ``"tool"`` disables auto-injection — the model must call
+ # ``memory_search`` to retrieve. See REALIGNMENT/04-phase-B-live-zone.md
+ # PR-B6.
+ memory_mode: Literal["auto_tail", "tool"] = "auto_tail"
# Qdrant connection (defaults resolve from HEADROOM_QDRANT_* env vars)
memory_qdrant_url: str | None = field(default_factory=qdrant_env.qdrant_env_url)
memory_qdrant_host: str = field(default_factory=qdrant_env.qdrant_env_host)
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index cec5093ee..3f29f6fe5 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -499,6 +499,19 @@ class HeadroomProxy(
_mem_db_path = str(_mem_dir / "memory.db")
logger.info(f"Memory: Project-scoped DB at {_mem_db_path}")
+ # PR-B6: translate the string-typed ``ProxyConfig.memory_mode``
+ # into the typed ``MemoryMode`` enum. Unknown values raise
+ # loudly per the no-silent-fallback policy.
+ from headroom.proxy.memory_handler import MemoryMode
+
+ try:
+ _memory_mode = MemoryMode(config.memory_mode)
+ except ValueError as exc:
+ raise ValueError(
+ f"Invalid memory_mode={config.memory_mode!r}; "
+ f"expected one of {[m.value for m in MemoryMode]}"
+ ) from exc
+
memory_config = MemoryConfig(
enabled=True,
backend=config.memory_backend,
@@ -508,6 +521,7 @@ class HeadroomProxy(
inject_context=config.memory_inject_context,
top_k=config.memory_top_k,
min_similarity=config.memory_min_similarity,
+ mode=_memory_mode,
qdrant_url=config.memory_qdrant_url,
qdrant_host=config.memory_qdrant_host,
qdrant_port=config.memory_qdrant_port,
diff --git a/tests/test_memory_auto_tail.py b/tests/test_memory_auto_tail.py
new file mode 100644
index 000000000..2f649b10c
--- /dev/null
+++ b/tests/test_memory_auto_tail.py
@@ -0,0 +1,313 @@
+"""PR-B6: tests that memory auto-injection lands in the live-zone tail.
+
+These tests verify three guarantees of the AutoTail memory mode:
+
+1. The retrieved memory context appears in the **latest user message tail**
+ (live zone) — never in the system prompt, instructions, or any frozen
+ prefix message. This is invariant I2 from PR-A2 carried forward to
+ PR-B6's chokepoint.
+
+2. The bytes inserted are **deterministic** for the same query across runs.
+ Memory injection mutates the cache-warm tail, so identical retrieval
+ inputs must produce identical output bytes; otherwise prompt-cache hit
+ rates collapse.
+
+3. System prompts and tool lists are **never modified** by the auto-injection
+ path. Memory tail-append is the only mutation; the cache-hot zone
+ (system / instructions / tool definitions) is sacrosanct.
+
+These cover the three test names called out in
+``REALIGNMENT/04-phase-B-live-zone.md`` PR-B6:
+
+- ``test_memory_appears_in_latest_user_message_tail``
+- ``test_memory_does_not_modify_system_or_tools``
+- ``test_same_query_byte_identical_across_runs``
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any
+
+import pytest
+
+from headroom.proxy.memory_handler import MemoryConfig, MemoryHandler, MemoryMode
+
+# ---------------------------------------------------------------------------
+# Fixtures: a deterministic in-memory backend stub.
+#
+# The realignment spec for PR-B6 requires byte-identical output across runs
+# for the same query. We avoid the real ONNX embedder + HNSW backend (which
+# is non-deterministic across processes due to thread scheduling) by stubbing
+# the backend with a fixed, ordered result set keyed on ``user_id`` + query.
+# This isolates the tail-injection logic — the layer this PR actually
+# changes — from upstream search non-determinism.
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _StubMemory:
+ """Minimal stand-in for a memory record."""
+
+ id: str
+ content: str
+ metadata: dict[str, Any]
+
+
+@dataclass
+class _StubResult:
+ """Minimal stand-in for a SearchResult."""
+
+ memory: _StubMemory
+ score: float
+ related_entities: list[str]
+
+
+class _DeterministicBackend:
+ """Stub backend whose ``search_memories`` returns a fixed sequence.
+
+ Returns the same results in the same order for every call regardless of
+ query — this is exactly what determinism testing requires (the bytes
+ appended to the tail must not depend on hidden state).
+ """
+
+ def __init__(self) -> None:
+ self._fixture = [
+ _StubResult(
+ memory=_StubMemory(
+ id="mem_alpha_001",
+ content="User prefers Python over Java for data work.",
+ metadata={"source_agent": "test"},
+ ),
+ score=0.91,
+ related_entities=["python", "java"],
+ ),
+ _StubResult(
+ memory=_StubMemory(
+ id="mem_alpha_002",
+ content="User's timezone is America/Los_Angeles.",
+ metadata={"source_agent": "test"},
+ ),
+ score=0.82,
+ related_entities=["timezone"],
+ ),
+ ]
+
+ async def search_memories(
+ self,
+ query: str, # noqa: ARG002 — deterministic stub ignores query
+ user_id: str, # noqa: ARG002
+ top_k: int = 10,
+ include_related: bool = False, # noqa: ARG002
+ entities: list[str] | None = None, # noqa: ARG002
+ ) -> list[_StubResult]:
+ return list(self._fixture[:top_k])
+
+
+def _build_handler() -> MemoryHandler:
+ """Build a MemoryHandler in AutoTail mode with the deterministic stub."""
+ config = MemoryConfig(
+ enabled=True,
+ backend="local",
+ inject_context=True,
+ inject_tools=True,
+ top_k=5,
+ min_similarity=0.3,
+ mode=MemoryMode.AUTO_TAIL,
+ )
+ handler = MemoryHandler(config)
+ # Bypass the lazy backend init — the stub satisfies the contract that
+ # ``search_and_format_context`` requires.
+ handler._backend = _DeterministicBackend()
+ handler._initialized = True
+ return handler
+
+
+# ---------------------------------------------------------------------------
+# Test 1: live-zone tail injection (Anthropic shape).
+# ---------------------------------------------------------------------------
+
+
+def test_memory_appears_in_latest_user_message_tail() -> None:
+ """AutoTail mode must append to the latest user message, not system."""
+ handler = _build_handler()
+ messages = [
+ {"role": "user", "content": "What language do I prefer?"},
+ ]
+
+ # Run the full search-and-format-and-inject path for Anthropic shape.
+ context = asyncio.run(handler.search_and_format_context("alpha", messages))
+ assert context is not None and context, "AutoTail mode must produce context"
+
+ new_messages, bytes_appended = MemoryHandler._append_to_latest_user_tail(
+ messages, context, provider="anthropic", frozen_message_count=0
+ )
+
+ assert bytes_appended == len(context)
+ assert len(new_messages) == 1
+ assert new_messages[0]["role"] == "user"
+ # Original query bytes are preserved at the head; memory context is
+ # appended at the tail, with the canonical "\n\n" separator.
+ assert new_messages[0]["content"].startswith("What language do I prefer?")
+ assert new_messages[0]["content"].endswith(context)
+ assert "\n\n" in new_messages[0]["content"]
+
+
+def test_memory_appears_in_latest_user_message_tail_openai_shape() -> None:
+ """AutoTail also works for OpenAI Chat Completions (string + list content)."""
+ handler = _build_handler()
+
+ # String content shape.
+ messages_str = [
+ {"role": "system", "content": "You are a helpful assistant."},
+ {"role": "user", "content": "Recall my preferences"},
+ ]
+ context = asyncio.run(handler.search_and_format_context("alpha", messages_str))
+ assert context
+
+ new_messages, bytes_appended = MemoryHandler._append_to_latest_user_tail(
+ messages_str, context, provider="openai"
+ )
+ assert bytes_appended == len(context)
+ # System message untouched.
+ assert new_messages[0] == messages_str[0]
+ # User message tail contains context.
+ assert new_messages[1]["content"].endswith(context)
+
+ # List content shape (vision-style multi-part input).
+ messages_list = [
+ {"role": "system", "content": "sys"},
+ {
+ "role": "user",
+ "content": [
+ {"type": "text", "text": "Recall my preferences"},
+ ],
+ },
+ ]
+ new_messages_list, bytes_appended_list = MemoryHandler._append_to_latest_user_tail(
+ messages_list, context, provider="openai"
+ )
+ assert bytes_appended_list == len(context)
+ assert new_messages_list[0] == messages_list[0]
+ assert new_messages_list[1]["content"][0]["text"].endswith(context)
+
+
+# ---------------------------------------------------------------------------
+# Test 2: system + tools are never mutated.
+# ---------------------------------------------------------------------------
+
+
+def test_memory_does_not_modify_system_or_tools() -> None:
+ """The cache hot zone (system / tools / instructions) must be untouched."""
+ handler = _build_handler()
+
+ system_prompt_before = "You are a careful assistant. Follow instructions exactly."
+ tools_before = [
+ {
+ "name": "do_thing",
+ "description": "Do a thing",
+ "input_schema": {"type": "object", "properties": {}, "required": []},
+ }
+ ]
+
+ messages = [
+ {"role": "system", "content": system_prompt_before},
+ {"role": "user", "content": "tell me about my preferences"},
+ ]
+
+ context = asyncio.run(handler.search_and_format_context("alpha", messages))
+ assert context
+
+ new_messages, bytes_appended = MemoryHandler._append_to_latest_user_tail(
+ messages, context, provider="openai"
+ )
+ assert bytes_appended > 0
+
+ # System message bytes are unchanged.
+ assert new_messages[0]["content"] == system_prompt_before
+ # Tools list is not touched by the tail-append helper (it never even
+ # receives `tools` as input). This is documented invariant: memory tail
+ # injection mutates ``messages``-shaped containers only.
+ assert tools_before == [
+ {
+ "name": "do_thing",
+ "description": "Do a thing",
+ "input_schema": {"type": "object", "properties": {}, "required": []},
+ }
+ ]
+
+ # Anthropic shape with frozen prefix: latest user message is below the
+ # frozen line — tail-append must be a no-op.
+ anthropic_messages = [
+ {"role": "user", "content": "first turn"},
+ {"role": "assistant", "content": "first reply"},
+ {"role": "user", "content": "second turn"},
+ ]
+ # Freeze everything (frozen_count == len). The latest user message is at
+ # index 2; the helper requires ``i >= frozen_message_count``, so a
+ # ``frozen_message_count`` of 3 makes the latest message ineligible.
+ no_op_msgs, no_op_bytes = MemoryHandler._append_to_latest_user_tail(
+ anthropic_messages,
+ context,
+ provider="anthropic",
+ frozen_message_count=len(anthropic_messages),
+ )
+ assert no_op_bytes == 0
+ # Nothing changes: identity preserved by the helper for fully-frozen tail.
+ assert no_op_msgs == anthropic_messages
+
+
+# ---------------------------------------------------------------------------
+# Test 3: byte-identical output across runs for the same query.
+# ---------------------------------------------------------------------------
+
+
+def test_same_query_byte_identical_across_runs() -> None:
+ """Two independent runs of the same query must produce identical bytes."""
+
+ def _one_run() -> tuple[str, list[dict[str, Any]]]:
+ handler = _build_handler()
+ messages = [
+ {"role": "user", "content": "What do you remember about me?"},
+ ]
+ context = asyncio.run(handler.search_and_format_context("alpha", messages))
+ assert context is not None
+ new_messages, _ = MemoryHandler._append_to_latest_user_tail(
+ messages, context, provider="anthropic", frozen_message_count=0
+ )
+ return context, new_messages
+
+ context_a, msgs_a = _one_run()
+ context_b, msgs_b = _one_run()
+
+ # The formatted memory context block must be byte-identical (no
+ # timestamps, randomized ordering, or hash-keyed iteration leaking in).
+ assert context_a == context_b, (
+ "Memory context must be deterministic across runs for the same query."
+ )
+
+ # The full mutated message list must also be byte-identical (the only
+ # other contributor — the user message — does not change across runs).
+ assert msgs_a == msgs_b
+
+
+# ---------------------------------------------------------------------------
+# Sanity: AUTO_TAIL is the default mode for a fresh MemoryConfig.
+# ---------------------------------------------------------------------------
+
+
+def test_default_mode_is_auto_tail() -> None:
+ """A MemoryConfig built without explicit mode must default to AUTO_TAIL."""
+ config = MemoryConfig(enabled=True)
+ assert config.mode is MemoryMode.AUTO_TAIL
+
+
+def test_unknown_provider_raises() -> None:
+ """``_append_to_latest_user_tail`` must reject unknown providers loudly."""
+ with pytest.raises(ValueError, match="Unknown provider"):
+ MemoryHandler._append_to_latest_user_tail(
+ [{"role": "user", "content": "x"}],
+ "ctx",
+ provider="bogus", # type: ignore[arg-type]
+ )
diff --git a/tests/test_memory_tool_mode.py b/tests/test_memory_tool_mode.py
new file mode 100644
index 000000000..6f5e86237
--- /dev/null
+++ b/tests/test_memory_tool_mode.py
@@ -0,0 +1,165 @@
+"""PR-B6: tests that MemoryMode.TOOL fully disables auto-injection.
+
+In Tool mode, the memory subsystem must be invisible to the prompt-construction
+path. The model can still call ``memory_search`` explicitly (the tool is
+registered through the existing tool-injection plumbing), but
+``search_and_format_context`` — the auto-injection chokepoint that returns
+text for the proxy to splice into the latest user turn — must return
+``None`` unconditionally.
+
+This is the load-bearing guarantee that lets us flip a deployment from
+``auto_tail`` to ``tool`` without auditing every handler.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from headroom.proxy.memory_handler import MemoryConfig, MemoryHandler, MemoryMode
+
+
+@dataclass
+class _StubMemory:
+ id: str
+ content: str
+ metadata: dict[str, Any]
+
+
+@dataclass
+class _StubResult:
+ memory: _StubMemory
+ score: float
+ related_entities: list[str]
+
+
+class _LoudBackend:
+ """Backend that fails the test if it is queried.
+
+ Tool mode must short-circuit *before* the backend is touched. If
+ ``search_memories`` runs, the chokepoint is broken.
+ """
+
+ def __init__(self) -> None:
+ self.calls = 0
+
+ async def search_memories(self, **_: Any) -> list[_StubResult]:
+ self.calls += 1
+ # Return data that would be appended in AutoTail mode — if Tool
+ # mode incorrectly auto-injects we can detect via the text content.
+ return [
+ _StubResult(
+ memory=_StubMemory(
+ id="leaked_001",
+ content="LEAK: this content must not appear in TOOL mode",
+ metadata={},
+ ),
+ score=0.99,
+ related_entities=[],
+ )
+ ]
+
+
+def _build_tool_mode_handler() -> tuple[MemoryHandler, _LoudBackend]:
+ config = MemoryConfig(
+ enabled=True,
+ backend="local",
+ inject_context=True,
+ inject_tools=True,
+ top_k=5,
+ min_similarity=0.3,
+ mode=MemoryMode.TOOL,
+ )
+ handler = MemoryHandler(config)
+ backend = _LoudBackend()
+ handler._backend = backend
+ handler._initialized = True
+ return handler, backend
+
+
+def test_tool_mode_skips_auto_injection() -> None:
+ """``search_and_format_context`` must return ``None`` in TOOL mode.
+
+ This is the single chokepoint enforcement: every provider handler
+ (Anthropic /v1/messages, OpenAI /v1/chat/completions and /v1/responses,
+ Gemini) calls this method. If it returns ``None``, no tail-injection
+ happens anywhere — without per-handler audit.
+ """
+ handler, backend = _build_tool_mode_handler()
+ messages = [
+ {"role": "user", "content": "What do you remember about me?"},
+ ]
+
+ result = asyncio.run(handler.search_and_format_context("alpha", messages))
+
+ assert result is None, "TOOL mode must skip auto-injection (return None)"
+ # Defense-in-depth: the backend must NOT have been queried. If it had
+ # been, we would have wasted compute and burned cache lines reading
+ # data that would never be used.
+ assert backend.calls == 0, (
+ f"TOOL mode must not even query the backend; saw {backend.calls} calls"
+ )
+
+
+def test_tool_mode_skip_emits_structured_log(caplog: Any) -> None:
+ """The skip must emit a structured ``event=memory_mode_skip`` log line.
+
+ Realignment build constraint: every cache-affecting decision is logged
+ in the ``event=foo key=val`` style so operators can audit routing.
+ """
+ handler, _backend = _build_tool_mode_handler()
+
+ with caplog.at_level(logging.INFO, logger="headroom.proxy.memory_handler"):
+ result = asyncio.run(
+ handler.search_and_format_context("alpha", [{"role": "user", "content": "hi"}])
+ )
+
+ assert result is None
+ skip_records = [r for r in caplog.records if "event=memory_mode_skip" in r.getMessage()]
+ assert skip_records, "TOOL mode skip must emit event=memory_mode_skip log line"
+ msg = skip_records[0].getMessage()
+ assert "mode=tool" in msg
+ assert "user_id=alpha" in msg
+
+
+def test_auto_tail_mode_does_query_backend() -> None:
+ """Sanity: AUTO_TAIL mode (the inverse) MUST query the backend.
+
+ Without this contrast, ``test_tool_mode_skips_auto_injection`` could be
+ passing because the wiring is broken in both modes. This pins down that
+ AUTO_TAIL still works end-to-end while TOOL skips.
+ """
+ config = MemoryConfig(
+ enabled=True,
+ backend="local",
+ inject_context=True,
+ inject_tools=True,
+ top_k=5,
+ min_similarity=0.3,
+ mode=MemoryMode.AUTO_TAIL,
+ )
+ handler = MemoryHandler(config)
+ backend = _LoudBackend()
+ handler._backend = backend
+ handler._initialized = True
+
+ result = asyncio.run(
+ handler.search_and_format_context("alpha", [{"role": "user", "content": "hi"}])
+ )
+ assert result is not None
+ assert backend.calls == 1
+
+
+def test_tool_mode_enum_value_is_stable() -> None:
+ """The ``"tool"`` string is the persistent on-the-wire identifier.
+
+ Pinned to catch accidental rename — the ProxyConfig.memory_mode field
+ accepts the string and must be able to round-trip via
+ ``MemoryMode("tool")``.
+ """
+ assert MemoryMode("tool") is MemoryMode.TOOL
+ assert MemoryMode("auto_tail") is MemoryMode.AUTO_TAIL
+ assert MemoryMode.TOOL.value == "tool"
+ assert MemoryMode.AUTO_TAIL.value == "auto_tail"