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, with no required service and no model calls of its own. Injected context still uses the host's context budget.

Its focus is instruction lifecycle: bind rules to original sources and scope, keep replaced decisions out of current recall, manage supported native settings across both hosts, and retain transcript pointers after compaction. Native memory remains the underlying store. See product scope and related work for the overlap, differences and evidence limits.

Start with templates for review

pip install epitype
epitype install
epitype starter

The five shipped templates are AI-authored examples without verified original sources. epitype starter puts them under _drafts/starter_templates/; installing them does not activate rules. Review any rule you adopt and bind it to its actual source before publishing it in your vault. See rule provenance.

Stop findings are reminders for the next prompt in the same session. They do not withhold a reply, request a rewrite, or start another model turn.

Where you actually notice it

You rejected an approach on Monday. On Thursday the agent proposes it again. Stop records the matching finding and queues a reminder with the relevant card for the next prompt in that session.

PreToolUse supplies advisory findings about writing and attribution. Explicit action guards and retained safety checks can deny a matching action; those boundaries are distinct from ordinary workflow reminders.

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 a security boundary around dangerous commands. That one is the host's job: permissions.deny in Claude Code, execpolicy in Codex. Epitype can deny a tool call whose text carries the literal fragments a scar card names, but an equivalent rewrite gets through — it is a guardrail against repeating a carded mistake, not a control that holds against someone trying to get past it.

How it works

Epitype reads the same vaults your host already uses, through these host events and the corresponding SubagentStop handler.

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.

Browser tracking stores resource IDs, not URLs, titles or page content. It only treats resources recorded as created by this agent session as its own; unclear ownership stays unverified. See Browser resource leak detection.

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. Most cards are context read back into a turn and refuse nothing.

A card's forbidden patterns identify wording the owner ruled out; require_when with require_text identifies a claim missing the required evidence. At Stop these findings are advisory. An explicit action guard using guard_tool with guard_all_of can deny a tool call whose text contains every literal fragment the card names, according to its on_hit setting. Literal matching does not parse shell syntax or infer intent.

fence_shell (powershell, bash or sh) checks tagged shell blocks with that shell's parser, without executing them. Syntax findings at Stop are also advisory. powershell means Windows PowerShell 5.1 (powershell.exe); untagged blocks are not checked. A missing, slow or broken parser does not block the turn.

That last one was removed in 2026-09-09 and restored on 2026-09-16, after the premise behind removing it was tested and failed: Claude's Bash permission patterns match positionally and have no AND operator, so four of nine hazard classes moved to the host and five could not be expressed at all. A literal conjunction over-approximates toward denial, which is the safe direction, and it is a guardrail against a mistake someone has already carded — not a security boundary. An equivalent rewrite of the same command gets through, by design.

Semantic judgement and genuinely irreversible actions stay with the host, which refuses the call before it runs: permissions.deny in Claude Code, execpolicy in Codex.

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, within a ten-minute budget, in three places: <governance vault>/.epitype/ (review pack, state, log and the gates' health file), the governance vault's MEMORY.md when its index has drifted, and — this one is worth knowing, because it happens unattended — the marked blocks inside ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md, so a rule you changed in a card is in front of the agent by morning without you remembering a command. Only the text between those markers is touched, the file is backed up first, and epitype sync --remove (or graft uninstall) takes the blocks back out. 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.

What a healthy install looks like

epitype doctor feeds a synthetic event to every hook and reports what answered:

HOSTS: claude, codex
SHIM RESOLUTION: PASS 5/5 repo_root=C:\Epitype\repo
REGISTRATION claude: PASS 6/6
REGISTRATION codex: PASS 6/6
HOOK SessionStart: PASS (515 ms)
HOOK UserPromptSubmit: PASS (369 ms)
HOOK PreCompact: PASS (297 ms)
HOOK PreToolUse: PASS (301 ms)
HOOK Stop: PASS (287 ms)
HOOK SubagentStop: PASS (268 ms)
HEALTH PASS 6/6

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.

Language

Every message a gate shows you comes in English or Traditional Chinese. A fresh install writes "language": "en" into ~/.epitype/config.json, unless your OS locale is Chinese, in which case it writes "language": "zh-TW". Edit that field to switch, or override it for one run with the EPITYPE_LANG environment variable (en or zh-TW), which wins over the config file. A config without the field behaves as zh-TW. epitype doctor prints the active setting on its LANGUAGE: line. The switch changes displayed text only — patterns, field names and what the gates match on are the same in both languages. Your cards stay in whatever language you wrote them in.

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 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.

Where your data goes

Nowhere. Epitype makes no network calls: there is no import of urllib, http, socket or any HTTP client anywhere in the package, and no telemetry, account or key. Your cards are Markdown files in your own vault directory; the search index is a local SQLite file that can be deleted and rebuilt. The gate log records rule names and timestamps — never message content.

How it compares

• claude-mem summarises sessions so the agent remembers more. Epitype keeps source-bound rulings, checks findings and supplies reminders.
• claudekit and similar hook toolkits give you building blocks to wire up. Epitype connects cards to recall, advisory checks and explicit action guards.
• A CLAUDE.md / AGENTS.md kit gives the agent more text to read. Epitype generates that resident block from your rule cards, then checks at the end of the turn whether the rule held.

They compose: nothing here stops you running a memory summariser alongside it.

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.
• Workflow findings and Stop checks are advisory. Explicit action guards and retained safety checks may deny a matching tool call. Epitype is not a complete security boundary; irreversible-action permissions remain the host's responsibility. Malformed cards fail open.
• 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.
• Browser resource tracking: what Epitype records, reminds about and leaves unverified.
• Failure modes: symptoms, countermeasures, verification boundaries.
• Uninstall: ownership-aware removal and backup guidance.

Status

v1.8.1, released 2026-09-28. Releases are cut when a batch of fixes is ready rather than on a fixed date. Issues get read, and an issue is the fastest way to move a fix up the queue.