Hermeneutic

Stop correcting the same agent mistake twice.

Mine corrections from your AI work logs, bring relevant lessons into the next task, and check outgoing claims before they ship.

by Hermes Labs

PyPI · Try the gate · Use your corrections · Integrations

Your agent says a feature is done before it has checked the work. You correct it. A week later, another session makes the same claim. Hermeneutic gives you two ways to close that loop: a fixed, fast draft gate for risky wording, and personal correction memory that retrieves past guidance when a similar task comes up. Either part can be used on its own.

Try the gate

Requires Python 3.10+. This first check needs no account, model, logs, or configuration:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install hermeneutic==0.1.14
printf '%s\n' 'Done — shipped 14 files, all tests pass.' | hermeneutic gate

The gate reports RISK for the precise completion and “all tests” claims and exits 1. Try printf '%s\n' 'Draft ready for review.' | hermeneutic gate to see a PASS (exit 0). For a real draft, use hermeneutic gate --draft response.txt. Unreadable or non-text input exits 2.

The check highlights English wording that needs a closer look. It cannot tell whether a claim is true. You decide whether to revise, verify, or send the draft.

Experimental language support

From this source branch, the draft gate supports Korean (ko), Chinese (zh), Japanese (ja), Turkish (tr), German (de), French (fr), Spanish (es), and Portuguese (pt) through trigger mapping. Local phrases map to the triggers the same English gate already checks. This is not translation or a separate set of risk rules, and it adds no model calls or runtime dependencies. The pinned PyPI release above does not include these adapters yet.

python -m pip install -e .
printf '%s\n' '5개 파일을 수정했습니다.' | hermeneutic gate --lang auto
hermeneutic gate --draft response.txt --lang zh

The CLI keeps its English default. --lang auto uses script and vocabulary hints; select a code explicitly for ambiguous or short text. Japanese kana is checked before Chinese Han characters; kanji-only Japanese needs --lang ja. Shared Spanish/Portuguese vocabulary may fall back to English. One adapter is selected per draft, so multilingual mixtures may need explicit selection. Shipped response hooks enable automatic mapping before the gate. Their existing advisory/retry behavior remains host-specific.

For Python callers, hermeneutic.lang.risk_score(text, lang="auto") returns hits with spans and matched snippets in the original draft. Router(lang="auto") enables mapping at stage 1 while downstream reviewers and repairers receive the original text. hermeneutic.risk_score and the default Router remain English-only.

Synthetic development-set results, replayed with explicit language selection:

A catch means any gate hit, including a low-severity advisory. These are small synthetic development sets, not held-out measurements or real-use coverage estimates. Automatic Korean routing catches 111/180 (61.7%) with 4/135 (3.0%) false fires; the other fixture results match explicit routing. See the validation methodology and replayable receipt for misses and limitations.

Use your corrections

For a fictional agent correction → saved episode → later evidence replay, start with the five-minute developer demo. It needs no personal logs; retrieval explicitly requires local Ollama. The demo ships with inspect and offline recall in this release.

If you have Claude Code session logs, mine correction episodes, group the recurring types, and build a local retrieval index:

hermeneutic mine ~/.claude/projects --format claude-code \
  --glob '**/*.jsonl' --out ~/.hermeneutic/triples.jsonl
hermeneutic bucket ~/.hermeneutic/triples.jsonl
hermeneutic inspect ~/.hermeneutic/triples.jsonl --limit 3
ollama pull nomic-embed-text
hermeneutic compile-index --triples ~/.hermeneutic/triples.jsonl
hermeneutic compile 'Finish the release and report what passed.'

The last two commands need Ollama running locally. If your logs contain a relevant correction, compile can return a short advisory preamble grounded in those past episodes. An empty result is possible when no match clears the threshold. The worked example shows the full path from a real correction to retrieved guidance. Codex and OpenAI message logs are also supported; see hermeneutic mine --help for the input formats.

Mining reads the paths you supply and stores local JSONL records. It does not silently teach new rules to the fixed gate. Retrieval uses local embeddings; it does not use Ollama to generate the guidance text.

Inspection rejects records larger than 1 MiB and non-standard JSON constants, escapes diagnostic paths, and rejects file changes observed during reading. Finish concurrent writers before inspection; this is not a transactional lock.

Before indexing, inspect validates the complete existing JSONL file and emits at most five preview records by default; --limit accepts a positive record count. Each JSON preview includes its source line, session (up to 128 characters), timestamp (64), and correction (160), with explicit truncation flags. Prior/next assistant messages and the original prompt are omitted. Malformed records produce a line-specific error and exit 2 without partial preview output. Inspection reads the file without modifying it and needs no network connection or Ollama. Previews can still contain private text; review them before sharing.

Where it fits

Use the standalone CLI in any workflow you control. The integration guides cover optional Claude Code, Codex, Gemini CLI, Qwen Code, OpenClaw, Hermes Agent, and other host paths. Integration capabilities vary by host; check the individual guide before expecting automatic gating or blocking. The Python Router is available if you want to compose your own review stages.

Hermeneutic's gate matches fixed English surface patterns and can miss a mistake or flag an innocent phrase. Correction retrieval depends on the history you supply and has not been shown to improve downstream outcomes across users. It is a way to surface previous guidance and scrutinize a draft, not a security boundary or a factuality guarantee.

Worked example · Integration guides · Evaluation results · Privacy and security · Contributing · Changelog

Apache-2.0. Hermes Labs builds agentic infrastructure for autonomous systems.