Epitype

繁體中文

You wrote the rule in CLAUDE.md. The agent still did something else.

You settled a decision three days ago. Today the agent answers from the version you replaced. One compaction later, a rule you put in the instruction file might as well not be there.

Epitype is the small layer I built for that. It runs on the hooks Claude Code and Codex already have, leaves your existing memory files where they are, and adds the part those files cannot do on their own: getting the right note in front of the agent at the moment it matters, and keeping the wrong one out.

It is Python standard library only. No service to sign up for, no model calls of its own, nothing to pay for.

Where you actually notice it

You rejected an approach on Monday. On Thursday the agent proposes it again. The Stop gate holds that reply back and hands over the ruling that closed the question, with its date and who made it.

A file write is about to commit a line that contradicts a settled rule. The write gate stops the content before it lands and writes one audit row, so later you can ask what was blocked, how often, and whether the rule is doing more harm than good.

The context gets compacted in the middle of a task. The next turn opens with the path to a recovery map written just before the compaction, so the agent can go read what was actually said instead of reconstructing it.

None of this is a new place to keep things. All three run on notes already sitting in the vault your host reads.

Install

You need Python 3.11 or newer and a Claude Code or Codex install with hook support.

pip install epitype

The epitype command covers installation, search, lint, exam and diagnostics. epitype-graft still works as an alias for the installer. The @hungyu/epitype package on npm is only a signpost back here; npm rejects the bare name as too close to an existing package.

Preview what the installer would change:

epitype install --dry-run

If the preview lists only the hosts and paths you expected, install and run the synthetic health check:

epitype install
epitype doctor

The installer looks for native vaults you already have. If there are none it creates an empty one. Reinstalling keeps a vault list you curated; run epitype vaults --resync --dry-run and then without --dry-run when you do want the latest detection result.

Who it is for

Worth a try if you already run Claude Code or Codex against a CLAUDE.md or AGENTS.md you maintain, you have watched an agent forget or reopen something you settled, and you want a record of what got stopped.

Probably not yet if you are new to CLI agents and have no accumulated rules to govern, or if what you actually want is something that refuses dangerous commands. That last one is the host's job, not this one's: permissions.deny in Claude Code, execpolicy in Codex. Epitype gates content, never actions.

How it works

Epitype hangs off five host events and reads the same vaults your host already uses.

Injected memory is advisory. It cannot override system or developer instructions, bypass host permissions, or hand a tool any authority by itself. Hook output is capped at 10 KiB, and every hook has a ten-second deadline that fails open.

Capture: filed, or waiting for you

A trigger match proves a sentence looks like a ruling, not that anyone checked it. So capture files a sentence only when it fits one of three shapes: an arrow reply whose owner half opens with a short answer, a correction that opens the sentence, or a named first-person authorization. Everything else the rules still catch goes to <vault>/_drafts/captured_pending/YYYYMMDD/ instead. Not indexed, not recalled, waiting for a person.

Both kinds carry provenance: auto-captured and verified: false. Promotion means editing those fields (verified: true plus verified_by / verified_at) and moving the file, and a replay refuses to do it for you.

A verified: false card is authority for nothing. The Stop gate and the write gate both read cards that declare a decision_key, which a captured card never has. Recall leaves it alone too: a captured quote sits at the bottom reading level, so memsearch finds it when someone goes looking for the exact words, while the prompt hook injects cards only. The measured trade-off is in docs/FAILURE_MODES.md §32 and §41.

Beyond recall

Decisions that stay replaced

Decision cards carry a stable decision_key, a status of active or superseded, an effective time, and a named source. One card is active per key. query, recall and the prompt hook drop superseded cards by default and keep them for provenance. Ask for --include-superseded when you actually want the history.

Scars, and what really stops an action

A scar is a rule born from an incident: the incident it came from, plus advice that names the safer route. A card is context read back into a turn. It is not a refusal and it cannot stop a tool call. Treating a lexical match as a blocker produces false denials and false confidence at the same time. Irreversible actions belong to the host's own rules, which refuse the call before it runs: permissions.deny in Claude Code, execpolicy in Codex. Epitype refuses content only, at the write gate and at the end of a turn.

An installer that leaves your setup alone

The installer merges only the entries it marks as its own, keeps the native vaults it detects, and backs up any host file before changing it. Stable shims mean you can move the repository without rewriting every registration. Uninstall takes back Epitype's own registrations and config and leaves native memory and vault cards untouched.

Tidying that happens on its own

The offline inventory pass, the dream, runs on its own. You never have to remember to start it.

By default (dream.mode: piggyback) a session start whose last dream is older than dream.interval_hours kicks off one detached, low-priority background run and returns without waiting for it. A lock carrying its pid, stale after 30 minutes, keeps a second one from starting. graft install --dream nightly [--at HH:MM] registers a daily system task instead, graft doctor shows the mode and the last completion, graft uninstall removes the task, and --dream off turns both off.

A run reads vaults and writes only inside <governance vault>/.epitype/ (review pack, state, log) within a ten-minute budget. On the way it harvests new material into drafts, and it never touches a card you already filed. The next session mentions it in one line.

The last section is the feedback review pack: one row per card that owner events, gate blocks or exam failures keep pointing at, raised once enough rows pile up (memspec.REVIEW_PACK_TRIGGER, 5) that a review sitting is worth holding. It judges nothing and edits nothing. No model is called, so an installed Epitype never spends your model budget while you are not looking.

When something breaks, you can see it

Missing indexes, stale indexes, shim failures, malformed cards and lock contention all end differently. Hooks fail open when they cannot finish safely, and the installer doctor reports recorded shim outages instead of reading silence as health.

epitype gates <vault> [--since Nd|YYYY-MM-DD] [--json] [--by kind|decision|session|day] turns a vault's _GATE_LOG.jsonl into a read-only report of what the gates actually blocked, by kind, card, day and session, and flags the same card blocking three times in one session as a likely false positive.

After installing

Approve Codex hooks

Registering a hook in Codex and trusting it are two different things. Check the real state after installing:

epitype trust

If an Epitype entry comes back UNTRUSTED, DISABLED or MODIFIED:

• In the terminal UI, type /hooks, press t to trust everything in the panel, then esc.
• In the Desktop app, open hooks need review or the Hooks panel and approve the Epitype entries for SessionStart, UserPromptSubmit, PreToolUse, PreCompact and Stop.

Run the check again. Codex is ready when it prints CODEX TRUST: PASS 5/5. doctor checks registration and synthetic execution, and does not replace this.

Choose a vault layout

Start from one of the tracked templates:

Search the local vault

Build the index once, then query it or recall against a prompt:

epitype search build C:\path\to\vault
epitype search query term --vault C:\path\to\vault
epitype search recall "natural-language prompt" --vault C:\path\to\vault

The database lives at <vault>/.epitype/memory_fts.sqlite3 and Git ignores it. Only build creates a missing index; an existing one refreshes incrementally when it goes stale. A missing index is reported as missing, not as a query that found nothing.

Command reference

epitype <command> --help prints the full option list for anything below.

Everyday

Maintenance and batch

Verify this checkout

From the repository root:

python tests/run_all.py
python tests/privacy_lint.py
python exam/exam_runner.py --strict

tests/run_all.py runs 50 component selftests across the core tools, hook adapters, package surface, installer, exam engine and privacy gate. The exam corpus in this repository is a small synthetic sample. The release gate for this version also passed a strict 330-case behavior corpus and two seed reviews, which are not part of this repository.

These checks are regression evidence. They are not proof that every future host version, or every way memory can fail you, is covered.

Moving or removing Epitype

After moving the repository, point the shims at the new path and check:

epitype relocate --to C:\path\to\new\repo
epitype doctor

Preview an uninstall before it removes anything:

epitype uninstall --dry-run
epitype uninstall

Read Uninstall Epitype before restoring a backup by hand.

Limits

• Hooks reach only the events and tools the host exposes. A direct file read stays outside the current-decision filter.
• Time and output ceilings force selection. Epitype never pushes a whole vault into a prompt.
• Epitype gates content, not actions. It never refuses a shell command or a read; irreversible actions are the host's to refuse. A malformed card fails open instead of taking the host with it.
• Claude Code and Codex are the tested boundary. A host upgrade still needs its own integration test.
• The bundled tests are synthetic. They exercise behaviour and failure handling, not months in the field.

Documentation

• Architecture: memory blocks, retrieval routes, decision cards, scar lifecycle, authority rules.
• Failure modes: symptoms, countermeasures, verification boundaries.
• Uninstall: ownership-aware removal and backup guidance.

Status

v1.3.0. Development happens in bursts rather than on a fixed cadence, so a quiet week is not an abandoned project. Issues get read, and an issue is the fastest way to move a fix up the queue.