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

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. 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 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 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.

4. Engine routing – MemorySyncEngine selects the backend adapter based on the proxy configuration defined in headroom/proxy/models.py.

5. Adapter execution – The specific adapter (e.g., 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 demonstrates how the engine handles tool dispatch:

# 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:

# 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:

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 – 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 – Central tool-name mapping that normalizes all vendor-specific calls to the cross-agent schema.
• headroom/learn/plugins/codex.py – Example vendor-specific normalizer implementation.
• headroom/proxy/memory_handler.py – Proxy-side gateway that extracts memory tool calls from LLM responses.
• 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 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 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 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, 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.

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