Hermeneutic mines past AI agent corrections into guidance for new tasks

Hermes Labs has released Hermeneutic, a command-line tool that treats the corrections developers make to AI coding agents as reusable context. According to the project's announcement on dev.to, the tool reads existing agent conversation logs, extracts the moments where a user steered an agent back on course, and later resurfaces guidance drawn from those episodes when a similar task comes up.

The motivating example from the announcement: you ask an agent to review a function, it starts refactoring instead, and you pull it back to the review you actually requested. That exchange encodes information about your intended scope, but it normally evaporates when the session ends.

How correction mining works

Hermeneutic ingests logs from Claude Code, Codex and OpenAI-format sessions. It looks for a four-part pattern: the original request, the agent's reply, the user's correction, and the fixed follow-up. When it finds one, it records the surrounding exchange into a local corpus of records stored as JSONL.

A bucket command then groups the mined corrections into recurring categories — missed constraints, wrong targets, unnecessary confirmation and scope expansion — so you can inspect which failure modes show up most often in your own history.

From history to guidance

The corpus becomes useful through retrieval. Hermeneutic embeds a new prompt using Ollama's nomic-embed-text model and matches it against earlier prompts in the corpus. When matches clear a relevance threshold, the associated correction categories are rendered through templates into a short guidance preamble, and each advice bullet cites the correction records it rests on, so the advice stays traceable.

In practice, the announcement suggests, a release-related prompt might resurface your earlier instruction to cite command output when reporting completion, while a review prompt might resurface the guidance to respect the requested scope. An optional Claude Code hook can inject the retrieved guidance into the prompt automatically rather than requiring you to paste it manually.

Setup

The tool requires Python 3.10+ and a local Ollama installation. The workflow as documented on dev.to:

python -m pip install hermeneutic==0.1.12

hermeneutic mine ~/.claude/projects --format claude-code --glob '**/*.l' --out ~/.hermeneutic/triples.l hermeneutic bucket ~/.hermeneutic/triples.l

ollama pull nomic-embed-text hermeneutic compile-index --triples ~/.hermeneutic/triples.l hermeneutic compile 'Review this function and report your findings.'

The final command emits guidance for the given prompt only when matching corrections meet the relevance threshold. The optional hook is installed with hermeneutic install-compile-hook. The project is available on GitHub, and the announcement notes the post itself was prepared with the company's agent infrastructure from the README and documentation.

Why it matters

Corrections are arguably the densest signal in any agent workflow — they capture exactly where the agent misread your intent — yet most tooling throws them away with the transcript. Hermeneutic's bet is that this discarded material is a free, personalized source of context that grows more valuable the longer you work with agents.

The implementation also has properties worth noting for teams cautious about agent memory features. Everything runs locally: the logs, the mined corpus and the embeddings never leave the machine, which matters for proprietary codebases. And unlike opaque memory systems, the guidance is auditable — you can inspect what was mined with bucket, and every recommendation points back to the specific exchanges that produced it.

There are caveats. This is version 0.1.12 of an early-stage project, the details come from a single vendor-authored announcement rather than independent use, and the approach depends on having accumulated enough corrections for retrieval to find meaningful matches. Over time, a corpus can also go stale or overweight idiosyncratic preferences. Still, it is a clear example of a broader trend: memory and context layers built on top of coding agents, and a comparatively transparent, local-first take on it.