mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-27 14:17:10 -04:00

fix(ccr): make headroom_retrieve a hash-only full-content lookup (#1532 )

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. -->

2026-06-28 10:32:43 -07:00

2.9 KiB

Raw Permalink Blame History

Hermes Agent Integration

CCR retrieval plugin for Hermes Agent (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

Copy the plugin into Hermes's user plugin directory:

mkdir -p ~/.hermes/plugins
cp -r headroom_retrieve ~/.hermes/plugins/

Enable it in ~/.hermes/config.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.
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:

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.

2.9 KiB Raw Permalink Blame History