# What Is the headroom_retrieve Tool? Fetching Original Uncompressed Content in Headroom CCR

> Discover the headroom_retrieve tool for accessing original uncompressed content from the Headroom CCR in memory cache. Learn how to fetch full data using compression markers.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: api-reference
- Published: 2026-06-13

---

**The `headroom_retrieve` tool is a Headroom CCR utility that fetches the full, uncompressed original content from the proxy's in-memory cache using a hash extracted from compression markers like `<<ccr:abc123>>`.**

The `headroom_retrieve` tool is a core component of the **Headroom CCR (Compress-Cache-Retrieve)** system in the `chopratejas/headroom` repository. When large tool outputs are compressed and replaced with hash markers, this tool allows language models to retrieve the complete original payload on demand. It communicates with the Headroom proxy to access TTL-controlled cached data.

## How headroom_retrieve Works in the CCR Pipeline

When Headroom compresses large tool outputs, it replaces them with markers such as `[N items compressed … hash=abc123]` or `<<ccr:abc123,base64,4.5KB>>`. The compressed payload is stored **in-memory on the Headroom proxy** with a configurable TTL. The marker is injected into the LLM's response, allowing the model to later request the original data.

The `headroom_retrieve` tool performs a **POST request to `/v1/retrieve`** on the Headroom proxy (default `http://127.0.0.1:8787`). The proxy looks up the hash in its CCR store and returns the raw uncompressed data along with metadata including token counts and tool provenance.

## Tool Implementation and Source Code

### Plugin Registration and Handler

The tool is implemented as a **Hermes plugin** that registers with the Headroom tool registry. In [`plugins/hermes/headroom_retrieve/__init__.py`](https://github.com/chopratejas/headroom/blob/main/plugins/hermes/headroom_retrieve/__init__.py), the plugin defines the tool schema and request handler (lines 52-90). This handler extracts the hash from tool arguments, constructs the HTTP request to the proxy, and returns either a `tool_result` containing the original content or a `tool_error` if the lookup fails.

### Proxy Endpoint

The server-side endpoint is implemented in [`headroom/proxy/server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py) around line 3319. This exposes the **POST `/v1/retrieve`** route that queries the CCR in-memory store. When the hash is found, the proxy returns a JSON payload containing the original uncompressed content.

## How to Use headroom_retrieve

### LLM-Side Tool Invocation

When a language model detects insufficient context from a compressed marker, it emits a tool use block:

```json
{
  "type": "tool_use",
  "id": "toolu_1",
  "name": "headroom_retrieve",
  "input": {
    "hash": "abc123"
  }
}

```

The Headroom proxy intercepts this call, performs the HTTP retrieval, and inserts the original content back into the conversation context.

### Direct HTTP API Call

You can call the retrieve endpoint directly from any HTTP client:

```python
import httpx

proxy_url = "http://127.0.0.1:8787"
payload = {"hash": "abc123"}  # hash extracted from the marker

resp = httpx.post(f"{proxy_url}/v1/retrieve", json=payload, timeout=15)

if resp.status_code == 200:
    data = resp.json()
    print("Original content:", data["original_content"])
else:
    print("Error:", resp.text)

```

### Hermes Plugin Integration

When using the Hermes plugin system, the tool registers automatically upon loading:

```python
from tools.registry import registry

# Register the plugin

registry.load_plugin("hermes.headroom_retrieve")

# Call the tool programmatically

result = registry.call_tool(
    name="headroom_retrieve",
    args={"hash": "abc123"}
)

print(result)  # Contains original_content, original_tokens, tool_name

```

## Response Format and Error Handling

A successful `headroom_retrieve` call returns a JSON object with the following fields:

- **original_content**: The raw, uncompressed data that was originally produced by the tool
- **original_tokens**: Token count of the content for cost estimation
- **tool_name**: The name of the tool that produced the compressed output

If the hash is unknown, expired, or the proxy is unreachable, the tool returns a structured error explaining the situation (e.g., "Content not found: expired (TTL passed)..."). This error handling is tested in [`tests/test_plugins_hermes_retrieve.py`](https://github.com/chopratejas/headroom/blob/main/tests/test_plugins_hermes_retrieve.py) and [`tests/test_ccr_response_handler_extra.py`](https://github.com/chopratejas/headroom/blob/main/tests/test_ccr_response_handler_extra.py).

Additional documentation on the CCR architecture and why reversible compression requires this retrieval mechanism is available in [`wiki/ccr.md`](https://github.com/chopratejas/headroom/blob/main/wiki/ccr.md) and [`wiki/index.md`](https://github.com/chopratejas/headroom/blob/main/wiki/index.md).

## Summary

- **`headroom_retrieve`** fetches original uncompressed content from Headroom's CCR cache using a hash identifier
- The tool performs **POST `/v1/retrieve`** requests to the Headroom proxy (default `http://127.0.0.1:8787`)
- Implementation lives in [`plugins/hermes/headroom_retrieve/__init__.py`](https://github.com/chopratejas/headroom/blob/main/plugins/hermes/headroom_retrieve/__init__.py) with the server endpoint in [`headroom/proxy/server.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py)
- Returns **original_content**, **original_tokens**, and **tool_name** for complete context restoration
- Handles expired or missing content with structured error responses

## Frequently Asked Questions

### What is the headroom_retrieve tool used for?

The `headroom_retrieve` tool enables language models to access the full, original uncompressed content of tool outputs that were previously compressed and cached by Headroom. When the LLM encounters a compression marker like `<<ccr:hash>>`, it uses this tool to fetch the complete payload rather than working with the truncated or compressed version.

### How does headroom_retrieve handle expired or missing content?

If the hash is unknown or the TTL has expired, the tool returns a structured error message indicating "Content not found: expired (TTL passed)" or similar. This allows the calling system to gracefully handle cache misses by either regenerating the content or proceeding without the full context.

### What endpoint does headroom_retrieve call?

The tool sends a **POST request to `/v1/retrieve`** on the Headroom proxy, typically running at `http://127.0.0.1:8787`. The request body contains a JSON payload with the hash field extracted from the compression marker.

### Where is the original uncompressed content stored?

The original content is stored **in-memory on the Headroom proxy** in a TTL-controlled CCR store. This ephemeral storage allows the system to maintain large tool outputs without transmitting them to the LLM on every turn, while keeping them accessible via the `headroom_retrieve` tool for on-demand retrieval.