# How Headroom's SharedContext Enables Compressed Inter-Agent Communication

> Discover how Headroom's SharedContext compresses data for efficient inter-agent communication. Learn about the CCR pipeline and token-efficient strings.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: deep-dive
- Published: 2026-06-13

---

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

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