How Headroom's CCR Algorithm Enables Reversible Compression: A Technical Deep Dive

Headroom's CCR (Compress-Cache-Retrieve) algorithm enables reversible compression by caching original payloads locally, injecting a retrieval tool into LLM requests, and automatically restoring full data when the model calls the tool, allowing aggressive token reduction without permanent data loss.

The CCR architecture in the chopratejas/headroom repository solves the fundamental trade-off between aggressive token compression and data preservation. By implementing a three-phase pipeline—Compress, Cache, and Retrieve—the system stores original JSON arrays in a local LRU cache while emitting compressed summaries to the LLM, ensuring the model can always access the full payload when needed.

How the CCR Algorithm Works

The CCR architecture consists of three tightly integrated components that operate seamlessly during request processing.

Compression and CCR Marker Generation

When a transform like SmartCrusher compresses a payload, the algorithm preserves the original data through a mirroring mechanism. In headroom/transforms/smart_crusher.py, the methods _mirror_ccr_to_python_store() and _mirror_single_hash_to_python_store() walk the rendered text for <<ccr:HASH>> markers and store the canonical payload in the Python compression store.

The compression process works as follows:

1. The original JSON array is compressed into a shortened summary.
2. A unique hash is generated for the original payload.
3. The full original data is saved in the local LRU cache (compression_store).
4. The compressed output includes a CCR marker containing the hash (e.g., <<ccr:abcd1234ef567890>>).

Implementation reference: Lines 661-689 in headroom/transforms/smart_crusher.py handle the mirroring of CCR data to the Python store.

Tool Injection and LLM Integration

The proxy layer automatically injects a retrieval capability into every request that contains CCR markers. The CCRToolInjector class in headroom/ccr/tool_injection.py performs two critical actions:

• Tool definition creation: The create_ccr_tool_definition() function builds provider-specific tool schemas (OpenAI, Anthropic, Google) for a function called headroom_retrieve that requires the hash from the CCR marker.
• Dynamic injection: The inject_tool_definition() method adds this tool to the request's tool list when a marker is present, optionally appending system-message instructions that tell the LLM how to invoke it.

Implementation reference: Lines 25-70 define the tool schema, while lines 338-354 in headroom/ccr/tool_injection.py handle the injection logic.

Automatic Retrieval and Response Handling

When the LLM determines it needs the full data, it calls headroom_retrieve with the hash. The CCRResponseHandler in headroom/ccr/response_handler.py intercepts this call through an automated pipeline:

• Detection: _extract_tool_calls() and _parse_ccr_tool_calls() (lines 123-170) identify CCR tool calls in the model's response.
• Retrieval: _execute_retrieval() fetches the original payload from the cache using get_compression_store().retrieve(hash) and returns a JSON result (lines 93-130).
• Continuation: handle_response() builds a tool-result message using _create_tool_result_message() and re-submits the enriched conversation to the model via the supplied API function until no CCR calls remain (lines 190-236).

The client never sees the tool call; the LLM receives the complete data transparently and continues its answer generation.

Enabling Reversible Compression in Your Implementation

To implement CCR in your Headroom deployment, you utilize the built-in transforms and injection handlers.

Step 1: Compress Content with SmartCrusher

from headroom.transforms.smart_crusher import SmartCrusher

crusher = SmartCrusher()
compressed, _, _ = crusher._smart_crush_content(
    content='[{"msg":"a"}, {"msg":"b"}, {"msg":"c"}]'  # large JSON array

)

print(compressed)   # → shortened JSON + "\n<<ccr:abcd1234ef567890>>"

The <<ccr:…>> marker carries the hash that links back to the cached original stored in headroom/cache/compression_store.py.

Step 2: Inject the Retrieval Tool

from headroom.ccr.tool_injection import CCRToolInjector

injector = CCRToolInjector(provider="openai")
messages, tools, injected = injector.process_request(
    messages=[{"role":"assistant","content":"..."}],
    tools=None,
    session_has_done_ccr=False,
)

# `tools` now contains a function definition for `headroom_retrieve`

Step 3: Handle CCR Tool Calls

from headroom.ccr.response_handler import CCRResponseHandler

handler = CCRResponseHandler()
final_response = await handler.handle_response(
    response=llm_reply,                # contains tool_use(headroom_retrieve, hash="...")

    messages=conversation_so_far,
    tools=tools,
    api_call_fn=proxy.api_call,        # async fn that talks to the LLM

    provider="anthropic",
)

# `final_response` contains the assistant's answer with the original

# JSON array injected; the client never sees the tool call.

Advanced Features: Search Within Compressed Data

The CCR architecture supports search-within-compressed-data through an optional query parameter in the tool schema. When the LLM includes a query in the retrieval call, CCRResponseHandler._execute_retrieval() executes a BM25 search against the cached entry.

# LLM includes a query:

#   headroom_retrieve(hash="abcd1234ef567890", query="error")

# The handler executes:

results = store.search("abcd1234ef567890", "error")

# → returns a JSON list of matching items, wrapped in a tool-result.

Implementation reference: Lines 271-284 in headroom/ccr/response_handler.py implement the search functionality.

Summary

• Headroom's CCR algorithm uses a three-phase approach (Compress-Cache-Retrieve) to enable reversible compression without data loss.
• Original payloads are stored in a local LRU cache (compression_store) keyed by hash, while compressed summaries with CCR markers are sent to the LLM.
• Automatic tool injection adds headroom_retrieve to the LLM's available functions, allowing the model to request full data when needed.
• Transparent handling via CCRResponseHandler manages the retrieval loop, re-invoking the model with tool results until the conversation completes.
• BM25 search support allows the LLM to query specific subsets of cached data without retrieving the entire payload.

Frequently Asked Questions

What is the CCR algorithm in Headroom?

The CCR (Compress-Cache-Retrieve) algorithm is Headroom's mechanism for reducing token usage in LLM workflows while preserving the ability to recover original data. It works by compressing large JSON arrays into summaries, caching the originals locally, and injecting a retrieval tool that the LLM can call to access the full payload when necessary.

How does reversible compression work in Headroom?

Reversible compression works by never discarding the original data. When SmartCrusher compresses content, it stores the full original JSON in a Python LRU cache and embeds a hash marker in the compressed text. If the LLM needs the complete data, it calls headroom_retrieve with that hash, and the CCRResponseHandler fetches the original from the cache and injects it back into the conversation.

Can I search within compressed data without retrieving everything?

Yes. The headroom_retrieve tool accepts an optional query parameter. When provided, CCRResponseHandler._execute_retrieval() performs a BM25 search against the cached entry and returns only the matching subset, allowing targeted data retrieval without the token overhead of the full payload.

Which files control the CCR injection and retrieval logic?

The core logic resides in three main files: headroom/transforms/smart_crusher.py handles compression and caching, headroom/ccr/tool_injection.py manages the injection of the retrieval tool into LLM requests, and headroom/ccr/response_handler.py coordinates the detection of tool calls and the re-invocation of the model with retrieved data.

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