epitype 1.0.0__tar.gz

epitype-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Epitype contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

epitype-1.0.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: epitype
+Version: 1.0.0
+Summary: Epitype is a memory governance layer for CLI agents.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/leavemagic-cyber/epitype
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Epitype
+
+[繁體中文](README.zh-TW.md)
+
+Epitype is a memory governance layer for CLI agents.
+
+It keeps the host's native memory as the storage authority, then adds the structure, timing, action gates, and evidence needed for remembered rules to affect later behavior.
+
+An agent can retrieve the right fact and still break the rule attached to it. Epitype focuses on that gap:
+
+- a replaced decision should not return as current;
+- an incident lesson should reach the tool action where it matters;
+- a permission should remain attributable to the person who gave it;
+- a memory failure should be visible and testable.
+
+Epitype currently supports Claude Code and Codex. It uses only the Python standard library and does not require a hosted memory service.
+
+## How it works
+
+Epitype connects the same native vaults to four host events:
+
+| Event | What Epitype does |
+|---|---|
+| `SessionStart` | Injects a bounded memory index and work ledger when those files exist. |
+| `UserPromptSubmit` | Recalls up to five relevant cards from each resolved vault within the shared output budget. Short owner-grant statements are stored verbatim, deduplicated, and indexed; their meaning is not inferred during capture. |
+| `PreToolUse` | Matches scar-card triggers against the tool and its input. A match returns a bounded denial, safer advice, and an audit row. |
+| `PreCompact` | Builds a small recovery map from the transcript tail before context compaction. |
+
+Injected memory remains advisory. It cannot override system or developer instructions, bypass host permissions, or grant a tool authority by itself. Hook output is capped at 10 KiB and each hook has a three-second fail-open deadline.
+
+## Governance beyond recall
+
+### Current decisions
+
+Decision cards have a stable `decision_key`, an `active` or `superseded` status, an effective time, and a named decision source. Exactly one card should be active for each key. `query`, `recall`, and the prompt hook exclude superseded cards by default while retaining them for provenance. Use `--include-superseded` only when you want the history.
+
+### Scars that can stop an action
+
+A scar is an incident-born rule. Adding `trigger.tool`, `trigger.input`, and actionable `advice` turns a suitable scar into a narrow action gate. Command matching inspects executable and unquoted argument positions by default, so a trigger word inside a quoted string, comment, or heredoc body does not block the command. Cards that need literal full-text matching can opt in explicitly.
+
+### Native-first installation
+
+The installer merges only entries marked as Epitype, keeps detected native vaults, and writes backups before changing an existing host file. Stable shims let the repository move without rewriting every host registration. Uninstall removes Epitype-owned registrations and configuration while preserving native memory and vault cards.
+
+### Failure evidence
+
+Missing indexes, stale indexes, shim failures, malformed cards, and lock contention have distinct outcomes. The hooks fail open when they cannot safely finish, and the installer doctor reports recorded shim outages instead of treating silence as health.
+
+## Quickstart
+
+Requirements: Python 3.11 or newer and a Claude Code or Codex installation with hook support.
+
+Install: `pip install epitype`, then use the `epitype-graft` command in place of `python install/graft.py` below (for example `epitype-graft install --dry-run`).
+
+The `epitype` package on npm is only a signpost back to this Python project.
+
+From the repository root, preview the planned changes:
+
+```powershell
+python install/graft.py install --dry-run
+```
+
+If the preview contains only the hosts and paths you expect, install and run the synthetic health check:
+
+```powershell
+python install/graft.py install
+python install/graft.py doctor
+```
+
+The installer detects existing native vaults. If it finds none, it creates an empty fallback vault. Reinstall preserves a curated vault list; use `python install/graft.py vaults --resync --dry-run` and then rerun without `--dry-run` when you intentionally want to adopt the latest detection result.
+
+### Approve Codex hooks
+
+Codex registration and Codex trust are separate. Check the real trust state after installation:
+
+```powershell
+python adapters/codex/hook_trust.py check
+```
+
+If any Epitype entry is `UNTRUSTED`, `DISABLED`, or `MODIFIED`:
+
+- In the terminal UI, enter `/hooks`, press `t` to trust all entries in the panel, then press `esc`.
+- In the Desktop app, open **hooks need review** or the **Hooks** panel and approve the Epitype entries for `SessionStart`, `UserPromptSubmit`, `PreToolUse`, and `PreCompact`.
+
+Run the check again. Codex is ready only when it prints `CODEX TRUST: PASS 4/4`. `doctor` verifies registration and synthetic execution; it does not replace this trust check.
+
+### Choose a vault layout
+
+Start from one of the tracked templates:
+
+| Template | Intended use |
+|---|---|
+| [`minimal`](templates/minimal/) | One person on one machine. |
+| [`team`](templates/team/) | A shared vault using the common write-lock contract. |
+| [`power`](templates/power/) | The full layout, including census and exam-ready directories. |
+
+## Search the local vault
+
+Build a vault's local FTS index, then query it directly or recall against a prompt:
+
+```powershell
+python epitype/memsearch.py build C:\path\to\vault
+python epitype/memsearch.py query term --vault C:\path\to\vault
+python epitype/memsearch.py recall "natural-language prompt" --vault C:\path\to\vault
+```
+
+The generated database lives at `<vault>/.epitype/memory_fts.sqlite3` and is ignored by Git. Only `build` creates a missing index. Existing indexes refresh incrementally when stale; a missing index is reported separately from a valid zero-result query.
+
+## Verify this checkout
+
+Run the public checks from the repository root:
+
+```powershell
+python tests/run_all.py
+python tests/privacy_lint.py
+python exam/exam_runner.py --strict
+```
+
+`tests/run_all.py` currently runs 17 component selftests covering the core tools, hook adapters, installer, exam engine, and privacy gate. The included exam corpus is a small synthetic sample. For this release, the publication gate also passed a strict 300-case behavior corpus and a 15-seed review; those release materials are not part of this repository.
+
+These checks are regression evidence, not proof that every future host version or every memory failure is covered.
+
+## Moving or removing Epitype
+
+After moving the repository, update the stable shim target and rerun the doctor:
+
+```powershell
+python install/graft.py relocate --to C:\path\to\new\repo
+```
+
+Preview uninstall before removing Epitype-owned files:
+
+```powershell
+python install/graft.py uninstall --dry-run
+python install/graft.py uninstall
+```
+
+Read [Uninstall Epitype](docs/UNINSTALL.md) before restoring a backup manually.
+
+## Limits
+
+- Hooks can govern only events and tools the host exposes. Direct file reads remain outside Epitype's current-decision filter.
+- The time and output ceilings require selection; Epitype never injects the entire vault into every prompt.
+- Action gates are only as precise as their scar triggers and advice. Malformed cards fail open rather than taking control of the host.
+- Claude Code and Codex are the tested host boundary. A host upgrade still needs integration testing.
+- The bundled tests are synthetic. They exercise behavior and failure handling, not long-term field performance.
+
+## Documentation
+
+- [Architecture](docs/ARCHITECTURE.md): memory blocks, retrieval routes, decision cards, scar lifecycle, and authority rules.
+- [Failure modes](docs/FAILURE_MODES.md): symptoms, countermeasures, and verification boundaries.
+- [Uninstall](docs/UNINSTALL.md): ownership-aware removal and backup guidance.

epitype-1.0.0/README.md

@@ -0,0 +1,152 @@
+# Epitype
+
+[繁體中文](README.zh-TW.md)
+
+Epitype is a memory governance layer for CLI agents.
+
+It keeps the host's native memory as the storage authority, then adds the structure, timing, action gates, and evidence needed for remembered rules to affect later behavior.
+
+An agent can retrieve the right fact and still break the rule attached to it. Epitype focuses on that gap:
+
+- a replaced decision should not return as current;
+- an incident lesson should reach the tool action where it matters;
+- a permission should remain attributable to the person who gave it;
+- a memory failure should be visible and testable.
+
+Epitype currently supports Claude Code and Codex. It uses only the Python standard library and does not require a hosted memory service.
+
+## How it works
+
+Epitype connects the same native vaults to four host events:
+
+| Event | What Epitype does |
+|---|---|
+| `SessionStart` | Injects a bounded memory index and work ledger when those files exist. |
+| `UserPromptSubmit` | Recalls up to five relevant cards from each resolved vault within the shared output budget. Short owner-grant statements are stored verbatim, deduplicated, and indexed; their meaning is not inferred during capture. |
+| `PreToolUse` | Matches scar-card triggers against the tool and its input. A match returns a bounded denial, safer advice, and an audit row. |
+| `PreCompact` | Builds a small recovery map from the transcript tail before context compaction. |
+
+Injected memory remains advisory. It cannot override system or developer instructions, bypass host permissions, or grant a tool authority by itself. Hook output is capped at 10 KiB and each hook has a three-second fail-open deadline.
+
+## Governance beyond recall
+
+### Current decisions
+
+Decision cards have a stable `decision_key`, an `active` or `superseded` status, an effective time, and a named decision source. Exactly one card should be active for each key. `query`, `recall`, and the prompt hook exclude superseded cards by default while retaining them for provenance. Use `--include-superseded` only when you want the history.
+
+### Scars that can stop an action
+
+A scar is an incident-born rule. Adding `trigger.tool`, `trigger.input`, and actionable `advice` turns a suitable scar into a narrow action gate. Command matching inspects executable and unquoted argument positions by default, so a trigger word inside a quoted string, comment, or heredoc body does not block the command. Cards that need literal full-text matching can opt in explicitly.
+
+### Native-first installation
+
+The installer merges only entries marked as Epitype, keeps detected native vaults, and writes backups before changing an existing host file. Stable shims let the repository move without rewriting every host registration. Uninstall removes Epitype-owned registrations and configuration while preserving native memory and vault cards.
+
+### Failure evidence
+
+Missing indexes, stale indexes, shim failures, malformed cards, and lock contention have distinct outcomes. The hooks fail open when they cannot safely finish, and the installer doctor reports recorded shim outages instead of treating silence as health.
+
+## Quickstart
+
+Requirements: Python 3.11 or newer and a Claude Code or Codex installation with hook support.
+
+Install: `pip install epitype`, then use the `epitype-graft` command in place of `python install/graft.py` below (for example `epitype-graft install --dry-run`).
+
+The `epitype` package on npm is only a signpost back to this Python project.
+
+From the repository root, preview the planned changes:
+
+```powershell
+python install/graft.py install --dry-run
+```
+
+If the preview contains only the hosts and paths you expect, install and run the synthetic health check:
+
+```powershell
+python install/graft.py install
+python install/graft.py doctor
+```
+
+The installer detects existing native vaults. If it finds none, it creates an empty fallback vault. Reinstall preserves a curated vault list; use `python install/graft.py vaults --resync --dry-run` and then rerun without `--dry-run` when you intentionally want to adopt the latest detection result.
+
+### Approve Codex hooks
+
+Codex registration and Codex trust are separate. Check the real trust state after installation:
+
+```powershell
+python adapters/codex/hook_trust.py check
+```
+
+If any Epitype entry is `UNTRUSTED`, `DISABLED`, or `MODIFIED`:
+
+- In the terminal UI, enter `/hooks`, press `t` to trust all entries in the panel, then press `esc`.
+- In the Desktop app, open **hooks need review** or the **Hooks** panel and approve the Epitype entries for `SessionStart`, `UserPromptSubmit`, `PreToolUse`, and `PreCompact`.
+
+Run the check again. Codex is ready only when it prints `CODEX TRUST: PASS 4/4`. `doctor` verifies registration and synthetic execution; it does not replace this trust check.
+
+### Choose a vault layout
+
+Start from one of the tracked templates:
+
+| Template | Intended use |
+|---|---|
+| [`minimal`](templates/minimal/) | One person on one machine. |
+| [`team`](templates/team/) | A shared vault using the common write-lock contract. |
+| [`power`](templates/power/) | The full layout, including census and exam-ready directories. |
+
+## Search the local vault
+
+Build a vault's local FTS index, then query it directly or recall against a prompt:
+
+```powershell
+python epitype/memsearch.py build C:\path\to\vault
+python epitype/memsearch.py query term --vault C:\path\to\vault
+python epitype/memsearch.py recall "natural-language prompt" --vault C:\path\to\vault
+```
+
+The generated database lives at `<vault>/.epitype/memory_fts.sqlite3` and is ignored by Git. Only `build` creates a missing index. Existing indexes refresh incrementally when stale; a missing index is reported separately from a valid zero-result query.
+
+## Verify this checkout
+
+Run the public checks from the repository root:
+
+```powershell
+python tests/run_all.py
+python tests/privacy_lint.py
+python exam/exam_runner.py --strict
+```
+
+`tests/run_all.py` currently runs 17 component selftests covering the core tools, hook adapters, installer, exam engine, and privacy gate. The included exam corpus is a small synthetic sample. For this release, the publication gate also passed a strict 300-case behavior corpus and a 15-seed review; those release materials are not part of this repository.
+
+These checks are regression evidence, not proof that every future host version or every memory failure is covered.
+
+## Moving or removing Epitype
+
+After moving the repository, update the stable shim target and rerun the doctor:
+
+```powershell
+python install/graft.py relocate --to C:\path\to\new\repo
+```
+
+Preview uninstall before removing Epitype-owned files:
+
+```powershell
+python install/graft.py uninstall --dry-run
+python install/graft.py uninstall
+```
+
+Read [Uninstall Epitype](docs/UNINSTALL.md) before restoring a backup manually.
+
+## Limits
+
+- Hooks can govern only events and tools the host exposes. Direct file reads remain outside Epitype's current-decision filter.
+- The time and output ceilings require selection; Epitype never injects the entire vault into every prompt.
+- Action gates are only as precise as their scar triggers and advice. Malformed cards fail open rather than taking control of the host.
+- Claude Code and Codex are the tested host boundary. A host upgrade still needs integration testing.
+- The bundled tests are synthetic. They exercise behavior and failure handling, not long-term field performance.
+
+## Documentation
+
+- [Architecture](docs/ARCHITECTURE.md): memory blocks, retrieval routes, decision cards, scar lifecycle, and authority rules.
+- [Failure modes](docs/FAILURE_MODES.md): symptoms, countermeasures, and verification boundaries.
+- [Uninstall](docs/UNINSTALL.md): ownership-aware removal and backup guidance.

epitype-1.0.0/adapters/__init__.py

@@ -0,0 +1 @@
+

epitype-1.0.0/adapters/claude/__init__.py

@@ -0,0 +1,8 @@
+"""Claude adapter package compatibility."""
+
+import sys
+
+from . import _hook_common
+
+
+sys.modules.setdefault("_hook_common", _hook_common)

epitype-1.0.0/adapters/claude/_hook_common.py

@@ -0,0 +1,188 @@
+import sys; sys.dont_write_bytecode = True; [getattr(stream, "reconfigure", lambda **_: None)(encoding="utf-8", errors="replace") for stream in (sys.stdout, sys.stderr)]  # cp950 consoles must not break hook entrypoints.
+"""Shared fail-open mechanics for Claude hook adapters."""
+
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+
+from epitype import memspec
+
+NATIVE_PROJECTS_SUBPATH = (".claude", "projects")
+_SLUG_PATTERN = re.compile(r"[^A-Za-z0-9]")
+
+
+def expired(started_at):
+    import time
+
+    return time.monotonic() - started_at >= memspec.HOOK_TIMEOUT_SECONDS
+
+
+def read_event(stream):
+    value = json.load(stream)
+    if not isinstance(value, dict):
+        raise ValueError("hook input must be a JSON object")
+    return value
+
+
+def load_config(started_at):
+    if expired(started_at):
+        return None
+    configured = os.environ.get(memspec.EPITYPE_CONFIG_ENV)
+    path = (
+        Path(configured).expanduser()
+        if configured
+        else Path.home() / ".epitype" / "config.json"
+    )
+    raw = path.read_text(encoding="utf-8")
+    value = json.loads(raw)
+    if not isinstance(value, dict):
+        raise ValueError("config must be an object")
+
+    raw_vaults = value.get(memspec.CONFIG_VAULTS_FIELD)
+    if not isinstance(raw_vaults, list) or not raw_vaults:
+        raise ValueError("config vaults must be a non-empty list")
+    vaults = []
+    for item in raw_vaults:
+        if not isinstance(item, str) or not item.strip():
+            raise ValueError("vault paths must be non-empty strings")
+        vault = Path(item).expanduser().resolve()
+        if not vault.is_dir():
+            raise NotADirectoryError(str(vault))
+        vaults.append(vault)
+
+    raw_budget = value.get(
+        memspec.CONFIG_BUDGET_BYTES_FIELD,
+        memspec.HOOK_DEFAULT_BUDGET_BYTES,
+    )
+    if isinstance(raw_budget, bool) or not isinstance(raw_budget, int):
+        raise ValueError("budget_bytes must be a positive integer")
+    budget = raw_budget
+    if budget <= 0:
+        raise ValueError("budget_bytes must be a positive integer")
+    return {
+        memspec.CONFIG_VAULTS_FIELD: vaults,
+        memspec.CONFIG_BUDGET_BYTES_FIELD: min(
+            budget,
+            memspec.HOOK_DEFAULT_BUDGET_BYTES,
+        ),
+    }
+
+
+def _holds_cards(vault):
+    try:
+        if (vault / memspec.MEMORY_INDEX_FILENAME).is_file():
+            return True
+        return any(
+            item.suffix.lower() == ".md" and not item.name.startswith("_")
+            for item in vault.iterdir()
+        )
+    except OSError:
+        return False
+
+
+def native_cwd_vaults(cwd, home=None):
+    """Claude Code auto-creates one memory directory per cwd slug; cards written
+    there must be recallable without editing config, so the cwd and each ancestor
+    join the vault list whenever their directory already holds an index or a card.
+    Empty auto-created shells are skipped so no index is planted in them."""
+    if not isinstance(cwd, str) or not cwd.strip():
+        return []
+    projects = (home or Path.home()).joinpath(*NATIVE_PROJECTS_SUBPATH)
+    try:
+        start = Path(cwd)
+        bases = (start, *start.parents)
+    except (TypeError, ValueError):
+        return []
+    found = []
+    for base in bases:
+        texts = {str(base)}
+        try:
+            texts.add(str(base.resolve()))
+        except OSError:
+            pass
+        for text in sorted(texts):
+            candidate = projects / _SLUG_PATTERN.sub("-", text) / "memory"
+            if candidate.is_dir() and _holds_cards(candidate):
+                resolved = candidate.resolve()
+                if resolved not in found:
+                    found.append(resolved)
+    return found
+
+
+def resolve_vaults(config, event, home=None):
+    """Closest native cwd vault first, then the configured vaults, deduplicated."""
+    vaults = native_cwd_vaults(event.get("cwd") if isinstance(event, dict) else None, home)
+    for vault in config[memspec.CONFIG_VAULTS_FIELD]:
+        if vault not in vaults:
+            vaults.append(vault)
+    return vaults
+
+
+def payload(event_name, context):
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": event_name,
+            "additionalContext": context,
+        }
+    }
+
+
+def encode_payload(value):
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+
+def payload_fits(event_name, context, context_budget):
+    if len(context.encode("utf-8")) > context_budget:
+        return False
+    encoded = encode_payload(payload(event_name, context)).encode("utf-8")
+    return len(encoded) <= memspec.HOOK_MAX_OUTPUT_BYTES
+
+
+def bounded_context(event_name, pieces, context_budget, required_first=False):
+    selected = []
+    for piece in pieces:
+        if not isinstance(piece, str) or not piece:
+            continue
+        candidate = "\n".join(selected + [piece])
+        if payload_fits(event_name, candidate, context_budget):
+            selected.append(piece)
+        elif required_first and not selected:
+            return None
+    return "\n".join(selected) if selected else None
+
+
+def emit(value):
+    encoded = encode_payload(value)
+    if len(encoded.encode("utf-8")) > memspec.HOOK_MAX_OUTPUT_BYTES:
+        raise ValueError("hook output exceeds the hard byte limit")
+    print(encoded)
+
+
+def run_synthetic(script, event, config_path, arguments=(), environment=None):
+    environment = {**os.environ, **(environment or {})}
+    environment[memspec.EPITYPE_CONFIG_ENV] = os.fspath(config_path)
+    environment["PYTHONDONTWRITEBYTECODE"] = "1"
+    return subprocess.run(
+        [sys.executable, os.fspath(script), *arguments],
+        input=json.dumps(event, ensure_ascii=False),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        env=environment,
+        timeout=10,
+        check=False,
+    )
+
+
+def write_config(path, vaults, budget=memspec.HOOK_DEFAULT_BUDGET_BYTES):
+    value = {
+        memspec.CONFIG_VAULTS_FIELD: [os.fspath(item) for item in vaults],
+        memspec.CONFIG_BUDGET_BYTES_FIELD: budget,
+    }
+    path.write_text(
+        json.dumps(value, ensure_ascii=False),
+        encoding="utf-8",
+    )