v1.10.1

Epitype 1.10.1 is a packaging-metadata release. There are no code changes from 1.10.0; see the 1.10.0 release notes for this round's features and fixes.

• The PyPI project page now links to the changelog and to the GitHub releases.
• The npm package @hungyu/epitype now includes CHANGELOG.md and links to the project homepage and issue tracker.

Install or update with python -m pip install --upgrade epitype.

Verified release evidence:

• Release workflow: 152/152 source-suite entries passed, distribution metadata checked, and the exact installed wheel exercised outside the checkout.
• PyPI 1.10.1: the wheel and source archive have the same SHA-256 hashes as the GitHub release assets, and the project page lists the Changelog and Releases links.

v1.10.0

Epitype 1.10.0 makes rule synchronization tolerate individual broken cards, shrinks generated rule text, and adds two maintenance commands: an index of the owner's own words and a nightly duplicate-card report. It retains the existing native-memory architecture and Python-standard-library dependency footprint.

• Isolate host sync failures per card. A card whose source cannot be matched keeps its last approved output and is listed in the report; other cards continue to sync. Generated rules are bound to their rule text and scope, so editing descriptions or aliases no longer requires re-approval, while changing the rule text still does.
• State repeated source notes once in generated rules and recall instead of before every rule. On the maintainer's vaults the generated rule files shrank by roughly a quarter to a third; per-rule exceptions are kept.
• Add epitype owner-index build|update|find: an incremental SQLite full-text index of the owner's own messages and selected question-box answers, with locators back to the source transcript. Replayed history, screen context and attachment lists embedded in AI transcripts are excluded. Extra transcript folders can be added with the owner_index_extra_roots configuration option.
• Add epitype dupes: a nightly cross-vault near-duplicate report (MinHash). Verdicts can be recorded with --judge; judged groups are not reported again unless a card body changes.
• Fuse recall ranking across BM25, aliases, one-hop card links and dates. Source offsets are prepared during the nightly run so hook-time recall avoids slow transcript scans for new or edited cards.

The duplicate detector is deliberately broad and reports candidates for review; it never edits or deletes cards. Recall ranking was compared on a fixed local question set before and after the change; the public tests use synthetic fixtures only, and these local measurements are not a claimed benchmark against other memory tools. Delivered context does not guarantee model compliance.

Install or update with python -m pip install --upgrade epitype. Existing source checkouts and hook registrations must be checked separately: a published package alone does not switch a host away from a configured source checkout.

Verified release evidence:

• Release workflow: 152/152 source-suite entries passed, distribution metadata checked, and the exact installed wheel exercised outside the checkout.
• Cross-platform CI: Windows/Linux on Python 3.11 and 3.13, plus the installed-wheel job, all passed.
• PyPI 1.10.0: the wheel and source archive have the same SHA-256 hashes as the GitHub release assets.

The first tagged build failed six suite entries; they were fixed before anything was published. Three were product regressions now corrected: a quieted card promoted to a behavior rule was skipped again by a recall pre-filter, a self-closing image tag in a transcript could swallow the owner's following words in the owner index, and a status or successor edit with unchanged rule text skipped successor validation.

v1.9.2

Epitype 1.9.2 corrects cases where cached delivery decisions could hide current instructions. It retains the existing native-memory architecture and Python-standard-library dependency footprint.

• Reconsider a quieted information card when it becomes a behavior rule. Only matched quiet candidates require the additional eligibility check.
• Deliver updated tool advice again for the same target while retaining deduplication for unchanged text and retry after failed output.
• Attribute recall-usage statistics to the originating vault, so identical filenames in different projects do not share counts. Ignore legacy unscoped derived caches; preserve all memory cards.
• Keep quiet lists unchanged when usage evidence is truncated, unreadable or lacks a resolvable vault. Report this coverage separately so other compliance replay can continue. This usage metric currently covers Claude transcripts; the separate delivery/compliance ledger covers both hosts.
• Correct stale architecture descriptions and clarify context cost. Add an evidence-based product overview and related-work comparison, including native memory, claude-mem, mcp-memory-service, ClawMem and Graphiti.

The improvement is lifecycle correctness, not a claimed benchmark win over other memory tools. Source binding does not establish semantic authorization, and delivered context does not guarantee model compliance. Tests use synthetic local fixtures; no new model calls or external memory service were introduced.

Install or update with python -m pip install --upgrade epitype. Existing source checkouts and hook registrations must be checked separately: a published package alone does not switch a host away from a configured source checkout.

Verified release evidence:

• Release workflow: 143/143 source-suite entries passed, distribution metadata checked, and the exact installed wheel exercised outside the checkout.
• Cross-platform CI: Windows/Linux on Python 3.11 and 3.13, plus the installed-wheel job, all passed.
• PyPI 1.9.2: the wheel and source archive have the same SHA-256 hashes as the GitHub release assets.

Ongoing maintenance uses Codex to review upstream hook changes, reproduce issues, inspect source/scope handling, add focused regressions and prepare tested releases. Epitype is an early-stage project; these engineering checks are not evidence of broad independent adoption.

v1.9.1

Why Epitype exists

Long-running coding work needs more than remembering a fact: a maintainer needs to know who issued an instruction, which project it applies to, whether a later decision replaced it, and what remains after context compaction. Epitype adds this instruction-governance workflow to the native memory files and hooks of Codex and Claude Code.

For example, a project-specific approval should retain its original scope when recalled in another session; an AI proposal should retain its authorship; a replaced rule should remain available as history without being presented as the current decision. These are the problems Epitype's source binding, decision lifecycle and host adapters address.

Related work and the difference in focus

The following comparison describes documented capabilities reviewed on 2026-10-21. These tools solve overlapping problems; it is not a performance ranking or a claim that no other project implements similar features.

Existing approach	Documented overlapping capability	Epitype's focus
Codex native memory and Claude Code memory	Persistent notes, memory generation and context loading	Keep native storage and loading; add source-bound instruction lifecycle management across both hosts.
claude-mem	Activity capture, model-assisted compression, retrieval and context injection across supported coding tools	Govern the authority, scope and lifecycle of instruction cards already held in native vaults.
mcp-memory-service	Persistent retrieval, hooks, contradictions and supersession	Bind rule content and execution fields to original conversation records and reviewed scope.
ClawMem	Context retrieval, source metadata, decision conflicts and compaction continuity	Connect instruction provenance with managed native settings and transcript recovery.
Graphiti	A temporal knowledge graph with episode provenance, changing facts and hybrid retrieval	Manage coding-agent instructions in existing file-based vaults without adding a graph database or model calls of its own.

Epitype's differentiating emphasis is the combination of these mechanisms in one local Codex/Claude workflow:

• Original-source binding: check message identity, role, quotation, scope metadata, complete rule payload and supersession links through a shared rule pipeline. AI-authored text remains AI-authored even when approved.
• Managed native settings: render supported host settings from the same cards, track ownership and withdraw managed entries while preserving unrelated settings. Native host permissions remain the enforcement mechanism; see host_native.py.
• Recoverable context: provide original-transcript pointers and handoffs after host compaction, alongside selective recall of current cards.
• Small deployment footprint: MIT licensed, Python standard library only, local files, no model calls by the package. Injected context still consumes the host's context budget.

Evidence and maintenance use

PyPI 1.9.1 and the passing Windows/Linux release CI provide inspectable delivery evidence. The code and provenance contract document what is checked. Source hashes do not prove semantic authorization, and hook delivery does not guarantee model compliance. No comparative recall-quality, cost or end-to-end superiority result is claimed.

The project is at an early adoption stage. Codex supports concrete maintenance work here: reviewing native-hook compatibility, reproducing regressions, reviewing source-validation changes and maintaining cross-platform releases. The intended ecosystem contribution is a reusable instruction-governance workflow for maintainers using long-running coding agents.

Release changes

Epitype 1.9.1 includes the accumulated changes since 1.8.1, plus portability and documentation corrections found during release validation.

• Synchronize supported native Claude and Codex settings from source-bound cards while preserving unrelated settings and handling invalid cards individually.
• Keep AI workflow checks advisory by default; retain explicit action and credential safety boundaries. Stop records findings for the next prompt instead of withholding or restarting replies.
• Improve original-source validation, author attribution, successor recall, host synchronization and compaction restoration.
• Correlate tool receipts, target identity and sequence evidence without treating missing evidence as a confirmed violation. Historical replay preserves recorded Windows and POSIX paths across hosts.
• Reduce repeated card reads, reuse verified provenance origins, and bound context and token reporting work.
• Detect Bash constructs that execute document text and check automatically backgrounded commands before subsequent work.
• Run stable hook adapters in the current interpreter and preserve valid earlier Codex compaction settings.
• Correct both READMEs to describe unpublished starter templates, advisory findings and explicit action guards. Make concurrency fixtures synchronize before actual claims and resolve Windows temporary path aliases.

The distribution contains product code and synthetic examples. It does not include the maintainer's personal memory vaults or local evidence corpus.

Python 3.11 or newer is required. The npm package is a pointer to the Python project and is published separately.

v1.8.1

Epitype v1.8.1

Patch release for the browser lifecycle ledger and an optional Claude plugin source package.

Changes

• Serialized first-time SQLite schema setup so concurrent hooks do not race on a new browser lifecycle ledger. Initialization errors now close the database connection, including on Windows. Existing unversioned ledger records are preserved.
• Added claude-plugin/, the static Epitype Essentials companion with three skills: verify completion, stage Git changes safely, and report status clearly. It reads no chat history, memory, credentials, or browser data and does not install the Epitype runtime or hooks. The Claude Directory submission is under Anthropic review; this source package is available now.

Install

pip install --upgrade epitype==1.8.1

The optional CLI package is also versioned as @hungyu/epitype 1.8.1 in this source tree; npm registry publication is separate.

Verification

The complete local component suite passed 83/83 on the database fix, including the concurrent ledger regression. The cold concurrent case passed 20 repeated runs. GitHub Actions on the exact v1.8.1 tag passed on Ubuntu and Windows with Python 3.11 and 3.13, plus the installed wheel smoke test.

v1.8.0

Epitype v1.8.0

Epitype helps Claude Code and Codex bring the right memory card into a working session and enforce the rules attached to it. This release improves recall, background maintenance, and the clarity of hook feedback.

What changed

• More useful recall: Claude Code and Codex receive bounded excerpts from relevant cards. When Epitype has only a file reference, it says that the original card still needs to be read.
• Resumable maintenance: The scheduled Dream run resumes from its last successful checkpoint. An incomplete scan is reported as incomplete instead of advancing the health checkpoint. Host synchronization and the review packet run before the expensive history pass.
• Browser cleanup reminders: Epitype records when an agent creates and closes an in-app browser tab or control session, then reminds the agent if one remains open. It does not record page URLs or content, and does not close pre-existing user tabs.
• Clearer hook feedback: Stop rules now distinguish a negated statement from a real proposal to weaken a check. Messages shown to the user focus on the required correction; browser cleanup reminders go to the agent rather than appearing as user-facing Hook feedback.
• Release portability: Self-checks cover Windows console encoding, Python 3.11 subprocess behavior, and the hook's PowerShell timeout path.

The included epitype starter command can add five general-purpose memory cards for a new user. These starter cards were introduced in v1.7.0 and remain available in v1.8.0.

Install or upgrade

Requires Python 3.11 or newer and Claude Code or Codex with hook support.

python -m pip install --upgrade epitype
epitype install
epitype starter
epitype doctor

epitype starter is optional. Read the English setup guide or 繁體中文說明 before adding hooks or starter cards.

Verification

The v1.8.0 CI run passed on Ubuntu and Windows with Python 3.11 and 3.13. The wheel and source archive are attached below and published on PyPI.

Full changelog

v1.7.0

Full Changelog: v1.6.2...v1.7.0

v1.6.2

Full Changelog: v1.6.1...v1.6.2

v1.5.0

v1.5.0

The last release made cards able to stop things. This one asks the next question: are they stopping the right things, and is stopping worth what it costs?

Seven days of real use answered it badly. One guard refused 147 real commands, and 136 of them (93%) were mistakes. Of 105 blocked turns, 19 were about wording or length — and because the host shows the assistant's text before the end-of-turn hook runs, blocking those took back nothing and only forced a second round. Rules meant to save tokens were spending them.

Blocking only when blocking buys something

• on_hit: note — the rule still matches and is still recorded, but the turn is not blocked; the violation is attached to the next prompt as one short line. Wording and length rules now use this. Blocks and notes are counted separately in the nightly report.
• Repasting a blocked turn is no longer blocked. By the time that fires, the duplicate is already on the reader's screen. "Add only what was missing" moved into the first block's reason — the only moment it can prevent anything.

Seeing what a rule actually does

• python -m epitype.compliance --samples <vault> [--card NAME] [--days N] replays recent real conversations and prints, per rule, the sentences it fires on. Author-written examples only test what the author imagined; the first run exposed several rules that were wrong most of the time, and a disagreement between the nightly replay and the live gate (when the evidence was a quotation, the gate passed it and the replay counted it as a miss). Both now read it the same way.
• An old state card says how old it is. A project card recalled after 30 days is prefixed with its age, so a status from three months ago no longer looks like today's. Decisions and lessons are never marked — they do not expire with age, and a mark on every line is a mark on none.
• A host registration that has fallen behind the code is noticed nightly. Code changes take effect immediately; hook registration only changes when the installer runs, so a machine running from a checkout could silently stop calling a new hook.

A first install that is not empty

• epitype starter writes five general rules into your vault: stage explicit paths instead of the whole tree (Bash and PowerShell), a completion claim must carry its evidence, no hedged completion, and no filler openers (as a non-blocking note). Each ships with both must-block and must-allow examples, checked by the gate's own code. It never overwrites a file you have, and --remove only takes back the ones you never edited.
• Gate messages in English or Traditional Chinese. A fresh install picks by OS locale; language in ~/.epitype/config.json or EPITYPE_LANG overrides it. Patterns, field names and what the gates match on are unchanged — only displayed text.
• README now shows the thing refusing something, the real doctor output, where your data goes (nowhere: no network calls, no telemetry, and the gate log holds rule names and timestamps but never message content), and how this compares to memory summarisers and hook toolkits.

Rule corrections, driven by replaying real blocked sentences

A completion claim now accepts a commit hash or a line-by-line check as evidence. "Todo list" only fires when a list is actually being listed. A correction rule no longer fires on the noun form or on plain agreement. "Never happened" only fires when the claim is about the speaker's own past work. A ratio rule no longer reads dates as ratios. A "no lowering the bar" rule no longer reads a denial as an admission. The subagent-report rule was retired in favour of the fact-based check that asks whether anything was verified after the delegation returned. The week-long "name the files you read" trial was ended early: the hard check already covers it, and the rule only asked every report to carry one more line.

Also

The latency tool measured against the real vault and wrote a fake block row on every run — 38% of the gate log was its own noise; it now measures a scratch copy. The heredoc guard narrowed to the one case that actually corrupts a file.

Full Changelog: v1.4.0...v1.5.0

v1.4.0

v1.4.0

Until now a memory card could only be read. On 2026-09-16 the same heredoc mistake was made four times in one conversation while three cards about it sat in the vault, were recalled, and were read by the model. Delivery is not enforcement. This release makes cards able to stop things.

Cards that bind

All three forms are literal matching; nothing reads intent.

• forbidden: patterns checked against what the model is about to say at the end of a turn. A hit sends the turn back to be rewritten.
• require_when + require_text: for "only say it once you've done it" rules. A completion claim without the required evidence text in the same message is blocked.
• guard_tool + guard_all_of: a tool call whose text contains every listed fragment is refused. An equivalent command written differently gets through; this guards against repeating a known mistake, not against a determined user.

It checks itself at night

The gates run while you wait, with deadlines, per-call read caps and fail-open errors, so they will miss things silently. epitype/compliance.py replays the day's transcripts overnight with the gates' own matching code, reconciles against the gates' audit log, and feeds the result back into card ordering. It produces nothing for a person to read.

What cannot be told apart is counted instead: a short violating sentence in quotes looks exactly like a genuine citation, so every quote exemption writes an audit row and the nightly reports quoted_exemptions.

Rules reach the agent, and come back out

epitype sync writes rules generated from cards into ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md, between markers only. It refuses on broken or duplicated markers, stops when a block holds text it didn't write, backs up before writing, and says out loud when it replaces content it cannot recognise, including on the unattended nightly run. graft uninstall removes the blocks, deletes files it created itself, and names every backup it leaves behind.

Found by review, not by the author's tests

The author's suite was green when four independent reviews ruled "do not release". Six rounds in total. Among what they reproduced:

• Auto-allowlisting a literal pattern's hit string disabled the whole rule for 90 days. It now allows only that one message's digest.
• Automatic demotion is gone. A rule with 6 hits, all 6 blocked, was switched off for 14 days, including a safety guard. Hit rate cannot tell "too broad" from "keeps being broken".
• A per-call card cap applied to enforcement as well as discovery: 500 armed cards, 12 live per turn. The cap now bounds discovery only.
• The documented install form skipped host sync entirely and still reported success.
• Isolated acceptance runs deleted a real nightly scheduled task, twice. Unscheduling now requires that the home was actually on nightly.

Upgrade

1. pip install -U epitype
2. epitype install
3. epitype doctor should print HEALTH 5/5

Full list: CHANGELOG.md