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.

Add cross-agent memory interoperability via MCP, sync engine, and atomic facts

Tejas Chopra82301bbf7667
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index f82a4614a..01a0ccb1e 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -320,6 +320,11 @@ rtk pip list rtk pnpm install rtk npm run <script>
# Marker used to detect if instructions are already injected
_RTK_MARKER = "<!-- headroom:rtk-instructions -->"
+# Memory MCP markers
+_MEMORY_MCP_MARKER = "# --- Headroom memory MCP (auto-injected) ---"
+_MEMORY_MCP_END = "# --- end Headroom memory ---"
+_MEMORY_AGENTS_MARKER = "<!-- headroom:memory-instructions -->"
+
def _ensure_rtk_binary(verbose: bool = False) -> Path | None:
"""Ensure rtk binary is installed (download if needed). No hook registration."""
@@ -364,11 +369,12 @@ def _inject_codex_provider_config(port: int) -> None:
config_dir = Path.home() / ".codex"
config_file = config_dir / "config.toml"
- headroom_section = (
- f"\n# --- Headroom proxy (auto-injected by headroom wrap codex) ---\n"
- f'model_provider = "headroom"\n'
- f"\n"
- f"[model_providers.headroom]\n"
+ # model_provider must be a top-level TOML key (before any [section]).
+ # The [model_providers.headroom] table can go at the end.
+ top_level_marker = "# --- Headroom proxy (auto-injected by headroom wrap codex) ---"
+ top_level_block = f'{top_level_marker}\nmodel_provider = "headroom"\n'
+ provider_section = (
+ f"\n[model_providers.headroom]\n"
f'name = "OpenAI via Headroom proxy"\n'
f'base_url = "http://127.0.0.1:{port}/v1"\n'
f'env_key = "OPENAI_API_KEY"\n'
@@ -377,7 +383,7 @@ def _inject_codex_provider_config(port: int) -> None:
f"# --- end Headroom ---\n"
)
- marker = "# --- Headroom proxy (auto-injected by headroom wrap codex) ---"
+ marker = top_level_marker
end_marker = "# --- end Headroom ---"
try:
@@ -386,14 +392,20 @@ def _inject_codex_provider_config(port: int) -> None:
if config_file.exists():
content = config_file.read_text()
if marker in content:
- # Replace existing section
+ # Remove existing Headroom blocks entirely
start = content.index(marker)
end = content.index(end_marker) + len(end_marker)
- content = content[:start].rstrip() + headroom_section + content[end:].lstrip("\n")
- else:
- content = content.rstrip() + "\n" + headroom_section
+ content = content[:start].rstrip("\n") + content[end:].lstrip("\n")
+
+ # Strip any stale top-level model_provider left behind
+ import re
+
+ content = re.sub(r'\nmodel_provider\s*=\s*"headroom"\n', "\n", content)
+
+ # Place top-level key at the very beginning, provider table at the end
+ content = top_level_block + "\n" + content.strip() + "\n" + provider_section
else:
- content = headroom_section
+ content = top_level_block + "\n" + provider_section
config_file.write_text(content)
click.echo(f" Codex config: injected Headroom provider (WS + HTTP) into {config_file}")
@@ -424,6 +436,81 @@ def _inject_rtk_instructions(file_path: Path, verbose: bool = False) -> bool:
return True
+def _inject_memory_mcp_config(db_path: str, user_id: str) -> None:
+ """Register headroom memory as an MCP server in Codex's config.toml.
+
+ Idempotent — replaces existing section if present.
+ """
+ import sys
+
+ config_dir = Path.home() / ".codex"
+ config_file = config_dir / "config.toml"
+
+ # Use forward slashes in TOML paths (works on all platforms, avoids
+ # backslash escaping issues on Windows)
+ python_bin = sys.executable.replace("\\", "/")
+ db_path_toml = db_path.replace("\\", "/")
+ mcp_section = (
+ f"\n{_MEMORY_MCP_MARKER}\n"
+ f"[mcp_servers.headroom_memory]\n"
+ f'command = "{python_bin}"\n'
+ f'args = ["-m", "headroom.memory.mcp_server", "--db", "{db_path_toml}", "--user", "{user_id}"]\n'
+ f"startup_timeout_sec = 30\n"
+ f"tool_timeout_sec = 30\n"
+ f"{_MEMORY_MCP_END}\n"
+ )
+
+ try:
+ config_dir.mkdir(parents=True, exist_ok=True)
+
+ if config_file.exists():
+ content = config_file.read_text()
+ if _MEMORY_MCP_MARKER in content:
+ start = content.index(_MEMORY_MCP_MARKER)
+ end = content.index(_MEMORY_MCP_END) + len(_MEMORY_MCP_END)
+ content = content[:start].rstrip("\n") + mcp_section + content[end:].lstrip("\n")
+ else:
+ content = content.rstrip() + "\n" + mcp_section
+ else:
+ content = mcp_section
+
+ config_file.write_text(content)
+ click.echo(f" Memory MCP: registered in {config_file}")
+ except Exception as e:
+ click.echo(f" Warning: could not register memory MCP: {e}")
+
+
+def _inject_memory_agents_md(file_path: Path) -> bool:
+ """Inject memory usage guidance into AGENTS.md.
+
+ Idempotent — skips if marker already present.
+ """
+ memory_block = (
+ f"{_MEMORY_AGENTS_MARKER}\n"
+ "## Memory\n\n"
+ "Use the `headroom_memory` MCP server for persistent cross-session knowledge.\n\n"
+ "**Before** answering questions about prior decisions, conventions, project context,\n"
+ "architecture, user preferences, org info, codenames, debugging history, or anything\n"
+ "from past sessions — call `memory_search` first.\n\n"
+ "**After** making durable decisions, discovering conventions, or learning important\n"
+ "facts — call `memory_save` to persist them for future sessions.\n\n"
+ "Memory is your first source of truth for anything not visible in the current conversation.\n"
+ )
+
+ if file_path.exists():
+ existing = file_path.read_text()
+ if _MEMORY_AGENTS_MARKER in existing:
+ return True # Already injected
+ with open(file_path, "a") as f:
+ f.write("\n\n" + memory_block)
+ else:
+ file_path.parent.mkdir(parents=True, exist_ok=True)
+ file_path.write_text(memory_block)
+
+ click.echo(f" Memory guidance injected into {file_path.name}")
+ return True
+
+
def _resolve_copilot_provider_type(backend: str | None, provider_type: str) -> str:
"""Resolve Copilot BYOK provider type for the current proxy backend."""
if provider_type != "auto":
@@ -1088,6 +1175,48 @@ def claude(
signal.signal(signal.SIGINT, cleanup)
signal.signal(signal.SIGTERM, cleanup)
+ # Memory sync BEFORE proxy startup — sync headroom DB ↔ Claude's files
+ if memory:
+ try:
+ import subprocess as _sp
+
+ mem_dir = Path.cwd() / ".headroom"
+ mem_dir.mkdir(parents=True, exist_ok=True)
+ _sync_db = str(mem_dir / "memory.db")
+ _sync_user = os.environ.get("USER", os.environ.get("USERNAME", "default"))
+
+ click.echo(f" Syncing memory (user={_sync_user})...")
+ sync_result = _sp.run(
+ [
+ sys.executable,
+ "-m",
+ "headroom.memory.sync",
+ "--db",
+ _sync_db,
+ "--user",
+ _sync_user,
+ "--agent",
+ "claude",
+ "--force",
+ ],
+ capture_output=True,
+ text=True,
+ timeout=30,
+ )
+ if sync_result.returncode == 0 and sync_result.stdout.strip():
+ import json as _json
+
+ stats = _json.loads(sync_result.stdout.strip().split("\n")[-1])
+ imp, exp, ms = stats["imported"], stats["exported"], stats["ms"]
+ if imp or exp:
+ click.echo(f" Memory synced: {imp} imported, {exp} exported ({ms}ms)")
+ else:
+ click.echo(f" Memory: up to date ({ms}ms)")
+ elif sync_result.returncode != 0:
+ click.echo(f" Warning: memory sync error: {sync_result.stderr[-200:]}")
+ except Exception as e:
+ click.echo(f" Warning: memory sync failed: {e}")
+
try:
click.echo()
click.echo(" ╔═══════════════════════════════════════════════╗")
@@ -1357,6 +1486,49 @@ def codex(
global_agents = Path.home() / ".codex" / "AGENTS.md"
_inject_rtk_instructions(global_agents, verbose=verbose)
+ # Setup memory MCP server for Codex (native tool integration)
+ if memory:
+ click.echo(" Setting up memory for Codex...")
+ mem_dir = Path.cwd() / ".headroom"
+ mem_dir.mkdir(parents=True, exist_ok=True)
+ db_path = str(mem_dir / "memory.db")
+ mem_user = os.environ.get("USER", os.environ.get("USERNAME", "default"))
+
+ # Register MCP server in Codex config
+ _inject_memory_mcp_config(db_path, mem_user)
+
+ # Inject memory guidance into project AGENTS.md
+ agents_md = Path.cwd() / "AGENTS.md"
+ _inject_memory_agents_md(agents_md)
+
+ # Sync Claude's memories → DB so MCP search finds them
+ try:
+ import asyncio
+
+ from headroom.memory.backends.local import LocalBackend, LocalBackendConfig
+ from headroom.memory.sync import sync_import
+ from headroom.memory.sync_adapters.claude_code import (
+ ClaudeCodeAdapter,
+ get_claude_memory_dir,
+ )
+
+ claude_memory_dir = get_claude_memory_dir()
+
+ async def _import_claude_memories() -> int:
+ config = LocalBackendConfig(db_path=db_path)
+ backend = LocalBackend(config)
+ await backend._ensure_initialized()
+ adapter = ClaudeCodeAdapter(claude_memory_dir)
+ count = await sync_import(backend, adapter, mem_user)
+ await backend.close()
+ return count
+
+ imported = asyncio.run(_import_claude_memories())
+ if imported:
+ click.echo(f" Memory: imported {imported} memories from Claude")
+ except Exception as e:
+ click.echo(f" Warning: Claude memory import failed: {e}")
+
if prepare_only:
_inject_codex_provider_config(port)
return
@@ -1373,7 +1545,15 @@ def codex(
# Inject Headroom provider into Codex config so WebSocket traffic also
# routes through the proxy. Codex ignores OPENAI_BASE_URL for its WS
# transport unless a custom provider declares supports_websockets = true.
+ # NOTE: this must run BEFORE _inject_memory_mcp_config because it rewrites
+ # the config file. Re-inject MCP config after if memory is enabled.
_inject_codex_provider_config(port)
+ if memory:
+ mem_dir = Path.cwd() / ".headroom"
+ _inject_memory_mcp_config(
+ str(mem_dir / "memory.db"),
+ os.environ.get("USER", os.environ.get("USERNAME", "default")),
+ )
_launch_tool(
binary=codex_bin,
diff --git a/headroom/memory/factory.py b/headroom/memory/factory.py
index bbecd971a..6047066bb 100644
--- a/headroom/memory/factory.py
+++ b/headroom/memory/factory.py
@@ -7,6 +7,7 @@ and proper wiring between components.
from __future__ import annotations
+from pathlib import Path
from typing import TYPE_CHECKING
from headroom.memory.config import (
@@ -199,12 +200,21 @@ def _create_vector_index(config: MemoryConfig) -> VectorIndex:
from headroom.memory.adapters.hnsw import HNSWVectorIndex
+ # Derive persistent save path from the main DB path so the HNSW
+ # index survives across process restarts (critical for cross-agent
+ # interop: memories saved by Codex MCP must be searchable by Claude).
+ hnsw_save_path: str | Path | None = None
+ if config.db_path:
+ hnsw_save_path = config.db_path.parent / f"{config.db_path.stem}_hnsw"
+
return HNSWVectorIndex(
dimension=config.vector_dimension,
ef_construction=config.hnsw_ef_construction,
m=config.hnsw_m,
ef_search=config.hnsw_ef_search,
max_entries=config.hnsw_max_entries,
+ save_path=hnsw_save_path,
+ auto_save=True,
)
raise ValueError(f"Unknown vector backend: {config.vector_backend}")
diff --git a/headroom/memory/mcp_server.py b/headroom/memory/mcp_server.py
new file mode 100644
index 000000000..298e60ff2
--- /dev/null
+++ b/headroom/memory/mcp_server.py
@@ -0,0 +1,375 @@
+"""Headroom Memory MCP Server.
+
+A stdio MCP server that exposes headroom's memory backend as tools
+that Codex (or any MCP-compatible client) can call natively.
+
+Tools:
+ memory_search — semantic search across stored memories
+ memory_save — persist a new fact/decision/convention
+
+Design:
+ - Embedder is pre-loaded at startup (no cold-start on first query)
+ - On startup, any memories missing vector embeddings are re-indexed
+ (fixes interop gap when memories were saved via a different path)
+ - Save always generates embeddings inline
+
+Usage:
+ # Standalone (for testing):
+ python -m headroom.memory.mcp_server --db /path/to/.headroom/memory.db
+
+ # Registered in Codex config.toml (done by `headroom wrap codex --memory`):
+ [mcp_servers.headroom_memory]
+ command = "python"
+ args = ["-m", "headroom.memory.mcp_server", "--db", ".headroom/memory.db"]
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+from headroom.memory.backends.local import LocalBackend, LocalBackendConfig
+
+logger = logging.getLogger("headroom.memory.mcp")
+
+# ---------------------------------------------------------------------------
+# Tool definitions
+# ---------------------------------------------------------------------------
+
+_TOOLS = [
+ Tool(
+ name="memory_search",
+ description=(
+ "Search persistent memory for relevant knowledge from prior sessions. "
+ "Use this for questions about architecture, conventions, prior decisions, "
+ "project context, user preferences, org info, codenames, debugging history, "
+ "or anything that might have been discussed before."
+ ),
+ inputSchema={
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "Natural-language search query.",
+ },
+ "top_k": {
+ "type": "integer",
+ "description": "Max results to return (default 10).",
+ "default": 10,
+ },
+ },
+ "required": ["query"],
+ },
+ ),
+ Tool(
+ name="memory_save",
+ description=(
+ "Save information to persistent memory for future sessions. "
+ "Use this for decisions, conventions, architecture context, "
+ "user preferences, project facts, or anything worth remembering.\n\n"
+ "IMPORTANT: Break information into atomic facts — one fact per "
+ "entry in the 'facts' array. Each fact should be a single, "
+ "self-contained statement that answers one question. "
+ "Do NOT combine multiple facts into one string.\n\n"
+ "Good: facts: ['Repo owner is Tejas C.', 'User prefers dark mode']\n"
+ "Bad: facts: ['Repo owner is Tejas C. Prefers dark mode.']"
+ ),
+ inputSchema={
+ "type": "object",
+ "properties": {
+ "facts": {
+ "type": "array",
+ "items": {"type": "string"},
+ "description": (
+ "Array of atomic facts to save. Each entry should be "
+ "one self-contained fact. The system stores and indexes "
+ "each fact separately for precise retrieval."
+ ),
+ },
+ "importance": {
+ "type": "number",
+ "description": "0.0 (low) to 1.0 (critical). Default 0.7.",
+ "default": 0.7,
+ },
+ },
+ "required": [],
+ },
+ ),
+]
+
+
+# ---------------------------------------------------------------------------
+# Startup: pre-load embedder + re-index unembedded memories
+# ---------------------------------------------------------------------------
+
+
+async def _warm_up_backend(backend: LocalBackend, user_id: str) -> None:
+ """Pre-load the embedder and re-index memories that lack embeddings.
+
+ Memories saved via other paths (e.g. Claude Code proxy direct SQL)
+ may exist in the store but have no vector embeddings. This scans
+ for those and re-indexes them so vector search works across agents.
+ """
+ await backend._ensure_initialized()
+ hm = backend._hierarchical_memory
+ if hm is None:
+ return
+
+ # Force-load the embedder now (not lazily on first search)
+ _dummy = await hm._embedder.embed("warmup")
+ logger.info("Memory MCP: embedder pre-loaded")
+
+ # Ensure ALL memories are in the vector index.
+ # Memories saved via other agents (Claude Code proxy, direct SQL) may
+ # exist in the store but not be indexed — re-embed and index them all.
+ all_memories = await backend.get_user_memories(user_id, limit=500)
+ if not all_memories:
+ return
+
+ indexed = 0
+ for mem in all_memories:
+ if mem.embedding is None:
+ mem.embedding = await hm._embedder.embed(mem.content)
+ await hm._store.save(mem)
+ await hm._vector_index.index(mem)
+ indexed += 1
+
+ logger.info(f"Memory MCP: indexed {indexed} memories into vector store")
+
+
+# ---------------------------------------------------------------------------
+# MCP Server
+# ---------------------------------------------------------------------------
+
+
+def create_memory_server(db_path: str, user_id: str = "default") -> Server:
+ """Create an MCP server backed by headroom's local memory."""
+
+ server = Server("headroom-memory")
+ _backend: LocalBackend | None = None
+ _init_task: asyncio.Task | None = None
+
+ async def _init_backend() -> LocalBackend:
+ """Initialize backend with ONNX embedder (fast, no PyTorch)."""
+ nonlocal _backend
+ config = LocalBackendConfig(db_path=db_path, embedder_backend="onnx")
+ _backend = LocalBackend(config)
+ await _warm_up_backend(_backend, user_id)
+ logger.info(f"Memory MCP: ready (db={db_path}, user={user_id})")
+ return _backend
+
+ async def _get_backend() -> LocalBackend:
+ nonlocal _backend, _init_task
+ if _backend is not None:
+ return _backend
+ # Wait for background init if it's running
+ if _init_task is not None:
+ await _init_task
+ return _backend # type: ignore[return-value]
+ # Fallback: init inline (shouldn't normally happen)
+ return await _init_backend()
+
+ @server.list_tools()
+ async def list_tools() -> list[Tool]:
+ # Kick off background init on first list_tools (called at MCP handshake)
+ nonlocal _init_task
+ if _backend is None and _init_task is None:
+ _init_task = asyncio.create_task(_init_backend())
+ return _TOOLS
+
+ @server.call_tool()
+ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+ backend = await _get_backend()
+
+ if name == "memory_search":
+ return await _handle_search(backend, arguments, user_id)
+ elif name == "memory_save":
+ return await _handle_save(backend, arguments, user_id)
+
+ return [TextContent(type="text", text=f"Unknown tool: {name}")]
+
+ return server
+
+
+async def _handle_search(
+ backend: LocalBackend, arguments: dict[str, Any], user_id: str
+) -> list[TextContent]:
+ query = arguments.get("query", "")
+ top_k = arguments.get("top_k", 10)
+
+ if not query:
+ return [TextContent(type="text", text="Error: query is required")]
+
+ try:
+ # Over-fetch to compensate for filtering out superseded memories
+ results = await backend.search_memories(
+ query=query,
+ user_id=user_id,
+ top_k=top_k * 3,
+ include_related=True,
+ )
+
+ if not results:
+ return [TextContent(type="text", text="No memories found.")]
+
+ # Filter out superseded memories — only return current/active ones.
+ # Re-check the store because in-memory HNSW metadata may be stale.
+ active_results = []
+ for r in results:
+ if getattr(r.memory, "superseded_by", None):
+ continue
+ # Double-check against the store for recently superseded memories
+ try:
+ stored = await backend.get_memory(r.memory.id)
+ if stored and getattr(stored, "superseded_by", None):
+ continue
+ except Exception:
+ pass
+ active_results.append(r)
+
+ if not active_results:
+ return [TextContent(type="text", text="No memories found.")]
+
+ # Trim to requested top_k
+ active_results = active_results[:top_k]
+
+ lines = []
+ for i, r in enumerate(active_results, 1):
+ score = f"{r.score:.2f}" if hasattr(r, "score") else "?"
+ lines.append(f"{i}. [relevance={score}] {r.memory.content}")
+ if hasattr(r, "related_entities") and r.related_entities:
+ lines.append(f" Related: {', '.join(r.related_entities[:3])}")
+
+ return [TextContent(type="text", text="\n".join(lines))]
+ except Exception as e:
+ logger.error(f"memory_search failed: {e}")
+ return [TextContent(type="text", text=f"Search error: {e}")]
+
+
+# Similarity threshold for auto-supersession: if a new memory is this
+# similar to an existing one, it replaces (supersedes) the old one.
+_SUPERSEDE_SIMILARITY = 0.70
+
+
+async def _handle_save(
+ backend: LocalBackend, arguments: dict[str, Any], user_id: str
+) -> list[TextContent]:
+ facts = arguments.get("facts", [])
+ importance = arguments.get("importance", 0.7)
+
+ # Backward compat: accept single "content" string too
+ if not facts:
+ content = arguments.get("content", "")
+ if content:
+ facts = [content]
+
+ if not facts:
+ return [TextContent(type="text", text="Error: facts array is required")]
+
+ try:
+ saved = 0
+ superseded = 0
+ results_lines: list[str] = []
+
+ for fact in facts:
+ fact = fact.strip()
+ if not fact:
+ continue
+
+ # Check for semantically similar existing memory to auto-supersede
+ superseded_id: str | None = None
+ try:
+ existing = await backend.search_memories(
+ query=fact,
+ user_id=user_id,
+ top_k=3,
+ )
+ for r in existing:
+ if getattr(r.memory, "superseded_by", None):
+ continue
+ if r.score >= _SUPERSEDE_SIMILARITY:
+ superseded_id = r.memory.id
+ logger.info(
+ f"Memory MCP: auto-superseding [{r.memory.id[:8]}] "
+ f"(similarity={r.score:.2f}): {r.memory.content[:60]}"
+ )
+ break
+ except Exception:
+ pass
+
+ if superseded_id:
+ memory = await backend.update_memory(
+ memory_id=superseded_id,
+ new_content=fact,
+ )
+ results_lines.append(
+ f" updated [{superseded_id[:8]}→{memory.id[:8]}]: {fact[:60]}"
+ )
+ superseded += 1
+ else:
+ memory = await backend.save_memory(
+ content=fact,
+ user_id=user_id,
+ importance=importance,
+ )
+ results_lines.append(f" saved [{memory.id[:8]}]: {fact[:60]}")
+ saved += 1
+
+ summary = f"Saved {saved} new, updated {superseded} existing ({saved + superseded} total)"
+ return [TextContent(type="text", text=summary + "\n" + "\n".join(results_lines))]
+ except Exception as e:
+ logger.error(f"memory_save failed: {e}")
+ return [TextContent(type="text", text=f"Save error: {e}")]
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+async def _run(db_path: str, user_id: str) -> None:
+ server = create_memory_server(db_path, user_id)
+ async with stdio_server() as (read_stream, write_stream):
+ await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description="Headroom Memory MCP Server")
+ parser.add_argument(
+ "--db",
+ default=str(Path.cwd() / ".headroom" / "memory.db"),
+ help="Path to memory SQLite database",
+ )
+ parser.add_argument(
+ "--user",
+ default=os.environ.get("USER", os.environ.get("USERNAME", "default")),
+ help="User ID for memory scoping",
+ )
+ args = parser.parse_args()
+
+ # Skip HuggingFace model freshness checks — use cached models only.
+ # This eliminates 1-2s of HTTP HEAD requests on every startup.
+ os.environ.setdefault("HF_HUB_OFFLINE", "1")
+ os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+
+ # Log to stderr (MCP uses stdout for protocol)
+ logging.basicConfig(
+ level=logging.INFO,
+ stream=sys.stderr,
+ format="%(name)s: %(message)s",
+ )
+
+ asyncio.run(_run(args.db, args.user))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/headroom/memory/sync.py b/headroom/memory/sync.py
new file mode 100644
index 000000000..2e8c041ec
--- /dev/null
+++ b/headroom/memory/sync.py
@@ -0,0 +1,394 @@
+"""Universal memory sync engine for cross-agent interoperability.
+
+Provides bidirectional sync between headroom's memory DB and any
+agent's native memory format via pluggable adapters.
+
+Architecture:
+ DB ← sync_import → Agent files (agent's knowledge enters the shared DB)
+ DB → sync_export → Agent files (shared knowledge flows to the agent)
+ sync() = import + export (bidirectional, fast no-op when unchanged)
+
+Usage:
+ from headroom.memory.sync import sync, SyncResult
+ from headroom.memory.sync_adapters.claude_code import ClaudeCodeAdapter
+
+ adapter = ClaudeCodeAdapter(memory_dir=Path("~/.claude/projects/.../memory"))
+ backend = LocalBackend(config)
+
+ result: SyncResult = await sync(backend, adapter, user_id="tcms")
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger("headroom.memory.sync")
+
+# State file for fast no-op detection
+_DEFAULT_STATE_PATH = Path.home() / ".headroom" / "sync_state.json"
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SyncResult:
+ """Result of a sync operation."""
+
+ imported: int = 0 # agent files → DB
+ exported: int = 0 # DB → agent files
+ skipped_unchanged: int = 0
+ skipped_dedup: int = 0
+ duration_ms: float = 0
+
+
+@dataclass
+class AgentMemory:
+ """A memory entry read from an agent's native format."""
+
+ content: str
+ category: str = ""
+ source_file: str = ""
+ content_hash: str = ""
+ metadata: dict[str, Any] = field(default_factory=dict)
+
+ def __post_init__(self) -> None:
+ if not self.content_hash:
+ self.content_hash = hashlib.sha256(self.content.encode()).hexdigest()[:16]
+
+
+# ---------------------------------------------------------------------------
+# Adapter interface
+# ---------------------------------------------------------------------------
+
+
+class AgentMemoryAdapter(ABC):
+ """Base class for agent memory format adapters.
+
+ Each agent (Claude Code, Codex, Aider, Cursor) has a subclass
+ that knows how to read/write that agent's native memory format.
+ """
+
+ agent_name: str = "unknown"
+
+ @abstractmethod
+ async def read_memories(self) -> list[AgentMemory]:
+ """Read memories from the agent's native format.
+
+ Returns a list of AgentMemory entries found in the agent's files.
+ """
+ ...
+
+ @abstractmethod
+ async def write_memories(self, memories: list[dict[str, Any]]) -> int:
+ """Write memories to the agent's native format.
+
+ Args:
+ memories: List of dicts with keys: content, category, importance,
+ headroom_id, source_agent, content_hash.
+
+ Returns:
+ Count of memories written.
+ """
+ ...
+
+ @abstractmethod
+ def fingerprint(self) -> str:
+ """Fast hash of the agent's memory state.
+
+ Used for no-op detection: if the fingerprint hasn't changed
+ since last sync, we can skip the full read/compare cycle.
+ """
+ ...
+
+
+# ---------------------------------------------------------------------------
+# Sync state persistence
+# ---------------------------------------------------------------------------
+
+
+def _load_sync_state(state_path: Path) -> dict[str, Any]:
+ """Load sync state from disk."""
+ if state_path.exists():
+ try:
+ return json.loads(state_path.read_text())
+ except (json.JSONDecodeError, OSError):
+ pass
+ return {}
+
+
+def _save_sync_state(state_path: Path, state: dict[str, Any]) -> None:
+ """Save sync state to disk."""
+ state_path.parent.mkdir(parents=True, exist_ok=True)
+ state_path.write_text(json.dumps(state, indent=2))
+
+
+def _db_fingerprint(memories: list[Any]) -> str:
+ """Compute a fast fingerprint of DB state."""
+ if not memories:
+ return "empty"
+ # Hash: count + most recent created_at
+ parts = [str(len(memories))]
+ for m in memories[:5]: # Sample first 5 for speed
+ parts.append(getattr(m, "id", "")[:8])
+ return hashlib.sha256("|".join(parts).encode()).hexdigest()[:16]
+
+
+# ---------------------------------------------------------------------------
+# Sync engine
+# ---------------------------------------------------------------------------
+
+
+async def sync(
+ backend: Any,
+ adapter: AgentMemoryAdapter,
+ user_id: str,
+ state_path: Path = _DEFAULT_STATE_PATH,
+ force: bool = False,
+) -> SyncResult:
+ """Bidirectional sync between headroom DB and an agent's memory.
+
+ 1. Fast no-op check (fingerprint comparison)
+ 2. Import: agent files → DB (new entries only, deduped by content hash)
+ 3. Export: DB → agent files (entries not already in agent's files)
+
+ Args:
+ backend: LocalBackend instance (must have save_memory, get_user_memories).
+ adapter: Agent-specific memory adapter.
+ user_id: User ID for memory scoping.
+ state_path: Path to sync state file.
+ force: Skip no-op check and always sync.
+
+ Returns:
+ SyncResult with import/export counts and timing.
+ """
+ start = time.monotonic()
+ result = SyncResult()
+
+ # --- Fast no-op check ---
+ if not force:
+ state = _load_sync_state(state_path)
+ adapter_key = f"{adapter.agent_name}:{user_id}"
+ prev = state.get(adapter_key, {})
+
+ current_agent_fp = adapter.fingerprint()
+ all_memories = await backend.get_user_memories(user_id, limit=500)
+ current_db_fp = _db_fingerprint(all_memories)
+
+ if (
+ prev.get("agent_fingerprint") == current_agent_fp
+ and prev.get("db_fingerprint") == current_db_fp
+ ):
+ result.duration_ms = (time.monotonic() - start) * 1000
+ logger.info(
+ f"Sync [{adapter.agent_name}]: no-op — nothing changed ({result.duration_ms:.1f}ms)"
+ )
+ return result
+ else:
+ all_memories = await backend.get_user_memories(user_id, limit=500)
+
+ # --- Phase 1: Import (agent files → DB) ---
+ result.imported = await sync_import(backend, adapter, user_id, all_memories)
+
+ # --- Phase 2: Export (DB → agent files) ---
+ # Re-fetch if imports happened (new entries)
+ if result.imported > 0:
+ all_memories = await backend.get_user_memories(user_id, limit=500)
+ result.exported = await sync_export(backend, adapter, user_id, all_memories)
+
+ # --- Update sync state ---
+ state = _load_sync_state(state_path)
+ adapter_key = f"{adapter.agent_name}:{user_id}"
+ state[adapter_key] = {
+ "agent_fingerprint": adapter.fingerprint(),
+ "db_fingerprint": _db_fingerprint(all_memories),
+ "last_sync": datetime.now(timezone.utc).isoformat(),
+ "last_imported": result.imported,
+ "last_exported": result.exported,
+ }
+ _save_sync_state(state_path, state)
+
+ result.duration_ms = (time.monotonic() - start) * 1000
+ logger.info(
+ f"Sync [{adapter.agent_name}]: imported={result.imported}, "
+ f"exported={result.exported} ({result.duration_ms:.1f}ms)"
+ )
+ return result
+
+
+async def sync_import(
+ backend: Any,
+ adapter: AgentMemoryAdapter,
+ user_id: str,
+ existing_memories: list[Any] | None = None,
+) -> int:
+ """Import: agent files → DB. Returns count imported."""
+ agent_memories = await adapter.read_memories()
+ if not agent_memories:
+ return 0
+
+ # Build set of existing content hashes for dedup
+ if existing_memories is None:
+ existing_memories = await backend.get_user_memories(user_id, limit=500)
+
+ existing_hashes: set[str] = set()
+ for mem in existing_memories:
+ h = (mem.metadata or {}).get("content_hash", "")
+ if h:
+ existing_hashes.add(h)
+ # Also hash the content directly for safety
+ existing_hashes.add(hashlib.sha256(mem.content.encode()).hexdigest()[:16])
+
+ imported = 0
+ for am in agent_memories:
+ if am.content_hash in existing_hashes:
+ continue
+
+ # Save to DB with lineage metadata
+ await backend.save_memory(
+ content=am.content,
+ user_id=user_id,
+ importance=0.6,
+ metadata={
+ "source_agent": adapter.agent_name,
+ "source_file": am.source_file,
+ "content_hash": am.content_hash,
+ "synced_at": datetime.now(timezone.utc).isoformat(),
+ "sync_direction": "import",
+ **am.metadata,
+ },
+ )
+ existing_hashes.add(am.content_hash)
+ imported += 1
+
+ if imported:
+ logger.info(f"Sync [{adapter.agent_name}]: imported {imported} memories from agent files")
+ return imported
+
+
+async def sync_export(
+ backend: Any,
+ adapter: AgentMemoryAdapter,
+ user_id: str,
+ existing_memories: list[Any] | None = None,
+) -> int:
+ """Export: DB → agent files. Returns count exported."""
+ if existing_memories is None:
+ existing_memories = await backend.get_user_memories(user_id, limit=500)
+
+ if not existing_memories:
+ return 0
+
+ # Read what the agent already has (to avoid re-exporting)
+ agent_memories = await adapter.read_memories()
+ agent_hashes: set[str] = {am.content_hash for am in agent_memories}
+
+ # Find memories to export (not already in agent, not imported FROM this agent)
+ to_export: list[dict[str, Any]] = []
+ for mem in existing_memories:
+ content_hash = hashlib.sha256(mem.content.encode()).hexdigest()[:16]
+
+ # Skip if agent already has it
+ if content_hash in agent_hashes:
+ continue
+
+ # Skip if this memory was originally imported FROM this same agent
+ # (prevents echo: agent → DB → agent)
+ meta = mem.metadata or {}
+ if (
+ meta.get("source_agent") == adapter.agent_name
+ and meta.get("sync_direction") == "import"
+ ):
+ continue
+
+ to_export.append(
+ {
+ "content": mem.content,
+ "category": getattr(mem, "category", "") or "",
+ "importance": getattr(mem, "importance", 0.5),
+ "headroom_id": mem.id,
+ "source_agent": meta.get("source_agent", "unknown"),
+ "content_hash": content_hash,
+ "created_at": mem.created_at.isoformat()
+ if hasattr(mem.created_at, "isoformat")
+ else str(mem.created_at),
+ }
+ )
+
+ if not to_export:
+ return 0
+
+ exported = await adapter.write_memories(to_export)
+ if exported:
+ logger.info(f"Sync [{adapter.agent_name}]: exported {exported} memories to agent files")
+ return exported
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point: python -m headroom.memory.sync --db ... --user ... --agent ...
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+ """CLI entry point for running sync from a subprocess."""
+ import argparse
+
+ parser = argparse.ArgumentParser(description="Headroom memory sync")
+ parser.add_argument("--db", required=True, help="Path to memory DB")
+ parser.add_argument("--user", required=True, help="User ID")
+ parser.add_argument("--agent", required=True, choices=["claude", "codex"], help="Agent to sync")
+ parser.add_argument("--force", action="store_true", help="Skip no-op check")
+ args = parser.parse_args()
+
+ import asyncio
+ import json as _json
+
+ async def _run() -> None:
+ from headroom.memory.backends.local import LocalBackend, LocalBackendConfig
+
+ config = LocalBackendConfig(db_path=args.db)
+ backend = LocalBackend(config)
+ await backend._ensure_initialized()
+
+ if args.agent == "claude":
+ from headroom.memory.sync_adapters.claude_code import (
+ ClaudeCodeAdapter,
+ get_claude_memory_dir,
+ )
+
+ adapter = ClaudeCodeAdapter(get_claude_memory_dir())
+ elif args.agent == "codex":
+ from headroom.memory.sync_adapters.codex_agent import CodexAdapter
+
+ adapter = CodexAdapter()
+ else:
+ print(_json.dumps({"error": f"Unknown agent: {args.agent}"}))
+ return
+
+ result = await sync(backend, adapter, args.user, force=args.force)
+ await backend.close()
+ print(
+ _json.dumps(
+ {
+ "imported": result.imported,
+ "exported": result.exported,
+ "ms": round(result.duration_ms),
+ }
+ )
+ )
+
+ asyncio.run(_run())
+
+
+if __name__ == "__main__":
+ main()
diff --git a/headroom/memory/sync_adapters/__init__.py b/headroom/memory/sync_adapters/__init__.py
new file mode 100644
index 000000000..e42d6b034
--- /dev/null
+++ b/headroom/memory/sync_adapters/__init__.py
@@ -0,0 +1 @@
+"""Agent memory sync adapters for cross-agent interoperability."""
diff --git a/headroom/memory/sync_adapters/claude_code.py b/headroom/memory/sync_adapters/claude_code.py
new file mode 100644
index 000000000..f46d34e1e
--- /dev/null
+++ b/headroom/memory/sync_adapters/claude_code.py
@@ -0,0 +1,233 @@
+"""Claude Code memory sync adapter.
+
+Reads/writes Claude Code's native memory format:
+ ~/.claude/projects/<sanitized-path>/memory/
+ MEMORY.md — index file (first 200 lines always in context)
+ user_role.md — individual memory files with YAML frontmatter
+ project_codename.md
+ ...
+
+Each .md file has:
+ ---
+ name: <title>
+ description: <one-line summary>
+ type: <user|project|reference|feedback>
+ headroom_id: <uuid> (added by sync for cross-reference)
+ source_agent: <agent name> (added by sync for lineage)
+ ---
+ <body content>
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+from typing import Any
+
+from headroom.memory.sync import AgentMemory, AgentMemoryAdapter
+
+
+def _sanitize_for_filename(text: str) -> str:
+ """Convert text to a safe filename slug."""
+ slug = re.sub(r"[^a-z0-9]+", "_", text.lower().strip())
+ slug = slug.strip("_")[:50]
+ return slug or "memory"
+
+
+def _parse_frontmatter(content: str) -> tuple[dict[str, str], str]:
+ """Parse YAML frontmatter from a markdown file.
+
+ Returns (frontmatter_dict, body).
+ """
+ if not content.startswith("---"):
+ return {}, content
+
+ end = content.find("---", 3)
+ if end == -1:
+ return {}, content
+
+ fm_text = content[3:end].strip()
+ body = content[end + 3 :].strip()
+
+ fm: dict[str, str] = {}
+ for line in fm_text.split("\n"):
+ if ":" in line:
+ key, _, value = line.partition(":")
+ fm[key.strip()] = value.strip().strip('"').strip("'")
+
+ return fm, body
+
+
+def _build_frontmatter(fields: dict[str, str]) -> str:
+ """Build YAML frontmatter block."""
+ lines = ["---"]
+ for key, value in fields.items():
+ if value:
+ lines.append(f"{key}: {value}")
+ lines.append("---")
+ return "\n".join(lines)
+
+
+class ClaudeCodeAdapter(AgentMemoryAdapter):
+ """Sync adapter for Claude Code's native memory files."""
+
+ agent_name = "claude"
+
+ def __init__(self, memory_dir: Path | str) -> None:
+ self._memory_dir = Path(memory_dir)
+
+ async def read_memories(self) -> list[AgentMemory]:
+ """Read all .md memory files (except MEMORY.md index)."""
+ if not self._memory_dir.exists():
+ return []
+
+ memories: list[AgentMemory] = []
+ for md_file in sorted(self._memory_dir.glob("*.md")):
+ if md_file.name == "MEMORY.md":
+ continue # Index file, not a memory
+
+ try:
+ content = md_file.read_text(encoding="utf-8")
+ except OSError:
+ continue
+
+ fm, body = _parse_frontmatter(content)
+ if not body.strip():
+ continue
+
+ memories.append(
+ AgentMemory(
+ content=body.strip(),
+ category=fm.get("type", ""),
+ source_file=md_file.name,
+ metadata={
+ "name": fm.get("name", ""),
+ "description": fm.get("description", ""),
+ "headroom_id": fm.get("headroom_id", ""),
+ "source_agent": fm.get("source_agent", "claude"),
+ },
+ )
+ )
+
+ return memories
+
+ async def write_memories(self, memories: list[dict[str, Any]]) -> int:
+ """Write memories as individual .md files with frontmatter.
+
+ Also updates MEMORY.md index.
+ """
+ if not memories:
+ return 0
+
+ self._memory_dir.mkdir(parents=True, exist_ok=True)
+
+ written = 0
+ new_index_entries: list[str] = []
+
+ for mem in memories:
+ content = mem["content"]
+ category = mem.get("category", "project")
+ headroom_id = mem.get("headroom_id", "")
+ source_agent = mem.get("source_agent", "unknown")
+ content_hash = mem.get("content_hash", "")
+
+ # Generate filename from content
+ first_line = content.split("\n")[0][:60].strip()
+ slug = _sanitize_for_filename(first_line)
+ filename = f"headroom_{slug}.md"
+
+ # Skip if file already exists with same content
+ target = self._memory_dir / filename
+ if target.exists():
+ existing_fm, existing_body = _parse_frontmatter(target.read_text(encoding="utf-8"))
+ existing_hash = hashlib.sha256(existing_body.strip().encode()).hexdigest()[:16]
+ if existing_hash == content_hash:
+ continue
+
+ # Build description (first 100 chars)
+ description = content.replace("\n", " ")[:100]
+
+ # Write file
+ fm = _build_frontmatter(
+ {
+ "name": first_line[:60],
+ "description": description,
+ "type": category or "project",
+ "headroom_id": headroom_id,
+ "source_agent": source_agent,
+ }
+ )
+ target.write_text(f"{fm}\n\n{content}\n", encoding="utf-8")
+ written += 1
+
+ # Track for MEMORY.md index
+ new_index_entries.append(f"- [{first_line[:60]}]({filename}) — {description[:80]}")
+
+ # Update MEMORY.md index
+ if new_index_entries:
+ self._update_memory_md_index(new_index_entries)
+
+ return written
+
+ def _update_memory_md_index(self, new_entries: list[str]) -> None:
+ """Append new entries to MEMORY.md under a Headroom section."""
+ memory_md = self._memory_dir / "MEMORY.md"
+
+ section_marker = "## Headroom Shared Memory"
+ new_section = f"\n{section_marker}\n" + "\n".join(new_entries) + "\n"
+
+ if memory_md.exists():
+ content = memory_md.read_text(encoding="utf-8")
+ if section_marker in content:
+ # Append to existing section (before next ## or end)
+ idx = content.index(section_marker)
+ # Find end of section (next ## or end of file)
+ next_section = content.find("\n## ", idx + len(section_marker))
+ if next_section == -1:
+ # Append at end
+ content = content.rstrip() + "\n" + "\n".join(new_entries) + "\n"
+ else:
+ # Insert before next section
+ content = (
+ content[:next_section].rstrip()
+ + "\n"
+ + "\n".join(new_entries)
+ + "\n"
+ + content[next_section:]
+ )
+ else:
+ content = content.rstrip() + "\n" + new_section
+ else:
+ content = "# Memory\n" + new_section
+
+ memory_md.write_text(content, encoding="utf-8")
+
+ def fingerprint(self) -> str:
+ """Hash of all .md filenames + mtimes for fast change detection."""
+ if not self._memory_dir.exists():
+ return "empty"
+
+ parts: list[str] = []
+ for md_file in sorted(self._memory_dir.glob("*.md")):
+ try:
+ stat = md_file.stat()
+ parts.append(f"{md_file.name}:{stat.st_mtime_ns}")
+ except OSError:
+ continue
+
+ if not parts:
+ return "empty"
+ return hashlib.sha256("|".join(parts).encode()).hexdigest()[:16]
+
+
+def get_claude_memory_dir(project_path: Path | None = None) -> Path:
+ """Get the Claude Code memory directory for a project.
+
+ Claude Code stores per-project memory at:
+ ~/.claude/projects/-<sanitized-path>/memory/
+ """
+ project = project_path or Path.cwd()
+ # Replace both Unix and Windows path separators (Claude Code does the same)
+ sanitized = str(project).replace("/", "-").replace("\\", "-")
+ return Path.home() / ".claude" / "projects" / sanitized / "memory"
diff --git a/headroom/memory/sync_adapters/codex_agent.py b/headroom/memory/sync_adapters/codex_agent.py
new file mode 100644
index 000000000..aefaba85e
--- /dev/null
+++ b/headroom/memory/sync_adapters/codex_agent.py
@@ -0,0 +1,106 @@
+"""Codex CLI memory sync adapter.
+
+Syncs memories to/from a headroom-managed section in AGENTS.md.
+Codex reads AGENTS.md automatically before every task.
+
+Note: Codex primarily uses the MCP server for memory (memory_search/save).
+This adapter provides supplementary context injection via AGENTS.md so
+Codex has key memories even without explicit tool calls.
+
+Format in AGENTS.md:
+ <!-- headroom:memory:start -->
+ ## Headroom Shared Memory
+ - fact 1
+ - fact 2
+ <!-- headroom:memory:end -->
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+from typing import Any
+
+from headroom.memory.sync import AgentMemory, AgentMemoryAdapter
+
+_MARKER_START = "<!-- headroom:memory:start -->"
+_MARKER_END = "<!-- headroom:memory:end -->"
+_MARKER_PATTERN = re.compile(
+ re.escape(_MARKER_START) + r"(.*?)" + re.escape(_MARKER_END),
+ re.DOTALL,
+)
+
+
+class CodexAdapter(AgentMemoryAdapter):
+ """Sync adapter for Codex's AGENTS.md."""
+
+ agent_name = "codex"
+
+ def __init__(self, agents_md_path: Path | str | None = None) -> None:
+ self._path = Path(agents_md_path) if agents_md_path else Path.cwd() / "AGENTS.md"
+
+ async def read_memories(self) -> list[AgentMemory]:
+ """Read memories from the headroom section of AGENTS.md."""
+ if not self._path.exists():
+ return []
+
+ content = self._path.read_text(encoding="utf-8")
+ match = _MARKER_PATTERN.search(content)
+ if not match:
+ return []
+
+ section = match.group(1).strip()
+ memories: list[AgentMemory] = []
+
+ for line in section.split("\n"):
+ line = line.strip()
+ if line.startswith("- "):
+ fact = line[2:].strip()
+ if fact:
+ memories.append(
+ AgentMemory(
+ content=fact,
+ source_file=self._path.name,
+ )
+ )
+
+ return memories
+
+ async def write_memories(self, memories: list[dict[str, Any]]) -> int:
+ """Write memories into the headroom section of AGENTS.md."""
+ if not memories:
+ return 0
+
+ # Build section content
+ lines = ["## Headroom Shared Memory", ""]
+ for mem in memories:
+ content = mem["content"].split("\n")[0].strip() # First line only
+ lines.append(f"- {content}")
+ lines.append("")
+
+ section = f"{_MARKER_START}\n" + "\n".join(lines) + f"{_MARKER_END}"
+
+ # Merge into AGENTS.md
+ if self._path.exists():
+ content = self._path.read_text(encoding="utf-8")
+ if _MARKER_START in content:
+ content = _MARKER_PATTERN.sub(section, content)
+ else:
+ content = content.rstrip() + "\n\n" + section + "\n"
+ else:
+ self._path.parent.mkdir(parents=True, exist_ok=True)
+ content = section + "\n"
+
+ self._path.write_text(content, encoding="utf-8")
+ return len(memories)
+
+ def fingerprint(self) -> str:
+ """Hash of AGENTS.md mtime."""
+ if not self._path.exists():
+ return "empty"
+ try:
+ stat = self._path.stat()
+ return hashlib.sha256(f"{self._path.name}:{stat.st_mtime_ns}".encode()).hexdigest()[:16]
+ except OSError:
+ return "error"
diff --git a/headroom/memory/writers/claude_writer.py b/headroom/memory/writers/claude_writer.py
index d106bfbfc..923b296fc 100644
--- a/headroom/memory/writers/claude_writer.py
+++ b/headroom/memory/writers/claude_writer.py
@@ -64,7 +64,8 @@ class ClaudeCodeMemoryWriter(AgentWriter):
project_path = self._project_path
# Claude Code stores per-project memory at:
# ~/.claude/projects/-<sanitized-path>/memory/MEMORY.md
- sanitized = str(project_path).replace("/", "-")
+ # Replace both Unix and Windows path separators
+ sanitized = str(project_path).replace("/", "-").replace("\\", "-")
claude_memory_dir = Path.home() / ".claude" / "projects" / sanitized / "memory"
return claude_memory_dir / "MEMORY.md"
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index f1464f625..9938408b9 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -963,14 +963,29 @@ class OpenAIHandlerMixin:
f"of context into instructions for user {memory_user_id}"
)
- # Inject memory tools
+ # Inject memory tools (Responses API format)
if self.memory_handler.config.inject_tools:
resp_tools = body.get("tools") or []
resp_tools, mem_tools_injected = self.memory_handler.inject_tools(
resp_tools, "openai"
)
if mem_tools_injected:
- body["tools"] = resp_tools
+ # Convert Chat Completions format to Responses API format
+ converted_tools = []
+ for t in resp_tools:
+ if t.get("type") == "function" and "function" in t:
+ fn = t["function"]
+ converted_tools.append(
+ {
+ "type": "function",
+ "name": fn.get("name"),
+ "description": fn.get("description", ""),
+ "parameters": fn.get("parameters", {}),
+ }
+ )
+ else:
+ converted_tools.append(t)
+ body["tools"] = converted_tools
logger.info(
f"[{request_id}] Memory: Injected memory tools (openai/responses)"
)
@@ -1037,13 +1052,67 @@ class OpenAIHandlerMixin:
and self.memory_handler.has_memory_tool_calls(resp_json, "openai")
):
try:
- tool_results = await self.memory_handler.handle_memory_tool_calls(
- resp_json, memory_user_id, "openai"
- )
- logger.info(
- f"[{request_id}] Memory: Handled {len(tool_results)} "
- f"tool call(s) for user {memory_user_id} (responses)"
- )
+ # Extract function_call items from output
+ from headroom.proxy.memory_handler import MEMORY_TOOL_NAMES
+
+ output_items = resp_json.get("output", [])
+ memory_fc_items = [
+ item
+ for item in output_items
+ if isinstance(item, dict)
+ and item.get("type") == "function_call"
+ and item.get("name") in MEMORY_TOOL_NAMES
+ ]
+
+ # Execute memory tool calls
+ tool_outputs: list[dict[str, Any]] = []
+ for fc in memory_fc_items:
+ call_id = fc.get("call_id", fc.get("id", ""))
+ name = fc.get("name", "")
+ args_str = fc.get("arguments", "{}")
+ try:
+ args = json.loads(args_str)
+ except json.JSONDecodeError:
+ args = {}
+
+ await self.memory_handler._ensure_initialized()
+ if self.memory_handler._backend:
+ result = await self.memory_handler._execute_memory_tool(
+ name, args, memory_user_id, "openai"
+ )
+ else:
+ result = json.dumps({"error": "Memory backend not initialized"})
+
+ tool_outputs.append(
+ {
+ "type": "function_call_output",
+ "call_id": call_id,
+ "output": result,
+ }
+ )
+
+ if tool_outputs:
+ # Make continuation request with tool results
+ response_id = resp_json.get("id")
+ continuation_body = {
+ "model": model,
+ "input": tool_outputs,
+ }
+ if response_id:
+ continuation_body["previous_response_id"] = response_id
+ existing_tools = body.get("tools")
+ if existing_tools:
+ continuation_body["tools"] = existing_tools
+
+ cont_response = await self._retry_request(
+ "POST", url, headers, continuation_body
+ )
+ resp_json = cont_response.json()
+ response = cont_response
+ logger.info(
+ f"[{request_id}] Memory: Handled {len(tool_outputs)} "
+ f"tool call(s) with continuation for user {memory_user_id} (responses)"
+ )
except Exception as e:
logger.warning(
f"[{request_id}] Memory tool handling failed (responses): {e}"
@@ -1279,6 +1348,116 @@ class OpenAIHandlerMixin:
# Not JSON — pass through as-is
tokens_saved = 0
+ # --- Memory: inject context, tools, and instructions ---
+ memory_user_id: str | None = None
+ if self.memory_handler and body:
+ memory_user_id = ws_headers.get(
+ "x-headroom-user-id",
+ os.environ.get("USER", os.environ.get("USERNAME", "default")),
+ )
+ try:
+ # Unwrap response.create envelope to access the response body
+ ws_response_body = body.get("response", body)
+
+ # Debug: log what Codex sends so we can see the full tool list
+ existing_tool_names = [
+ t.get("name") or t.get("function", {}).get("name", "?")
+ for t in (ws_response_body.get("tools") or [])
+ ]
+ instr_preview = (ws_response_body.get("instructions") or "")[:200]
+ logger.info(
+ f"[{request_id}] WS Memory: Codex tools={existing_tool_names}, "
+ f"instructions_len={len(ws_response_body.get('instructions') or '')}, "
+ f"instructions_preview={instr_preview!r}"
+ )
+
+ # Inject memory context into instructions
+ if self.memory_handler.config.inject_context:
+ ws_input = ws_response_body.get("input", "")
+ ws_instructions = ws_response_body.get("instructions")
+ ws_msgs: list[dict[str, Any]] = []
+ if ws_instructions:
+ ws_msgs.append({"role": "system", "content": ws_instructions})
+ if isinstance(ws_input, str) and ws_input:
+ ws_msgs.append({"role": "user", "content": ws_input})
+ elif isinstance(ws_input, list):
+ from headroom.proxy.responses_converter import (
+ responses_items_to_messages,
+ )
+
+ converted_msgs, _ = responses_items_to_messages(ws_input)
+ ws_msgs.extend(converted_msgs)
+
+ memory_context = await self.memory_handler.search_and_format_context(
+ memory_user_id, ws_msgs
+ )
+ if memory_context:
+ existing = ws_response_body.get("instructions") or ""
+ if existing:
+ ws_response_body["instructions"] = f"{existing}\n\n{memory_context}"
+ else:
+ ws_response_body["instructions"] = memory_context
+ logger.info(
+ f"[{request_id}] WS Memory: Injected {len(memory_context)} chars "
+ f"of context into instructions"
+ )
+
+ # Inject memory tools (Responses API format)
+ if self.memory_handler.config.inject_tools:
+ ws_tools = ws_response_body.get("tools") or []
+ ws_tools, mem_injected = self.memory_handler.inject_tools(
+ ws_tools, "openai"
+ )
+ if mem_injected:
+ converted_tools = []
+ for t in ws_tools:
+ if t.get("type") == "function" and "function" in t:
+ fn = t["function"]
+ converted_tools.append(
+ {
+ "type": "function",
+ "name": fn.get("name"),
+ "description": fn.get("description", ""),
+ "parameters": fn.get("parameters", {}),
+ }
+ )
+ else:
+ converted_tools.append(t)
+ ws_response_body["tools"] = converted_tools
+
+ # Add memory instruction so the model uses
+ # memory tools as persistent cross-session knowledge.
+ mem_instruction = (
+ "\n\n## Memory\n"
+ "You have persistent memory via memory_search and "
+ "memory_save tools. Memory stores knowledge across "
+ "sessions — user info, project details, org context, "
+ "decisions, architecture, conventions, anything worth "
+ "remembering.\n\n"
+ "- ALWAYS call memory_search BEFORE searching files "
+ "when the user asks a question that could be answered "
+ "from prior knowledge.\n"
+ "- Call memory_save to store important facts, decisions, "
+ "or context that would be useful in future sessions.\n"
+ "- Memory is your first source of truth for anything "
+ "not visible in the current conversation."
+ )
+ existing_instr = ws_response_body.get("instructions") or ""
+ ws_response_body["instructions"] = existing_instr + mem_instruction
+ logger.info(
+ f"[{request_id}] WS Memory: Injected memory tools + instruction"
+ )
+
+ # Write back into envelope if it was wrapped
+ if "response" in body and isinstance(body["response"], dict):
+ body["response"] = ws_response_body
+ else:
+ body = ws_response_body
+
+ first_msg_raw = json.dumps(body)
+ except Exception as e:
+ logger.warning(f"[{request_id}] WS Memory injection failed: {e}")
+
# --- Connect to upstream OpenAI WebSocket ---
logger.info(f"[{request_id}] WS /v1/responses connecting to {upstream_url}")
@@ -1303,7 +1482,7 @@ class OpenAIHandlerMixin:
# Send (potentially compressed) first message
await upstream.send(first_msg_raw)
- # Bidirectional relay
+ # Bidirectional relay with memory tool interception
async def _client_to_upstream() -> None:
try:
while True:
@@ -1318,14 +1497,164 @@ class OpenAIHandlerMixin:
await upstream.close()
async def _upstream_to_client() -> None:
+ """Relay upstream→client with transparent memory tool handling.
+
+ Uses a buffer-then-decide approach:
+ 1. Buffer events until first output item arrives
+ 2. If first output is a memory tool → suppress entire response,
+ execute tools silently, send continuation upstream
+ 3. If first output is non-memory → flush buffer, stream normally
+ 4. Continuation response events are relayed to Codex seamlessly
+
+ This prevents orphaned response.created events from confusing Codex.
+ """
+ from headroom.proxy.memory_handler import MEMORY_TOOL_NAMES
+
+ memory_enabled = bool(self.memory_handler and memory_user_id)
+
+ # Per-response state (reset after each response.completed)
+ event_buffer: list[str] = []
+ decided = False
+ suppress_response = False
+ pending_fcs: list[dict[str, Any]] = []
+ resp_id: str | None = None
+
+ def _reset() -> None:
+ nonlocal decided, suppress_response, resp_id
+ event_buffer.clear()
+ decided = False
+ suppress_response = False
+ pending_fcs.clear()
+ resp_id = None
+
try:
async for msg in upstream:
- if isinstance(msg, str):
- await websocket.send_text(msg)
- elif isinstance(msg, bytes):
+ if isinstance(msg, bytes):
await websocket.send_bytes(msg)
- else:
- await websocket.send_text(str(msg))
+ continue
+ msg_str = msg if isinstance(msg, str) else str(msg)
+
+ if not memory_enabled:
+ await websocket.send_text(msg_str)
+ continue
+
+ # Parse event
+ try:
+ event = json.loads(msg_str)
+ except (json.JSONDecodeError, TypeError):
+ await websocket.send_text(msg_str)
+ continue
+
+ event_type = event.get("type", "")
+
+ # --- Phase 1: Buffer until first output item ---
+ if not decided:
+ event_buffer.append(msg_str)
+
+ if event_type == "response.output_item.added":
+ item = event.get("item", {})
+ if (
+ item.get("type") == "function_call"
+ and item.get("name") in MEMORY_TOOL_NAMES
+ ):
+ # Memory tool first → suppress entire response
+ suppress_response = True
+ decided = True
+ event_buffer.clear()
+ logger.info(
+ f"[{request_id}] WS Memory: Detected "
+ f"{item.get('name')} — suppressing response"
+ )
+ else:
+ # Non-memory first → flush buffer, pass through
+ decided = True
+ for buf in event_buffer:
+ await websocket.send_text(buf)
+ event_buffer.clear()
+
+ elif event_type == "response.completed":
+ # No output items at all — flush
+ decided = True
+ for buf in event_buffer:
+ await websocket.send_text(buf)
+ event_buffer.clear()
+ _reset()
+
+ continue
+
+ # --- Phase 2a: Suppress mode (memory response) ---
+ if suppress_response:
+ if event_type == "response.output_item.done":
+ item = event.get("item", {})
+ if (
+ item.get("type") == "function_call"
+ and item.get("name") in MEMORY_TOOL_NAMES
+ ):
+ pending_fcs.append(item)
+
+ elif event_type == "response.completed":
+ resp = event.get("response", {})
+ resp_id = resp.get("id")
+
+ if pending_fcs:
+ logger.info(
+ f"[{request_id}] WS Memory: Executing "
+ f"{len(pending_fcs)} tool(s) transparently"
+ )
+
+ # Execute memory tool calls
+ tool_outputs: list[dict[str, Any]] = []
+ for fc in pending_fcs:
+ call_id = fc.get("call_id", fc.get("id", ""))
+ fc_name = fc.get("name", "")
+ args_str = fc.get("arguments", "{}")
+ try:
+ fc_args = json.loads(args_str)
+ except json.JSONDecodeError:
+ fc_args = {}
+
+ await self.memory_handler._ensure_initialized()
+ if self.memory_handler._backend:
+ result = await self.memory_handler._execute_memory_tool(
+ fc_name, fc_args, memory_user_id, "openai"
+ )
+ else:
+ result = json.dumps(
+ {"error": "backend not ready"}
+ )
+
+ tool_outputs.append(
+ {
+ "type": "function_call_output",
+ "call_id": call_id,
+ "output": result,
+ }
+ )
+ logger.info(
+ f"[{request_id}] WS Memory: Executed "
+ f"{fc_name} for user {memory_user_id}"
+ )
+
+ # Send continuation upstream
+ cont: dict[str, Any] = {
+ "type": "response.create",
+ "response": {"input": tool_outputs},
+ }
+ if resp_id:
+ cont["response"]["previous_response_id"] = resp_id
+ await upstream.send(json.dumps(cont))
+ logger.info(
+ f"[{request_id}] WS Memory: Sent continuation "
+ f"with {len(tool_outputs)} result(s)"
+ )
+
+ _reset()
+ # All events suppressed in this mode
+ continue
+
+ # --- Phase 2b: Pass-through mode ---
+ await websocket.send_text(msg_str)
+
except Exception as relay_err:
if "WebSocketDisconnect" not in type(relay_err).__name__:
logger.debug(
diff --git a/headroom/proxy/handlers/streaming.py b/headroom/proxy/handlers/streaming.py
index 193bcda9a..3bb3f0b45 100644
--- a/headroom/proxy/handlers/streaming.py
+++ b/headroom/proxy/handlers/streaming.py
@@ -614,15 +614,18 @@ class StreamingMixin:
f"[{request_id}] Memory: Detected tool calls in streaming response"
)
- # Execute memory tool calls silently — response already
- # streamed so we cannot make a continuation request.
+ # Execute memory tool calls — response already streamed
+ # so results are saved but continuation is not possible
+ # in SSE streaming mode. The WS and non-streaming paths
+ # handle continuation properly.
tool_results = await self.memory_handler.handle_memory_tool_calls(
parsed_response, memory_user_id, provider
)
if tool_results:
logger.info(
- f"[{request_id}] Memory: Tool calls executed silently "
- "(streaming mode — no continuation)"
+ f"[{request_id}] Memory: Tool calls executed "
+ f"({len(tool_results)} results saved, SSE streaming — "
+ "continuation handled by client)"
)
# CCR Feedback: Record headroom_retrieve tool calls for TOIN learning.
diff --git a/headroom/proxy/memory_handler.py b/headroom/proxy/memory_handler.py
index de215e7a4..d1bc17034 100644
--- a/headroom/proxy/memory_handler.py
+++ b/headroom/proxy/memory_handler.py
@@ -380,7 +380,14 @@ class MemoryHandler:
entities_str = ", ".join(result.related_entities[:3])
memory_lines.append(f" (Related: {entities_str})")
- context = f"""## Relevant Memories for This User
+ except Exception as e:
+ logger.warning(f"Memory: Search failed for user {user_id}: {e}")
+ return None
+
+ if not memory_lines:
+ return None
+
+ context = f"""## Relevant Memories for This User
The following information was previously saved about this user:
@@ -388,15 +395,11 @@ The following information was previously saved about this user:
Use this context to provide personalized and contextually relevant responses."""
- logger.info(
- f"Memory: Injecting {len(filtered_results)} memories "
- f"({len(context)} chars) for user {user_id}"
- )
- return context
-
- except Exception as e:
- logger.warning(f"Memory: Search failed for user {user_id}: {e}")
- return None
+ logger.info(
+ f"Memory: Injecting {len(memory_lines)} memories "
+ f"({len(context)} chars) for user {user_id}"
+ )
+ return context
def _extract_user_query(self, messages: list[dict[str, Any]]) -> str:
"""Extract the user query from the last user message."""
@@ -445,10 +448,25 @@ Use this context to provide personalized and contextually relevant responses."""
return []
elif provider == "openai":
+ # Chat Completions format: choices[0].message.tool_calls
choices = response.get("choices", [])
if choices:
message = choices[0].get("message", {})
- return list(message.get("tool_calls", []) or [])
+ tc_list = list(message.get("tool_calls", []) or [])
+ if tc_list:
+ return tc_list
+
+ # Responses API format: output[] with type=function_call
+ output = response.get("output", [])
+ if isinstance(output, list):
+ fc_items = [
+ item
+ for item in output
+ if isinstance(item, dict) and item.get("type") == "function_call"
+ ]
+ if fc_items:
+ return fc_items
+
return []
return []
@@ -474,13 +492,15 @@ Use this context to provide personalized and contextually relevant responses."""
for tc in tool_calls:
tool_name = tc.get("name") or tc.get("function", {}).get("name")
- tool_id = tc.get("id", "")
+ tool_id = tc.get("id") or tc.get("call_id", "")
# Parse input data
if provider == "anthropic":
input_data = tc.get("input", {})
else:
- args_str = tc.get("function", {}).get("arguments", "{}")
+ # Chat Completions format: function.arguments
+ # Responses API format: arguments (top-level string)
+ args_str = tc.get("arguments") or tc.get("function", {}).get("arguments") or "{}"
try:
input_data = json.loads(args_str)
except json.JSONDecodeError:
diff --git a/tests/test_memory_sync.py b/tests/test_memory_sync.py
new file mode 100644
index 000000000..b7ca48c35
--- /dev/null
+++ b/tests/test_memory_sync.py
@@ -0,0 +1,643 @@
+"""Comprehensive tests for the universal memory sync engine.
+
+Tests cover:
+- Core sync: import, export, bidirectional
+- Idempotency and deduplication
+- Fast no-op detection
+- Lineage and governance metadata
+- Claude Code adapter: read/write frontmatter files
+- Codex adapter: read/write AGENTS.md sections
+- Cross-agent interop: save in one agent, find in another
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+
+from headroom.memory.sync import (
+ AgentMemory,
+ AgentMemoryAdapter,
+ SyncResult,
+ sync,
+ sync_export,
+ sync_import,
+)
+from headroom.memory.sync_adapters.claude_code import (
+ ClaudeCodeAdapter,
+ _parse_frontmatter,
+)
+from headroom.memory.sync_adapters.codex_agent import CodexAdapter
+
+
+# ---------------------------------------------------------------------------
+# Fake backend for testing (no real DB/embeddings needed)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class FakeMemory:
+ id: str = ""
+ content: str = ""
+ user_id: str = ""
+ category: str = ""
+ importance: float = 0.5
+ created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+ metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class FakeBackend:
+ """In-memory backend for testing sync without real DB."""
+
+ def __init__(self) -> None:
+ self._memories: list[FakeMemory] = []
+ self._next_id = 1
+
+ async def get_user_memories(self, user_id: str, limit: int = 500) -> list[FakeMemory]:
+ return [m for m in self._memories if m.user_id == user_id][:limit]
+
+ async def save_memory(
+ self,
+ content: str,
+ user_id: str,
+ importance: float = 0.5,
+ metadata: dict[str, Any] | None = None,
+ **kwargs: Any,
+ ) -> FakeMemory:
+ mem = FakeMemory(
+ id=f"mem_{self._next_id:04d}",
+ content=content,
+ user_id=user_id,
+ importance=importance,
+ metadata=metadata or {},
+ )
+ self._next_id += 1
+ self._memories.append(mem)
+ return mem
+
+ def add_memory(self, content: str, user_id: str = "tcms", **kwargs: Any) -> FakeMemory:
+ """Sync helper to pre-populate memories."""
+ mem = FakeMemory(
+ id=f"mem_{self._next_id:04d}",
+ content=content,
+ user_id=user_id,
+ metadata=kwargs.get("metadata", {}),
+ importance=kwargs.get("importance", 0.5),
+ )
+ self._next_id += 1
+ self._memories.append(mem)
+ return mem
+
+
+# ---------------------------------------------------------------------------
+# Core sync tests
+# ---------------------------------------------------------------------------
+
+
+class TestSyncImport:
+ """Test importing from agent files into DB."""
+
+ @pytest.fixture
+ def backend(self):
+ return FakeBackend()
+
+ @pytest.fixture
+ def claude_dir(self, tmp_path):
+ d = tmp_path / "memory"
+ d.mkdir()
+ return d
+
+ def _write_claude_memory(self, memory_dir: Path, name: str, content: str, **fm_fields: str) -> None:
+ slug = name.lower().replace(" ", "_")
+ fields = {"name": name, "description": content[:80], "type": "project", **fm_fields}
+ fm_lines = ["---"]
+ for k, v in fields.items():
+ fm_lines.append(f"{k}: {v}")
+ fm_lines.append("---")
+ (memory_dir / f"{slug}.md").write_text("\n".join(fm_lines) + f"\n\n{content}\n")
+
+ @pytest.mark.asyncio
+ async def test_import_claude_files_to_db(self, backend, claude_dir):
+ self._write_claude_memory(claude_dir, "Project codename", "The secret name is TC")
+ self._write_claude_memory(claude_dir, "Dark mode", "User prefers dark mode")
+
+ adapter = ClaudeCodeAdapter(claude_dir)
+ imported = await sync_import(backend, adapter, "tcms")
+
+ assert imported == 2
+ mems = await backend.get_user_memories("tcms")
+ contents = {m.content for m in mems}
+ assert "The secret name is TC" in contents
+ assert "User prefers dark mode" in contents
+
+ @pytest.mark.asyncio
+ async def test_import_skips_existing(self, backend, claude_dir):
+ """Memories already in DB are not re-imported."""
+ backend.add_memory("The secret name is TC", metadata={
+ "content_hash": hashlib.sha256(b"The secret name is TC").hexdigest()[:16]
+ })
+
+ self._write_claude_memory(claude_dir, "Project codename", "The secret name is TC")
+ self._write_claude_memory(claude_dir, "New fact", "Something new")
+
+ adapter = ClaudeCodeAdapter(claude_dir)
+ imported = await sync_import(backend, adapter, "tcms")
+
+ assert imported == 1 # Only "Something new"
+
+ @pytest.mark.asyncio
+ async def test_import_preserves_lineage(self, backend, claude_dir):
+ self._write_claude_memory(claude_dir, "Fact", "Important fact")
+
+ adapter = ClaudeCodeAdapter(claude_dir)
+ await sync_import(backend, adapter, "tcms")
+
+ mems = await backend.get_user_memories("tcms")
+ assert len(mems) == 1
+ assert mems[0].metadata["source_agent"] == "claude"
+ assert mems[0].metadata["source_file"] == "fact.md"
+ assert "content_hash" in mems[0].metadata
+ assert mems[0].metadata["sync_direction"] == "import"
+
+
+class TestSyncExport:
+ """Test exporting from DB to agent files."""
+
+ @pytest.fixture
+ def backend(self):
+ return FakeBackend()
+
+ @pytest.fixture
+ def claude_dir(self, tmp_path):
+ d = tmp_path / "memory"
+ d.mkdir()
+ return d
+
+ @pytest.mark.asyncio
+ async def test_export_new_memory_to_claude_files(self, backend, claude_dir):
+ backend.add_memory("Project uses Python 3.12", metadata={
+ "source_agent": "codex",
+ "sync_direction": "export", # Not from claude import
+ })
+
+ adapter = ClaudeCodeAdapter(claude_dir)
+ exported = await sync_export(backend, adapter, "tcms")
+
+ assert exported == 1
+ # Check file was created
+ md_files = list(claude_dir.glob("headroom_*.md"))
+ assert len(md_files) == 1
+
+ content = md_files[0].read_text()
+ assert "Python 3.12" in content
+ assert "headroom_id: mem_0001" in content
+ assert "source_agent: codex" in content
+
+ @pytest.mark.asyncio
+ async def test_export_skips_claude_originated(self, backend, claude_dir):
+ """Don't re-export memories that were imported FROM claude (anti-echo)."""
+ backend.add_memory("From claude", metadata={
+ "source_agent": "claude",
+ "sync_direction": "import",
+ })
+ backend.add_memory("From codex", metadata={
+ "source_agent": "codex",
+ })
+
+ adapter = ClaudeCodeAdapter(claude_dir)
+ exported = await sync_export(backend, adapter, "tcms")
+
+ assert exported == 1 # Only "From codex"
+
+ @pytest.mark.asyncio
+ async def test_export_updates_memory_md_index(self, backend, claude_dir):
+ # Create an existing MEMORY.md
+ (claude_dir / "MEMORY.md").write_text("# Memory\n\n## User\n- Some existing entry\n")
+
+ backend.add_memory("New fact from codex", metadata={"source_agent": "codex"})
+
+ adapter = ClaudeCodeAdapter(claude_dir)
+ await sync_export(backend, adapter, "tcms")
+
+ memory_md = (claude_dir / "MEMORY.md").read_text()
+ assert "Headroom Shared Memory" in memory_md
+ assert "New fact from codex" in memory_md
+ assert "Some existing entry" in memory_md # Preserved
+
+
+class TestBidirectionalSync:
+ """Test full bidirectional sync."""
+
+ @pytest.fixture
+ def backend(self):
+ return FakeBackend()
+
+ @pytest.fixture
+ def claude_dir(self, tmp_path):
+ d = tmp_path / "memory"
+ d.mkdir()
+ return d
+
+ @pytest.fixture
+ def state_path(self, tmp_path):
+ return tmp_path / "sync_state.json"
+
+ def _write_claude_memory(self, memory_dir: Path, name: str, content: str) -> None:
+ slug = name.lower().replace(" ", "_")
+ fm = f"---\nname: {name}\ndescription: {content[:80]}\ntype: project\n---"
+ (memory_dir / f"{slug}.md").write_text(f"{fm}\n\n{content}\n")
+
+ @pytest.mark.asyncio
+ async def test_bidirectional_sync(self, backend, claude_dir, state_path):
+ # Claude has a memory file
+ self._write_claude_memory(claude_dir, "Convention", "Always use ruff for linting")
+
+ # DB has a memory from Codex
+ backend.add_memory("Secret name is TC", metadata={"source_agent": "codex"})
+
+ adapter = ClaudeCodeAdapter(claude_dir)
+ result = await sync(backend, adapter, "tcms", state_path=state_path, force=True)
+
+ assert result.imported == 1 # Claude file → DB
+ assert result.exported == 1 # Codex memory → Claude file
+
+ # Verify DB has both
+ mems = await backend.get_user_memories("tcms")
+ contents = {m.content for m in mems}
+ assert "Always use ruff for linting" in contents
+ assert "Secret name is TC" in contents
+
+ # Verify Claude dir has the exported file
+ all_files = list(claude_dir.glob("headroom_*.md"))
+ assert len(all_files) >= 1
+ exported_content = " ".join(f.read_text() for f in all_files)
+ assert "TC" in exported_content
+
+ @pytest.mark.asyncio
+ async def test_sync_idempotent(self, backend, claude_dir, state_path):
+ """Running sync twice produces no duplicates."""
+ self._write_claude_memory(claude_dir, "Fact", "Python 3.12 is required")
+ backend.add_memory("Port 8787 is default", metadata={"source_agent": "codex"})
+
+ adapter = ClaudeCodeAdapter(claude_dir)
+
+ r1 = await sync(backend, adapter, "tcms", state_path=state_path, force=True)
+ assert r1.imported == 1
+ assert r1.exported == 1
+
+ r2 = await sync(backend, adapter, "tcms", state_path=state_path, force=True)
+ assert r2.imported == 0 # Already imported
+ assert r2.exported == 0 # Already exported
+
+ # No duplicates in DB
+ mems = await backend.get_user_memories("tcms")
+ assert len(mems) == 2
+
+ @pytest.mark.asyncio
+ async def test_fast_noop_when_unchanged(self, backend, claude_dir, state_path):
+ """Second sync with no changes completes in < 10ms."""
+ self._write_claude_memory(claude_dir, "Fact", "Some fact")
+
+ adapter = ClaudeCodeAdapter(claude_dir)
+
+ # First sync (populates state)
+ await sync(backend, adapter, "tcms", state_path=state_path, force=True)
+
+ # Second sync (should be fast no-op)
+ start = time.monotonic()
+ r = await sync(backend, adapter, "tcms", state_path=state_path)
+ elapsed = (time.monotonic() - start) * 1000
+
+ assert r.imported == 0
+ assert r.exported == 0
+ assert elapsed < 50 # Generous threshold for CI
+
+
+class TestLineageAndGovernance:
+ """Test metadata tracking for audit and lineage."""
+
+ @pytest.fixture
+ def backend(self):
+ return FakeBackend()
+
+ @pytest.fixture
+ def claude_dir(self, tmp_path):
+ d = tmp_path / "memory"
+ d.mkdir()
+ return d
+
+ @pytest.mark.asyncio
+ async def test_lineage_tracks_source_agent(self, backend, claude_dir):
+ fm = "---\nname: test\ndescription: test\ntype: project\n---"
+ (claude_dir / "test.md").write_text(f"{fm}\n\nClaude discovered this\n")
+
+ adapter = ClaudeCodeAdapter(claude_dir)
+ await sync_import(backend, adapter, "tcms")
+
+ mems = await backend.get_user_memories("tcms")
+ assert mems[0].metadata["source_agent"] == "claude"
+
+ @pytest.mark.asyncio
+ async def test_exported_files_have_headroom_id(self, backend, claude_dir):
+ backend.add_memory("From codex", metadata={"source_agent": "codex"})
+
+ adapter = ClaudeCodeAdapter(claude_dir)
+ await sync_export(backend, adapter, "tcms")
+
+ md_files = list(claude_dir.glob("headroom_*.md"))
+ assert len(md_files) == 1
+ content = md_files[0].read_text()
+ assert "headroom_id:" in content
+
+ @pytest.mark.asyncio
+ async def test_sync_state_records_timestamps(self, backend, claude_dir, tmp_path):
+ state_path = tmp_path / "state.json"
+ fm = "---\nname: t\ndescription: t\ntype: project\n---"
+ (claude_dir / "t.md").write_text(f"{fm}\n\nFact\n")
+
+ adapter = ClaudeCodeAdapter(claude_dir)
+ await sync(backend, adapter, "tcms", state_path=state_path, force=True)
+
+ state = json.loads(state_path.read_text())
+ key = "claude:tcms"
+ assert key in state
+ assert "last_sync" in state[key]
+ assert "agent_fingerprint" in state[key]
+ assert "db_fingerprint" in state[key]
+
+
+# ---------------------------------------------------------------------------
+# Claude Code adapter tests
+# ---------------------------------------------------------------------------
+
+
+class TestClaudeCodeAdapter:
+ """Test Claude Code adapter read/write."""
+
+ @pytest.fixture
+ def memory_dir(self, tmp_path):
+ d = tmp_path / "memory"
+ d.mkdir()
+ return d
+
+ def test_parse_frontmatter(self):
+ content = "---\nname: Test\ntype: project\n---\n\nBody content here."
+ fm, body = _parse_frontmatter(content)
+ assert fm["name"] == "Test"
+ assert fm["type"] == "project"
+ assert body == "Body content here."
+
+ def test_parse_frontmatter_no_frontmatter(self):
+ content = "Just plain content."
+ fm, body = _parse_frontmatter(content)
+ assert fm == {}
+ assert body == "Just plain content."
+
+ @pytest.mark.asyncio
+ async def test_read_memories_skips_memory_md(self, memory_dir):
+ (memory_dir / "MEMORY.md").write_text("# Index\n- entry")
+ (memory_dir / "fact.md").write_text(
+ "---\nname: Fact\ntype: project\n---\n\nImportant fact."
+ )
+
+ adapter = ClaudeCodeAdapter(memory_dir)
+ mems = await adapter.read_memories()
+
+ assert len(mems) == 1
+ assert mems[0].content == "Important fact."
+ assert mems[0].source_file == "fact.md"
+
+ @pytest.mark.asyncio
+ async def test_write_creates_valid_md(self, memory_dir):
+ adapter = ClaudeCodeAdapter(memory_dir)
+ written = await adapter.write_memories([
+ {
+ "content": "Project uses FastAPI",
+ "category": "architecture",
+ "headroom_id": "mem_001",
+ "source_agent": "codex",
+ "content_hash": "abc123",
+ }
+ ])
+
+ assert written == 1
+ files = list(memory_dir.glob("headroom_*.md"))
+ assert len(files) == 1
+
+ content = files[0].read_text()
+ fm, body = _parse_frontmatter(content)
+ assert fm["type"] == "architecture"
+ assert fm["headroom_id"] == "mem_001"
+ assert fm["source_agent"] == "codex"
+ assert "FastAPI" in body
+
+ def test_fingerprint_changes_on_modification(self, memory_dir):
+ (memory_dir / "test.md").write_text("content 1")
+
+ adapter = ClaudeCodeAdapter(memory_dir)
+ fp1 = adapter.fingerprint()
+
+ (memory_dir / "test.md").write_text("content 2")
+ fp2 = adapter.fingerprint()
+
+ assert fp1 != fp2
+
+ def test_fingerprint_stable_when_unchanged(self, memory_dir):
+ (memory_dir / "test.md").write_text("stable content")
+
+ adapter = ClaudeCodeAdapter(memory_dir)
+ assert adapter.fingerprint() == adapter.fingerprint()
+
+ def test_fingerprint_empty_dir(self, tmp_path):
+ empty = tmp_path / "empty"
+ empty.mkdir()
+ adapter = ClaudeCodeAdapter(empty)
+ assert adapter.fingerprint() == "empty"
+
+
+# ---------------------------------------------------------------------------
+# Codex adapter tests
+# ---------------------------------------------------------------------------
+
+
+class TestCodexAdapter:
+ """Test Codex AGENTS.md adapter."""
+
+ @pytest.fixture
+ def agents_md(self, tmp_path):
+ return tmp_path / "AGENTS.md"
+
+ @pytest.mark.asyncio
+ async def test_read_from_agents_md(self, agents_md):
+ agents_md.write_text(
+ "# Instructions\n\n"
+ "<!-- headroom:memory:start -->\n"
+ "## Headroom Shared Memory\n\n"
+ "- Secret name is TC\n"
+ "- Uses Python 3.12\n"
+ "<!-- headroom:memory:end -->\n"
+ )
+
+ adapter = CodexAdapter(agents_md)
+ mems = await adapter.read_memories()
+
+ assert len(mems) == 2
+ assert mems[0].content == "Secret name is TC"
+ assert mems[1].content == "Uses Python 3.12"
+
+ @pytest.mark.asyncio
+ async def test_write_to_agents_md(self, agents_md):
+ agents_md.write_text("# Existing instructions\n")
+
+ adapter = CodexAdapter(agents_md)
+ written = await adapter.write_memories([
+ {"content": "Port 8787 is default"},
+ {"content": "Uses ruff for linting"},
+ ])
+
+ assert written == 2
+ content = agents_md.read_text()
+ assert "headroom:memory:start" in content
+ assert "Port 8787 is default" in content
+ assert "Uses ruff for linting" in content
+ assert "Existing instructions" in content # Preserved
+
+ @pytest.mark.asyncio
+ async def test_write_replaces_existing_section(self, agents_md):
+ agents_md.write_text(
+ "# Instructions\n\n"
+ "<!-- headroom:memory:start -->\n"
+ "## Old\n- old fact\n"
+ "<!-- headroom:memory:end -->\n"
+ )
+
+ adapter = CodexAdapter(agents_md)
+ await adapter.write_memories([{"content": "new fact"}])
+
+ content = agents_md.read_text()
+ assert "new fact" in content
+ assert "old fact" not in content
+
+ @pytest.mark.asyncio
+ async def test_read_empty_agents_md(self, agents_md):
+ agents_md.write_text("# No memory section\n")
+ adapter = CodexAdapter(agents_md)
+ mems = await adapter.read_memories()
+ assert mems == []
+
+ @pytest.mark.asyncio
+ async def test_read_nonexistent_file(self, tmp_path):
+ adapter = CodexAdapter(tmp_path / "nonexistent.md")
+ mems = await adapter.read_memories()
+ assert mems == []
+
+
+# ---------------------------------------------------------------------------
+# Cross-agent integration tests
+# ---------------------------------------------------------------------------
+
+
+class TestCrossAgentInterop:
+ """Test that memories flow between agents via sync."""
+
+ @pytest.fixture
+ def backend(self):
+ return FakeBackend()
+
+ @pytest.fixture
+ def claude_dir(self, tmp_path):
+ d = tmp_path / "claude_memory"
+ d.mkdir()
+ return d
+
+ @pytest.fixture
+ def agents_md(self, tmp_path):
+ return tmp_path / "AGENTS.md"
+
+ @pytest.fixture
+ def state_path(self, tmp_path):
+ return tmp_path / "state.json"
+
+ @pytest.mark.asyncio
+ async def test_codex_saves_claude_finds(
+ self, backend, claude_dir, state_path
+ ):
+ """Memory saved via Codex MCP appears in Claude's files after sync."""
+ # Simulate Codex saving via MCP (directly to backend)
+ backend.add_memory(
+ "Secret name is TC",
+ metadata={"source_agent": "codex", "content_hash": "x"},
+ )
+
+ # Sync to Claude
+ adapter = ClaudeCodeAdapter(claude_dir)
+ result = await sync(backend, adapter, "tcms", state_path=state_path, force=True)
+
+ assert result.exported == 1
+
+ # Claude's memory dir should have the file
+ files = list(claude_dir.glob("headroom_*.md"))
+ assert len(files) == 1
+ assert "TC" in files[0].read_text()
+
+ @pytest.mark.asyncio
+ async def test_claude_saves_codex_finds(
+ self, backend, claude_dir, agents_md, state_path
+ ):
+ """Memory saved in Claude's files appears in Codex AGENTS.md after sync."""
+ # Claude has a memory
+ fm = "---\nname: Linting\ndescription: use ruff\ntype: project\n---"
+ (claude_dir / "linting.md").write_text(f"{fm}\n\nAlways use ruff for linting\n")
+
+ # Sync Claude → DB
+ claude_adapter = ClaudeCodeAdapter(claude_dir)
+ await sync(backend, claude_adapter, "tcms", state_path=state_path, force=True)
+
+ # Sync DB → Codex AGENTS.md
+ codex_adapter = CodexAdapter(agents_md)
+ result = await sync(backend, codex_adapter, "tcms", state_path=state_path, force=True)
+
+ assert result.exported >= 1
+ assert "ruff" in agents_md.read_text()
+
+ @pytest.mark.asyncio
+ async def test_full_round_trip(
+ self, backend, claude_dir, agents_md, state_path
+ ):
+ """Full round trip: Claude → DB → Codex, Codex → DB → Claude."""
+ # Claude has a memory
+ fm = "---\nname: Framework\ntype: project\n---"
+ (claude_dir / "framework.md").write_text(f"{fm}\n\nUses FastAPI\n")
+
+ # Codex has a memory (in DB via MCP)
+ backend.add_memory("Port is 8787", metadata={"source_agent": "codex"})
+
+ # Sync both adapters
+ claude_adapter = ClaudeCodeAdapter(claude_dir)
+ codex_adapter = CodexAdapter(agents_md)
+
+ await sync(backend, claude_adapter, "tcms", state_path=state_path, force=True)
+ await sync(backend, codex_adapter, "tcms", state_path=state_path, force=True)
+
+ # DB has both memories
+ mems = await backend.get_user_memories("tcms")
+ contents = {m.content for m in mems}
+ assert "Uses FastAPI" in contents
+ assert "Port is 8787" in contents
+
+ # Claude files have Codex's memory
+ all_claude = " ".join(f.read_text() for f in claude_dir.glob("headroom_*.md"))
+ assert "8787" in all_claude
+
+ # AGENTS.md has both (from DB)
+ agents_content = agents_md.read_text()
+ assert "FastAPI" in agents_content or "8787" in agents_content
diff --git a/tests/test_ws_memory_relay.py b/tests/test_ws_memory_relay.py
new file mode 100644
index 000000000..87f4298e3
--- /dev/null
+++ b/tests/test_ws_memory_relay.py
@@ -0,0 +1,524 @@
+"""Tests for WebSocket memory tool interception in the Codex Responses API relay.
+
+Verifies that:
+1. Memory tool events are suppressed from reaching Codex
+2. response.created is buffered and only flushed for non-memory responses
+3. Tool execution happens and continuation is sent upstream
+4. Non-memory responses pass through with normal streaming latency
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+import pytest
+
+from headroom.proxy.memory_handler import MEMORY_TOOL_NAMES
+
+
+# ---------------------------------------------------------------------------
+# Minimal WS relay state machine (mirrors the logic in openai.py)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class WSMemoryRelayState:
+ """State machine for WS event processing with memory tool interception.
+
+ This mirrors the logic in ``_upstream_to_client`` but is decoupled from
+ actual WebSocket I/O so it can be unit-tested.
+ """
+
+ memory_tool_names: set[str] = field(default_factory=lambda: set(MEMORY_TOOL_NAMES))
+
+ # Per-response state (reset after each response.completed)
+ event_buffer: list[str] = field(default_factory=list)
+ decided: bool = False
+ suppress_response: bool = False
+ pending_function_calls: list[dict[str, Any]] = field(default_factory=list)
+ last_response_id: str | None = None
+
+ def process_event(self, msg_str: str) -> dict[str, Any]:
+ """Process a single upstream WS event.
+
+ Returns a dict with possible keys:
+ relay: list[str] — events to send to Codex
+ execute_tools: list — function_call items to execute
+ send_continuation: dict — continuation payload to send upstream
+ """
+ result: dict[str, Any] = {"relay": [], "execute_tools": [], "send_continuation": None}
+
+ try:
+ event = json.loads(msg_str)
+ except (json.JSONDecodeError, TypeError):
+ # Not JSON — always relay
+ result["relay"].append(msg_str)
+ return result
+
+ event_type = event.get("type", "")
+ output_index = event.get("output_index")
+
+ # ---- Phase 1: Buffering (before first output item) ----
+ if not self.decided:
+ self.event_buffer.append(msg_str)
+
+ if event_type == "response.output_item.added":
+ item = event.get("item", {})
+ if (
+ item.get("type") == "function_call"
+ and item.get("name") in self.memory_tool_names
+ ):
+ # Memory tool is first output → suppress entire response
+ self.suppress_response = True
+ self.decided = True
+ self.event_buffer.clear()
+ else:
+ # Non-memory item → flush buffer and pass through
+ self.decided = True
+ result["relay"].extend(self.event_buffer)
+ self.event_buffer.clear()
+
+ elif event_type == "response.completed":
+ # Response completed with no output items — flush all
+ self.decided = True
+ result["relay"].extend(self.event_buffer)
+ self.event_buffer.clear()
+
+ return result
+
+ # ---- Phase 2a: Suppress mode (memory tool response) ----
+ if self.suppress_response:
+ # Capture completed function_call items
+ if event_type == "response.output_item.done":
+ item = event.get("item", {})
+ if (
+ item.get("type") == "function_call"
+ and item.get("name") in self.memory_tool_names
+ ):
+ self.pending_function_calls.append(item)
+
+ if event_type == "response.completed":
+ resp = event.get("response", {})
+ self.last_response_id = resp.get("id")
+
+ if self.pending_function_calls:
+ result["execute_tools"] = list(self.pending_function_calls)
+ # Build continuation payload
+ # (actual tool execution + output building done by caller)
+ result["send_continuation"] = {
+ "response_id": self.last_response_id,
+ "function_calls": list(self.pending_function_calls),
+ }
+
+ # Reset for next response (continuation)
+ self._reset_response_state()
+
+ return result # Nothing relayed in suppress mode
+
+ # ---- Phase 2b: Pass-through mode (normal response) ----
+ result["relay"].append(msg_str)
+ return result
+
+ def _reset_response_state(self) -> None:
+ """Reset per-response state for the next response."""
+ self.event_buffer.clear()
+ self.decided = False
+ self.suppress_response = False
+ self.pending_function_calls.clear()
+ self.last_response_id = None
+
+
+# ---------------------------------------------------------------------------
+# Test helpers
+# ---------------------------------------------------------------------------
+
+def _make_event(event_type: str, **kwargs: Any) -> str:
+ data: dict[str, Any] = {"type": event_type}
+ data.update(kwargs)
+ return json.dumps(data)
+
+
+def _response_created(response_id: str = "resp_A") -> str:
+ return _make_event("response.created", response={"id": response_id})
+
+
+def _output_item_added_text(index: int = 0) -> str:
+ return _make_event(
+ "response.output_item.added",
+ output_index=index,
+ item={"type": "message", "role": "assistant"},
+ )
+
+
+def _output_item_added_function_call(
+ name: str, index: int = 0, call_id: str = "call_1"
+) -> str:
+ return _make_event(
+ "response.output_item.added",
+ output_index=index,
+ item={"type": "function_call", "name": name, "call_id": call_id},
+ )
+
+
+def _function_call_args_delta(index: int = 0, delta: str = '{"qu') -> str:
+ return _make_event(
+ "response.function_call_arguments.delta",
+ output_index=index,
+ delta=delta,
+ )
+
+
+def _function_call_args_done(
+ index: int = 0, arguments: str = '{"query": "codename"}'
+) -> str:
+ return _make_event(
+ "response.function_call_arguments.done",
+ output_index=index,
+ arguments=arguments,
+ )
+
+
+def _output_item_done_function_call(
+ name: str,
+ index: int = 0,
+ call_id: str = "call_1",
+ arguments: str = '{"query": "codename"}',
+) -> str:
+ return _make_event(
+ "response.output_item.done",
+ output_index=index,
+ item={
+ "type": "function_call",
+ "name": name,
+ "call_id": call_id,
+ "arguments": arguments,
+ },
+ )
+
+
+def _output_text_delta(index: int = 0, text: str = "Hello") -> str:
+ return _make_event(
+ "response.output_text.delta",
+ output_index=index,
+ delta=text,
+ )
+
+
+def _output_item_done_text(index: int = 0) -> str:
+ return _make_event(
+ "response.output_item.done",
+ output_index=index,
+ item={"type": "message", "role": "assistant"},
+ )
+
+
+def _response_completed(response_id: str = "resp_A") -> str:
+ return _make_event(
+ "response.completed",
+ response={"id": response_id, "status": "completed"},
+ )
+
+
+def _output_item_added_shell(index: int = 0) -> str:
+ """Simulate a Codex built-in tool (shell) that should pass through."""
+ return _make_event(
+ "response.output_item.added",
+ output_index=index,
+ item={"type": "function_call", "name": "shell", "call_id": "call_shell"},
+ )
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+class TestWSMemoryRelayNonMemory:
+ """Responses with no memory tools pass through normally."""
+
+ def test_text_response_relayed_immediately(self):
+ """Text-only response: all events relayed, no buffering after first item."""
+ relay = WSMemoryRelayState()
+
+ events = [
+ _response_created(),
+ _output_item_added_text(),
+ _output_text_delta(text="The answer is 42"),
+ _output_item_done_text(),
+ _response_completed(),
+ ]
+
+ all_relayed: list[str] = []
+ for ev in events:
+ result = relay.process_event(ev)
+ all_relayed.extend(result["relay"])
+ assert result["execute_tools"] == []
+ assert result["send_continuation"] is None
+
+ # All 5 events should be relayed
+ assert len(all_relayed) == 5
+
+ # First event (response.created) should be buffered then flushed
+ # with the second event (output_item_added_text)
+ types = [json.loads(e)["type"] for e in all_relayed]
+ assert types == [
+ "response.created",
+ "response.output_item.added",
+ "response.output_text.delta",
+ "response.output_item.done",
+ "response.completed",
+ ]
+
+ def test_shell_tool_relayed(self):
+ """Codex built-in tools (shell) pass through without interception."""
+ relay = WSMemoryRelayState()
+
+ events = [
+ _response_created(),
+ _output_item_added_shell(),
+ _response_completed(),
+ ]
+
+ all_relayed: list[str] = []
+ for ev in events:
+ result = relay.process_event(ev)
+ all_relayed.extend(result["relay"])
+ assert result["execute_tools"] == []
+ assert result["send_continuation"] is None
+
+ assert len(all_relayed) == 3
+
+ def test_empty_response_relayed(self):
+ """Response with no output items still relays created + completed."""
+ relay = WSMemoryRelayState()
+
+ events = [
+ _response_created(),
+ _response_completed(),
+ ]
+
+ all_relayed: list[str] = []
+ for ev in events:
+ result = relay.process_event(ev)
+ all_relayed.extend(result["relay"])
+
+ assert len(all_relayed) == 2
+
+
+class TestWSMemoryRelayMemoryTool:
+ """Responses with memory tools are intercepted transparently."""
+
+ def test_memory_search_fully_suppressed(self):
+ """memory_search call: ALL events suppressed from Codex."""
+ relay = WSMemoryRelayState()
+
+ events = [
+ _response_created("resp_A"),
+ _output_item_added_function_call("memory_search", index=0),
+ _function_call_args_delta(index=0),
+ _function_call_args_done(index=0),
+ _output_item_done_function_call("memory_search", index=0),
+ _response_completed("resp_A"),
+ ]
+
+ all_relayed: list[str] = []
+ tool_executions: list[Any] = []
+ continuations: list[Any] = []
+
+ for ev in events:
+ result = relay.process_event(ev)
+ all_relayed.extend(result["relay"])
+ tool_executions.extend(result["execute_tools"])
+ if result["send_continuation"]:
+ continuations.append(result["send_continuation"])
+
+ # ZERO events relayed to Codex
+ assert len(all_relayed) == 0, (
+ f"Expected 0 relayed events, got {len(all_relayed)}: "
+ f"{[json.loads(e)['type'] for e in all_relayed]}"
+ )
+
+ # Tool execution triggered
+ assert len(tool_executions) == 1
+ assert tool_executions[0]["name"] == "memory_search"
+
+ # Continuation requested
+ assert len(continuations) == 1
+ assert continuations[0]["response_id"] == "resp_A"
+
+ def test_memory_save_also_suppressed(self):
+ """memory_save call is also intercepted."""
+ relay = WSMemoryRelayState()
+
+ events = [
+ _response_created("resp_B"),
+ _output_item_added_function_call("memory_save", index=0, call_id="call_save"),
+ _function_call_args_done(index=0, arguments='{"content": "user likes dark mode"}'),
+ _output_item_done_function_call(
+ "memory_save", index=0, call_id="call_save",
+ arguments='{"content": "user likes dark mode"}',
+ ),
+ _response_completed("resp_B"),
+ ]
+
+ all_relayed: list[str] = []
+ tool_executions: list[Any] = []
+
+ for ev in events:
+ result = relay.process_event(ev)
+ all_relayed.extend(result["relay"])
+ tool_executions.extend(result["execute_tools"])
+
+ assert len(all_relayed) == 0
+ assert len(tool_executions) == 1
+ assert tool_executions[0]["name"] == "memory_save"
+
+ def test_continuation_response_relayed_normally(self):
+ """After memory tool handling, the continuation response passes through."""
+ relay = WSMemoryRelayState()
+
+ # --- First response: memory_search (suppressed) ---
+ first_response_events = [
+ _response_created("resp_A"),
+ _output_item_added_function_call("memory_search", index=0),
+ _function_call_args_done(index=0),
+ _output_item_done_function_call("memory_search", index=0),
+ _response_completed("resp_A"),
+ ]
+
+ for ev in first_response_events:
+ relay.process_event(ev)
+
+ # --- Second response: continuation text (relayed) ---
+ continuation_events = [
+ _response_created("resp_B"),
+ _output_item_added_text(index=0),
+ _output_text_delta(index=0, text="The codename is Pegasus-2"),
+ _output_item_done_text(index=0),
+ _response_completed("resp_B"),
+ ]
+
+ all_relayed: list[str] = []
+ for ev in continuation_events:
+ result = relay.process_event(ev)
+ all_relayed.extend(result["relay"])
+ assert result["execute_tools"] == []
+ assert result["send_continuation"] is None
+
+ # All continuation events relayed
+ assert len(all_relayed) == 5
+ types = [json.loads(e)["type"] for e in all_relayed]
+ assert types[0] == "response.created"
+ assert types[-1] == "response.completed"
+
+ # Verify the text content
+ text_events = [
+ json.loads(e) for e in all_relayed
+ if json.loads(e)["type"] == "response.output_text.delta"
+ ]
+ assert len(text_events) == 1
+ assert text_events[0]["delta"] == "The codename is Pegasus-2"
+
+ def test_non_json_message_always_relayed(self):
+ """Binary or non-JSON messages pass through regardless."""
+ relay = WSMemoryRelayState()
+
+ result = relay.process_event("not valid json {{{")
+ assert len(result["relay"]) == 1
+ assert result["relay"][0] == "not valid json {{{"
+
+ def test_multiple_memory_tools_in_one_response(self):
+ """Multiple memory tools in one response — all suppressed."""
+ relay = WSMemoryRelayState()
+
+ events = [
+ _response_created("resp_multi"),
+ _output_item_added_function_call("memory_search", index=0, call_id="call_1"),
+ _output_item_done_function_call("memory_search", index=0, call_id="call_1"),
+ # The model decides to save something too
+ _output_item_added_function_call("memory_save", index=1, call_id="call_2"),
+ _output_item_done_function_call(
+ "memory_save", index=1, call_id="call_2",
+ arguments='{"content": "test"}',
+ ),
+ _response_completed("resp_multi"),
+ ]
+
+ all_relayed: list[str] = []
+ tool_executions: list[Any] = []
+ continuations: list[Any] = []
+
+ for ev in events:
+ result = relay.process_event(ev)
+ all_relayed.extend(result["relay"])
+ tool_executions.extend(result["execute_tools"])
+ if result["send_continuation"]:
+ continuations.append(result["send_continuation"])
+
+ assert len(all_relayed) == 0
+ assert len(tool_executions) == 2
+ assert {t["name"] for t in tool_executions} == {"memory_search", "memory_save"}
+ assert len(continuations) == 1
+
+
+class TestWSMemoryRelayStateReset:
+ """State resets properly between responses."""
+
+ def test_state_resets_after_memory_response(self):
+ """After a memory response, the relay is ready for a fresh response."""
+ relay = WSMemoryRelayState()
+
+ # Memory response
+ for ev in [
+ _response_created("resp_A"),
+ _output_item_added_function_call("memory_search"),
+ _output_item_done_function_call("memory_search"),
+ _response_completed("resp_A"),
+ ]:
+ relay.process_event(ev)
+
+ # State should be reset
+ assert relay.decided is False
+ assert relay.suppress_response is False
+ assert len(relay.pending_function_calls) == 0
+ assert len(relay.event_buffer) == 0
+
+ def test_alternating_memory_and_normal(self):
+ """Memory response → normal response → both work correctly."""
+ relay = WSMemoryRelayState()
+
+ # 1. Memory response (suppressed)
+ for ev in [
+ _response_created("resp_A"),
+ _output_item_added_function_call("memory_search"),
+ _output_item_done_function_call("memory_search"),
+ _response_completed("resp_A"),
+ ]:
+ relay.process_event(ev)
+
+ # 2. Continuation text response (relayed)
+ relayed: list[str] = []
+ for ev in [
+ _response_created("resp_B"),
+ _output_item_added_text(),
+ _output_text_delta(text="Pegasus-2"),
+ _output_item_done_text(),
+ _response_completed("resp_B"),
+ ]:
+ result = relay.process_event(ev)
+ relayed.extend(result["relay"])
+
+ assert len(relayed) == 5
+
+ # 3. Another normal response should also work
+ relayed2: list[str] = []
+ for ev in [
+ _response_created("resp_C"),
+ _output_item_added_shell(),
+ _response_completed("resp_C"),
+ ]:
+ result = relay.process_event(ev)
+ relayed2.extend(result["relay"])
+
+ assert len(relayed2) == 3