Files
headroom/tests/test_memory_handler_native_ops.py
fda75de505 fix(memory): run only the memory tools the proxy injected on the request (#4870)
## Description

With memory enabled (`--memory`, `--learn`, `wrap/init --memory`), the
proxy ran any upstream tool call named
`memory_list`/`memory_save`/`memory_search`/`memory_update`/`memory_delete`,
and hid it from the client. That held even when the proxy had not
offered those tools on the request (`--no-memory-tools`), or when the
client had declared a tool with that name itself.

The proxy now runs only the memory tools it injected on the current
request. Every other call reaches the client unchanged. The proxy does
not run it, does not withhold it, and sends no continuation upstream.
Anthropic streaming already followed this rule
(`_server_memory_tool_names`). That helper is now shared, and every
executor uses it.

**Behaviour change**
- With `--no-memory-tools`, memory tool calls from the model now reach
the client instead of running on the proxy.
- A memory-named tool that the client declares is now the client's. The
proxy no longer runs it on any path, including the streaming path that
used to run it as a side effect.
- Injected memory tools behave as before: they run on the proxy, are
hidden from the client, and the turn continues upstream.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/proxy/memory_handler.py`: `server_memory_tool_names(tools,
client_tools)` moved here from `AnthropicHandlerMixin`. It now reads
Anthropic, Chat and Responses tool shapes through `extract_tool_name`.
`handle_memory_tool_calls` takes a required `tool_names` and skips every
other call.
- `handlers/openai.py`, Chat Completions (non-streaming): records the
injected names and passes them to the executor.
- `handlers/openai.py`, Responses (HTTP): runs a `function_call` only if
its name was injected. Before, any name in `MEMORY_TOOL_NAMES` ran.
- `handlers/openai.py`, Responses over WebSocket: the injected names are
kept per `response.create`, like the user id. The relay holds back and
runs only those calls.
- `handlers/anthropic.py`, non-streaming: passes the injected names it
already computed for streaming.
- `handlers/streaming.py`: removes the branch that ran memory calls
after the stream had already reached the client. It ran only for tools
the proxy had not injected. Memory handling in the stream (SSE
buffering, the Claude Code credential warning) now turns on only when
the proxy injected memory tools.
- Tests: new `tests/test_memory_tools_only_when_injected.py`. Existing
fixtures that relied on the old behaviour now inject the tool they call:
`test_codex_project_context.py`, `test_memory_handler_native_ops.py`,
`test_memory_handler_project_isolation.py`,
`test_memory_tool_stream.py`.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

The new tests use `create_app` with a fake memory backend and a
`MockTransport` upstream. The WebSocket test uses a scripted upstream
socket. For each path (chat, Responses, Responses over WebSocket,
Anthropic, Anthropic streaming) they check two cases. First, injection
is off and the model calls `memory_delete`. Second, injection is on and
the client declares its own `memory_delete`. Each case expects zero
backend calls, exactly one upstream request, and the call in the
client's response. The control cases inject `memory_list` and expect it
to run as before.

On `origin/main` (0368a872):
```text
PASSED tests/test_memory_tools_only_when_injected.py::test_memory_call_the_proxy_did_not_inject_reaches_the_client[client_declared-anthropic_stream]
PASSED tests/test_memory_tools_only_when_injected.py::test_memory_call_the_proxy_injected_still_runs[chat]
PASSED tests/test_memory_tools_only_when_injected.py::test_memory_call_the_proxy_injected_still_runs[responses]
PASSED tests/test_memory_tools_only_when_injected.py::test_memory_call_the_proxy_injected_still_runs[anthropic]
PASSED tests/test_memory_tools_only_when_injected.py::test_ws_memory_call_the_proxy_injected_still_runs
FAILED tests/test_memory_tools_only_when_injected.py::test_memory_call_the_proxy_did_not_inject_reaches_the_client[not_injected-chat]
FAILED tests/test_memory_tools_only_when_injected.py::test_memory_call_the_proxy_did_not_inject_reaches_the_client[not_injected-responses]
FAILED tests/test_memory_tools_only_when_injected.py::test_memory_call_the_proxy_did_not_inject_reaches_the_client[not_injected-anthropic]
FAILED tests/test_memory_tools_only_when_injected.py::test_memory_call_the_proxy_did_not_inject_reaches_the_client[not_injected-anthropic_stream]
FAILED tests/test_memory_tools_only_when_injected.py::test_memory_call_the_proxy_did_not_inject_reaches_the_client[client_declared-chat]
FAILED tests/test_memory_tools_only_when_injected.py::test_memory_call_the_proxy_did_not_inject_reaches_the_client[client_declared-responses]
FAILED tests/test_memory_tools_only_when_injected.py::test_memory_call_the_proxy_did_not_inject_reaches_the_client[client_declared-anthropic]
FAILED tests/test_memory_tools_only_when_injected.py::test_ws_memory_call_the_proxy_did_not_inject_reaches_the_client[not_injected]
FAILED tests/test_memory_tools_only_when_injected.py::test_ws_memory_call_the_proxy_did_not_inject_reaches_the_client[client_declared]
9 failed, 5 passed in 3.05s
```
On this branch:
```text
14 passed in 3.23s
```
The existing tests for memory, anthropic, openai and streaming (165
files under `tests/`, not `test_live`) pass on both branches:
```text
origin/main: 3183 passed, 44 skipped in 230.96s
this branch: 3197 passed, 44 skipped in 229.83s
```
`uvx ruff@0.17.3 check` and `format --check` pass on the changed files.
`mypy` on the four changed modules reports no issues.

## Real Behavior Proof

- Environment: macOS, Python 3.12,
`create_app(ProxyConfig(memory_enabled=True,
memory_storage_mode="global", ...))` in-process via
`httpx.ASGITransport`. The upstream is `httpx.MockTransport`, the memory
backend is a recording fake, and `LITELLM_LOCAL_MODEL_COST_MAP=True`.
- Exact command / steps: a harness sends one request per path. The
mocked upstream answers with a tool call to `memory_delete`. The harness
records backend calls, upstream request count, and whether the client
response contains the call.
- Observed result (`origin/main` → this branch):
```text
chat       inject=False memory_delete  upstream_calls=2 backend_calls=[delete] client_saw_tool_call=False  →  upstream_calls=1 backend_calls=[] client_saw_tool_call=True
responses  inject=False memory_delete  upstream_calls=2 backend_calls=[delete] client_saw_tool_call=False  →  upstream_calls=1 backend_calls=[] client_saw_tool_call=True
anthropic  inject=False memory_delete  upstream_calls=2 backend_calls=[delete] client_saw_tool_call=False  →  upstream_calls=1 backend_calls=[] client_saw_tool_call=True
anthropic stream inject=False memory_delete  backend_calls=[delete] client_saw_tool_call=True  →  backend_calls=[] client_saw_tool_call=True
chat       inject=True, client-declared memory_delete  upstream_calls=2 backend_calls=[delete]  →  upstream_calls=1 backend_calls=[]
anthropic  inject=True, client-declared memory_delete  upstream_calls=2 backend_calls=[delete]  →  upstream_calls=1 backend_calls=[]
```
- Not tested: a live provider and a live Codex WebSocket session. The
WebSocket path is covered by the in-process test above.

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: n/a.
- Stable/default behavior changed: only for memory-named tool calls that
the proxy did not inject. See "Behaviour change" above. The default
`--memory` setup, where the proxy injects the tools, is unchanged.
- Kill switch / disable path: none needed.
- Unsafe override required: no.
- Qualification impact: none.
- Rollback path: revert this PR.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

Follow-up, not in this PR: on the Chat, Responses and WebSocket paths, a
single turn can call an injected memory tool and a client tool together.
The proxy then continues upstream without an output for the client's
call. That was already true for a client tool such as `shell`. It now
also applies to a memory-named tool that the client declared, which the
proxy used to run. The Anthropic non-streaming path already handles this
by returning the turn to the client. Bringing the OpenAI paths in line
is a separate change.

The docs need no change: `--no-memory-tools` is already documented as
"Disable automatic memory tool injection", which is now what it does.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4870"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-14 10:47:05 +05:30

1835 lines
62 KiB
Python

from __future__ import annotations
import asyncio
import json
import sys
from pathlib import Path
from types import SimpleNamespace
import pytest
from headroom.proxy import memory_handler as memory_handler_module
from headroom.proxy.memory_handler import (
MEMORY_TOOL_NAMES,
NATIVE_MEMORY_TOOL_NAME,
MemoryConfig,
MemoryHandler,
)
ALL_MEMORY_TOOLS = frozenset(MEMORY_TOOL_NAMES | {NATIVE_MEMORY_TOOL_NAME})
@pytest.fixture
def handler(tmp_path: Path) -> MemoryHandler:
return MemoryHandler(
MemoryConfig(
enabled=False,
use_native_tool=True,
native_memory_dir=str(tmp_path / "native"),
),
agent_type="codex",
)
class FakeBackend:
def __init__(self) -> None:
self.search_results: list[object] = []
self.searched: list[dict[str, object]] = []
self.saved: list[dict[str, object]] = []
self.updated: list[dict[str, object]] = []
self.deleted: list[str] = []
self.accessed: list[list[str]] = []
self.raise_on: str | None = None
async def search_memories(self, **kwargs): # noqa: ANN003
self.searched.append(kwargs)
if self.raise_on == "search":
raise RuntimeError("search failed")
return self.search_results
async def save_memory(self, **kwargs): # noqa: ANN003
if self.raise_on == "save":
raise RuntimeError("save failed")
self.saved.append(kwargs)
return SimpleNamespace(id=f"mem-{len(self.saved)}", content=kwargs["content"])
async def update_memory(self, **kwargs): # noqa: ANN003
if self.raise_on == "update":
raise RuntimeError("update failed")
self.updated.append(kwargs)
return SimpleNamespace(id=kwargs["memory_id"])
async def delete_memory(self, memory_id: str, user_id: str | None = None): # noqa: ANN201
if self.raise_on == "delete":
raise RuntimeError("delete failed")
self.deleted.append(memory_id)
return True
async def record_access(self, memory_ids: list[str]) -> int:
if self.raise_on == "record_access":
raise RuntimeError("access tracking failed")
self.accessed.append(memory_ids)
return len(memory_ids)
def make_result(
memory_id: str,
content: str,
*,
score: float = 0.9,
metadata: dict[str, object] | None = None,
related_entities: list[str] | None = None,
created_at: str | None = None,
importance: float = 0.5,
) -> object:
return SimpleNamespace(
memory=SimpleNamespace(
id=memory_id,
content=content,
metadata=metadata or {},
created_at=created_at,
importance=importance,
),
score=score,
related_entities=related_entities or [],
)
@pytest.mark.asyncio
async def test_execute_native_memory_tool_dispatches_and_wraps_errors(
handler: MemoryHandler, monkeypatch: pytest.MonkeyPatch
) -> None:
handler._backend = object()
called: list[tuple[str, dict[str, object], str]] = []
async def fake_ensure_initialized() -> None:
return None
async def fake_view(input_data, user_id, *, backend): # noqa: ANN001
assert backend is handler._backend
called.append(("view", input_data, user_id))
return "viewed"
async def fake_create(input_data, user_id, *, backend): # noqa: ANN001
assert backend is handler._backend
called.append(("create", input_data, user_id))
return "created"
monkeypatch.setattr(handler, "_ensure_initialized", fake_ensure_initialized)
monkeypatch.setattr(handler, "_native_view_semantic", fake_view)
monkeypatch.setattr(handler, "_native_create_semantic", fake_create)
assert await handler._execute_native_memory_tool({"command": "view"}, "u1") == "viewed"
assert await handler._execute_native_memory_tool({"command": "create"}, "u1") == "created"
assert (
await handler._execute_native_memory_tool({"command": "bad"}, "u1")
== "Error: Unknown command 'bad'"
)
async def boom(input_data, user_id, *, backend): # noqa: ANN001
raise RuntimeError("oops")
monkeypatch.setattr(handler, "_native_view_semantic", boom)
assert await handler._execute_native_memory_tool({"command": "view"}, "u1") == "Error: oops"
assert [entry[0] for entry in called] == ["view", "create"]
@pytest.mark.asyncio
async def test_semantic_search_recent_all_and_overview(handler: MemoryHandler) -> None:
backend = FakeBackend()
handler._backend = backend
backend.search_results = [
make_result(
"m1",
"Alice likes pizza and pasta",
score=0.91,
related_entities=["Alice", "pizza"],
created_at="2026-04-22",
),
make_result("m2", "Bob prefers ramen", score=0.83),
]
search_text = await handler._semantic_search("pizza", "u1", backend=handler._backend)
assert "Found 2 memories matching 'pizza'" in search_text
assert "[91% match] Alice likes pizza and pasta" in search_text
assert "Related: Alice, pizza" in search_text
recent_text = await handler._get_recent_memories("u1", limit=2, backend=handler._backend)
assert "Recent memories:" in recent_text
assert "(2026-04-22)" in recent_text
all_text = await handler._list_all_memories("u1", limit=2, backend=handler._backend)
assert "Showing up to 2 memories:" in all_text
assert "Showing first 2" in all_text
overview = await handler._get_memory_overview("u1", backend=handler._backend)
assert "Memory System (2 memories stored)" in overview
assert "view /memories/search/<your query>" in overview
@pytest.mark.asyncio
async def test_semantic_helpers_handle_empty_backend_and_errors(handler: MemoryHandler) -> None:
assert (
await handler._semantic_search(
"x",
"u1",
backend=handler._backend,
)
== "Error: Memory backend not initialized"
)
assert (
await handler._get_recent_memories(
"u1",
backend=handler._backend,
)
== "Error: Memory backend not initialized"
)
assert (
await handler._list_all_memories(
"u1",
backend=handler._backend,
)
== "Error: Memory backend not initialized"
)
assert (
await handler._get_memory_overview(
"u1",
backend=handler._backend,
)
== "Error: Memory backend not initialized"
)
backend = FakeBackend()
handler._backend = backend
assert "No memories found matching 'x'" in await handler._semantic_search(
"x",
"u1",
backend=handler._backend,
)
assert "No memories stored yet." in await handler._list_all_memories(
"u1",
backend=handler._backend,
)
assert "No memories stored yet." in await handler._get_recent_memories(
"u1",
backend=handler._backend,
)
backend.raise_on = "search"
assert "Error searching memories: search failed" == await handler._semantic_search(
"x",
"u1",
backend=handler._backend,
)
assert "Error getting recent memories: search failed" == await handler._get_recent_memories(
"u1",
backend=handler._backend,
)
assert "Error listing memories: search failed" == await handler._list_all_memories(
"u1",
backend=handler._backend,
)
overview = await handler._get_memory_overview("u1", backend=handler._backend)
assert "📁 Memory System" in overview
assert "To SEARCH memories" in overview
@pytest.mark.asyncio
async def test_native_view_semantic_routes_paths(
handler: MemoryHandler, monkeypatch: pytest.MonkeyPatch
) -> None:
seen: list[tuple[str, object]] = []
async def fake_search(query, user_id, top_k=5, *, backend): # noqa: ANN001
assert backend is handler._backend
seen.append(("search", query))
return "search-result"
async def fake_recent(user_id, limit=10, *, backend): # noqa: ANN001
assert backend is handler._backend
seen.append(("recent", limit))
return "recent-result"
async def fake_all(user_id, limit=20, *, backend): # noqa: ANN001
assert backend is handler._backend
seen.append(("all", limit))
return "all-result"
async def fake_overview(user_id, *, backend): # noqa: ANN001
assert backend is handler._backend
seen.append(("overview", user_id))
return "overview-result"
monkeypatch.setattr(handler, "_semantic_search", fake_search)
monkeypatch.setattr(handler, "_get_recent_memories", fake_recent)
monkeypatch.setattr(handler, "_list_all_memories", fake_all)
monkeypatch.setattr(handler, "_get_memory_overview", fake_overview)
assert (
await handler._native_view_semantic(
{"path": "/memories/search/pizza"},
"u1",
backend=handler._backend,
)
== "search-result"
)
assert (
await handler._native_view_semantic(
{"path": "/memories/recent"},
"u1",
backend=handler._backend,
)
== "recent-result"
)
assert (
await handler._native_view_semantic(
{"path": "/memories/all"},
"u1",
backend=handler._backend,
)
== "all-result"
)
assert (
await handler._native_view_semantic(
{"path": "/memories"},
"u1",
backend=handler._backend,
)
== "overview-result"
)
assert (
await handler._native_view_semantic(
{"path": "/memories/work/projects"},
"u1",
backend=handler._backend,
)
== "search-result"
)
assert (
await handler._native_view_semantic(
{"path": "/memories/search/"},
"u1",
backend=handler._backend,
)
).startswith("Error: Please provide a search query")
assert seen == [
("search", "pizza"),
("recent", 10),
("all", 20),
("overview", "u1"),
("search", "work projects"),
]
@pytest.mark.asyncio
async def test_native_semantic_create_append_delete_and_rename(handler: MemoryHandler) -> None:
backend = FakeBackend()
handler._backend = backend
assert (
await handler._native_create_semantic(
{},
"u1",
backend=handler._backend,
)
== "Error: path is required"
)
assert (
await handler._native_create_semantic(
{"path": "/memories/topic.txt"},
"u1",
backend=handler._backend,
)
== "Error: file_text is required (the memory content)"
)
created = await handler._native_create_semantic(
{"path": "/memories/topic.txt", "file_text": "prefers pizza"},
"u1",
backend=handler._backend,
)
assert created == "File created successfully at: /memories/topic.txt"
assert backend.saved[-1]["metadata"] == {
"virtual_path": "/memories/topic.txt",
"topic": "topic",
}
assert (
await handler._native_append_semantic(
{},
"u1",
backend=handler._backend,
)
== "Error: path is required"
)
assert (
await handler._native_append_semantic(
{"path": "/memories/topic.txt"},
"u1",
backend=handler._backend,
)
== "Error: insert_text is required"
)
appended = await handler._native_append_semantic(
{"path": "/memories/topic.txt", "insert_text": "and pasta"},
"u1",
backend=handler._backend,
)
assert appended == "The file /memories/topic.txt has been edited."
assert backend.saved[-1]["metadata"]["appended"] is True
backend.search_results = [
make_result(
"m1", "prefers pizza", metadata={"virtual_path": "/memories/topic.txt"}, score=0.6
),
make_result("m2", "prefers pasta", metadata={}, score=0.91),
]
deleted = await handler._native_delete_semantic(
{"path": "/memories/topic.txt"},
"u1",
backend=handler._backend,
)
assert deleted == "Successfully deleted /memories/topic.txt"
assert backend.deleted == ["m1", "m2"]
backend.search_results = [
make_result(
"m3", "old content", metadata={"virtual_path": "/memories/old.txt"}, importance=0.7
)
]
renamed = await handler._native_rename_semantic(
{"old_path": "/memories/old.txt", "new_path": "/memories/new/topic.txt"},
"u1",
backend=handler._backend,
)
assert renamed == "Successfully renamed /memories/old.txt to /memories/new/topic.txt"
assert backend.deleted[-1] == "m3"
assert backend.saved[-1]["metadata"] == {
"virtual_path": "/memories/new/topic.txt",
"topic": "new_topic",
}
@pytest.mark.asyncio
async def test_native_semantic_update_delete_rename_and_backend_errors(
handler: MemoryHandler,
) -> None:
backend = FakeBackend()
handler._backend = backend
assert (
await handler._native_update_semantic(
{},
"u1",
backend=handler._backend,
)
== "Error: path is required"
)
assert (
await handler._native_update_semantic(
{"path": "/memories/t.txt"},
"u1",
backend=handler._backend,
)
== "Error: old_str is required"
)
backend.search_results = [
make_result("m1", "hello hello world", metadata={"virtual_path": "/memories/t.txt"})
]
multi = await handler._native_update_semantic(
{"path": "/memories/t.txt", "old_str": "hello", "new_str": "bye"},
"u1",
backend=handler._backend,
)
assert "Multiple occurrences of old_str `hello`" in multi
backend.search_results = [
make_result("m1", "hello world", metadata={"virtual_path": "/memories/t.txt"})
]
edited = await handler._native_update_semantic(
{"path": "/memories/t.txt", "old_str": "hello", "new_str": "bye"},
"u1",
backend=handler._backend,
)
assert "The memory file has been edited." in edited
assert backend.updated[-1]["new_content"] == "bye world"
class NoUpdateBackend:
def __init__(self) -> None:
self.search_results: list[object] = []
self.saved: list[dict[str, object]] = []
self.deleted: list[str] = []
async def search_memories(self, **kwargs): # noqa: ANN003
return self.search_results
async def delete_memory(self, memory_id: str, user_id: str | None = None): # noqa: ANN201
self.deleted.append(memory_id)
return True
async def save_memory(self, **kwargs): # noqa: ANN003
self.saved.append(kwargs)
return SimpleNamespace(id=f"mem-{len(self.saved)}")
no_update_backend = NoUpdateBackend()
no_update_backend.search_results = [
make_result("m2", "alpha beta", metadata={"virtual_path": "/memories/t.txt"})
]
handler._backend = no_update_backend
fallback = await handler._native_update_semantic(
{"path": "/memories/t.txt", "old_str": "alpha", "new_str": "omega"},
"u1",
backend=handler._backend,
)
assert "The memory file has been edited." in fallback
assert no_update_backend.deleted[-1] == "m2"
assert no_update_backend.saved[-1]["content"] == "omega beta"
backend = FakeBackend()
handler._backend = backend
assert (
await handler._native_delete_semantic(
{},
"u1",
backend=handler._backend,
)
== "Error: path is required"
)
assert (
await handler._native_rename_semantic(
{},
"u1",
backend=handler._backend,
)
== "Error: old_path is required"
)
assert (
await handler._native_rename_semantic(
{"old_path": "/memories/a.txt"},
"u1",
backend=handler._backend,
)
== "Error: new_path is required"
)
assert (
await handler._native_delete_semantic(
{"path": "/memories/x.txt"},
"u1",
backend=handler._backend,
)
== "Error: The path /memories/x.txt does not exist"
)
assert (
await handler._native_rename_semantic(
{"old_path": "/memories/x.txt", "new_path": "/memories/y.txt"},
"u1",
backend=handler._backend,
)
== "Error: The path /memories/x.txt does not exist"
)
backend.search_results = [
make_result("m9", "content", metadata={"virtual_path": "/memories/other.txt"}, score=0.1)
]
assert (
await handler._native_delete_semantic(
{"path": "/memories/x.txt"},
"u1",
backend=handler._backend,
)
== "Error: The path /memories/x.txt does not exist"
)
assert (
await handler._native_rename_semantic(
{"old_path": "/memories/x.txt", "new_path": "/memories/y.txt"},
"u1",
backend=handler._backend,
)
== "Error: The path /memories/x.txt does not exist"
)
backend.raise_on = "search"
assert (
await handler._native_create_semantic(
{"path": "/memories/topic.txt", "file_text": "content"},
"u1",
backend=handler._backend,
)
== "File created successfully at: /memories/topic.txt"
)
backend.raise_on = "save"
assert (
await handler._native_create_semantic(
{"path": "/memories/topic.txt", "file_text": "content"},
"u1",
backend=handler._backend,
)
).startswith("Error: ")
assert (
await handler._native_append_semantic(
{"path": "/memories/topic.txt", "insert_text": "content"},
"u1",
backend=handler._backend,
)
).startswith("Error: ")
backend.raise_on = "search"
assert (
await handler._native_update_semantic(
{"path": "/memories/t.txt", "old_str": "a", "new_str": "b"},
"u1",
backend=handler._backend,
)
).startswith("Error: ")
assert (
await handler._native_delete_semantic(
{"path": "/memories/x.txt"},
"u1",
backend=handler._backend,
)
).startswith("Error: ")
assert (
await handler._native_rename_semantic(
{"old_path": "/memories/x.txt", "new_path": "/memories/y.txt"},
"u1",
backend=handler._backend,
)
).startswith("Error: ")
@pytest.mark.asyncio
@pytest.mark.parametrize(
"command",
[
pytest.param(
{"command": "create", "path": "/memories/topic.txt", "file_text": "new"},
id="create",
),
pytest.param({"command": "view", "path": "/memories/search/hello"}, id="search"),
pytest.param({"command": "view", "path": "/memories/recent"}, id="recent"),
pytest.param({"command": "view", "path": "/memories/all"}, id="all"),
pytest.param({"command": "view", "path": "/memories"}, id="overview"),
pytest.param({"command": "view", "path": "/memories/topic.txt"}, id="topic"),
pytest.param(
{
"command": "str_replace",
"path": "/memories/topic.txt",
"old_str": "hello",
"new_str": "bye",
},
id="update",
),
pytest.param(
{"command": "insert", "path": "/memories/topic.txt", "insert_text": "more"},
id="insert",
),
pytest.param({"command": "delete", "path": "/memories/topic.txt"}, id="delete"),
pytest.param(
{
"command": "rename",
"old_path": "/memories/topic.txt",
"new_path": "/memories/new.txt",
},
id="rename",
),
],
)
async def test_native_commands_use_only_the_resolved_project_backend(
handler: MemoryHandler, monkeypatch: pytest.MonkeyPatch, command: dict
) -> None:
from headroom.memory.storage_router import RequestContext
global_backend = FakeBackend()
handler._backend = global_backend
handler._initialized = True
contexts = [
RequestContext(
headers={"x-headroom-project-id": project},
system_prompt="",
base_user_id="same-user",
)
for project in ("project-one", "project-two")
]
backends = [FakeBackend(), FakeBackend()]
scopes = [handler._router.scope_for(context) for context in contexts]
routed = []
def _get_or_create_backend(db_path):
routed.append(db_path)
return backends[[scope.db_path for scope in scopes].index(db_path)]
monkeypatch.setattr(handler._router, "_get_or_create_backend", _get_or_create_backend)
operation_fields = ("searched", "saved", "updated", "deleted", "accessed")
for index, backend in enumerate(backends):
backend.search_results = [
make_result(
f"memory-{index}",
f"hello project-{index}",
metadata={"virtual_path": "/memories/topic.txt"},
)
]
for index, (context, backend) in enumerate(zip(contexts, backends)):
other_backend = backends[1 - index]
other_counts = [len(getattr(other_backend, field)) for field in operation_fields]
result = await handler._execute_native_memory_tool(
command, "same-user", request_context=context
)
assert not result.startswith("Error:"), result
assert routed == [scope.db_path for scope in scopes[: index + 1]]
assert [len(getattr(other_backend, field)) for field in operation_fields] == other_counts
assert handler._backend is global_backend
assert all(getattr(global_backend, field) == [] for field in operation_fields)
assert all(
operation["user_id"] == "same-user"
for operation in backend.searched + backend.saved + backend.updated
)
if command["command"] == "view":
assert f"hello project-{index}" in result
assert f"hello project-{1 - index}" not in result
assert backend.searched
elif command["command"] in {"create", "insert"}:
assert len(backend.saved) == 1
elif command["command"] == "str_replace":
assert backend.updated == [
{
"memory_id": f"memory-{index}",
"new_content": f"bye project-{index}",
"user_id": "same-user",
}
]
elif command["command"] == "delete":
assert backend.deleted == [f"memory-{index}"]
else:
assert backend.deleted == [f"memory-{index}"]
assert backend.saved[-1]["content"] == f"hello project-{index}"
assert backend.saved[-1]["metadata"]["virtual_path"] == "/memories/new.txt"
@pytest.mark.asyncio
@pytest.mark.parametrize("scope_mode", ["no-context", "global", "user", "composite"])
async def test_native_dispatch_preserves_legacy_scope_and_composite_identity(
handler: MemoryHandler, monkeypatch: pytest.MonkeyPatch, scope_mode: str
) -> None:
from headroom.memory.storage_router import MemoryStorageMode, RequestContext
global_backend = FakeBackend()
selected_backend = FakeBackend()
handler._backend = global_backend
handler._initialized = True
context = None
expected_backend = global_backend
expected_user_id = "same-user"
if scope_mode != "no-context":
handler._router._config.mode = {
"global": MemoryStorageMode.GLOBAL,
"user": MemoryStorageMode.USER,
"composite": MemoryStorageMode.PROJECT,
}[scope_mode]
context = RequestContext(
headers={"x-headroom-project-id": "selected-project"},
system_prompt="",
base_user_id="same-user",
)
if scope_mode == "composite":
handler.config.backend = "qdrant-neo4j"
scope = handler._router.scope_for(context)
expected_user_id = f"same-user::{scope.project_key}"
else:
expected_backend = selected_backend
monkeypatch.setattr(
handler._router, "_get_or_create_backend", lambda db_path: selected_backend
)
result = await handler._execute_native_memory_tool(
{"command": "create", "path": "/memories/topic.txt", "file_text": "content"},
"same-user",
request_context=context,
)
assert result == "File created successfully at: /memories/topic.txt"
assert len(expected_backend.saved) == 1
assert expected_backend.saved[0]["user_id"] == expected_user_id
other_backend = selected_backend if expected_backend is global_backend else global_backend
assert other_backend.saved == []
assert handler._backend is global_backend
@pytest.mark.asyncio
async def test_overlapping_native_rename_keeps_its_selected_backend(
handler: MemoryHandler, monkeypatch: pytest.MonkeyPatch
) -> None:
from headroom.memory.storage_router import RequestContext
global_backend = FakeBackend()
handler._backend = global_backend
handler._initialized = True
contexts = [
RequestContext(
headers={"x-headroom-project-id": project}, system_prompt="", base_user_id=user_id
)
for project, user_id in (("project-one", "user-one"), ("project-two", "user-two"))
]
backends = [FakeBackend(), FakeBackend()]
scopes = [handler._router.scope_for(context) for context in contexts]
monkeypatch.setattr(
handler._router,
"_get_or_create_backend",
lambda db_path: backends[[scope.db_path for scope in scopes].index(db_path)],
)
backends[0].search_results = [
make_result(
"private-one", "private content", metadata={"virtual_path": "/memories/old.txt"}
)
]
search_started = asyncio.Event()
second_request_finished = asyncio.Event()
search = backends[0].search_memories
async def _blocked_search(**kwargs):
search_started.set()
await second_request_finished.wait()
return await search(**kwargs)
monkeypatch.setattr(backends[0], "search_memories", _blocked_search)
first_request = asyncio.create_task(
handler._execute_native_memory_tool(
{"command": "rename", "old_path": "/memories/old.txt", "new_path": "/memories/new.txt"},
"user-one",
request_context=contexts[0],
)
)
try:
await asyncio.wait_for(search_started.wait(), timeout=2.0)
second_result = await handler._execute_native_memory_tool(
{"command": "create", "path": "/memories/two.txt", "file_text": "second content"},
"user-two",
request_context=contexts[1],
)
assert second_result == "File created successfully at: /memories/two.txt"
second_request_finished.set()
first_result = await asyncio.wait_for(first_request, timeout=2.0)
finally:
second_request_finished.set()
first_request.cancel()
await asyncio.gather(first_request, return_exceptions=True)
assert first_result == "Successfully renamed /memories/old.txt to /memories/new.txt"
assert backends[0].deleted == ["private-one"]
assert backends[0].saved[0]["content"] == "private content"
assert backends[0].saved[0]["user_id"] == "user-one"
assert backends[0].searched[0]["user_id"] == "user-one"
assert len(backends[1].saved) == 1
assert backends[1].saved[0]["user_id"] == "user-two"
assert backends[1].deleted == []
assert handler._backend is global_backend
assert global_backend.searched == global_backend.saved == global_backend.deleted == []
@pytest.mark.asyncio
async def test_execute_search_update_delete_and_handler_status(
handler: MemoryHandler, monkeypatch: pytest.MonkeyPatch
) -> None:
backend = FakeBackend()
handler._backend = backend
assert json.loads(await handler._execute_search({}, "u1")) == {
"status": "error",
"error": "query is required",
}
backend.search_results = [
make_result("m1", "pizza", score=0.9123, related_entities=["food", "italy"])
]
search_payload = json.loads(
await handler._execute_search(
{"query": "pizza", "top_k": 3, "include_related": False, "entities": ["food"]},
"u1",
)
)
assert search_payload["status"] == "found"
assert search_payload["count"] == 1
assert search_payload["memories"][0] == {
"id": "m1",
"content": "pizza",
"score": 0.912,
"entities": ["food", "italy"],
}
assert json.loads(await handler._execute_update({}, "u1")) == {
"status": "error",
"error": "memory_id is required",
}
assert json.loads(await handler._execute_update({"memory_id": "m1"}, "u1")) == {
"status": "error",
"error": "new_content is required",
}
backend.search_results = [make_result("m1", "old content")]
update_payload = json.loads(
await handler._execute_update(
{"memory_id": "m1", "new_content": "new content", "reason": "cleanup"},
"u1",
provider="openai",
)
)
assert update_payload == {"status": "updated", "memory_id": "m1"}
assert backend.updated[-1]["new_content"] == "new content"
class NoUpdateBackend:
def __init__(self) -> None:
self.deleted: list[str] = []
self.saved: list[dict[str, object]] = []
async def delete_memory(self, memory_id: str, user_id: str | None = None): # noqa: ANN201
self.deleted.append(memory_id)
return True
async def save_memory(self, **kwargs): # noqa: ANN003
self.saved.append(kwargs)
return SimpleNamespace(id="m2")
no_update_backend = NoUpdateBackend()
handler._backend = no_update_backend
update_fallback = json.loads(
await handler._execute_update({"memory_id": "m1", "new_content": "replacement"}, "u1")
)
assert update_fallback == {
"status": "updated",
"memory_id": "m2",
"note": "Replaced via delete+save",
}
assert no_update_backend.deleted == ["m1"]
handler._backend = backend
assert json.loads(await handler._execute_delete({}, "u1")) == {
"status": "error",
"error": "memory_id is required",
}
delete_payload = json.loads(await handler._execute_delete({"memory_id": "m1"}, "u1"))
assert delete_payload == {"status": "deleted", "memory_id": "m1"}
assert handler.health_status() == {
"enabled": False,
"backend": "local",
"initialized": False,
"native_tool": True,
"bridge_enabled": False,
}
seen = {"count": 0}
async def fake_ensure_initialized() -> None:
seen["count"] += 1
monkeypatch.setattr(handler, "_ensure_initialized", fake_ensure_initialized)
await handler.ensure_initialized()
assert seen["count"] == 1
@pytest.mark.asyncio
async def test_warmup_embedder_and_close(handler: MemoryHandler) -> None:
assert await handler.warmup_embedder() is False
class FakeEmbedder:
def __init__(self) -> None:
self.calls: list[str] = []
async def embed(self, value: str) -> None:
self.calls.append(value)
embedder = FakeEmbedder()
handler._initialized = True
handler._backend = SimpleNamespace(_hierarchical_memory=SimpleNamespace(_embedder=embedder))
assert await handler.warmup_embedder() is True
assert embedder.calls == ["warmup"]
handler._backend = SimpleNamespace(
_hierarchical_memory=SimpleNamespace(_embedder=SimpleNamespace())
)
assert await handler.warmup_embedder() is False
handler._backend = SimpleNamespace(close=lambda: None)
await handler.close()
assert handler.backend is None
assert handler.initialized is False
@pytest.mark.asyncio
async def test_execute_memory_tool_save_returns_dedup_hint(handler: MemoryHandler) -> None:
backend = FakeBackend()
handler._backend = backend
assert json.loads(await handler._execute_memory_tool("unknown", {}, "u1")) == {
"error": "Unknown tool: unknown"
}
assert json.loads(await handler._execute_memory_tool("memory_save", {}, "u1")) == {
"status": "error",
"error": "content is required",
}
backend.search_results = [
make_result(
"other",
"Very similar memory content " * 5,
score=0.8,
metadata={"source_agent": "claude"},
),
make_result("mem-1", "self result", score=0.99),
]
saved = json.loads(
await handler._execute_memory_tool(
"memory_save",
{
"content": "Useful fact",
"importance": 0.7,
"facts": ["fact"],
"entities": ["entity"],
"extracted_entities": ["entity"],
"relationships": ["rel"],
"extracted_relationships": ["rel"],
},
"u1",
provider="openai",
)
)
assert saved["status"] == "saved"
assert saved["memory_id"] == "mem-1"
assert "Similar memory exists" in saved["note"]
assert "saved by claude" in saved["note"]
assert backend.saved[-1]["metadata"]["source_provider"] == "openai"
assert backend.deleted == []
backend.raise_on = "save"
errored = json.loads(await handler._execute_memory_tool("memory_save", {"content": "x"}, "u1"))
# Backend exception text is logged, never returned to the model.
assert errored["status"] == "error"
assert errored["error"] == "internal_error"
assert "save failed" not in json.dumps(errored)
@pytest.mark.asyncio
async def test_execute_save_handles_search_failure(handler: MemoryHandler) -> None:
backend = FakeBackend()
handler._backend = backend
backend.raise_on = "search"
saved = json.loads(await handler._execute_save({"content": "Useful fact"}, "u1"))
assert saved == {"status": "saved", "memory_id": "mem-1", "content": "Useful fact"}
@pytest.mark.asyncio
async def test_execute_save_preserves_high_similarity_distinct_memory(
handler: MemoryHandler,
) -> None:
backend = FakeBackend()
handler._backend = backend
backend.search_results = [
make_result(
"existing-memory",
"User uses Python at work",
score=0.99,
metadata={"source_agent": "claude"},
)
]
saved = json.loads(
await handler._execute_save(
{"content": "User prefers Python for side projects"},
"u1",
)
)
# Give any accidentally scheduled background work a chance to run.
await asyncio.sleep(0)
assert saved["status"] == "saved"
assert "Similar memory exists" in saved["note"]
assert "ignore if these are distinct facts" in saved["note"]
assert backend.deleted == []
def test_inject_tools_extract_query_and_has_tool_calls(
handler: MemoryHandler, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.setattr(
handler,
"_get_memory_tools",
lambda: [
{
"function": {
"name": "memory_save",
"description": "save memory",
"parameters": {"type": "object"},
}
}
],
)
anthropic_tools, injected = handler.inject_tools([], "anthropic")
assert injected is True
assert anthropic_tools == [{"type": "memory_20250818", "name": "memory"}]
custom_handler = MemoryHandler(
MemoryConfig(enabled=False, inject_tools=True), agent_type="codex"
)
monkeypatch.setattr(
custom_handler,
"_get_memory_tools",
lambda: [
{
"function": {
"name": "memory_save",
"description": "save memory",
"parameters": {"type": "object"},
}
}
],
)
anthropic_custom, injected_custom = custom_handler.inject_tools([], "anthropic")
assert injected_custom is True
assert anthropic_custom == [
{"name": "memory_save", "description": "save memory", "input_schema": {"type": "object"}}
]
openai_custom, _ = custom_handler.inject_tools([], "openai")
assert openai_custom == [
{
"function": {
"name": "memory_save",
"description": "save memory",
"parameters": {"type": "object"},
}
}
]
existing, was_injected = custom_handler.inject_tools(
[{"function": {"name": "memory_save"}}],
"openai",
)
assert was_injected is False
assert existing == [{"function": {"name": "memory_save"}}]
assert handler._extract_user_query([{"role": "assistant", "content": "skip"}]) == ""
# Pre-PR-this method truncated at 500 chars; that was a real bug
# (none of Letta / Mem0 / Cognee / Supermemory truncate the
# retrieval query). Now returns the full message — embedder
# handles its own context window. See ``MemoryQuery``.
assert handler._extract_user_query([{"role": "user", "content": "x" * 600}]) == "x" * 600
assert (
handler._extract_user_query(
[{"role": "user", "content": [{"type": "text", "text": "hello"}, {"type": "image"}]}]
)
== "hello"
)
anthropic_response = {
"content": [{"type": "tool_use", "name": "memory_save", "id": "1", "input": {}}]
}
openai_response = {
"choices": [{"message": {"tool_calls": [{"id": "1", "function": {"name": "memory_save"}}]}}]
}
responses_api = {"output": [{"type": "function_call", "call_id": "2", "name": "memory"}]}
assert handler.has_memory_tool_calls(anthropic_response, "anthropic") is True
assert handler.has_memory_tool_calls(openai_response, "openai") is True
assert handler.has_memory_tool_calls(responses_api, "openai") is True
assert handler.has_memory_tool_calls({"content": []}, "anthropic") is False
@pytest.mark.asyncio
async def test_memory_handler_misc_helpers(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
handler = MemoryHandler(
MemoryConfig(
enabled=False,
use_native_tool=True,
inject_tools=True,
native_memory_dir=str(tmp_path / "native"),
),
agent_type="codex",
)
first_lock = handler._get_init_lock()
assert handler._get_init_lock() is first_lock
assert handler.get_beta_headers() == {"anthropic-beta": "context-management-2025-06-27"}
disabled_headers = MemoryHandler(
MemoryConfig(enabled=False, use_native_tool=False), agent_type="codex"
)
assert disabled_headers.get_beta_headers() == {}
tools, injected = handler._inject_native_tool([])
assert injected is True
assert tools == [{"type": "memory_20250818", "name": "memory"}]
same_tools, same_injected = handler._inject_native_tool([{"name": "memory"}])
assert same_injected is False
assert same_tools == [{"name": "memory"}]
calls = {"count": 0}
monkeypatch.setitem(
__import__("sys").modules,
"headroom.memory.tools",
SimpleNamespace(
get_memory_tools_optimized=lambda: (
calls.__setitem__("count", calls["count"] + 1) or [{"name": "tool"}]
)
),
)
cache_handler = MemoryHandler(MemoryConfig(enabled=False), agent_type="codex")
assert cache_handler._get_memory_tools() == [{"name": "tool"}]
assert cache_handler._get_memory_tools() == [{"name": "tool"}]
assert calls["count"] == 1
assert cache_handler._extract_tool_calls(
{"content": [{"type": "tool_use", "id": "1"}]}, "anthropic"
) == [{"type": "tool_use", "id": "1"}]
assert cache_handler._extract_tool_calls(
{"choices": [{"message": {"tool_calls": [{"id": "2"}]}}]},
"openai",
) == [{"id": "2"}]
assert cache_handler._extract_tool_calls(
{"output": [{"type": "function_call", "call_id": "3"}]},
"openai",
) == [{"type": "function_call", "call_id": "3"}]
assert cache_handler._extract_tool_calls({}, "other") == []
closed: list[str] = []
class Closable:
async def close(self) -> None:
closed.append("closed")
await cache_handler._close_backend_instance(Closable(), reason="test")
assert closed == ["closed"]
await cache_handler._close_backend_instance(SimpleNamespace(), reason="test")
class BrokenCloser:
def close(self) -> None:
raise RuntimeError("boom")
await cache_handler._close_backend_instance(BrokenCloser(), reason="test")
@pytest.mark.asyncio
async def test_search_and_format_context_and_handle_memory_tool_calls(
handler: MemoryHandler, monkeypatch: pytest.MonkeyPatch
) -> None:
backend = FakeBackend()
handler._backend = backend
handler._initialized = True
backend.search_results = [
make_result("m1", "Alice likes pizza", score=0.8, related_entities=["Alice", "pizza"]),
make_result("m2", "below threshold", score=0.2),
]
inject_none = await handler.search_and_format_context(
"u1",
[{"role": "assistant", "content": "skip"}],
)
assert inject_none is None
context = await handler.search_and_format_context(
"u1",
[{"role": "user", "content": "What food does Alice like?"}],
)
assert "## Relevant Memories for This User" in context
# Format now includes memory ID in brackets so the model can address
# rows directly via memory_update / memory_delete without round-
# tripping through memory_search.
assert "1. [m1] Alice likes pizza" in context
assert "(Related: Alice, pizza)" in context
assert backend.accessed == [["m1"]]
backend.raise_on = "search"
assert (
await handler.search_and_format_context("u1", [{"role": "user", "content": "Question"}])
is None
)
backend.raise_on = None
backend.raise_on = "record_access"
context = await handler.search_and_format_context(
"u1",
[{"role": "user", "content": "What food does Alice like?"}],
)
assert "1. [m1] Alice likes pizza" in context
backend.raise_on = None
async def fake_ensure_initialized() -> None:
return None
async def fake_execute_memory_tool(
tool_name, input_data, user_id, provider="anthropic", *, request_context=None
): # noqa: ANN001
return f"ran:{tool_name}:{user_id}:{provider}:{input_data}"
async def fake_execute_native(input_data, user_id, request_context=None): # noqa: ANN001
return f"native:{user_id}:{input_data}"
monkeypatch.setattr(handler, "_ensure_initialized", fake_ensure_initialized)
monkeypatch.setattr(handler, "_execute_memory_tool", fake_execute_memory_tool)
monkeypatch.setattr(handler, "_execute_native_memory_tool", fake_execute_native)
anthropic_results = await handler.handle_memory_tool_calls(
{
"content": [
{"type": "tool_use", "name": "memory_save", "id": "a1", "input": {"content": "x"}},
{"type": "tool_use", "name": "memory", "id": "a2", "input": {"command": "view"}},
{"type": "tool_use", "name": "other", "id": "a3", "input": {}},
]
},
"u1",
"anthropic",
tool_names=ALL_MEMORY_TOOLS,
)
assert anthropic_results == [
{
"type": "tool_result",
"tool_use_id": "a1",
"content": "ran:memory_save:u1:anthropic:{'content': 'x'}",
},
{"type": "tool_result", "tool_use_id": "a2", "content": "native:u1:{'command': 'view'}"},
]
openai_results = await handler.handle_memory_tool_calls(
{
"choices": [
{
"message": {
"tool_calls": [
{
"id": "o1",
"function": {
"name": "memory_search",
"arguments": '{"query":"pizza"}',
},
},
{"id": "o2", "function": {"name": "other", "arguments": "{}"}},
]
}
}
]
},
"u1",
"openai",
tool_names=ALL_MEMORY_TOOLS,
)
assert openai_results == [
{
"role": "tool",
"tool_call_id": "o1",
"content": "ran:memory_search:u1:openai:{'query': 'pizza'}",
}
]
handler._backend = None
skipped = await handler.handle_memory_tool_calls(
{
"choices": [
{
"message": {
"tool_calls": [
{
"id": "o3",
"function": {"name": "memory_delete", "arguments": "{}"},
}
]
}
}
]
},
"u1",
"openai",
tool_names=ALL_MEMORY_TOOLS,
)
assert skipped == []
@pytest.mark.asyncio
async def test_search_records_only_memories_left_by_final_text_budget(
handler: MemoryHandler,
) -> None:
backend = FakeBackend()
handler._backend = backend
handler._initialized = True
backend.search_results = [
make_result("m1", "First preference"),
make_result("m2", "Second preference"),
]
class FirstEntryBudget:
max_entries = 2
min_similarity = 0.3
max_tokens = 1024
@staticmethod
def apply_to_text(text: str) -> str:
return text.split("2. [m2]", maxsplit=1)[0]
context = await handler.search_and_format_context(
"u1",
[{"role": "user", "content": "What are my preferences?"}],
budget=FirstEntryBudget(),
)
assert "[m1]" in context
assert "[m2]" not in context
assert backend.accessed == [["m1"]]
@pytest.mark.asyncio
async def test_ensure_initialized_timeout_and_cancellation(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
handler = MemoryHandler(
MemoryConfig(
enabled=True, use_native_tool=True, native_memory_dir=str(tmp_path / "native")
),
agent_type="codex",
)
closed: list[str] = []
class ClosableBackend:
async def close(self) -> None:
closed.append("closed")
async def fake_init_backend_locked() -> None:
handler._backend = ClosableBackend()
monkeypatch.setattr(handler, "_init_backend_locked", fake_init_backend_locked)
async def fake_wait_for_timeout(coro, timeout): # noqa: ANN001
await coro
raise asyncio.TimeoutError
monkeypatch.setattr(memory_handler_module.asyncio, "wait_for", fake_wait_for_timeout)
await handler._ensure_initialized()
assert handler.backend is None
assert handler.initialized is False
assert closed == ["closed"]
async def fake_wait_for_cancel(coro, timeout): # noqa: ANN001
await coro
raise asyncio.CancelledError
monkeypatch.setattr(memory_handler_module.asyncio, "wait_for", fake_wait_for_cancel)
with pytest.raises(asyncio.CancelledError):
await handler._ensure_initialized()
assert handler.backend is None
assert handler.initialized is False
assert closed == ["closed", "closed"]
@pytest.mark.asyncio
async def test_init_backend_locked_local_and_bridge_import(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
handler = MemoryHandler(
MemoryConfig(
enabled=True,
backend="local",
db_path=str(tmp_path / "memory.db"),
bridge_enabled=True,
bridge_auto_import=True,
bridge_md_paths=[str(tmp_path / "notes.md")],
bridge_md_format="auto",
bridge_export_path=str(tmp_path / "export"),
),
agent_type="codex",
)
seen: dict[str, object] = {}
class FakeLocalBackendConfig:
def __init__(self, **kwargs): # noqa: ANN003
seen["config"] = kwargs
for key, value in kwargs.items():
setattr(self, key, value)
class FakeLocalBackend:
def __init__(self, config) -> None: # noqa: ANN001
seen["backend_config"] = config
async def _ensure_initialized(self) -> None:
seen["backend_initialized"] = True
async def fake_init_and_import_bridge() -> None:
seen["bridge_called"] = True
monkeypatch.setitem(
sys.modules,
"headroom.memory.backends.local",
SimpleNamespace(
LocalBackend=FakeLocalBackend,
LocalBackendConfig=FakeLocalBackendConfig,
),
)
monkeypatch.setitem(sys.modules, "onnxruntime", SimpleNamespace())
monkeypatch.setattr(handler, "_init_and_import_bridge", fake_init_and_import_bridge)
await handler._init_backend_locked()
assert handler.initialized is True
assert seen["backend_initialized"] is True
assert seen["bridge_called"] is True
assert seen["config"] == {
"db_path": str(tmp_path / "memory.db"),
"embedder_backend": "onnx",
"embedder_model": "all-MiniLM-L6-v2",
"vector_dimension": 384,
}
@pytest.mark.asyncio
async def test_init_and_import_bridge_success_and_failure(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
handler = MemoryHandler(
MemoryConfig(
enabled=True,
bridge_enabled=True,
bridge_md_paths=[str(tmp_path / "notes.md")],
bridge_md_format="auto",
bridge_export_path=str(tmp_path / "export"),
),
agent_type="codex",
)
handler._backend = object()
seen: dict[str, object] = {}
class FakeMarkdownFormat(str):
pass
class FakeBridgeConfig:
def __init__(self, **kwargs): # noqa: ANN003
seen["bridge_config"] = kwargs
class FakeMemoryBridge:
def __init__(self, config, backend) -> None: # noqa: ANN001
seen["bridge_backend"] = backend
self.config = config
async def import_from_markdown(self):
return SimpleNamespace(sections_imported=2, sections_skipped_duplicate=1)
monkeypatch.setitem(
sys.modules,
"headroom.memory.bridge",
SimpleNamespace(MemoryBridge=FakeMemoryBridge),
)
monkeypatch.setitem(
sys.modules,
"headroom.memory.bridge_config",
SimpleNamespace(
BridgeConfig=FakeBridgeConfig,
MarkdownFormat=FakeMarkdownFormat,
),
)
await handler._init_and_import_bridge()
assert isinstance(handler._bridge, FakeMemoryBridge)
assert seen["bridge_backend"] is handler._backend
assert seen["bridge_config"] == {
"md_paths": [tmp_path / "notes.md"],
"md_format": "auto",
"auto_import_on_startup": True,
"export_path": tmp_path / "export",
}
class BrokenMemoryBridge(FakeMemoryBridge):
async def import_from_markdown(self):
raise RuntimeError("bridge failed")
handler._bridge = None
monkeypatch.setitem(
sys.modules,
"headroom.memory.bridge",
SimpleNamespace(MemoryBridge=BrokenMemoryBridge),
)
await handler._init_and_import_bridge()
assert isinstance(handler._bridge, BrokenMemoryBridge)
def test_memory_handler_init_defaults_and_tool_injection_edges(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
native_dir = tmp_path / "workspace-memory"
monkeypatch.setattr(
"headroom.paths.native_memory_dir",
lambda: native_dir,
)
handler = MemoryHandler(MemoryConfig(enabled=False, use_native_tool=True), agent_type="codex")
assert handler._native_memory_dir == native_dir
assert native_dir.exists()
disabled_injection = MemoryHandler(
MemoryConfig(enabled=False, inject_tools=False, use_native_tool=False),
agent_type="codex",
)
assert disabled_injection.inject_tools(None, "openai") == ([], False)
same_type_tools, same_type_injected = handler._inject_native_tool(
[{"type": "memory_20250818", "name": "other"}]
)
assert same_type_injected is False
assert same_type_tools == [{"type": "memory_20250818", "name": "other"}]
@pytest.mark.asyncio
async def test_ensure_initialized_fast_paths_and_qdrant_variants(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
disabled = MemoryHandler(MemoryConfig(enabled=False), agent_type="codex")
await disabled._ensure_initialized()
assert disabled.initialized is False
initialized = MemoryHandler(MemoryConfig(enabled=True), agent_type="codex")
initialized._initialized = True
await initialized._ensure_initialized()
assert initialized.initialized is True
qdrant_handler = MemoryHandler(
MemoryConfig(enabled=True, backend="qdrant-neo4j"),
agent_type="codex",
)
seen: dict[str, object] = {}
class FakeMem0Config:
def __init__(self, **kwargs): # noqa: ANN003
seen["config"] = kwargs
class FakeAdapter:
def __init__(self, config) -> None: # noqa: ANN001
seen["adapter_config"] = config
async def ensure_initialized(self) -> None:
seen["initialized"] = True
monkeypatch.setitem(
sys.modules,
"headroom.memory.backends.direct_mem0",
SimpleNamespace(DirectMem0Adapter=FakeAdapter, Mem0Config=FakeMem0Config),
)
await qdrant_handler._init_backend_locked()
assert qdrant_handler.initialized is True
assert seen["initialized"] is True
assert seen["config"] == {
"qdrant_url": None,
"qdrant_host": "localhost",
"qdrant_port": 6333,
"qdrant_api_key": None,
"neo4j_uri": "neo4j://localhost:7687",
"neo4j_user": "neo4j",
"neo4j_password": "",
"enable_graph": True,
}
monkeypatch.setitem(sys.modules, "headroom.memory.backends.direct_mem0", None)
import builtins
real_import = builtins.__import__
def fake_import(name, globals=None, locals=None, fromlist=(), level=0):
if name == "headroom.memory.backends.direct_mem0":
raise ImportError("missing mem0")
return real_import(name, globals, locals, fromlist, level)
monkeypatch.setattr(builtins, "__import__", fake_import)
broken_qdrant = MemoryHandler(
MemoryConfig(enabled=True, backend="qdrant-neo4j"),
agent_type="codex",
)
with pytest.raises(ImportError, match="missing mem0"):
await broken_qdrant._init_backend_locked()
monkeypatch.setattr(builtins, "__import__", real_import)
unknown = MemoryHandler(MemoryConfig(enabled=True, backend="local"), agent_type="codex")
unknown.config.backend = "mystery" # type: ignore[assignment]
with pytest.raises(ValueError, match="Unknown memory backend"):
await unknown._init_backend_locked()
@pytest.mark.asyncio
async def test_init_and_import_bridge_early_return_and_context_formatting_edges(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
handler = MemoryHandler(
MemoryConfig(
enabled=True, bridge_enabled=True, bridge_md_paths=[str(tmp_path / "notes.md")]
),
agent_type="codex",
)
handler._bridge = object()
await handler._init_and_import_bridge()
assert handler._bridge is not None
handler.config.inject_context = False
assert (
await handler.search_and_format_context("u1", [{"role": "user", "content": "hello"}])
is None
)
handler.config.inject_context = True
handler._backend = FakeBackend()
handler._initialized = True
handler._backend.search_results = [make_result("m1", "too low", score=0.1)]
assert (
await handler.search_and_format_context(
"u1", [{"role": "user", "content": [{"type": "image"}]}]
)
is None
)
assert (
await handler.search_and_format_context("u1", [{"role": "user", "content": "hello"}])
is None
)
@pytest.mark.asyncio
async def test_extract_tool_calls_and_handle_tool_calls_parse_edges(
handler: MemoryHandler, monkeypatch: pytest.MonkeyPatch
) -> None:
assert handler._extract_tool_calls({"content": "bad"}, "anthropic") == []
assert handler._extract_tool_calls({"choices": []}, "openai") == []
assert handler._extract_tool_calls({"output": "bad"}, "openai") == []
backend = FakeBackend()
handler._backend = backend
async def fake_ensure_initialized() -> None:
return None
async def fake_execute(
tool_name, input_data, user_id, provider="anthropic", *, request_context=None
): # noqa: ANN001
return f"ok:{tool_name}:{input_data}"
monkeypatch.setattr(handler, "_ensure_initialized", fake_ensure_initialized)
monkeypatch.setattr(handler, "_execute_memory_tool", fake_execute)
results = await handler.handle_memory_tool_calls(
{
"output": [
{
"type": "function_call",
"call_id": "fc1",
"name": "memory_search",
"arguments": "{bad",
},
{"type": "function_call", "call_id": "fc2", "name": "other", "arguments": "{}"},
]
},
"u1",
"openai",
tool_names=ALL_MEMORY_TOOLS,
)
assert results == [{"role": "tool", "tool_call_id": "fc1", "content": "ok:memory_search:{}"}]
# ── memory_list (browse without semantic query) ──────────────────────
@pytest.mark.asyncio
async def test_execute_list_returns_recent_memories_with_ids(handler: MemoryHandler) -> None:
"""memory_list returns memories in reverse-chronological order with
IDs, content, and timestamps. Distinct from memory_search — no
semantic query required; model can browse to discover IDs."""
class ListBackend:
async def search_memories(self, **kwargs): # noqa: ANN003
return []
async def list_memories(self, *, user_id, limit): # noqa: ANN001, ANN201
assert user_id == "u1"
assert limit == 5
return [
make_result("mem_002", "newest fact", created_at="2026-05-19T12:00:00+00:00"),
make_result("mem_001", "older fact", created_at="2026-05-18T10:00:00+00:00"),
]
handler._backend = ListBackend() # type: ignore[assignment]
handler._initialized = True
out = await handler._execute_list({"limit": 5}, "u1")
payload = json.loads(out)
assert payload["status"] == "ok"
assert payload["count"] == 2
assert payload["memories"][0]["id"] == "mem_002"
assert payload["memories"][0]["content"] == "newest fact"
assert payload["memories"][0]["created_at"] == "2026-05-19T12:00:00+00:00"
assert payload["memories"][1]["id"] == "mem_001"
@pytest.mark.asyncio
async def test_execute_list_falls_back_to_search_when_list_unavailable(
handler: MemoryHandler,
) -> None:
"""Backends without list_memories fall back to an empty-query
search — most backends treat that as "return recent." Locks the
fallback path so a future backend without list_memories still works."""
class SearchOnlyBackend:
async def search_memories(self, *, query, user_id, top_k, **kwargs): # noqa: ANN001, ANN003
assert query == "" # fallback uses empty query
assert top_k == 3
return [make_result("mem_x", "anything", created_at=None)]
handler._backend = SearchOnlyBackend() # type: ignore[assignment]
handler._initialized = True
out = await handler._execute_list({"limit": 3}, "u1")
payload = json.loads(out)
assert payload["status"] == "ok"
assert payload["count"] == 1
assert payload["memories"][0]["id"] == "mem_x"
@pytest.mark.asyncio
async def test_execute_list_caps_limit_to_1_100(handler: MemoryHandler) -> None:
"""Defensive: input limit is clamped to [1, 100]. Protects the
backend from a runaway value the model might invent."""
received_limits: list[int] = []
class LimitWatcher:
async def search_memories(self, **kwargs): # noqa: ANN003
return []
async def list_memories(self, *, user_id, limit): # noqa: ANN001, ANN201
received_limits.append(limit)
return []
handler._backend = LimitWatcher() # type: ignore[assignment]
handler._initialized = True
await handler._execute_list({"limit": 99999}, "u1")
await handler._execute_list({"limit": 0}, "u1")
await handler._execute_list({"limit": "bogus"}, "u1") # type: ignore[dict-item]
assert received_limits == [100, 1, 10] # clamped to 100, 1, default 10
@pytest.mark.asyncio
async def test_memory_list_dispatched_via_execute_memory_tool(handler: MemoryHandler) -> None:
"""End-to-end: memory_list in MEMORY_TOOL_NAMES means the
handler.handle_memory_tool_calls dispatcher routes it correctly."""
class StubBackend:
async def search_memories(self, **kwargs): # noqa: ANN003
return []
async def list_memories(self, *, user_id, limit): # noqa: ANN001, ANN201
return [make_result("m1", "fact", created_at=None)]
handler._backend = StubBackend() # type: ignore[assignment]
handler._initialized = True
out = await handler._execute_memory_tool("memory_list", {"limit": 5}, "u1", "anthropic")
payload = json.loads(out)
assert payload["status"] == "ok"
assert payload["memories"][0]["id"] == "m1"
@pytest.mark.asyncio
async def test_search_and_format_context_degrades_gracefully_on_backend_error(
handler: MemoryHandler, monkeypatch: pytest.MonkeyPatch
) -> None:
import sqlite3
async def fail_init() -> None:
raise sqlite3.OperationalError("unable to open database file")
monkeypatch.setattr(handler, "_ensure_initialized", fail_init)
result = await handler.search_and_format_context("u1", [{"role": "user", "content": "hello"}])
assert result is None