Reversible Compression (CCR)

Headroom's CCR (Compress-Cache-Retrieve) architecture makes compression reversible. When content is compressed, the original data is cached locally. If the LLM needs the full data, it retrieves it instantly.

The problem with traditional compression

Traditional compression forces a difficult tradeoff:

• Aggressive compression risks losing data the LLM needs
• Conservative compression misses out on token savings

CCR eliminates this tradeoff entirely. Compress aggressively, retrieve on demand.

Architecture

CCR flows through four phases:

TOOL OUTPUT (1000 items)
  -> SmartCrusher compresses to 20 items
  -> Original cached with hash=abc123
  -> Retrieval tool injected into context

LLM PROCESSING
  Option A: LLM solves task with 20 items -> Done (90% savings)
  Option B: LLM calls headroom_retrieve(hash=abc123)
            -> Response Handler returns full data automatically

Phase 1: Compression Store

When SmartCrusher compresses tool output:

1. The original content is stored, keyed by hash, with LRU-style eviction once the store hits capacity. In the proxy, this store defaults to a SQLite file (ccr_store.db in the workspace directory) rather than a pure in-process dict -- so it survives a proxy restart and is shared across worker processes. Set HEADROOM_CCR_BACKEND=memory to opt back into an in-process-only store. Other backend names are resolved via the headroom.ccr_backend setuptools entry-point group (e.g. a redis backend, if one is installed and registered) -- none besides sqlite/memory ship in this repo. See headroom/cache/compression_store.py:1000-1017.
2. A hash key is generated for retrieval
3. A marker is added to the compressed output:

[1000 items compressed to 20. Retrieve more: hash=abc123]

Phase 2: Tool Injection

Headroom injects a headroom_retrieve tool into the LLM's available tools:

{
  "name": "headroom_retrieve",
  "description": "Retrieve original uncompressed data from Headroom cache",
  "parameters": {
    "hash": "The hash key from the compression marker"
  }
}

The LLM sees this tool alongside your application's tools and can call it whenever the compressed data is insufficient.

Phase 3: Response Handler

When the LLM calls headroom_retrieve:

1. The Response Handler intercepts the tool call
2. Data is retrieved from the local cache (around 1ms)
3. The result is added to the conversation
4. The API call continues automatically

The client never sees CCR tool calls on the Anthropic and OpenAI proxy paths; Headroom resolves them transparently there.

Phase 4: Context Tracker

Across multiple turns, the Context Tracker maintains awareness of all compressed content:

1. Remembers what was compressed in earlier turns
2. Analyzes new queries for relevance to compressed content
3. Proactively expands relevant data before the LLM asks

Turn 1: User searches for files
        -> 500 files compressed to 15, cached (hash=abc123)
        -> LLM answers with 15 files

Turn 5: User asks "What about the auth middleware?"
        -> Context Tracker detects "auth" may match cached content
        -> Proactively expands compressed data
        -> LLM finds auth_middleware.py in the full list

Retrieving originals

CCR works automatically on the Anthropic and OpenAI proxy paths, but you can also retrieve cached data programmatically:

import { compress } from "headroom-ai";
import type { CCRConfig } from "headroom-ai";

// CCR is enabled by default when compressing through the proxy.
const result = await compress(messages, {
  model: "gpt-4o",
});

// Access compressed messages — CCR markers are embedded automatically
console.log(result.messages);

// CCR configuration options
const ccrConfig: CCRConfig = {
  enabled: true,
  injectTool: true,             // Inject headroom_retrieve tool
  injectRetrievalMarker: true,  // Add retrieval markers to compressed output
  feedbackEnabled: true,        // Learn from retrieval patterns
  storeMaxEntries: 1000,        // Max cached items
  storeTtlSeconds: 3600,        // Cache TTL
};

from openai import OpenAI

# Start `headroom proxy` first (defaults to port 8787); use --no-optimize
# for a passthrough baseline or --no-ccr to disable CCR specifically.
client = OpenAI(base_url="http://127.0.0.1:8787/v1", api_key="local")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
)

Retention

Proxy CCR originals are kept for 1800 seconds (30 minutes) by default. For longer autonomous agent runs, set HEADROOM_CCR_TTL_SECONDS before starting the proxy:

HEADROOM_CCR_TTL_SECONDS=7200 headroom proxy

Check the effective setting at /v1/retrieve/stats under store.default_ttl_seconds.

Message-level CCR

Retired: The "Message-level CCR via IntelligentContext" feature (where IntelligentContext would store dropped messages in CCR with a retrieval marker) was part of the IntelligentContextConfig API that has since been removed. Context management is now handled automatically by the pipeline without a separate configurable IntelligentContext stage. Tool-output CCR via SmartCrusher and ContentRouter remains fully supported.

CCR-enabled components

Why CCR matters

CCR gives you the savings of aggressive compression with zero risk: SmartCrusher, LogCompressor, SearchCompressor, and Kompress can all compress as aggressively as their configuration allows, because the original is always one retrieval away. See How Compression Works for measured savings ranges per compressor.