mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
c2fc4d3753
The optional `query` parameter on headroom_retrieve routed retrieval through CompressionStore.search(), which BM25-scored the items inside a single cached blob and dropped everything below a 0.3 relevance floor. On small per-blob corpora with conversational queries this returned an empty result the large majority of the time, so the LLM saw "nothing found" for content that was actually present — pushing users to turn compression off entirely. Retrieval is fundamentally a hash lookup (this already matches the Rust proxy's CCR store, which is put/get only — "no BM25 search"). Remove the query/search path end to end and always return the full original content: Core (Python proxy): - tool schemas (anthropic/openai/google) drop the `query` property - parse_tool_call returns the hash (str | None) instead of (hash, query) - response handler, proxy POST/GET/tool-call handlers, the MCP retrieve tool, and the streaming feedback recorders retrieve by hash only - proactive context-tracker expansion always restores full content - delete CompressionStore.search() and its BM25 machinery (the bm25 module stays — it is still used by relevance/) - CCRToolCall.query, CCRToolResult.was_search, and ExpansionRecommendation.expand_full/search_query are removed Plugins (advertised a now-defunct query param to the LLM): - hermes (Python), openclaw + opencode (TypeScript) retrieve tools drop `query` from their schemas, signatures, request URLs, and tests Benchmarks/docs: - ccr_regression + adversarial benchmarks switch from store.search() to full hash retrieval (search input-injection tests repurposed to the hash, the only remaining input surface) - wiki/ARCHITECTURE.md, wiki/ccr.md, docs/content/docs/ccr.mdx, config.py and store docstrings updated to describe hash-only retrieval Tests updated to assert full-content retrieval and guard the removed surface; the full CCR/proxy/store/TOIN suite passes. ruff + mypy clean. ## Description <!-- Briefly explain the change and why it is needed. --> Closes # ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - ## Testing <!-- Check what you actually ran, then paste the real command output below. --> - [ ] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [ ] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text # Paste relevant command output or artifact links here ``` ## Real Behavior Proof - Environment: - Exact command / steps: - Observed result: - Not tested: ## Review Readiness - [ ] I have performed a self-review - [ ] This PR is ready for human review ## Checklist - [ ] My code follows the project's style guidelines - [ ] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes - [ ] I have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) Add screenshots to help explain your changes. ## Additional Notes <!-- Mention any N/A checklist items, tradeoffs, follow-ups, or maintainer context. -->
66 lines
2.9 KiB
Markdown
66 lines
2.9 KiB
Markdown
# 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`.
|
|
- Retrieval is by hash and always returns the full original content.
|
|
- 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.
|