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

> Explore Headroom's CCR algorithm for reversible compression. Learn how it caches data and restores it via LLM tool injection, reducing tokens without data loss.

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

---

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

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

### Step 2: Inject the Retrieval Tool

```python
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

```python
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.

```python

# 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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/smart_crusher.py) handles compression and caching, [`headroom/ccr/tool_injection.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/tool_injection.py) manages the injection of the retrieval tool into LLM requests, and [`headroom/ccr/response_handler.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/response_handler.py) coordinates the detection of tool calls and the re-invocation of the model with retrieved data.