Pre-this-PR the auto-injected memory block rendered rows as `1. <content>`
with no addressable handle. To UPDATE or DELETE a row the model first had
to call memory_search to discover its ID — two round trips, against the
model-as-judge architecture.
This PR adds three tightly-coupled affordances so the model can act on
memory directly:
1. Auto-tail rows now carry the memory ID:
`1. [mem_alpha_001] User prefers Python`
The bracketed token is the canonical ID — same identifier accepted by
memory_update and memory_delete.
2. New `memory_list` tool — chronological browse (vs `memory_search`'s
semantic lookup). Returns recent memories with their IDs. Backend
dispatches to `Backend.list_memories` if available, else falls back
to an empty-query `search_memories`. Caps at 100 entries.
3. ID-usage guidance text appended to the auto-tail block. Tells the
model that bracketed IDs can go straight to memory_update /
memory_delete with no intervening search. The guidance lives in the
user-message tail (never system) — preserves cache-prefix byte
stability (invariant I2).
`memory_update` and `memory_delete` tool descriptions also point at the
[id] block as a valid ID source — keeps tool docs consistent with the
new affordance.
Verification:
- 10/10 tests pass in tests/test_memory_auto_tail.py (incl. 2 new
guidance tests + 2 new ID-format tests)
- 31/31 tests pass in tests/test_memory_handler_native_ops.py (incl. 4
new memory_list dispatch tests + existing assertions updated for the
[id] format change)
- Golden fixtures regenerated for the tool-description copy changes
(tests/fixtures/memory_tool_definitions/{anthropic,openai}.json)
- Live end-to-end test against real Anthropic API
(tests/test_proxy_memory_integration.py::TestMemoryIdAutoTailAndUpdate):
seeded memory → auto-tail → Claude → memory_update with exact ID.
PASSED.
Closes the second half of P0-6: once memory injects memory_save / memory_search
into body["tools"] for a session, every subsequent turn injects the byte-equal
same definitions — even if memory is disabled mid-session. Toggling tool list
mid-session busts Anthropic prefix cache per guide §6.3 #2.
Adds in headroom/proxy/helpers.py:
* SessionToolTracker — bounded LRU keyed by (provider, session_id) storing
GOLDEN tool-definition bytes from the first injection. Tracker is
provider-aware so the same session_id under Anthropic and OpenAI keeps
independent state. Reentrant lock for concurrent access; LRU eviction at
HEADROOM_TOOL_TRACKER_MAX_SESSIONS (default 1000).
* apply_session_sticky_memory_tools — single coordination point with three
paths: first-time inject (record golden bytes), sticky replay (always
inject golden bytes regardless of inject_this_turn), and skip. Honors
HEADROOM_TOOL_INJECTION_STICKY=disabled as a loud operator opt-in for
rollback (NOT a fallback).
* serialize_tool_definition_canonical — deterministic byte serialization
via the same separators=(",",":")/ensure_ascii=False rules as
serialize_body_canonical.
* log_tool_injection_decision — structured per-decision log line; never
logs the tool definition contents.
Wires the helper into all four memory tool injection sites:
* handlers/anthropic.py — /v1/messages
* handlers/openai.py — /v1/chat/completions
* handlers/openai.py — /v1/responses
* handlers/openai.py — Codex WS path
memory_handler.MemoryHandler gains compute_memory_tool_definitions(provider) —
a pure builder that returns the tool definitions without mutating a tools
list, so the proxy can route through the sticky tracker. The legacy
inject_tools(...) is preserved for callers without a session_id.
Tests: tests/test_memory_tool_session_sticky.py — 29 unit + integration
cases covering: turn-1→turn-2 byte-equality (Anthropic + OpenAI), sticky
replay after memory disabled, golden-fixture pin, LRU eviction, provider
isolation under shared session_id, thread-safe concurrent access, env-var
contract, disabled-mode passthrough, dedupe with client tools.
Golden fixtures pin canonical bytes:
* tests/fixtures/memory_tool_definitions/anthropic.json
* tests/fixtures/memory_tool_definitions/openai.json
No regex. No hardcodes (env-configurable: HEADROOM_TOOL_INJECTION_STICKY,
HEADROOM_TOOL_TRACKER_MAX_SESSIONS). No silent fallbacks. Per-decision
structured logging. Realignment build constraints satisfied.
