How Headroom's SharedContext Enables Compressed Inter-Agent Communication

Headroom's SharedContext automatically compresses large payloads using the CCR (Compress-Cache-Retrieve) pipeline, allowing agents to exchange compact token-efficient strings instead of full text while retaining access to original content via the full=True parameter.

The SharedContext class in the Headroom framework provides a thread-safe, in-process mechanism for multi-agent workflows to share data without incurring heavy token costs. By integrating compression directly into the storage layer at headroom/shared_context.py, it minimizes network overhead when specialized agents need to exchange research results, documents, or large context windows.

Core Architecture of the Shared Store

The implementation centers on a lightweight key-value store that handles concurrency, eviction, and statistics aggregation while delegating payload compression to a dedicated pipeline.

The SharedContext Class

The primary store lives in [headroom/shared_context.py](https://github.com/chopratejas/headroom/blob/main/headroom/shared_context.py) and is guarded by a threading.Lock (lines 78‑90). The constructor initializes a model for token counting, configures a TTL (time-to-live) for entries, and sets a maximum entry count to prevent unbounded memory growth. All mutations are atomic operations protected by this lock, ensuring safe concurrent access from multiple agents.

The Compression Pipeline

When put() is called, the payload is wrapped as a "tool" message and passed to the compression engine in [headroom/compress.py](https://github.com/chopratejas/headroom/blob/main/headroom/compress.py#L162). The compress function returns a CompressionResult (lines 108‑112) containing:

• tokens_before: Original token count
• tokens_after: Compressed token count
• Compressed text payload

This CCR stack integration ensures that heavy computational work happens once during storage, not during retrieval.

ContextEntry Metadata Structure

Each stored value is wrapped in a ContextEntry object (lines 36‑48) that tracks:

• Original and compressed token counts
• Compression savings percentage
• Timestamp and writing agent identifier
• The compressed payload itself

Automatic Eviction and TTL Management

To prevent stale data from bloating long-running pipelines, SharedContext implements deterministic eviction via _evict_if_needed() (lines 109‑119). This method first removes expired keys based on the configured TTL, then deletes the oldest entry if the store remains at capacity. This guarantees that memory usage remains bounded regardless of workflow duration.

API Design for Efficient Agent Hand-offs

The public interface exposes methods that distinguish between compressed and full content retrieval:

• put(key, content, agent=None) → ContextEntry: Compresses the payload and stores metadata.
• get(key, full=False) → str | None: Returns the compressed string by default; setting full=True returns the original uncompressed text.
• get_entry(key) → ContextEntry | None: Retrieves the complete metadata object for inspection.
• stats() → SharedContextStats: Aggregates compression metrics across all entries (lines 87‑102).
• clear(): Removes all entries from the store.

This design allows agents to pass compressed references efficiently while preserving the ability to materialize full content when necessary.

Performance Benefits in Multi-Agent Workflows

The compression integration delivers measurable advantages for distributed agent architectures:

• Reduced token cost: The debug log in SharedContext.put (lines 134‑139) indicates the compression routine typically reduces token counts by approximately 80 %, significantly lowering API costs for large context transfers.
• Fast hand-off: Agents exchange short compressed strings rather than full documents, minimizing network latency and context window consumption.
• Deterministic resource management: TTL and size limits ensure automatic cleanup of stale data, critical for long-running pipelines.
• Operational visibility: The stats() method exposes total tokens saved and overall savings percentage, enabling runtime monitoring and tuning.

Implementation Example

The following pattern demonstrates typical usage across multiple agents:

from headroom import SharedContext

# Initialize with default model and 1-hour TTL

ctx = SharedContext()

# Agent A stores a large research result

big_text = "..."  # lengthy document or research output

ctx.put("research", big_text, agent="researcher")

# Agent B fetches the compressed version for quick reference

compressed = ctx.get("research")
print("Compressed size:", len(compressed))

# Agent C requires the full original text for detailed analysis

full = ctx.get("research", full=True)
assert full == big_text

# Monitor compression efficiency across the workflow

stats = ctx.stats()
print(f"Saved {stats.total_tokens_saved} tokens "
      f"({stats.savings_percent}% overall)")

# Clean up when the workflow completes

ctx.clear()

Supporting utilities for token counting reside in [headroom/utils.py](https://github.com/chopratejas/headroom/blob/main/headroom/utils.py), while the test suite in [tests/test_shared_context.py](https://github.com/chopratejas/headroom/blob/main/tests/test_shared_context.py) validates TTL behavior, eviction policies, and compression correctness.

Summary

• Automatic compression: Every put() operation invokes the CCR pipeline, storing both compressed and original content.
• Efficient retrieval: The get() method returns compressed strings by default, with full=True providing access to original payloads.
• Thread-safe storage: A threading.Lock protects all mutations in headroom/shared_context.py, enabling safe concurrent access.
• Resource management: TTL-based eviction and entry limits prevent memory leaks in long-running agent workflows.
• Observability: Built-in statistics track token savings and compression ratios across the shared context.

Frequently Asked Questions

How does SharedContext achieve compression?

SharedContext delegates compression to the CCR stack in headroom/compress.py. When put() is called, the content is wrapped as a tool message and processed by the compress function, which returns a CompressionResult containing the compressed text and token counts. This compressed representation is stored alongside metadata regarding the original size.

What is the difference between get() and get_entry()?

The get(key, full=False) method returns the value as a string—either compressed (default) or original (when full=True). In contrast, get_entry(key) returns the complete ContextEntry object containing metadata such as timestamps, agent identifiers, and compression statistics without automatically extracting the payload string.

How does TTL eviction work in SharedContext?

The _evict_if_needed() method (lines 109‑119) runs automatically during storage operations. It first removes entries exceeding the configured TTL, then deletes the oldest remaining entry if the store exceeds its maximum capacity. This ensures the cache remains within memory bounds while prioritizing recent data.

What is the typical compression ratio achieved?

According to the debug logging in SharedContext.put (lines 134‑139), the compression pipeline typically achieves approximately 80 % token reduction, though actual ratios depend on the content structure and the specific compression model configured in the constructor.

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