Hermes
Add query-aware context and tool-output compression to the Hermes Agent with the first-party Compresr plugin.
Hermes Agent is Nous Research's open-source coding and CLI agent. The Compresr Python SDK ships a first-party Hermes plugin (under compresr.integrations.hermes) that compresses the two biggest token sinks in a long agent session — mid-conversation context compaction and large tool outputs — query-aware, using Compresr's compression models. Both features are opt-in and fail open: any API error falls back to Hermes's built-in behavior and never drops context.
Opt-in and fail-open
The plugin stays inert until you enable a feature and set an API key, and every compression call falls back to Hermes's native behavior on error — it never breaks a tool call or loses a transcript.
1. Install
Guided install (prompts for your API key and enables the plugin):
The installer asks for COMPRESR_API_KEY (get one at compresr.ai → Dashboard → API Keys) and writes it to ~/.hermes/.env. compresr-sdk login works too.
Already have the SDK? pip install compresr alone ships the plugin via the hermes_agent.plugins entry point — just hermes plugins enable compresr and set COMPRESR_API_KEY yourself.
2. Enable in config.yaml
The plugin exposes two independent features. Turn on whichever you want in ~/.hermes/config.yaml:
Environment variables take precedence over the compresr: block. With an API key set and one of the switches above flipped, everything else is automatic.
3. Config reference
| Env var | Config key (compresr:) | Default | What it does |
|---|---|---|---|
COMPRESR_API_KEY | — (stored in ~/.hermes/.env) | — | Compresr API key (cmp_...). Without it the plugin stays inert. |
COMPRESR_BASE_URL | base_url | https://api.compresr.ai | Override for self-hosted / on-prem. |
COMPRESR_MODEL | model | latte_v2 | Context-engine model (latte_v1 or latte_v2). |
COMPRESR_TARGET_RATIO | target_ratio | derived from Hermes's compression.target_ratio | Context-engine ratio: a 0-1 fraction or an Nx factor. |
COMPRESR_TIMEOUT | timeout | 60 | Context-engine API timeout (seconds). |
COMPRESR_TOOL_OUTPUT_ENABLED | tool_output_enabled | false | Master switch for tool-output compression. |
COMPRESR_TOOL_OUTPUT_MODEL | tool_output_model | toc_latte_v2 | Tool-output compression model. |
COMPRESR_TOOL_OUTPUT_MIN_TOKENS | tool_output_min_tokens | 1500 | Skip tool outputs smaller than this (avoids latency on trivial results). |
COMPRESR_TOOL_OUTPUT_TARGET_RATIO | tool_output_target_ratio | 2.0 | Tool-output Nx compression factor. |
COMPRESR_TOOL_OUTPUT_TIMEOUT | tool_output_timeout | 30 | Tool-output API timeout (seconds). |
COMPRESR_TOOL_OUTPUT_MAX_CACHE_MB | tool_output_max_cache_mb | 256 | Cap on the on-disk recovery cache (LRU-pruned). |
4. What gets compressed
The plugin compresses two things, each independently:
(1) Conversation context. When Hermes hits its compaction threshold, instead of asking an auxiliary LLM to summarize the mid-conversation window, the Compresr context engine sends it to latte_v2 query-aware and folds the prior summary back in for continuity. Head and tail turns are protected by Hermes's own pruning; only the middle window is compressed. If the call fails, Hermes aborts compaction and preserves the transcript verbatim (30-second cooldown) — it never inserts a lossy placeholder.
(2) Tool outputs. As each tool result arrives, if it is at least tool_output_min_tokens (1500 by default), it is compressed with toc_latte_v2 before it reaches the model. The compression query is derived from the tool's own arguments — a query, pattern, command, url, or file_path — so the kept content is the part relevant to why the tool was called, not a generic summary. The verbatim original stays recoverable (see below).
5. Nothing is lost — tool-output recovery
Every compressed tool output ends with a recovery footer, for example:
The original output — with secrets and PII masked (see Security) — is written to a content-addressed file under ~/.hermes/cache/compresr/tool-output/, so the agent can recover the full detail that was summarized away using an ordinary read_file or search_files; no special API is needed. The cache is LRU-pruned to tool_output_max_cache_mb.
6. Security
Before anything leaves the process — and before it is written to the recovery cache — the plugin redacts secrets and PII from tool outputs and compression queries (PEM keys, sk_/pk_/cmp_ tokens, GitHub/Slack/AWS/GCP tokens, JWTs, URI credentials, and emails). The Compresr base_url is SSRF-validated: non-HTTPS endpoints (except localhost), cloud-metadata hosts, and private IP ranges are rejected.
7. Observability
/compresrin any session prints live stats: calls, tokens saved, errors, and recoveries.- Every compression call is tagged
source: integration:hermes, so usage and spend are attributable in your Compresr dashboard. - On a permanent configuration error (an invalid model or key), the affected feature disables itself loudly with an actionable message instead of retrying silently.
When this helps
- Long agentic sessions: context compaction and repeated large tool outputs are the two biggest token sinks in a multi-hour Hermes run — this targets both.
- Big tool outputs: file reads, shell output, search dumps, and code-execution results are shrunk to what the current step needs, with full recovery on demand.
- Zero workflow change: flip a switch and keep working — the agent behaves the same, just with a shorter, cheaper context.