How Headroom Enables Cross-Agent Memory Sharing Between Claude, Codex, and Gemini

Headroom's cross-agent memory functionality allows Claude, Codex, and Gemini to share persistent context through a unified storage backend and proxy layer that injects memory tools into every request.

The open-source Headroom proxy (chopratejas/headroom) implements cross-agent memory by intercepting LLM requests to persist facts across sessions. This architecture enables any supported agent to write memories that other agents can later retrieve using the same stable user_id.

How Cross-Agent Memory Works in Headroom

Headroom's architecture centers on three components that abstract storage complexity away from individual LLMs.

Unified Memory Backend

All memories are stored in a single backend—either SQLite for local development or Qdrant with Neo4j for production deployments. The Memory dataclass in headroom/memory/models.py represents stored entries keyed by a stable user_id and optionally scoped to specific projects. This design ensures that memories saved by Claude Code remain accessible when Gemini processes a subsequent request for the same user.

Memory Tools Architecture

The five CRUD operations—memory_save, memory_search, memory_update, memory_delete, and memory_list—are defined in headroom/memory/tools.py (lines 25-95). These OpenAI-style function definitions are exported in two flavors (plain and optimized) to accommodate different backend capabilities. The proxy injects these tools into every request's tool list, regardless of which LLM is processing the conversation.

MemoryHandler Proxy Layer

The core orchestration happens in headroom/proxy/memory_handler.py through the MemoryHandler class. This layer handles three critical responsibilities: injecting available tools into the request, searching the backend and appending retrieved context to user messages, and executing any tool calls present in the model's response.

Storing Memories from Claude Codex

When Claude Codex decides to persist information, it calls the memory_save tool that Headroom injected into its environment. The MemoryHandler.handle_memory_tool_calls method extracts the payload and forwards it to _execute_save (lines 1170-1190 in headroom/proxy/memory_handler.py).

{
  "type": "tool_use",
  "name": "memory_save",
  "input": {
    "content": "User prefers dark mode in all applications",
    "importance": 0.8,
    "entities": ["dark mode"]
  }
}

The _execute_save method writes a new row to the storage backend, optionally deduplicating against existing entries using cosine similarity thresholds defined on lines 81-83. Because storage is shared across agents, this memory becomes immediately available to Gemini or any other connected LLM.

Retrieving Context for Gemini

Headroom supports two retrieval modes that allow Gemini to access memories written by other agents.

AUTO_TAIL (Default)

The MemoryHandler.search_and_format_context method builds a vector query from the current user message and executes backend.search_memories. Results are formatted and injected into the latest user turn via _append_to_latest_user_tail (lines 922-978). The LLM receives these facts as read-only background context.

TOOL (Explicit)

Gemini can explicitly invoke memory_search. The proxy detects this via has_memory_tool_calls (lines 1016-1023) and routes execution through handle_memory_tool_calls, returning structured results from backend.search_memories (lines 1100-1135).

Both paths access the same backend data, ensuring continuity across agent boundaries.

Safety Mechanisms and Scoping

Headroom implements several safeguards to prevent cross-contamination and ensure data integrity.

Per-Project Isolation

The _resolve_for_request method (lines 639-656) routes requests to project-specific SQLite files or namespaced Qdrant collections. This prevents memories from leaking between unrelated workspaces while maintaining the ability to share within a project scope.

Read-Only Context Injection

Injected memory blocks include a clear warning header (lines 889-897) indicating the content is background information, not an instruction. This mitigates prompt injection risks.

Deduplication Thresholds

The system uses DEDUP_AUTO_THRESHOLD and DEDUP_HINT_THRESHOLD (lines 81-82) to prevent storing duplicate facts, reducing storage overhead and context noise.

Native Anthropic Memory Integration

When configured with use_native_tool=True, Headroom can inject Anthropic's proprietary memory_20250818 tool (defined as NATIVE_MEMORY_TOOL_NAME on line 84) while maintaining the shared backend for other agents. This configuration automatically adds the required beta header (NATIVE_MEMORY_BETA_HEADER, line 86), allowing Claude Codex to use native memory APIs while Gemini continues accessing the same data through Headroom's custom tools.

Implementation Examples

Initialize the handler at proxy startup:

from headroom.proxy.memory_handler import MemoryConfig, MemoryHandler

config = MemoryConfig(
    enabled=True,
    backend="local",
    db_path="headroom_memory.db",
    inject_tools=True,
    inject_context=True,
    mode=MemoryMode.AUTO_TAIL,
)
memory_handler = MemoryHandler(config, agent_type="claude-codex")

Gemini retrieving context automatically:

context = await memory_handler.search_and_format_context(
    user_id="alice",
    messages=request["messages"]
)
new_messages, _ = memory_handler._append_to_latest_user_tail(
    request["messages"], context, provider="anthropic"
)

Summary

• Headroom enables cross-agent memory sharing by providing a unified storage backend (SQLite or Qdrant/Neo4j) accessible to Claude, Codex, and Gemini.
• The MemoryHandler in headroom/proxy/memory_handler.py orchestrates tool injection, context retrieval, and execution.
• Five memory tools (save, search, update, delete, list) defined in headroom/memory/tools.py are injected into every agent request.
• AUTO_TAIL mode automatically prepends relevant memories to user messages, while TOOL mode allows explicit memory operations.
• Project scoping via _resolve_for_request and deduplication thresholds ensure safe, isolated memory management across different workspaces.

Frequently Asked Questions

How does Headroom prevent memory leakage between different users?

The MemoryHandler._resolve_for_request method ensures strict isolation by keying all memories to a stable user_id and optionally routing to project-specific storage namespaces. This prevents cross-user contamination while allowing intentional sharing within scoped projects.

Can I use Headroom with only Claude Code and not Gemini?

Yes. Headroom's architecture supports any combination of agents. You can configure the proxy for Claude Code only, and the memory backend will still function normally, storing data that remains accessible if you later add Gemini or other supported LLMs.

What happens when two agents try to save the same memory?

The _execute_save method implements deduplication using cosine similarity thresholds (DEDUP_AUTO_THRESHOLD and DEDUP_HINT_THRESHOLD). If the new content is semantically similar to existing entries, the system updates the existing record rather than creating a duplicate.

Does Headroom support cloud-based vector databases?

Yes. While the local SQLite backend suffices for individual development, Headroom supports production deployments through Qdrant with Neo4j integration via headroom/memory/backends/direct_mem0.py, enabling scalable vector search across millions of memories.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}