Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
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.pyindex 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_markerend_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 entirelystart = 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_sectionelse:- content = headroom_section+ content = top_level_block + "\n" + provider_sectionconfig_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.pyindex 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 Pathfrom typing import TYPE_CHECKINGfrom 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.pynew file mode 100644index 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.pynew file mode 100644index 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__.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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.pyindex 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_toolslogger.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-istokens_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 messageawait upstream.send(first_msg_raw)- # Bidirectional relay+ # Bidirectional relay with memory tool interceptionasync 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.pyindex 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.pyindex 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 UserThe 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 contextdef _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_callschoices = 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 dataif 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.pynew file mode 100644index 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_contentdiff --git a/tests/test_ws_memory_relay.py b/tests/test_ws_memory_relay.pynew file mode 100644index 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