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

> Discover how Headroom enables cross-agent memory sharing between Claude, Codex, and Gemini. Our unified backend gives agents persistent context for better collaboration.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: deep-dive
- Published: 2026-06-20

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/memory_handler.py)).

```json
{
  "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:

```python
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:

```python
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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/backends/direct_mem0.py), enabling scalable vector search across millions of memories.