# How Cross-Agent Memory Works in Headroom: Universal Memory Sync for LLM Agents

> Discover how Headroom's universal memory sync engine enables cross-agent memory by normalizing tool calls and routing them for deterministic results across LLM agents.

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

---

**Headroom implements cross-agent memory through a universal memory-sync engine that normalizes vendor-specific tool calls into a shared schema, routes them through pluggable storage adapters, and returns deterministic results to any participating LLM agent.**

Headroom is an open-source framework that enables different LLM agents—such as Claude, Codex, and GPT—to share a unified memory store as if they were a single coherent system. The cross-agent memory system eliminates vendor-specific tool fragmentation by enforcing a normalized schema and pluggable backend adapters. This architecture ensures that a memory saved by one agent can be retrieved seamlessly by another, regardless of the underlying model provider.

## The Three Pillars of Cross-Agent Memory Architecture

### Cross-Agent Schema

The foundation of interoperability is the **cross-agent schema**, a normalized set of tool-call names defined in [`headroom/learn/_shared.py`](https://github.com/chopratejas/headroom/blob/main/headroom/learn/_shared.py). This mapping eliminates vendor-specific nomenclature—such as OpenAI's `search` or Anthropic's `tool_use`—by translating every variant into standard names like `memory_search` and `memory_save`. The mapping table ensures that all agents communicate using the same vocabulary regardless of their native API.

### Sync Adapters

Storage backends are abstracted through **sync adapters**, located in `headroom/memory/sync_adapters/`. These small, pluggable classes translate generic schema operations into concrete storage commands for SQLite, Qdrant, Neo4j, or any future backend. Because adapters are decoupled from core logic, adding a new vector store requires only implementing the adapter interface without touching the orchestration logic.

### Memory Sync Engine

The **MemorySyncEngine** in [`headroom/memory/sync.py`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/sync.py) serves as the central orchestrator. It receives normalized tool calls, selects the appropriate adapter based on runtime configuration, and enforces operational constraints such as *top-k* limits and similarity thresholds. The engine also guarantees deterministic ordering of results across restarts, ensuring consistent behavior for stateful agent workflows.

## Cross-Agent Memory Data Flow

1. **Agent emits tool call** – A Claude or Codex response contains a vendor-specific memory request.

2. **Proxy extraction** – [`headroom/proxy/memory_handler.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/memory_handler.py) intercepts the response and extracts the tool name and arguments.

3. **Normalization** – The raw tool name is converted to the cross-agent schema using the mapping in [`headroom/learn/_shared.py`](https://github.com/chopratejas/headroom/blob/main/headroom/learn/_shared.py).

4. **Engine routing** – `MemorySyncEngine` selects the backend adapter based on the proxy configuration defined in [`headroom/proxy/models.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/models.py).

5. **Adapter execution** – The specific adapter (e.g., [`headroom/memory/sync_adapters/qdrant_adapter.py`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/sync_adapters/qdrant_adapter.py)) executes the search or save operation against the concrete store.

6. **Deterministic return** – Results are re-ordered deterministically and returned to the agent as standardized `memory_search` responses.

## Implementation Details and Code Examples

### The Memory Sync Engine

The `MemorySyncEngine` class initializes available adapters and routes incoming requests to the appropriate backend. This implementation from [`headroom/memory/sync.py`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/sync.py) demonstrates how the engine handles tool dispatch:

```python

# headroom/memory/sync.py

class MemorySyncEngine:
    def __init__(self, config: MemoryConfig):
        self.adapters = {
            "sqlite": SqliteAdapter(config.sqlite_path),
            "qdrant": QdrantAdapter(config.qdrant_url, config.qdrant_api_key),
            # additional adapters can be added here

        }

    async def handle(self, tool_name: str, args: dict) -> dict:
        # Translate to the generic schema (already normalized by the proxy)

        adapter = self.adapters[config.backend]
        if tool_name == "memory_search":
            return await adapter.search(args)
        if tool_name == "memory_save":
            return await adapter.save(args)
        # … other tool handlers …

```

### Tool Name Normalization

Before reaching the sync engine, vendor-specific tool names are normalized using the mapping table in [`headroom/learn/_shared.py`](https://github.com/chopratejas/headroom/blob/main/headroom/learn/_shared.py):

```python

# headroom/learn/_shared.py

AGENT_TO_GENERIC = {
    # OpenAI

    "search": "memory_search",
    "save": "memory_save",
    # Anthropic

    "tool_use": "memory_search",   # example mapping

    # Codex

    "codex_search": "memory_search",
}
def normalize_tool(name: str) -> str:
    return AGENT_TO_GENERIC.get(name, name)

```

### Client-Side Memory Operations

You can interact with the cross-agent memory system directly through the `HeadroomClient` in [`headroom/proxy/client.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/client.py):

```python
from headroom.proxy.client import HeadroomClient

client = HeadroomClient()
response = client.ask(
    "Summarize the latest design doc.",
    tools=["memory_search"],          # request the memory tool

    memory_top_k=5,                  # config per-request overrides

)
print(response.content)              # will contain retrieved memories if any

```

## Key Source Files for Cross-Agent Memory

- **[`headroom/memory/sync.py`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/sync.py)** – Core **MemorySyncEngine** that routes generic tool calls to concrete adapters.
- **`headroom/memory/sync_adapters/`** – Directory containing pluggable **backend adapters** for SQLite, Qdrant, Neo4j, and other storage systems.
- **[`headroom/learn/_shared.py`](https://github.com/chopratejas/headroom/blob/main/headroom/learn/_shared.py)** – Central **tool-name mapping** that normalizes all vendor-specific calls to the cross-agent schema.
- **[`headroom/learn/plugins/codex.py`](https://github.com/chopratejas/headroom/blob/main/headroom/learn/plugins/codex.py)** – Example **vendor-specific normalizer** implementation.
- **[`headroom/proxy/memory_handler.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/memory_handler.py)** – Proxy-side **gateway** that extracts memory tool calls from LLM responses.
- **[`headroom/proxy/models.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/models.py)** – Configuration models exposing `memory_backend`, `memory_top_k`, and `memory_min_similarity` settings.

## Summary

- Headroom achieves cross-agent memory through a **universal schema** that normalizes vendor-specific tool names into generic operations like `memory_search` and `memory_save`.
- **Sync adapters** provide plug-and-play abstraction for diverse storage backends without modifying core logic.
- The **MemorySyncEngine** orchestrates all operations, enforcing consistency and deterministic ordering across agent restarts.
- Memories saved by one agent (e.g., Codex) are immediately retrievable by others (e.g., Claude) through the shared pipeline.

## Frequently Asked Questions

### Can I add a custom vector database to Headroom's cross-agent memory system?

Yes. You can extend the system by creating a new adapter class in `headroom/memory/sync_adapters/` that implements the standard interface for `search`, `save`, and `delete` operations. Register your adapter in `MemorySyncEngine.adapters` in [`headroom/memory/sync.py`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/sync.py) without modifying the core normalization or orchestration logic.

### How does Headroom prevent naming conflicts between different LLM vendors?

Headroom uses the **cross-agent schema** defined in [`headroom/learn/_shared.py`](https://github.com/chopratejas/headroom/blob/main/headroom/learn/_shared.py) to map vendor-specific names—such as OpenAI's `search` or Anthropic's `tool_use`—to standardized names like `memory_search`. This normalization occurs in the proxy layer before requests reach the sync engine, ensuring all agents use identical terminology regardless of their origin.

### Is the memory retrieval order deterministic across different agents?

Yes. The `MemorySyncEngine` in [`headroom/memory/sync.py`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/sync.py) explicitly guarantees deterministic ordering of results. This ensures that agents receive consistent context regardless of which specific agent originally saved the memory or when the system was restarted.

### What configuration options control cross-agent memory behavior?

Memory behavior is controlled through settings in [`headroom/proxy/models.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/models.py), including `memory_backend` (selecting the storage adapter), `memory_top_k` (limiting result counts), and `memory_min_similarity` (setting relevance thresholds). These can be set globally or overridden per-request via the `HeadroomClient` interface.