# How SharedContext Enables Multi-Agent Workflow Coordination in Headroom

> Discover how Headroom's SharedContext streamlines multi-agent workflow coordination. This thread-safe cache provides immediate access to shared string data for every agent.

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

---

**SharedContext is a thread-safe, compressed cache that stores arbitrary strings produced by one agent and makes a compressed version immediately available to any other agent in the same workflow.**

In the `chopratejas/headroom` repository, coordinating multiple AI agents requires passing large intermediate results between participants without overwhelming memory or bandwidth. The `SharedContext` class provides a centralized mechanism for this data exchange, implementing automatic compression and configurable TTL policies to optimize multi-agent workflows.

## Compression Pipeline and ContextEntry Storage

When an agent stores data using `ctx.put(key, content)`, the implementation in [`headroom/shared_context.py`](https://github.com/chopratejas/headroom/blob/main/headroom/shared_context.py) (lines 36-48) routes the raw string through Headroom's **Compress-Cache-Retrieve (CCR)** pipeline. The system invokes `headroom.compress.compress` to generate a compressed payload alongside token statistics and transform metadata.

The method then creates a `ContextEntry` dataclass instance that records:
- Original text and compressed version
- Token counts for both representations
- Originating agent identifier (optional)
- Timestamp for expiration tracking

This architecture ensures agents store optimized representations rather than raw payloads, typically achieving approximately 80% size reduction in production workflows.

## On-Demand Full Retrieval

The `get()` method in [`headroom/shared_context.py`](https://github.com/chopratejas/headroom/blob/main/headroom/shared_context.py) (lines 44-53) supports dual retrieval modes. By default, `ctx.get(key)` returns the compressed payload, minimizing data transfer between workflow steps. When downstream agents require complete fidelity, passing `full=True` retrieves the original uncompressed text from the `ContextEntry`.

This pattern allows agents to request only the detail level necessary for their specific sub-task—compressed summaries for quick decisions, full content for citation extraction—without regenerating intermediate results.

## Thread Safety for Concurrent Agents

The implementation protects shared state with a single `threading.Lock` as shown in lines 88-90 of [`headroom/shared_context.py`](https://github.com/chopratejas/headroom/blob/main/headroom/shared_context.py). Every public method—`put`, `get`, `keys`, `stats`, and `clear`—acquires this lock before accessing the internal dictionary.

This design guarantees that multiple agents can safely write and read from the cache simultaneously without race conditions, making `SharedContext` suitable for parallel agent execution patterns.

## Automatic Eviction and TTL Management

`SharedContext` enforces resource boundaries through lazy and proactive eviction strategies defined in lines 86-104 of [`headroom/shared_context.py`](https://github.com/chopratejas/headroom/blob/main/headroom/shared_context.py):

- **TTL expiration**: Each entry carries a timestamp. Expired items are removed during `get` or `keys` calls.
- **Size limits**: The `_evict_if_needed` method triggers on every `put` operation when `max_entries` is exceeded, discarding oldest entries first (FIFO).

Default configurations use a one-hour TTL and 100-entry maximum, though both parameters are configurable during instantiation.

## Monitoring Compression Effectiveness

The `stats()` method (lines 86-102) aggregates diagnostic metrics across all live entries:

- `entries`: Count of active items
- `total_original_tokens`: Aggregate uncompressed token count
- `total_compressed_tokens`: Aggregate compressed token count
- `savings_percent`: Calculated compression efficiency

These values enable logging and monitoring interfaces to quantify the performance benefits of shared context compression in production multi-agent workflows.

## Practical Implementation Example

The following pattern demonstrates coordinating three agents through a shared research context:

```python
from headroom import SharedContext

# Initialize with defaults (model=claude-sonnet-4-5-20250929, ttl=1h, max_entries=100)

ctx = SharedContext()

# Agent A generates content

large_report = "..."  # extensive research string

ctx.put("research_report", large_report, agent="researcher")

# Agent B retrieves compressed version for summary decision

summary = ctx.get("research_report")
print("Compressed size:", len(summary))

# Agent C retrieves full version for citation extraction

full_report = ctx.get("research_report", full=True)
print("Original size:", len(full_report))

# Monitor cache state

print("Active keys:", ctx.keys())
print("Compression stats:", ctx.stats())

```

## Summary

- **SharedContext** facilitates multi-agent coordination in `chopratejas/headroom` through a centralized, thread-safe cache implemented in [`headroom/shared_context.py`](https://github.com/chopratejas/headroom/blob/main/headroom/shared_context.py).
- **Automatic compression** via the CCR pipeline reduces data transfer size by approximately 80% while preserving full content accessibility via the `full=True` parameter.
- **Concurrent safety** is guaranteed by a `threading.Lock` protecting all public methods, enabling parallel agent execution without race conditions.
- **Resource management** combines TTL expiration (default 1 hour) and FIFO eviction (default 100 entries) to prevent unbounded memory growth.
- **Observable metrics** via `stats()` expose token savings and cache utilization for workflow optimization.

## Frequently Asked Questions

### How does SharedContext handle concurrent writes from multiple agents?

According to [`headroom/shared_context.py`](https://github.com/chopratejas/headroom/blob/main/headroom/shared_context.py) (lines 88-90), a single `threading.Lock` protects the internal dictionary. All public methods including `put`, `get`, and `keys` acquire this lock before accessing shared state, ensuring atomic operations and preventing race conditions during concurrent agent execution.

### What is the default TTL and maximum entry limit for SharedContext?

By default, `SharedContext` initializes with a one-hour TTL and a maximum of 100 entries (`max_entries=100`). The `_evict_if_needed` method (lines 86-104) proactively removes oldest entries when limits are exceeded, while expired items are lazily filtered during retrieval operations.

### Can I retrieve the original uncompressed text after storing content?

Yes. While `ctx.get(key)` returns the compressed version by default to minimize bandwidth, passing `full=True` retrieves the original text stored in the `ContextEntry` dataclass (lines 44-53). This allows specific agents to access complete details without regenerating content, while others operate on compressed summaries.

### How does the compression pipeline affect token usage?

The CCR pipeline in `headroom.compress.compress` processes content through configurable transforms, typically achieving approximately 80% size reduction. The `stats()` method (lines 86-102) tracks `total_original_tokens` versus `total_compressed_tokens`, enabling quantification of actual savings for workflow optimization and cost management.