# How to Set Up Cross-Agent Memory Sharing in Headroom: A Complete Guide

> Master cross-agent memory sharing in Headroom. Learn to configure SharedContext for efficient data transfer using advanced compression algorithms. Get the complete guide now.

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

---

**Headroom enables cross-agent memory sharing through the `SharedContext` component, which automatically compresses large payloads using SmartCrusher, CodeCompressor, and Kompress algorithms while maintaining an in-memory store accessible to all agents in a workflow.**

Cross-agent memory sharing in Headroom allows multiple AI agents to exchange large context payloads without transmitting full raw data between them. This is achieved through a centralized `SharedContext` instance that transparently compresses data and manages access across agent boundaries. In this guide, you will learn how to configure the shared memory store, implement the compression pipeline, and enable seamless data exchange between agents.

## Understanding the SharedContext Architecture

The `SharedContext` class serves as the primary interface for cross-agent memory sharing in Headroom. Located in [`headroom/memory/wrapper.py`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/wrapper.py), this component provides a high-level façade that abstracts the underlying compression and storage mechanisms.

When an agent stores data using `SharedContext.put()`, the system:

1. Invokes `headroom.compress()` to analyze the payload type
2. Applies appropriate compression algorithms (SmartCrusher for JSON, CodeCompressor for source code, Kompress for plain text)
3. Creates a `ContextEntry` object in [`headroom/memory/models.py`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/models.py) containing metadata such as original token counts, compressed token counts, applied transforms, and timestamps
4. Stores the entry in an in-memory backend defined in [`headroom/memory/backends/mem0.py`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/backends/mem0.py)

## Configuring the SharedContext Instance

To enable cross-agent memory sharing, instantiate a single `SharedContext` object that will be imported across all agent modules. The constructor accepts parameters for token counting, TTL eviction, and entry limits.

```python

# common.py - Shared configuration used by all agents

from headroom import SharedContext

shared_ctx = SharedContext(
    model="claude-sonnet-4-5-20250929",  # For accurate token counting

    ttl=3600,                            # Entries expire after 1 hour

    max_entries=100                      # Evict oldest when full

)

```

The `model` parameter ensures accurate token counts for compression ratio calculations. The `ttl` (time-to-live) and `max_entries` parameters prevent unbounded memory growth by automatically evicting stale entries.

## Writing Data to the Shared Store

Agents store large payloads using the `put()` method, which returns a `ContextEntry` containing compression statistics.

```python

# agent_a.py - Research agent storing results

from common import shared_ctx

def researcher_task():
    large_json = {"data": ["..." * 10000]}  # Large research payload

    
    # Compression happens automatically

    entry = shared_ctx.put(
        "research_results", 
        large_json, 
        agent="researcher"
    )
    
    print(f"Compressed {entry.original_tokens} → {entry.compressed_tokens} tokens")
    return {"status": "stored", "key": "research_results"}

```

The `put()` method handles all compression transparently through [`headroom/compress.py`](https://github.com/chopratejas/headroom/blob/main/headroom/compress.py), selecting the appropriate algorithm based on payload content type.

## Retrieving Data Across Agents

Downstream agents access shared data using `get()`, which returns compressed data by default or the full original when specified.

```python

# agent_b.py - Coding agent retrieving context

from common import shared_ctx

def coder_task():
    # Get compressed version (default behavior)

    summary = shared_ctx.get("research_results")
    
    # Retrieve full original when needed for code generation

    full_data = shared_ctx.get("research_results", full=True)
    
    print(f"Summary size: {len(summary)} chars")
    return full_data

```

Setting `full=True` bypasses the compressed representation and returns the original payload, useful when the complete context is required for specific operations.

## Managing and Inspecting the Memory Store

The `SharedContext` exposes utilities for monitoring store health and managing entries.

```python

# inspect.py - Administrative operations

from common import shared_ctx

def monitor_store():
    # Get aggregate statistics

    stats = shared_ctx.stats()
    print(f"Total entries: {stats.entries}")
    print(f"Compression savings: {stats.savings_percent}%")
    
    # Inspect specific entry metadata

    entry = shared_ctx.get_entry("research_results")
    print(f"Transforms applied: {entry.transforms}")
    
    # List all available keys

    available_keys = shared_ctx.keys()
    
    # Clear specific entry or entire store

    shared_ctx.clear("research_results")  # Single key

    # shared_ctx.clear()  # Entire store

```

## Summary

- **Cross-agent memory sharing** in Headroom relies on a single `SharedContext` instance shared across all agents in a workflow
- The compression pipeline automatically selects between SmartCrusher, CodeCompressor, and Kompress based on payload type
- Store configuration via `ttl` and `max_entries` parameters ensures bounded memory usage through automatic eviction
- Agents use `put()` to store compressed data and `get()` to retrieve either compressed or full representations
- The underlying architecture in [`headroom/memory/backends/mem0.py`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/backends/mem0.py) and [`headroom/memory/models.py`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/models.py) provides metadata tracking and statistics

## Frequently Asked Questions

### What compression algorithms does Headroom use for cross-agent memory sharing?

Headroom employs a three-tier compression pipeline located in [`headroom/compress.py`](https://github.com/chopratejas/headroom/blob/main/headroom/compress.py). **SmartCrusher** handles JSON payloads, **CodeCompressor** processes source code files, and **Kompress** manages plain text. The system automatically detects payload type and applies the appropriate algorithm when `SharedContext.put()` is invoked.

### How do I prevent the shared memory store from growing indefinitely?

Configure eviction policies when instantiating `SharedContext`. Set the `ttl` parameter (in seconds) to automatically remove entries after a specified duration, and use `max_entries` to enforce a hard limit on the number of stored items. When the limit is reached, the oldest entries are evicted first, as implemented in [`headroom/memory/backends/mem0.py`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/backends/mem0.py).

### Can I retrieve the original uncompressed data after storing it?

Yes. By default, `SharedContext.get(key)` returns the compressed representation to minimize token usage. However, passing `full=True` as a parameter—`shared_ctx.get(key, full=True)`—returns the original uncompressed payload from the `ContextEntry` stored in memory.

### How do multiple agents access the same SharedContext instance?

Agents import the configured instance from a shared module (such as [`common.py`](https://github.com/chopratejas/headroom/blob/main/common.py) in the examples above). Alternatively, dependency injection containers can pass the same `SharedContext` reference to each agent during initialization. This shared reference ensures all agents read from and write to the same underlying store in [`headroom/memory/backends/mem0.py`](https://github.com/chopratejas/headroom/blob/main/headroom/memory/backends/mem0.py).