# How Cross-Agent Memory Shares Compressed Context in Headroom

> Discover how Headroom's Cross-Agent Memory shares compressed context using its universal memory sync engine and CCR pipeline for efficient LLM agent collaboration.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-16

---

**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`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/sync_adapters/claude_code.py).
2. The `sync()` function in [`headroom/memory/sync.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/sync_adapters/claude_code.py) reads and writes Claude's native memory format.
- `CodexAdapter` in [`headroom/memory/sync_adapters/codex_agent.py`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/sync_adapters/codex_agent.py) handles Codex-specific memory structures.

### 3. Context Tracker ([`headroom/ccr/context_tracker.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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

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

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

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

```python
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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.