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

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, 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 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:

{
  "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:

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:

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 and 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 and 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 with the server endpoint in 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.

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