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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix: B6 — memory injection moves to live-zone user-tail
chopratejas2ee05774b92d
diff --git a/headroom/proxy/handlers/gemini.py b/headroom/proxy/handlers/gemini.pyindex 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_tokensoptimization_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.pyindex e8e0d2b74..f6b82020e 100644--- a/headroom/proxy/memory_handler.py+++ b/headroom/proxy/memory_handler.py@@ -25,6 +25,7 @@ Usage:from __future__ import annotationsimport asyncio+import enumimport inspectimport jsonimport 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 = Truetop_k: int = 10min_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 = Falsenative_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.pyindex a4aa0641e..76c2b610c 100644--- a/headroom/proxy/models.py+++ b/headroom/proxy/models.py@@ -205,6 +205,12 @@ class ProxyConfig:memory_inject_context: bool = Truememory_top_k: int = 10memory_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.pyindex 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.pynew file mode 100644index 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.pynew file mode 100644index 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"