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

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

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.

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

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

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

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

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

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