# How Headroom's CCR Architecture Enables Reversible Compression > Discover how Headroom's CCR architecture achieves fully reversible LLM compression. Learn how it stores original payloads and uses a retrieval tool for data restoration. Visit chopratejas/headroom today. - Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom) - Tags: architecture - Published: 2026-06-16 --- **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 `<>`. According to the source code in [`headroom/transforms/smart_crusher.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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: ```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) # Output: shortened JSON + "\n<>" ``` The `<>` 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: ```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 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: ```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="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: ```python # 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** (`<>`) 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`](https://github.com/chopratejas/headroom/blob/main/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 `<>` 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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/smart_crusher.py)) populates this cache with the canonical payload keyed by the hash found in the CCR marker.