Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Hermes Agent

Contexere plugs into Hermes twice: a plugin on the hook path, and the MCP server.

layermechanismwhat changes
hooks~/.hermes/plugins/contexere/__init__.py calling contexere --pre-hook, --post-hook, --session-startterminal tool output is distilled before it enters Hermes’ context
MCPmcp_servers.omni running contexere --mcpContexere’s MCP tools become first-class Hermes tools

Prerequisites

brew install fajarhide/tap/contexere
contexere --version
contexere doctor

export HERMES_VENV="${HERMES_HOME:-$HOME/.hermes}/hermes-agent/venv"
export HERMES_PY="$HERMES_VENV/bin/python"
"$HERMES_PY" --version      # 3.11 or newer

The venv Python is needed because hermes plugins enable runs inside it.

Install

contexere init --hermes
hermes plugins enable contexere
hermes gateway restart
"$HERMES_PY" -m pip install hermes-omni-plugin

contexere init --hermes is idempotent. It installs the plugin scaffold, registers the MCP server in ~/.hermes/config.yaml if it is not already there, enables Hermes compression when that is safe, and writes Hermes-oriented defaults to ~/.contexere/config.toml without overwriting an existing Contexere config.

Before 0.8.6 the plugin was named omni-signal-engine. contexere init --hermes removes that copy and, where plugins.enabled listed the old name, lists contexere in its place.

Use either hermes-omni-plugin or the contexere init --hermes scaffold, not both at once, or you get duplicate plugin registrations.

Config

# ~/.hermes/config.yaml

plugins:
  enabled:
    - contexere

mcp_servers:
  omni:
    command: "/opt/homebrew/bin/contexere"
    args: ["--mcp"]
    env:
      CONTEXERE_AGENT_ID: "hermes"

compression:
  enabled: true
  threshold: 0.50     # compress at 50% context usage
  target_ratio: 0.20  # keep 20%

Three things have to be true: plugins.enabled contains contexere, mcp_servers.omni points at the real binary, and compression.enabled is on so Hermes’ own compaction and Contexere’s pressure warnings line up rather than fighting.

CONTEXERE_AGENT_ID: "hermes" matters more than it looks. Without it, Hermes’ rows blend with every other host’s and no figure about either is meaningful.

Verify

contexere doctor

hermes plugins list | grep contexere   # expect: listed as enabled
hermes tools list | grep mcp_omni_     # the advertised set, after a restart

Then a functional check on a real fixture:

cat tests/fixtures/cargo_test_500.txt | contexere --post-hook 2>&1 | head -20
# passing test lines stripped, failures preserved

For a live test, run something noisy through Hermes’ terminal tool (terminal("npm install", timeout=120)) and compare the tool result size against raw npm output. Confirm with contexere stats.

Read the list rather than a number written down. This guide has said 27, which came from grepping the server source and counted a filter name as a tool, and then 25, which is the whole surface and not what a host is told about. Hermes is a Full-tier host, so it is advertised contexere_retrieve and contexere_explain_savings, the two that pay for their place in the prefix of every request. CONTEXERE_MCP_TOOLS=all serves the whole surface.

Where Contexere helps and where it does not

outputContexere’s effect
npm install, cargo build, docker buildlarge, 70% and up. Progress, cache hits and layer hashes are pure ceremony.
test runslarge. The verdict and the failures survive, the ok lines do not.
file readsnothing from the filters, a great deal from the ledger on re-reads
kubectl -o json, terraform plansnothing, deliberately. Structured payloads pass through.
short commandsnothing, or slightly negative. The marker costs more than the saving.

Use the MCP tools as Hermes’ controls over all of it: contexere_explain_savings to see what a recent command actually cost, contexere_retrieve to get folded content back, and contexere_budget to see where the session’s tokens went. That tool is outside the set advertised by default, so it needs CONTEXERE_MCP_TOOLS=all.

After a Hermes upgrade

hermes plugins list | grep contexere
hermes tools list | grep mcp_omni_
contexere doctor

An upgrade can reset plugins.enabled or move the venv. Both fail quietly: the plugin simply stops being called, and nothing announces it.