How Headroom's CCR Architecture Enables Reversible Compression

Headroom's CCR (Compress-Cache-Retrieve) architecture makes LLM compression fully reversible by storing original payloads in a local LRU cache, injecting a retrieval tool into the LLM context, and automatically handling tool calls to restore complete data when needed.

The Headroom proxy solves the token economy problem by allowing aggressive compression of large JSON payloads without sacrificing data integrity. Its CCR architecture, implemented in the chopratejas/headroom repository, ensures that every compressed summary can be expanded back to the original source, giving language models the efficiency of truncation with the safety of complete context retention.

The Three-Stage CCR Pipeline

The CCR architecture operates through three tightly integrated components that function as a transparent middleware layer between the client and the LLM.

Compression-Store Caching with SmartCrusher

When the SmartCrusher transform compresses a payload, it preserves the original JSON array in a Python-local LRU cache called compression_store while generating a unique hash. The compressed output includes a CCR marker containing this hash in the format <<ccr:HASH>>.

According to the source code in headroom/transforms/smart_crusher.py, the _mirror_ccr_to_python_store() and _mirror_single_hash_to_python_store() methods (lines 661-689) walk the rendered text to identify these markers and store the canonical payload in the compression store, ensuring the original data remains available for the duration of the session.

Runtime Tool Injection

Before the LLM receives the compressed context, the proxy dynamically injects the headroom_retrieve tool definition into the request. The create_ccr_tool_definition() function in headroom/ccr/tool_injection.py (lines 25-70) constructs provider-specific schemas for OpenAI, Anthropic, and Google APIs.

The CCRToolInjector.inject_tool_definition() method (lines 338-354) appends this tool to the request's tool list and optionally augments system messages with instructions explaining how to invoke it. The tool schema requires the hash from the CCR marker and optionally accepts a query parameter for targeted retrieval.

Automatic Retrieval and Response Reconstruction

When the LLM decides it needs the full data, it calls headroom_retrieve. The CCRResponseHandler intercepts this call transparently without exposing the tool invocation to the client. The _extract_tool_calls() and _parse_ccr_tool_calls() methods (lines 123-170 in headroom/ccr/response_handler.py) identify CCR-specific tool invocations.

The _execute_retrieval() method (lines 93-130) fetches the original payload using get_compression_store().retrieve(hash) and returns it as a JSON result. The handle_response() method (lines 190-236) constructs a tool-result message in the provider's native format, re-invokes the model API with the enriched conversation, and loops until no CCR calls remain. This gives the LLM the complete context needed to produce an accurate final answer while the client sees only a seamless response.

Search-Within-Compressed Data

The architecture supports BM25 search against cached entries for granular data access. When the LLM provides a query parameter in the headroom_retrieve call, _execute_retrieval() (lines 271-284 in headroom/ccr/response_handler.py) executes store.search(hash, query) to return only matching subsets rather than the full payload, optimizing token usage during retrieval.

Implementation Examples

Compressing Tool Output with CCR Markers

When SmartCrusher processes large JSON arrays, it automatically generates CCR markers and caches the original data:

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)

# Output: shortened JSON + "\n<<ccr:abcd1234ef567890>>"

The <<ccr:…>> marker carries the hash that the LLM will later use to retrieve the original payload.

Injecting the Retrieval Tool

The proxy middleware injects the headroom_retrieve tool definition before sending requests to the LLM:

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 the `headroom_retrieve` function definition

Handling LLM Retrieval Calls

When the LLM requests data via the injected tool, the response handler manages the retrieval and model re-invocation:

from headroom.ccr.response_handler import CCRResponseHandler

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

    messages=conversation_so_far,
    tools=tools,
    api_call_fn=proxy.api_call,        # async function for LLM API calls

    provider="anthropic",
)

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

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

Searching Within Cached Data

For partial retrieval, the LLM can include a query parameter:

# LLM invokes: headroom_retrieve(hash="abcd1234ef567890", query="error")

# The handler executes:

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

# Returns matching items only, wrapped in a tool-result message

Summary

• Three integrated components work together: compression-store caching, tool injection, and automatic response handling.
• Original data preservation occurs in a local LRU cache keyed by unique hashes, ensuring no data loss during aggressive compression.
• CCR markers (<<ccr:HASH>>) embed retrieval references directly in compressed text, creating a link between summaries and full payloads.
• Transparent operation means clients see a single clean API surface while the LLM accesses complete data through automated tool results.
• BM25 search support allows the LLM to retrieve specific subsets of cached data rather than entire payloads, maximizing token efficiency.

Frequently Asked Questions

What makes CCR compression "reversible" compared to standard truncation?

Standard truncation permanently discards data, whereas CCR preserves the original JSON array in a local LRU cache (headroom/cache/compression_store.py) keyed by a unique hash. The compressed text includes a CCR marker containing this hash, allowing the system to retrieve and reconstruct the full original payload at any time during the conversation.

How does the LLM know when to call the headroom_retrieve tool?

The CCRToolInjector class automatically appends the headroom_retrieve tool definition to the request's tool list and optionally injects system-message instructions explaining its usage. When the LLM encounters a CCR marker in the compressed context and determines it needs the full data, it invokes the tool with the hash extracted from the <<ccr:HASH>> marker.

Can CCR retrieval return partial data instead of the full payload?

Yes. The headroom_retrieve tool schema includes an optional query parameter. When provided, the CCRResponseHandler._execute_retrieval() method (lines 271-284) executes a BM25 search against the cached entry using store.search(hash, query), returning only the matching subset of the original JSON array rather than the entire payload.

Where is the original data stored during the compression phase?

The original data is stored in a Python-local LRU cache implemented in headroom/cache/compression_store.py. When SmartCrusher compresses content, its _mirror_ccr_to_python_store() method (lines 661-689 in headroom/transforms/smart_crusher.py) populates this cache with the canonical payload keyed by the hash found in the CCR marker.

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