@lh8ppl/claude-memory-kit 0.3.5 → 0.4.1

package/README.md

@@ -5,91 +5,178 @@
   </picture>
 </p>
 
-# @lh8ppl/claude-memory-kit
+<p align="center">
+  <strong>Persistent, per-project memory for <a href="https://docs.claude.com/en/docs/claude-code">Claude Code</a> — plain markdown, committed with your code, recalled by meaning.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@lh8ppl/claude-memory-kit"><img src="https://img.shields.io/npm/v/@lh8ppl/claude-memory-kit?label=npm&color=blue" alt="npm"></a>
+  <a href="https://github.com/LH8PPL/claude-memory-kit/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/Node.js-bundled%20%C2%B7%20none%20required-brightgreen" alt="Node.js bundled, none required">
+  <a href="https://github.com/LH8PPL/claude-memory-kit/actions/workflows/ci.yml"><img src="https://github.com/LH8PPL/claude-memory-kit/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Windows-supported-0078D6?logo=windows&logoColor=white" alt="Windows supported">
+  <img src="https://img.shields.io/badge/macOS-supported-000000?logo=apple&logoColor=white" alt="macOS supported">
+  <img src="https://img.shields.io/badge/Linux-supported-FCC624?logo=linux&logoColor=black" alt="Linux supported">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Claude_Code-supported-6E56CF" alt="Claude Code supported">
+  <img src="https://img.shields.io/badge/Kiro-supported-6E56CF" alt="Kiro supported">
+</p>
+
+Claude forgets everything when a session ends — so every new chat you re-explain who you are, what you're building, and how you like things done. **claude-memory-kit** fixes that: it quietly captures your decisions, preferences, and project context, then hands them back at the start of every session. Everything is plain text inside your project, and it travels with the code — `git clone` brings the memory along.
+
+> [!NOTE]
+> **Not a developer?** If you can open a project in Claude Code, you're set — let Claude run the setup for you (see [Quickstart](#quickstart)).
 
-**`cmk`** — the CLI for [claude-memory-kit](https://github.com/LH8PPL/claude-memory-kit), a per-project, in-repo memory system for [Claude Code](https://docs.claude.com/en/docs/claude-code). It fixes Claude's per-session amnesia so you don't have to re-tell the backstory every time you start a new session.
+## How it feels
 
-## What it does
+You open Claude Code on a project you haven't touched in weeks. Before you say anything, Claude already knows your stack, your conventions, and what you decided last time:
 
-- **Cross-project persona — the wedge (v0.2)** — when you state how you work *everywhere* ("always use uv, never pip", "from now on run the linter before committing"), the per-turn auto-extract promotes it into your **user tier** (`~/.claude-memory-kit/`) **that turn**. So a brand-new project **cold-opens already knowing your style** — layered structure, your tooling, your testing discipline — with no hand-curation and no waiting. Carry it between your own machines with `cmk persona export`/`import`, or pin a single fact across projects with `cmk lessons promote`.
-- **Frozen snapshot at session start** — MEMORY.md + USER.md + SOUL.md + INDEX.md + today's session log inject once at the first tool call, so Claude sees your context every session without you re-telling it. The snapshot opens with an **authority instruction** ("when injected memory contradicts your assumptions, injected memory wins"), so the agent leads with its memory instead of re-deriving answers from the code.
-- **Auto-extract on every assistant turn** — a background `claude --print` subagent reads each turn and saves durable facts to memory. Durable project knowledge (setup/config, conventions, workflows, tool quirks) becomes a **rich Why/How fact file** (structured + searchable); lighter signals stay terse `MEMORY.md` bullets. Runs automatically, so the rich tier survives even when the model uses Claude Code's built-in memory instead. No manual writes needed.
-- **Claude knows WHEN to recall** — the auto-invoked `memory-search` skill fires on "what did we decide about X" / "have we seen this error before" and searches the deep archive in a forked side-context, returning a curated citation-backed summary. Read-only by contract.
-- **Explicit capture when you want it** — say "remember this" / "from now on" / "we decided" / "forget X" (the `memory-write` skill), or run `cmk remember "<fact>"`. Both dedup, screen for secrets, abstract machine paths to `~`, and write silently. For backtick/quote-heavy rich facts, capture them shell-safe as JSON: `cmk remember --from-file fact.json` (or `--json` from stdin) — content never touches the shell.
-- **Search + MCP — Claude runs every memory op for you, in conversation** — `cmk search "<term>"` (keyword over facts + scratchpads; with the optional local embedder, **semantic + hybrid recall**: ask in your own words and get the fact even with zero keyword overlap — measured R@5 0.941 / paraphrase 1.000 on the kit's benchmark, no API calls). `cmk install` registers the kit's **MCP server**, so Claude can do the whole memory surface as tools without you ever typing `cmk`: capture (`mk_remember`, rich Why/How too), recall (`mk_search` / `mk_get` / `mk_timeline` / `mk_cite`), adjust trust (`mk_trust`), promote a fact across projects (`mk_lessons_promote`), forget (`mk_forget` — previews first, then deletes on confirm), and clear the review/conflict queues (`mk_queue_list` / `mk_queue_resolve`). The tools are allow-listed on install, so they run prompt-free.
-- **Bounded by compression** — session → daily → weekly Haiku rollups (cron or lazy-on-read) keep the snapshot small as history grows. The session-buffer rollup self-heals at session start too, so memory stays bounded even if you never cleanly close the window.
-- **Don't start empty — import the rules you already own** — `cmk import-claude-md` parses an existing `CLAUDE.md` / `.cursorrules` / `AGENTS.md` into typed, searchable facts through the same safe write path (secret screening, sanitization, dedup), with provenance back to source file + line. `--dry-run` previews first.
-- **Per-project, in-repo** — `context/` lives inside your project and travels with `git clone`. Each project keeps its own memory.
-- **9 health checks** — `cmk doctor` validates hook wiring, distill freshness, transcript firing, INDEX consistency, cron registration, native-memory coexistence, stale locks, native-binding health (npm 12 readiness), and version drift (a project scaffold behind your installed `cmk` after an update) — each failure with a repair command.
+```
+claude-memory-kit: 23 fact(s) in context, 2 captured in the last 24h, 1 conflict pending
+```
+
+You work. It learns — automatically, no buttons. Next session, it remembers this one too.
+
+## Features
 
-## Install — pick ONE route
+- **Remembers across sessions** — a frozen snapshot of your project + persona injects once at session start, so Claude leads with what it knows instead of re-deriving it from code.
+- **Captures automatically, prompt-free** — a background pass reads each turn and saves durable facts as searchable notes. No "save" button. When you *do* say "remember this," the kit auto-approves its **own** tools and skills so the save happens with no "Allow?" prompt — nothing else is touched.
+- **Recalls by meaning** — ask in your own words ("where do credentials go") and get the right fact even with zero keyword overlap. Fully local, zero API calls — **R@5 0.941 / paraphrase 1.000** ([benchmarks](#benchmarks)).
+- **Learns how you work, everywhere** — state a habit once ("always use uv, never pip") and a brand-new project cold-opens already knowing it.
+- **Stays private + bounded** — secrets are screened before any write, machine paths are abstracted to `~`, and rolling compression keeps memory small as history grows.
+- **Guards against accidental deletion** — a hook **blocks** a destructive command (`rm`, `git reset --hard`, …) the moment it targets a memory path, before it runs.
+- **Works across your agents** — the same memory brain on **Claude Code** and **[Kiro](https://kiro.dev)** (IDE + `kiro-cli`). A project's `context/` is shared, so memory you build in one is there in the other.
+- **Per-project, in your repo** — `context/` lives in your project and travels with `git clone`. Each project keeps its own memory.
 
-Each route is complete on its own. **Don't run both** — they wire the same hooks.
+## Quickstart
+
+> [!IMPORTANT]
+> Pick **one** route — both wire the same hooks and are complete on their own.
 
 ### Route A — npm (recommended)
 
+Install the CLI once, then run `cmk install` in each project — pick your agent:
+
 ```bash
 npm install -g @lh8ppl/claude-memory-kit
 cd ~/my-project
-cmk install        # scaffolds context/ + the memory-write + memory-search skills AND wires the lifecycle hooks into .claude/settings.json
-cmk install --with-semantic   # (optional) local semantic recall — one-time ~260 MB, search defaults to hybrid
-cmk register-crons            # (optional) scheduled background compression — otherwise self-heals lazily
-cmk import-claude-md --yes    # (optional) seed memory from an existing CLAUDE.md / .cursorrules (--dry-run previews)
-cmk doctor         # verify, then restart Claude Code
 ```
 
-`cmk install` is a complete entry point: it scaffolds `context/`, drops the `memory-write` + `memory-search` skills into `.claude/skills/` (committed — travels with `git clone`), and writes the 5 lifecycle hooks (PATH-resolved, cross-OS) into the project's `.claude/settings.json`. It also **registers the kit's MCP server** in `.mcp.json` and allow-lists its tools (`mcp__cmk__*`) in `.claude/settings.json`, so Claude can drive memory as tools with no per-call prompt, and writes a `.gitattributes` block pinning committed memory to LF (so a Windows clone can't mangle line endings — your memory stays readable cross-platform). No separate `/plugin` step needed. Use `cmk install --no-hooks` to skip the hooks + MCP wiring (scaffold-only).
+**Claude Code:**
+
+```bash
+cmk install                   # scaffold context/ + wire hooks (one step)
+cmk install --with-semantic   # optional: local semantic recall (~260 MB, once)
+cmk doctor                    # verify, then restart Claude Code
+```
+
+**Kiro** (IDE + `kiro-cli` — see [the Kiro guide](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/KIRO.md)):
+
+```bash
+cmk install --ide kiro                   # wire Kiro end-to-end
+cmk install --ide kiro --with-semantic   # …with local semantic recall
+cmk doctor                                # verify, then restart Kiro
+```
 
-> Installing the package globally adds the `cmk` CLI **and** the installer. It's the `cmk install` *subcommand* that wires the hooks — not the bare `npm install`.
+`cmk install` is the whole entry point: it scaffolds `context/`, drops the memory skills, wires the lifecycle hooks, and registers the MCP server so the agent can drive memory as tools — no `/plugin` step needed. A project can carry **both** agents — run both installs; they share one `context/`.
 
-### Route B — Claude Code plugin marketplace
+> [!TIP]
+> Prefer not to touch the terminal? Open the project in Claude Code and say *"install claude-memory-kit and set it up here."* Claude runs the commands; you just approve them. **Restart Claude Code once** afterward (`/exit`, then `claude`) so the hooks load.
 
-Inside Claude Code:
+### Route B — Claude Code plugin
 
 ```text
 /plugin marketplace add LH8PPL/claude-memory-kit   # add this repo as a plugin source (once per machine)
-/plugin install claude-memory-kit                  # install the global machinery — hooks + skills (once per machine)
-cd ~/my-project                                    # the project you want memory in — bootstrap scaffolds into the CURRENT dir
-/claude-memory-kit:bootstrap                        # scaffold this project's context/ memory tree (once per project)
+/plugin install claude-memory-kit                  # install hooks + skills (once per machine)
+cd ~/my-project
+/claude-memory-kit:bootstrap                        # scaffold this project's memory (once per project)
 ```
 
-The first two commands are **global** (per machine); `bootstrap` is **per project** — run it again (after a `cd`) in each project. The plugin bundles the hooks + the `bootstrap`, `memory-write`, and `memory-search` skills, so it's complete without the npm CLI (add the CLI later only if you want `cmk search` / `cmk doctor` / cron).
+The plugin bundles the hooks + skills, so it's complete without the npm CLI. Add the CLI later only if you want `cmk search` / `cmk doctor` / cron.
+
+> [!NOTE]
+> **Updating** has two parts on both routes: update the machinery, then re-stamp each project (`cmk install` again, or `/claude-memory-kit:bootstrap`). `cmk doctor` flags any project that's behind so you don't have to remember.
+
+## How it works
+
+`context/` is the source of truth — plain markdown, committed with your code. A regenerable SQLite + FTS5 index (plus an optional local embedder) powers search. Memory lives in three tiers:
+
+| Tier | Location | Scope | What lives here |
+| --- | --- | --- | --- |
+| **Project** | `<repo>/context/` | committed — travels with `clone` | Decisions, conventions, file purposes |
+| **Local** | `<repo>/context.local/` | gitignored, per-machine | Machine paths, local tool versions |
+| **User** | `~/.claude-memory-kit/` | cross-project, per-person | Persona, cross-project lessons |
+
+Project memory follows the **repo** (teammates get it on clone). Your persona follows **you** — machine-local, never committed. Carry it between your own machines with `cmk persona export` / `import`.
 
 ## CLI
 
-Most-used commands (full list via `cmk --help`):
+You rarely type these yourself — Claude drives the same operations as tools mid-conversation through the kit's **MCP server** (full tool reference: **[docs/MCP.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/MCP.md)**). The commands:
 
 | Command | Purpose |
 | --- | --- |
-| `cmk install` | Scaffold `context/` + the `memory-write`/`memory-search` skills + `.gitignore` + CLAUDE.md block + wire hooks (`--no-hooks` for scaffold-only) |
-| `cmk doctor` | Run HC-1..HC-9 health checks, surface repair commands |
+| `cmk install [--with-semantic] [--ide claude-code\|kiro]` | Scaffold + wire hooks + register the MCP server (complete entry point) |
+| `cmk uninstall [--ide claude-code\|kiro]` | Remove one agent's wiring — conservative, never deletes `context/` |
+| `cmk doctor` | Run HC-1..HC-10 health checks; surface a repair command per failure |
 | `cmk repair --hooks` / `--locks` / `--index` / `--all` | Idempotent self-repair |
-| `cmk search "<query>" [--mode keyword\|semantic\|hybrid] [--scope facts\|transcripts\|decisions]` | Search memory — by meaning with the embedder (hybrid default after `--with-semantic`); `--scope transcripts` = the raw session record; `--scope decisions` = the decision journal (history / "what did we reject") |
-| `cmk get <id…>` / `cmk timeline <id>` / `cmk cite <id>` / `cmk recent-activity` | Read the index back — full fact bodies + provenance, sequential context around an observation, a canonical citation link, recent changes (the CLI side of the `mk_*` MCP read tools) |
+| `cmk search "<query>" [--mode keyword\|semantic\|hybrid] [--scope facts\|transcripts\|decisions]` | Search memory by meaning (hybrid default after `--with-semantic`); `--scope transcripts` = raw session record; `--scope decisions` = the decision journal (history / "what did we reject") |
+| `cmk remember "<fact>"` | Capture a fact explicitly (deduped, secret-screened, path-abstracted). `--from-file fact.json` for backtick/quote-heavy rich facts |
+| `cmk get <id…>` / `cmk timeline <id>` / `cmk cite <id>` / `cmk recent-activity` | Read the index back — full fact bodies + provenance, context around an observation, a citation link, recent changes (the CLI side of the `mk_*` MCP read tools) |
+| `cmk forget <id>` | Tombstone a fact — gone from `cmk search` immediately (audit trail preserved) |
+| `cmk lessons promote <id> [--to USER.md\|HABITS.md]` | Promote one project fact to your cross-project **user tier** so it applies in **every** project |
 | `cmk roll --scope now\|today\|recent` | Manually trigger a compression pipeline |
-| `cmk register-crons [--dry-run] [--unregister]` | Register daily + weekly jobs with cron / launchd / Task Scheduler |
-| `cmk forget <id>` | Tombstone a fact — disappears from `cmk search` immediately, no manual reindex (audit trail preserved) |
-| `cmk lessons promote <id> [--to USER.md\|HABITS.md]` | Promote one captured fact to your cross-project **user tier** (the safe path — sanitized, secret-screened, audited) so it applies in **every** project |
-| `cmk disable-native-memory` / `enable-native-memory` | Opt out of Claude Code's built-in Auto Memory so the kit is your single, lean memory layer (committable — travels with `git clone`) |
-| `cmk persona generate` | Run cross-project persona synthesis on demand (instead of waiting for the weekly pass) |
-| `cmk persona export <file>` / `import <file>` | Carry your cross-project persona (the user tier) to another of **your** machines — export to one portable bundle, import on the other (overwrites with backup + rollback). The persona stays private (never committed to a project) |
-| `cmk import-anthropic-memory [--dry-run] [--yes]` | Merge bullets from Anthropic's native auto-memory into MEMORY.md |
-| `cmk import-claude-md [file] [--dry-run] [--yes]` | Onboard from the rules you already own — parse an existing `CLAUDE.md` / `.cursorrules` / `AGENTS.md` into typed facts through the safe write path (Poison_Guard + sanitization + dedup) |
+| `cmk register-crons [--dry-run] [--unregister]` | Register daily + weekly compression jobs (cron / launchd / Task Scheduler) |
+| `cmk disable-native-memory` / `enable-native-memory` | Opt out of Claude Code's built-in Auto Memory so the kit is your single, lean layer |
+| `cmk persona generate` · `export <file>` · `import <file>` | Synthesize your cross-project persona on demand; carry it to another of **your** machines (private — never committed) |
+| `cmk import-claude-md [file]` · `import-anthropic-memory` | Seed memory from an existing `CLAUDE.md` / `.cursorrules` / `AGENTS.md`, or merge Anthropic's native auto-memory bullets (`--dry-run` previews) |
+
+Full reference with examples: **[docs/CLI.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/CLI.md)** or `cmk --help`.
+
+## Working with Kiro
+
+[Kiro](https://kiro.dev) (the AWS agentic IDE + `kiro-cli`) is a first-class target — `cmk install --ide kiro` wires it end-to-end for both the IDE and the terminal, and a project's `context/` is shared with Claude Code. The full setup, surface table, and dual-agent notes are in **[the Kiro guide](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/KIRO.md)**.
+
+## Uninstalling
+
+`cmk uninstall` is **conservative** — it removes only the kit's managed wiring for one agent and **never deletes your `context/` memory** (your data) or anything outside the kit's markers.
+
+**Claude Code:**
+
+```bash
+cmk uninstall              # remove the CLAUDE.md block + hooks
+```
+
+**Kiro:**
+
+```bash
+cmk uninstall --ide kiro   # remove the .kiro/ blocks + skills + IDE hooks + AGENTS.md + ~/.kiro CLI agent
+```
+
+On a dual-agent project, uninstall one and the other keeps working. To remove the memory data too, delete `context/` (and `context.local/`) yourself — the kit won't do it for you.
+
+## Benchmarks
+
+Recall quality is **measured, not claimed** — `npm run bench:recall` runs a LongMemEval-style harness through the kit's real write / index / search paths.
+
+| Pipeline | R@5 | Paraphrase recall | API calls |
+| --- | --- | --- | --- |
+| Keyword (FTS5 one-shot) | 0.176 | 0.000 | 0 |
+| Agentic keyword (iterative + LLM reformulation) | 0.529 | 0.300 | 1/query |
+| **Semantic (sqlite-vec + local bge-base, the default)** | **0.941** | **1.000** | **0** |
+
+Keyword search structurally misses natural-language questions; the embedded semantic backend closes the paraphrase gap entirely — locally, with no API calls.
 
 ## Requirements
 
 - Node.js ≥ 20
-- Claude Code (for the hook-driven auto-memory loop)
+- Claude Code (for the hook-driven auto-memory loop) — or [Kiro](https://kiro.dev)
 - Optional: `cmk install --with-semantic` for semantic/hybrid recall (installs the local `@huggingface/transformers` embedder, ~260 MB once — no API, no Python)
 
-## Three-tier model
-
-| Tier | Location | Scope |
-| --- | --- | --- |
-| **P** (project) | `<repo>/context/` | committed to git, travels with `clone` |
-| **L** (local) | `<repo>/context.local/` | gitignored, per-machine |
-| **U** (user) | `~/.claude-memory-kit/` | cross-project per-user |
-
 ## Documentation
 
 Full docs, architecture, and design live in the repository:

package/bin/cmk-approve-permission.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// PermissionRequest hook handler — the prompt-free auto-approver (Task 172).
+//
+// Wired by `cmk install` as a Claude Code PermissionRequest hook (matchers
+// "mcp__cmk__.*" and "Skill"). Reads the permission request on stdin and, if it
+// is for one of the kit's OWN surfaces (an `mcp__cmk__<tool>` MCP tool or a
+// scaffolded kit skill), prints the allow decision to stdout so Claude Code
+// approves it without a prompt. For anything else it prints nothing and exits 0,
+// leaving CC's normal permission flow untouched.
+//
+// Why this exists: CC 2.1.x stopped honouring the kit's `permissions.allow`
+// MCP rules + skill `allowed-tools` for these prompts (anthropics/claude-code
+// #17499, #18837→#14956). The PermissionRequest hook is the documented,
+// working mechanism (proven live, v041l).
+//
+// Output contract (code.claude.com/docs/en/hooks-guide):
+//   stdout = {"hookSpecificOutput":{"hookEventName":"PermissionRequest",
+//             "decision":{"behavior":"allow"}}}  → auto-approve
+//   stdout empty + exit 0                         → no opinion (CC asks as usual)
+// Fail-SILENT: any load/parse/logic error prints nothing and exits 0 — a broken
+// auto-approver must never wedge the session OR wrongly approve; it just stops
+// auto-approving and the user sees the normal prompt.
+
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const readHookStdinPath = join(__dirname, '..', 'src', 'read-hook-stdin.mjs');
+const modulePath = join(__dirname, '..', 'src', 'approve-permission.mjs');
+
+let readHookStdin;
+let evaluatePermissionRequest;
+try {
+  ({ readHookStdin } = await import(pathToFileURL(readHookStdinPath).href));
+  ({ evaluatePermissionRequest } = await import(pathToFileURL(modulePath).href));
+} catch {
+  process.exit(0); // fail-silent: no opinion
+}
+
+// Drain the hook payload — but not on an interactive TTY (a manual run), where a
+// blocking stdin read would hang forever (the Task-101 lesson).
+const raw = readHookStdin({ isTTY: process.stdin.isTTY });
+
+let payload;
+try {
+  payload = raw.trim() === '' ? {} : JSON.parse(raw);
+} catch {
+  process.exit(0); // fail-silent on unparseable input
+}
+
+let decision;
+try {
+  decision = evaluatePermissionRequest(payload);
+} catch {
+  process.exit(0); // fail-silent on any logic error
+}
+
+if (decision) {
+  process.stdout.write(JSON.stringify(decision));
+}
+process.exit(0);

package/bin/cmk-daily-distill.mjs

@@ -26,12 +26,15 @@ const __dirname = dirname(__filename);
 // relative to bin/ → ../src/ for both modules.
 const dailyDistillModulePath = join(__dirname, '..', 'src', 'daily-distill.mjs');
 const compressorModulePath = join(__dirname, '..', 'src', 'compressor.mjs');
+const compactionStateModulePath = join(__dirname, '..', 'src', 'compaction-state.mjs');
 
 let dailyDistill;
 let HaikuViaAnthropicApi;
+let recordCronHeartbeat;
 try {
   ({ dailyDistill } = await import(pathToFileURL(dailyDistillModulePath).href));
   ({ HaikuViaAnthropicApi } = await import(pathToFileURL(compressorModulePath).href));
+  ({ recordCronHeartbeat } = await import(pathToFileURL(compactionStateModulePath).href));
 } catch (err) {
   process.stderr.write(
     `cmk-daily-distill: failed to load modules: ${err?.message ?? err}\n`,
@@ -52,6 +55,17 @@ const envRoot = process.env.CMK_PROJECT_DIR && process.env.CMK_PROJECT_DIR.lengt
   : null;
 const projectRoot = argvRoot ?? envRoot ?? process.cwd();
 
+// Task 167 (D-207): record the cron HEARTBEAT on every fire — BEFORE the distill
+// work, so a run that crashes mid-distill still proves "the cron is alive" (the
+// anacron model: a run HAPPENED, regardless of outcome). This is the durable
+// liveness signal the lazy-roll gate keys off (by age); without it a registered
+// cron would read "dead" after 48h even while firing nightly. Best-effort.
+try {
+  recordCronHeartbeat?.({ projectRoot });
+} catch {
+  // never let a heartbeat write failure abort the distill
+}
+
 try {
   const backend = new HaikuViaAnthropicApi();
   const r = await dailyDistill({ projectRoot, backend });

package/bin/cmk-guard-memory.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// PreToolUse hook handler — the memory delete-guardrail (D-192).
+//
+// Wired by `cmk install` as a Claude Code PreToolUse hook (matcher
+// "Bash|PowerShell"). Reads the tool call on stdin and, if it's a destructive
+// command aimed at a claude-memory-kit memory path (context/ , the persona
+// tier, a memory file), BLOCKS it by exiting 2 — Claude Code shows the stderr
+// reason to the model and the command never runs.
+//
+// Exit contract (Claude Code PreToolUse):
+//   exit 0 → allow (no opinion)
+//   exit 2 → BLOCK; stderr is surfaced as the reason
+// Fail-OPEN: any load/parse error exits 0 — a broken guardrail must never wedge
+// the session; it just stops guarding.
+
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const readHookStdinPath = join(__dirname, '..', 'src', 'read-hook-stdin.mjs');
+const modulePath = join(__dirname, '..', 'src', 'guard-memory.mjs');
+
+let readHookStdin;
+let evaluatePayload;
+try {
+  ({ readHookStdin } = await import(pathToFileURL(readHookStdinPath).href));
+  ({ evaluatePayload } = await import(pathToFileURL(modulePath).href));
+} catch (err) {
+  process.stderr.write(`cmk-guard-memory: failed to load modules: ${err?.message ?? err}\n`);
+  process.exit(0); // fail-open
+}
+
+// Drain the hook payload — but not on an interactive TTY (a manual run), where
+// a blocking stdin read would hang forever (the Task-101 lesson).
+const raw = readHookStdin({ isTTY: process.stdin.isTTY });
+
+let payload;
+try {
+  payload = raw.trim() === '' ? {} : JSON.parse(raw);
+} catch {
+  process.exit(0); // fail-open on unparseable input
+}
+
+let verdict;
+try {
+  verdict = evaluatePayload(payload);
+} catch {
+  process.exit(0); // fail-open on any logic error
+}
+
+if (verdict && verdict.block) {
+  process.stderr.write(`${verdict.reason}\n`);
+  process.exit(2); // BLOCK
+}
+
+process.exit(0); // allow

package/bin/cmk-inject-context.mjs

@@ -59,6 +59,18 @@ try {
 // is discarded; readHookStdin returns '' for a TTY so a manual run finishes.
 readHookStdin({ isTTY: process.stdin.isTTY });
 
+// Task 167 NOTE (D-207, the live-test revision): an earlier design (Q4) tried a
+// SYNCHRONOUS now.md drain HERE, before injectContext, to make THIS session read
+// the rolled state. The live test proved that doesn't fit: a real now→today Haiku
+// roll takes ~18–37s, but the SessionStart hook ceiling is 30s — so the
+// synchronous drain reliably timed out and fell back to the detached path anyway.
+// The research (claude-mem/mem0/Letta) confirms the event-driven peers compact at
+// session END (the Stop hook, no user waiting), NOT session start. So the kit
+// keeps the now→today roll on the DETACHED SessionStart path (spawned inside
+// injectContext) + the SessionEnd compress-session hook — and the real fix is the
+// cron-liveness gate (167.A), which stops a dead cron from suppressing that roll.
+// now.md heals next session via the detached roll and never compounds.
+
 try {
   const r = injectContext({ cwd: process.cwd(), compressLazyPath });
   process.stdout.write(JSON.stringify(r.hookOutput));

package/bin/cmk-weekly-curate.mjs

@@ -20,12 +20,15 @@ const __dirname = dirname(__filename);
 
 const weeklyCurateModulePath = join(__dirname, '..', 'src', 'weekly-curate.mjs');
 const compressorModulePath = join(__dirname, '..', 'src', 'compressor.mjs');
+const compactionStateModulePath = join(__dirname, '..', 'src', 'compaction-state.mjs');
 
 let weeklyCurate;
 let HaikuViaAnthropicApi;
+let recordCronHeartbeat;
 try {
   ({ weeklyCurate } = await import(pathToFileURL(weeklyCurateModulePath).href));
   ({ HaikuViaAnthropicApi } = await import(pathToFileURL(compressorModulePath).href));
+  ({ recordCronHeartbeat } = await import(pathToFileURL(compactionStateModulePath).href));
 } catch (err) {
   process.stderr.write(
     `cmk-weekly-curate: failed to load modules: ${err?.message ?? err}\n`,
@@ -49,6 +52,15 @@ const projectRoot = argvRoot ?? envRoot ?? process.cwd();
 // project-only (backward-compatible).
 const userDir = join(homedir(), '.claude-memory-kit');
 
+// Task 167 (D-207): record the cron heartbeat on every fire (anacron model —
+// proves the cron is alive regardless of curate outcome). The lazy-roll gate
+// keys off its age. Best-effort; never abort the curate on a heartbeat failure.
+try {
+  recordCronHeartbeat?.({ projectRoot });
+} catch {
+  // best-effort
+}
+
 try {
   const backend = new HaikuViaAnthropicApi();
   const r = await weeklyCurate({ projectRoot, userDir, backend });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lh8ppl/claude-memory-kit",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "cmk — the CLI for claude-memory-kit. Per-project, in-repo memory system for Claude Code.",
   "type": "module",
   "bin": {
@@ -12,7 +12,9 @@
     "cmk-capture-prompt": "./bin/cmk-capture-prompt.mjs",
     "cmk-observe-edit": "./bin/cmk-observe-edit.mjs",
     "cmk-capture-turn": "./bin/cmk-capture-turn.mjs",
-    "cmk-compress-session": "./bin/cmk-compress-session.mjs"
+    "cmk-compress-session": "./bin/cmk-compress-session.mjs",
+    "cmk-guard-memory": "./bin/cmk-guard-memory.mjs",
+    "cmk-approve-permission": "./bin/cmk-approve-permission.mjs"
   },
   "files": [
     "bin/",

package/src/agent-profile.mjs

@@ -0,0 +1,115 @@
+// agent-profile.mjs — the per-agent profile factory (Task 50.C).
+//
+// D-180: per-agent adapters are DATA, not classes. This factory validates +
+// normalizes a profile DECLARATION so the install routing (Task 50.F) can drive
+// ANY agent through ONE code path — the config legs (MCP registration, hook
+// entry) go through the shared `mutateAgentConfig` primitive (Task 50.B); the
+// instruction leg goes through the kit's marker-block machinery. The factory
+// itself does NO I/O — it's a pure validator/normalizer that returns a frozen
+// descriptor. A bad profile fails LOUD at definition time (throws), not at
+// install time against a user's machine.
+//
+// Integration-type taxonomy (the claude-mem insight — the type dictates which
+// legs an agent wires):
+//   native-hooks-mcp   — instruction + MCP + lifecycle hooks (Claude Code, Kiro)
+//   hooks-mcp          — instruction + MCP + hooks, hooks via a dedicated file
+//                        (Cursor) — same required legs as native-hooks-mcp;
+//                        the `hooks.mechanism` field distinguishes them
+//   mcp-only           — instruction + MCP, NO hooks (Copilot/Warp/Roo/Goose)
+//   instruction-only   — instruction file only, NO MCP, NO hooks (AGENTS.md rung)
+//
+// Public surface:
+//   defineAgentProfile(declaration) → frozen normalized descriptor (throws on invalid)
+//   INTEGRATION_TYPES — frozen list of the valid integrationType values
+
+export const INTEGRATION_TYPES = Object.freeze([
+  'native-hooks-mcp',
+  'hooks-mcp',
+  'mcp-only',
+  'instruction-only',
+]);
+
+const TYPES = new Set(INTEGRATION_TYPES);
+
+// Which legs each type REQUIRES / FORBIDS. instructionFile is required by every
+// type (the universal leg). mcp + hooks vary by type.
+const TYPE_LEGS = Object.freeze({
+  'native-hooks-mcp': { mcp: 'required', hooks: 'required' },
+  'hooks-mcp': { mcp: 'required', hooks: 'required' },
+  'mcp-only': { mcp: 'required', hooks: 'forbidden' },
+  'instruction-only': { mcp: 'forbidden', hooks: 'forbidden' },
+});
+
+function fail(msg) {
+  throw new Error(`defineAgentProfile: ${msg}`);
+}
+
+/**
+ * Validate + normalize an agent profile declaration.
+ * @param {object} decl
+ * @returns {Readonly<object>} the frozen descriptor
+ */
+export function defineAgentProfile(decl) {
+  if (decl === null || typeof decl !== 'object') {
+    fail('declaration must be an object');
+  }
+  const { name, displayName, integrationType, detect, instructionFile, mcp, hooks, transcript } = decl;
+
+  // ── universal required fields ────────────────────────────────────────────
+  if (typeof name !== 'string' || name.length === 0) {
+    fail('name is required (non-empty string)');
+  }
+  if (!TYPES.has(integrationType)) {
+    fail(`integrationType must be one of: ${INTEGRATION_TYPES.join(', ')} (got ${JSON.stringify(integrationType)})`);
+  }
+  if (detect === null || typeof detect !== 'object') {
+    fail(`profile ${name}: detect descriptor is required (e.g. {homeDir:'.kiro'} | {command:'x'} | {always:true})`);
+  }
+  if (typeof instructionFile !== 'string' || instructionFile.length === 0) {
+    fail(`profile ${name}: instructionFile is required (every integration type wires the instruction leg)`);
+  }
+
+  // ── per-type leg contract (the parity invariant 50.D will also enforce) ──
+  const legs = TYPE_LEGS[integrationType];
+  enforceLeg(name, integrationType, 'mcp', mcp, legs.mcp);
+  enforceLeg(name, integrationType, 'hooks', hooks, legs.hooks);
+
+  // ── shape checks on present legs ─────────────────────────────────────────
+  if (mcp !== undefined) {
+    if (typeof mcp.path !== 'string' || typeof mcp.serversKey !== 'string') {
+      fail(`profile ${name}: mcp requires {path, serversKey} strings`);
+    }
+  }
+  if (hooks !== undefined) {
+    if (typeof hooks.mechanism !== 'string') {
+      fail(`profile ${name}: hooks requires a {mechanism} string`);
+    }
+    if (hooks.eventMap === null || typeof hooks.eventMap !== 'object') {
+      fail(`profile ${name}: hooks requires an {eventMap} object`);
+    }
+  }
+
+  // ── normalize + freeze ───────────────────────────────────────────────────
+  const descriptor = {
+    name,
+    displayName: displayName || name,
+    integrationType,
+    detect: Object.freeze({ ...detect }),
+    instructionFile,
+    ...(mcp !== undefined ? { mcp: Object.freeze({ ...mcp }) } : {}),
+    ...(hooks !== undefined
+      ? { hooks: Object.freeze({ ...hooks, eventMap: Object.freeze({ ...hooks.eventMap }) }) }
+      : {}),
+    ...(transcript !== undefined ? { transcript: Object.freeze({ ...transcript }) } : {}),
+  };
+  return Object.freeze(descriptor);
+}
+
+function enforceLeg(name, type, leg, value, requirement) {
+  if (requirement === 'required' && value === undefined) {
+    fail(`profile ${name}: integrationType '${type}' requires the ${leg} leg`);
+  }
+  if (requirement === 'forbidden' && value !== undefined) {
+    fail(`profile ${name}: integrationType '${type}' must NOT declare ${leg} (it over-wires its type)`);
+  }
+}