How Cross-Agent Memory Shares Compressed Context in Headroom

Headroom enables multiple LLM agents to share compressed knowledge through a universal memory sync engine that stores deterministic hashes in a global compression store and expands them on demand using the CCR (Compress-Cache-Retrieve) pipeline.

The open-source Headroom project (chopratejas/headroom) solves the fragmentation problem when different LLM agents like Claude and Codex work on the same project. By implementing a cross-agent memory sharing system for compressed context, Headroom allows agents to exchange large amounts of data without redundant storage or re-compression overhead.

The CCR Pipeline Architecture

Headroom implements cross-agent memory sharing through the Compress-Cache-Retrieve (CCR) pipeline. When an agent generates large amounts of data, the system compresses it and stores the result in a global compression store keyed by a deterministic hash.

According to the chopratejas/headroom source code, the flow works as follows:

1. An agent writes its native memories (e.g., Claude's ~/.claude/projects/.../memory) using an adapter like ClaudeCodeAdapter in headroom/memory/sync_adapters/claude_code.py.
2. The sync() function in headroom/memory/sync.py imports these files into the Headroom database, recording the hash in DB metadata as content_hash if the data was CCR-compressed.
3. The compression store (accessed via headroom/ccr/context_tracker.py → get_compression_store()) holds the original content keyed by that hash.
4. The CCR context tracker receives a track_compression() call whenever a tool result is compressed, storing a CompressedContext record with the hash, turn number, workspace key, and sample content.
5. On subsequent requests from any agent in the same workspace, analyze_query() filters stored contexts by workspace_key, calculates relevance scores, and returns an ExpansionRecommendation.
6. execute_expansions() retrieves the full payload from the compression store and returns expanded content for the LLM prompt.
7. When another agent performs a sync export, sync_export() in headroom/memory/sync.py writes references to the agent's native files without duplicating storage.

How Cross-Agent Compression Propagates

The system achieves cross-agent memory sharing through workspace-scoped hash tracking. Each compressed payload is identified by a deterministic hash and indexed by a workspace key, which guarantees that only agents working on the same project can access each other's compressed data.

Because the sync layer writes the compressed entry into the shared Headroom DB and the context tracker indexes it by hash and workspace key, every agent that runs a sync import/export cycle can read the same compressed context without re-compressing the original data. This prevents cross-project leaks while enabling seamless collaboration between different LLM agents.

Key Implementation Components

1. Universal Sync Engine (headroom/memory/sync.py)

The sync() function handles bidirectional database-to-agent synchronization, persisting the CCR hash in the DB during import. The sync_export() function enables other agents to discover and reference existing compressed entries without creating duplicates.

2. Agent-Specific Adapters

Headroom provides adapters for different LLM agents:

• ClaudeCodeAdapter in headroom/memory/sync_adapters/claude_code.py reads and writes Claude's native memory format.
• CodexAdapter in headroom/memory/sync_adapters/codex_agent.py handles Codex-specific memory structures.

3. Context Tracker (headroom/ccr/context_tracker.py)

The ContextTracker class manages the CCR lifecycle:

• track_compression() records compression events with metadata including workspace_key, hash_key, and turn_number.
• analyze_query() matches incoming queries against stored compressed contexts using workspace isolation.
• execute_expansions() retrieves full original payloads from the compression store based on ExpansionRecommendation objects.

4. Compression Store (headroom/cache/compression_store.py)

The global store accessed via get_compression_store() maps each deterministic hash to its original uncompressed content, enabling efficient retrieval across different agent sessions.

Practical Code Examples

Importing an Agent's Memories and Syncing to the Database

from headroom.memory.sync import sync
from headroom.memory.backends.local import LocalBackend, LocalBackendConfig
from headroom.memory.sync_adapters.claude_code import ClaudeCodeAdapter, get_claude_memory_dir

backend = LocalBackend(LocalBackendConfig(db_path="data/headroom.db"))
adapter = ClaudeCodeAdapter(get_claude_memory_dir())
await sync(backend, adapter, user_id="alice")

Tracking a Compression Event

Called from transforms such as SearchCompressor to record compressed context:

from headroom.ccr.context_tracker import get_context_tracker

tracker = get_context_tracker()
tracker.track_compression(
    hash_key="abc123",
    turn_number=4,
    tool_name="Search",
    original_count=120,
    compressed_count=12,
    workspace_key="myproject",
    query_context="search for auth files",
    sample_content='["src/auth.py", "src/login.py", ...]',
)

Analyzing Queries and Expanding Compressed Context

tracker = get_context_tracker()
recs = tracker.analyze_query(
    query="How does the login flow work?",
    workspace_key="myproject",
)
expanded = tracker.execute_expansions(recs)
prompt = "\n".join([msg["content"] for msg in expanded])

# send `prompt` together with the original user query to the LLM

Exporting Database Entries to Another Agent

from headroom.memory.sync import sync_export
from headroom.memory.sync_adapters.codex_agent import CodexAdapter

adapter = CodexAdapter()
await sync_export(backend, adapter, user_id="alice")

Summary

• Cross-agent memory sharing in Headroom relies on the CCR pipeline to compress large contexts once and share them via deterministic hashes.
• The sync() function in headroom/memory/sync.py imports agent memories into a shared database, preserving compression metadata.
• Workspace keys ensure isolation, preventing compressed context from leaking across different projects.
• The ContextTracker in headroom/ccr/context_tracker.py manages compression tracking, query analysis, and context expansion.
• Agents like Claude and Codex interact through adapter classes that translate between native memory formats and the universal Headroom schema.
• execute_expansions() retrieves full content from the global compression store, enabling any synced agent to benefit from earlier compressed data without re-processing.

Frequently Asked Questions

How does Headroom prevent compressed context from leaking across projects?

The system uses a workspace key to isolate compressed data. When track_compression() stores a CompressedContext record, it includes the workspace_key parameter. The analyze_query() method filters results by this same key, ensuring agents can only access compressed contexts from their current project workspace.

What determines when context gets compressed in the CCR pipeline?

Compression typically occurs when tool results exceed size thresholds, triggering transforms like SearchCompressor. These transforms call track_compression() with metadata including original_count and compressed_count. The hash is generated deterministically from the content, allowing the get_compression_store() to deduplicate identical contexts across different agent sessions.

Can custom LLM agents integrate with Headroom's memory sharing?

Yes. Developers can create custom adapters by implementing the sync adapter interface used by ClaudeCodeAdapter and CodexAdapter. The adapter must handle reading the agent's native memory format and writing it back during sync_export(). As long as the adapter correctly handles the content_hash metadata for CCR-compressed entries, custom agents can participate in the cross-agent memory sharing ecosystem.

How does the system handle retrieval when multiple compressed contexts match a query?

The analyze_query() method in headroom/ccr/context_tracker.py calculates relevance scores for all matching CompressedContext records within the same workspace. It returns an ExpansionRecommendation containing the highest-scoring hashes, which execute_expansions() then retrieves from the compression store. This scoring mechanism ensures the most relevant historical context gets expanded into the prompt, even when multiple compressed entries exist.

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