SharedContext

Compressed inter-agent context sharing. Reduce token usage by ~80% when agents hand off to each other.

When agents hand off to each other, context gets replayed in full. SharedContext compresses what moves between agents using Headroom's compression pipeline, typically saving ~80% of tokens on agent handoffs.

Quick Start

import {  } from "headroom-ai";

const  = new ();

// Agent A stores large output
const  = await .put("research", bigResearchOutput, {
  : "researcher",
});

// Agent B gets compressed version (~80% smaller)
const  = .get("research");

// Agent B needs full details on demand
const  = .get("research", { : true });

API

`put(key, content, agent?)`

Store content under a key. Compresses automatically using Headroom's full pipeline (SmartCrusher for JSON, CodeCompressor for code, Kompress for text).

const  = await .put("findings", bigJsonOutput, {
  : "researcher",
});

.originalTokens;   // 20000
.compressedTokens;  // 4000
.savingsPercent;    // 80.0
.transforms;        // ["router:json:0.20"]

`get(key, full?)`

Retrieve content. Returns the compressed version by default, or the original with full=True.

const  = .get("findings");                  // 4K tokens
const  = .get("findings", { : true });    // 20K tokens
const  = .get("nonexistent");                  // null

`stats()`

Aggregated statistics across all entries.

const  = .stats();
.entries;                // 3
.totalOriginalTokens;    // 60000
.totalCompressedTokens;  // 12000
.totalTokensSaved;       // 48000
.savingsPercent;         // 80.0

`keys()` and `clear()`

keys() lists all non-expired keys. clear() removes all entries.

Configuration

const  = new ({
  : "claude-sonnet-4-5-20250929",  // For token counting
  : 3600,                             // 1 hour (default)
  : 100,                       // Evicts oldest when full
});

Entries expire after ttl seconds. When maxEntries is reached, the oldest entry is evicted.

Framework Examples

SharedContext is framework-agnostic. It works anywhere context moves between agents.

CrewAI

from headroom import SharedContext

ctx = SharedContext()

# After researcher task completes
ctx.put("findings", researcher_task.output.raw)

# Coder task gets compressed context
coder_context = ctx.get("findings")

LangGraph

from headroom import SharedContext

ctx = SharedContext()

def researcher_node(state):
    result = do_research()
    ctx.put("research", result)
    return {"research_summary": ctx.get("research")}

def coder_node(state):
    # Compressed summary in state, full details on demand
    full = ctx.get("research", full=True)
    return {"code": write_code(full)}

OpenAI Agents SDK

from headroom import SharedContext

ctx = SharedContext()

def compress_handoff(messages):
    for msg in messages:
        if len(msg.content) > 1000:
            ctx.put(msg.id, msg.content)
            msg.content = ctx.get(msg.id)
    return messages

handoff(agent=coder, input_filter=compress_handoff)

How It Works

Under the hood, put() calls headroom.compress() -- the same pipeline used by the Headroom proxy -- and stores the original in memory. get() returns the compressed version. get(full=True) returns the original.

The compression pipeline routes content to the best compressor:

JSON arrays -- SmartCrusher (70-95% compression)
Code -- CodeCompressor (AST-aware)
Text -- Kompress (ModernBERT-based) or passthrough

On this page