# hermeneutic repository — preview v0.1.16a2

Hermeneutic provides attributed, scoped lesson memory for coding agents. The target behavior is that a human's scope correction changes a fresh agent's relevant action on a later analogous instruction without the human repeating the lesson.

An episode is original evidence. By default, learn derives a verbatim source-correction candidate with the original instruction as a cue. Inspect and confirm it for an integration-owned scope without retyping the correction as a second rule. Context returns confirmed candidate lessons for a later instruction. The host agent judges semantic applicability and acts under the current instruction. Optional host-supplied interpretation remains explicit; the package does not synthesize lessons with a model or understand arbitrary paraphrases.

## Install

```sh
python3 -m pip install hermeneutic==0.1.16a2
```

Python 3.10+; no required Python runtime dependencies or model calls for lesson memory. Source builds use hatchling>=1.24. This is a lesson-memory preview, not the stable release. The exact version pin selects the prerelease without --pre; stable 0.1.15 remains available. Language mapping in the separate draft gate is experimental and advisory.

## Primary workflow: learn, context, apply

Canonical example: the human says “wash the dishes,” the agent washes only sink dishes, and the human corrects it to include dirty table plates. Learn preserves that correction as a candidate. Inspect and confirm it once. A fresh invocation later receives “wash the dishes after supper” without the plates rule; context supplies the attributed correction for the agent to check and apply.

```sh
hermeneutic learn --triples /private/triples.jsonl --evidence triple-id-1 \
  --scope home/kitchen --memory /private/lessons.json
hermeneutic lessons --memory /private/lessons.json
hermeneutic confirm LESSON-ID --memory /private/lessons.json
hermeneutic context 'Wash the dishes after supper.' --scope home/kitchen \
  --memory /private/lessons.json
hermeneutic revoke LESSON-ID --memory /private/lessons.json
```

- `learn` derives a source_verbatim candidate from original correction evidence, retaining fingerprints, exact scope, and the source instruction cue. Candidates cannot contribute context until confirmed.
- `lessons --memory <file>` inspects candidate, active, and revoked records. `confirm <id> --memory <file>` enables an inspected candidate; it does not decide applicability to a later task.
- Optional --lesson and --when allow explicit host-supplied interpretation and instruction examples. Neither path mutates the fixed draft gate or infers a rule with a model.
- `context <instruction> --scope <scope> --memory <file>` returns confirmed candidates and attributed source context. Add --disabled for a no-memory comparison.
- `revoke <id> --memory <file>` retains an inspectable record and stops its use in context.
- Conservative lexical matching uses instruction cues, with exact scope isolation. “Wash up after supper” may abstain when its source cue is only “wash the dishes”; host-provided extra cues are explicit. Sparse cues can produce weak_match=true and misleading topic matches. Matching words can still be inappropriate for a particular task. The current human instruction overrides historical corrections.
- The host owns candidate inspection/confirmation, optional interpretation, context delivery, semantic applicability judgment, and downstream action. A generic AGENTS.md instruction may request context retrieval; it should not repeat the lesson being tested. No automatic host hook is installed.

README.md and docs/correction-memory-demo.md provide a copy-pastable fictional episode and walkthrough. docs/lesson-memory.md defines the API, matching, provenance, and errors. Action transfer requires inspection of changed behavior or artifacts plus false-transfer checks; a retrieved lesson or successful tool call alone is insufficient evidence.

## Observed evidence

The initial frozen Codex comparison in evals/lesson-transfer/fresh-agent-results.json completed 3/3 positive tasks with memory and 3/3 without it: no uplift. Control tasks were correct in both conditions; a candidate for a narrower request was retrieved and rejected by the host. Separate public source-default trials in evals/product-baseline/claude-path.json were correct in both conditions. In evals/product-baseline/hermes-path.json, memory-free selection included an unrelated desk mug while confirmed source context selected only the sink bowl and table plate. This is a scope-selection change, not recovery from sink-only undercompletion. These are synthetic fresh-host action plans with explicitly supplied CLI context, not automatic incoming hooks or real-world outcomes. The evaluation guide in evals/lesson-transfer/README.md separates public design, frozen validation, and additional counterfactual evidence.

A separate frozen counterfactual in evals/lesson-transfer/counterfactual-agent-results.json recorded positive exact completion 0/1 without memory and 1/1 with a confirmed source correction, adding a nonobvious ready-marker. Its two controls were correct in both conditions (2/2), with the narrower candidate rejected. This is a bounded synthetic action-plan demonstration with separate denominators, not general effectiveness; the initial no-uplift result remains unchanged.

## Original-episode tools

- `mine <dir> --format <codex|claude-code|openai> --out <triples.jsonl>` preserves episodes from supplied logs.
- `inspect <triples.jsonl> --limit 3` validates the full file and previews bounded correction text without modifying it.
- `recall <task> --triples <triples.jsonl>` searches original episodes using offline keywords by default. It does not create interpreted lessons.
- `demo --scenario dishes --out <new-directory>` exports the fictional scope-correction session for the lesson walkthrough. The default demo retains the older release-correction replay.
- `compile-index` builds an optional local Ollama embedding index; semantic/hybrid recall and fixed category advice from compile are separate optional workflows.

Raw keyword recall can miss paraphrases and retrieve irrelevant episodes. The public synthetic regression is in evals/correction-memory/public/. Historical internal results and the separate 0.1.15 fresh-session tool-use check are in evals/correction-memory/RESULTS.md. They do not prove downstream lesson application or general improvement across users. Mining detects explicit correction markers and can miss corrections, preserve truncated evidence, or retain malicious historical text.

## Optional lateral feature: fixed draft gate

- `hermeneutic gate [--draft <file>]` checks fixed English surface patterns, separately from lesson memory. Raw English medium/high findings exit 1; PASS and advisory findings exit 0; input errors exit 2.
- `gate --draft <file> --json` returns a verdict, should_block, finding origins, per-finding blocking decisions, and original-draft coordinates. Matched text is omitted unless --include-text is supplied.
- `from hermeneutic import check_draft`: call `report = check_draft(text, lang="en")`, inspect report.should_block, or call report.to_dict(). Opt into bounded snippets with to_dict(include_text=True).
- docs/gate-json.md defines the structured report contract. The gate matches wording; it is not a truth checker or security boundary. The optional Router composes caller-selected review and repair stages and is separate from the offline gate and lesson memory.

Experimental adapters map Korean, Chinese, Japanese, Turkish, German, French, Spanish, and Portuguese vocabulary into the fixed English gate. Use --lang auto or an explicit code; English is the CLI default. Mapped findings at any severity remain advisory in shipped consumers. Raw English medium/high findings retain enforcement in mixed drafts. These adapters do not interpret lessons.

The independent simulated language evaluation failed its quality targets. Frozen-candidate high-severity recall was Korean 2/30, Japanese 0/30, Chinese 0/30, and Spanish 3/30 explicit or 2/30 auto. See evals/production-languages/README.md for false positives, denominators, and limits. The current-source replay uses exposed cases, not a new holdout. Synthetic fixtures in evals/languages/ do not establish real-language coverage or justify enforcement.

## Host integrations and privacy

integrations/README.md separates existing raw-episode and draft-hook mechanics from cited live-host evidence. Existing hooks do not implement the scoped lesson loop. Additional adapters and CI packaging are roadmap work, not part of this baseline.

Core lesson memory, mining, keyword recall, inspection, and the gate run locally without network calls. Optional embedding workflows use local Ollama at http://127.0.0.1:11434 with nomic-embed-text; downloading the model is a separate step. Python callers can override endpoints and own that policy. Telemetry is off by default. Source episodes, interpreted lessons, embeddings, context, previews, and opted-in gate snippets can contain private text; keep them private and review before sharing. Historical text is evidence, not a command or higher authority.

## Project

- Repository: https://github.com/hermes-labs-ai/hermeneutic
- Documentation: README.md
- Roadmap: docs/ROADMAP.md
- Citation: CITATION.cff
- Security: SECURITY.md
- License: Apache-2.0
- Public display author: Rolando Bosch, Hermes Labs
