Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

feat(plugins): Hermes agent headroom_retrieve plugin (#824)

jimu058bcedab838
diff --git a/plugins/hermes/README.md b/plugins/hermes/README.md
new file mode 100644
index 000000000..6f2ab2be5
--- /dev/null
+++ b/plugins/hermes/README.md
@@ -0,0 +1,66 @@
+# Hermes Agent Integration
+
+CCR retrieval plugin for [Hermes Agent](https://hermes-agent.nousresearch.com/) (Nous Research). Gives Hermes a native `headroom_retrieve` tool so compression markers produced by the headroom proxy are no longer a black box — the agent can fetch the original content back on demand instead of guessing or re-running commands.
+
+## Why this is needed
+
+When Hermes routes its LLM traffic through `headroom proxy`, large tool outputs get compressed into markers like:
+
+```
+[1500 items compressed to 50. Retrieve more: hash=abc123] # Kompress path
+<<ccr:abc123>> / <<ccr:abc123,base64,4.5KB>> # SmartCrusher opaque-blob path
+```
+
+Claude Code users get the `headroom_retrieve` MCP tool injected automatically. Hermes registers its own tools, so without this plugin the markers are irreversible from the agent's point of view — in practice the model either re-runs the original command (wasting tokens/time) or, worse, treats `ccr:abc123` as a file path and tries to `cat` it.
+
+This plugin closes the loop by calling the proxy's `POST /v1/retrieve` HTTP endpoint directly. It complements (does not overlap with) `headroom wrap hermes` proxy-side support.
+
+## Install
+
+1. Copy the plugin into Hermes's user plugin directory:
+
+ ```bash
+ mkdir -p ~/.hermes/plugins
+ cp -r headroom_retrieve ~/.hermes/plugins/
+ ```
+
+2. Enable it in `~/.hermes/config.yaml`:
+
+ ```yaml
+ toolsets:
+ - hermes-cli
+ - web
+ - headroom # add this
+
+ plugins:
+ enabled:
+ - headroom_retrieve
+ ```
+
+ > Note: once the `plugins.enabled` key exists it acts as an explicit allowlist — list any other user plugins you already rely on.
+
+3. Restart the Hermes gateway / TUI (plugin discovery is cached per process).
+
+## Recommended proxy configuration
+
+Hermes tool names don't match headroom's built-in `DEFAULT_EXCLUDE_TOOLS` (which protects Claude Code's `Read`/`Grep`/`Edit`/...), so two exclusions are strongly recommended on the proxy side:
+
+```bash
+HEADROOM_EXCLUDE_TOOLS=read_file,headroom_retrieve
+```
+
+- `read_file` — Hermes's file reads are reference data the agent needs verbatim, same rationale as Claude Code's `Read`.
+- `headroom_retrieve` — without this, retrieved originals get re-compressed on the next request, producing an endless marker→retrieve→marker loop.
+
+## Behavior
+
+- Accepts the bare hash or the whole marker — `<<ccr:abc123,base64,4.5KB>>`, `ccr:abc123`, and `hash=abc123` are all normalized to `abc123`.
+- Optional `query` parameter filters very large results via the proxy's BM25 search.
+- Clear, actionable errors: expired hash (TTL) and proxy-unreachable cases both tell the model to re-run the original command instead of retrying blindly.
+
+## Requirements
+
+- headroom proxy running on `127.0.0.1:8787` (edit `_PROXY_URL` in `__init__.py` otherwise)
+- `httpx` (already a Hermes dependency)
+
+Tested against headroom 0.22.4 and 0.23.0 with Hermes Agent on macOS and Linux.
diff --git a/plugins/hermes/headroom_retrieve/__init__.py b/plugins/hermes/headroom_retrieve/__init__.py
new file mode 100644
index 000000000..812b0e12b
--- /dev/null
+++ b/plugins/hermes/headroom_retrieve/__init__.py
@@ -0,0 +1,102 @@
+"""Headroom CCR retrieve plugin.
+
+The headroom proxy (127.0.0.1:8787) compresses large tool outputs in LLM
+requests, replacing them with markers like ``[N items compressed ...
+hash=abc123]`` or ``<<ccr:abc123>>``. This plugin gives Hermes a tool to fetch the original
+uncompressed content back from the proxy's compression store, so compressed
+markers are no longer a black box.
+
+Storage is in-memory on the proxy side with a TTL — expired or
+post-proxy-restart hashes return 404 and the tool reports that clearly.
+"""
+
+from __future__ import annotations
+
+import httpx
+from tools.registry import tool_error, tool_result
+
+_PROXY_URL = "http://127.0.0.1:8787"
+
+HEADROOM_RETRIEVE_SCHEMA = {
+ "name": "headroom_retrieve",
+ "description": (
+ "Retrieve the original uncompressed content behind a headroom "
+ "compression marker. Markers look like "
+ "'[N items compressed ... hash=abc123]' OR '<<ccr:abc123>>' OR "
+ "'<<ccr:abc123,base64,4.5KB>>'. They are NOT file paths — never try "
+ "to cat/read them. When you see one in a tool result or in "
+ "conversation history, call this tool with the hash (the hex string "
+ "after 'hash=' or 'ccr:') to read the full original content instead "
+ "of guessing or re-running the command. For very large results, pass "
+ "the optional 'query' to filter to the relevant parts (BM25 search). "
+ "Content expires after a TTL — if expired, re-run the original "
+ "command instead."
+ ),
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "hash": {
+ "type": "string",
+ "description": "Hash from the compression marker, e.g. 'abc123' from '[... hash=abc123]' or '<<ccr:abc123>>'",
+ },
+ "query": {
+ "type": "string",
+ "description": "Optional search query to filter large results to relevant items",
+ },
+ },
+ "required": ["hash"],
+ },
+}
+
+
+def _handle_headroom_retrieve(args: dict, **kw) -> str:
+ hash_key = str(args.get("hash") or "").strip()
+ # Tolerate the model passing the whole marker instead of the bare hash:
+ # '<<ccr:abc123,base64,4.5KB>>' / 'ccr:abc123' / 'hash=abc123' -> 'abc123'
+ hash_key = hash_key.strip("<>").removeprefix("ccr:").removeprefix("hash=")
+ hash_key = hash_key.split(",")[0].strip()
+ if not hash_key:
+ return tool_error(
+ "hash is required (from a '[... hash=abc123]' or '<<ccr:abc123>>' marker)"
+ )
+
+ payload: dict = {"hash": hash_key}
+ query = str(args.get("query") or "").strip()
+ if query:
+ payload["query"] = query
+
+ try:
+ resp = httpx.post(f"{_PROXY_URL}/v1/retrieve", json=payload, timeout=15)
+ except httpx.HTTPError as exc:
+ return tool_error(
+ f"headroom proxy unreachable at {_PROXY_URL} ({type(exc).__name__}). "
+ "The proxy may be down; re-run the original command to get the data."
+ )
+
+ if resp.status_code == 404:
+ return tool_error(
+ "Content not found: expired (TTL passed) or proxy restarted. "
+ "Re-run the original command to regenerate the data."
+ )
+ if resp.status_code != 200:
+ return tool_error(f"headroom proxy returned HTTP {resp.status_code}: {resp.text[:200]}")
+
+ data = resp.json()
+ return tool_result(
+ {
+ "original_content": data.get("original_content", ""),
+ "original_tokens": data.get("original_tokens"),
+ "tool_name": data.get("tool_name"),
+ }
+ )
+
+
+def register(ctx) -> None:
+ """Register the headroom_retrieve tool. Called by the plugin loader."""
+ ctx.register_tool(
+ name="headroom_retrieve",
+ toolset="headroom",
+ schema=HEADROOM_RETRIEVE_SCHEMA,
+ handler=_handle_headroom_retrieve,
+ emoji="🗜️",
+ )
diff --git a/plugins/hermes/headroom_retrieve/plugin.yaml b/plugins/hermes/headroom_retrieve/plugin.yaml
new file mode 100644
index 000000000..45f60c2ab
--- /dev/null
+++ b/plugins/hermes/headroom_retrieve/plugin.yaml
@@ -0,0 +1,6 @@
+name: headroom_retrieve
+version: 1.0.0
+description: "Retrieve original content compressed by the headroom proxy (CCR markers)"
+author: akb4q
+provides_tools:
+ - headroom_retrieve
diff --git a/tests/test_plugins_hermes_retrieve.py b/tests/test_plugins_hermes_retrieve.py
new file mode 100644
index 000000000..226e2d198
--- /dev/null
+++ b/tests/test_plugins_hermes_retrieve.py
@@ -0,0 +1,183 @@
+"""Tests for the Hermes headroom_retrieve plugin (plugins/hermes/).
+
+The plugin targets the Hermes Agent runtime, which provides a
+``tools.registry`` module. That module does not exist inside the headroom
+codebase, so these tests stub it before loading the plugin file directly
+via importlib.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+import types
+from pathlib import Path
+from typing import Any
+
+import httpx
+import pytest
+
+PLUGIN_PATH = (
+ Path(__file__).resolve().parent.parent
+ / "plugins"
+ / "hermes"
+ / "headroom_retrieve"
+ / "__init__.py"
+)
+
+
+def _load_plugin() -> types.ModuleType:
+ """Load the plugin file with a stubbed Hermes ``tools.registry``."""
+ registry = types.ModuleType("tools.registry")
+ registry.tool_error = lambda msg: json.dumps({"error": msg}) # type: ignore[attr-defined]
+ registry.tool_result = lambda data: json.dumps({"result": data}) # type: ignore[attr-defined]
+ tools_pkg = types.ModuleType("tools")
+ tools_pkg.registry = registry # type: ignore[attr-defined]
+ sys.modules.setdefault("tools", tools_pkg)
+ sys.modules["tools.registry"] = registry
+
+ spec = importlib.util.spec_from_file_location("hermes_headroom_retrieve", PLUGIN_PATH)
+ assert spec is not None and spec.loader is not None
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+class _FakeResponse:
+ def __init__(self, status_code: int, payload: dict[str, Any] | None = None) -> None:
+ self.status_code = status_code
+ self._payload = payload or {}
+ self.text = json.dumps(self._payload)
+
+ def json(self) -> dict[str, Any]:
+ return self._payload
+
+
+def plugin() -> types.ModuleType:
+ return _load_plugin()
+
+
+ ("raw", "expected"),
+ [
+ ("abc123", "abc123"),
+ ("ccr:abc123", "abc123"),
+ ("<<ccr:abc123>>", "abc123"),
+ ("<<ccr:abc123,base64,4.5KB>>", "abc123"),
+ ("hash=abc123", "abc123"),
+ (" <<ccr:abc123>> ", "abc123"),
+ ],
+)
+def test_handler_normalizes_marker_shapes_to_bare_hash(
+ plugin: types.ModuleType, monkeypatch: pytest.MonkeyPatch, raw: str, expected: str
+) -> None:
+ # Arrange
+ seen: dict[str, Any] = {}
+
+ def fake_post(url: str, json: dict[str, Any], timeout: int) -> _FakeResponse: # noqa: A002
+ seen["payload"] = json
+ return _FakeResponse(200, {"original_content": "data", "original_tokens": 1})
+
+ monkeypatch.setattr(plugin.httpx, "post", fake_post)
+
+ # Act
+ plugin._handle_headroom_retrieve({"hash": raw})
+
+ # Assert
+ assert seen["payload"]["hash"] == expected
+
+
+def test_handler_passes_optional_query_through(
+ plugin: types.ModuleType, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ # Arrange
+ seen: dict[str, Any] = {}
+
+ def fake_post(url: str, json: dict[str, Any], timeout: int) -> _FakeResponse: # noqa: A002
+ seen["payload"] = json
+ return _FakeResponse(200, {"original_content": "data"})
+
+ monkeypatch.setattr(plugin.httpx, "post", fake_post)
+
+ # Act
+ plugin._handle_headroom_retrieve({"hash": "abc123", "query": "error lines"})
+
+ # Assert
+ assert seen["payload"] == {"hash": "abc123", "query": "error lines"}
+
+
+def test_handler_returns_original_content_on_200(
+ plugin: types.ModuleType, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ # Arrange
+ payload = {"original_content": "full text", "original_tokens": 42, "tool_name": "read_file"}
+ monkeypatch.setattr(plugin.httpx, "post", lambda *a, **kw: _FakeResponse(200, payload))
+
+ # Act
+ out = json.loads(plugin._handle_headroom_retrieve({"hash": "abc123"}))
+
+ # Assert
+ assert out["result"]["original_content"] == "full text"
+ assert out["result"]["original_tokens"] == 42
+ assert out["result"]["tool_name"] == "read_file"
+
+
+def test_handler_reports_expired_entry_on_404(
+ plugin: types.ModuleType, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ # Arrange
+ monkeypatch.setattr(plugin.httpx, "post", lambda *a, **kw: _FakeResponse(404))
+
+ # Act
+ out = json.loads(plugin._handle_headroom_retrieve({"hash": "deadbeef"}))
+
+ # Assert: actionable message, not a bare error
+ assert "expired" in out["error"]
+ assert "re-run" in out["error"].lower()
+
+
+def test_handler_reports_unreachable_proxy_on_connection_error(
+ plugin: types.ModuleType, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ # Arrange
+ def raise_connect_error(*a: Any, **kw: Any) -> None:
+ raise httpx.ConnectError("connection refused")
+
+ monkeypatch.setattr(plugin.httpx, "post", raise_connect_error)
+
+ # Act
+ out = json.loads(plugin._handle_headroom_retrieve({"hash": "abc123"}))
+
+ # Assert
+ assert "unreachable" in out["error"]
+
+
+def test_handler_rejects_empty_hash(plugin: types.ModuleType) -> None:
+ # Act
+ out = json.loads(plugin._handle_headroom_retrieve({"hash": " "}))
+
+ # Assert
+ assert "required" in out["error"]
+
+
+def test_register_exposes_tool_with_marker_aware_schema(plugin: types.ModuleType) -> None:
+ # Arrange
+ registered: dict[str, Any] = {}
+
+ class FakeCtx:
+ def register_tool(self, **kwargs: Any) -> None:
+ registered.update(kwargs)
+
+ # Act
+ plugin.register(FakeCtx())
+
+ # Assert
+ assert registered["name"] == "headroom_retrieve"
+ assert registered["toolset"] == "headroom"
+ assert registered["schema"]["parameters"]["required"] == ["hash"]
+ # The description must teach both marker formats so the model recognizes them.
+ description = registered["schema"]["description"]
+ assert "<<ccr:" in description
+ assert "hash=" in description