@lh8ppl/claude-memory-kit 0.4.0 → 0.4.1

package/README.md

@@ -5,97 +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>
 
-**`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.
+<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>
 
-## What it does
+<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>
 
-- **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.
-- **Guards your memory from an accidental delete** — `cmk install` wires a `PreToolUse` hook (`cmk-guard-memory`) that **blocks** a destructive command (`rm`, `Remove-Item`, `del`, `git clean`, `git reset --hard`, `find … -delete`, `truncate`, `>`-truncate) the moment it's aimed at a memory path — *before* it runs, on both Claude Code (`Bash` / `PowerShell`) and Kiro (`execute_bash`). Fail-open (a broken guard never wedges your session) and intentionally broad (a false block is recoverable; a false allow is the data loss it prevents). A safe command, or a delete of anything else, runs untouched.
-- **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.
+<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)).
 
-## Install — pick ONE route
+## How it feels
 
-Each route is complete on its own. **Don't run both** — they wire the same hooks.
+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:
+
+```
+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
+
+- **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.
+
+## 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 install --ide kiro        # (optional) target Kiro instead — wires the IDE + kiro-cli surfaces (MCP + steering + AGENTS.md + skills + hooks)
-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:**
 
-> 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`.
+```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)):
 
-**Other agents (Kiro).** `cmk install --ide kiro` targets [Kiro](https://kiro.dev) (AWS's agentic IDE + `kiro-cli`) instead of Claude Code — one command wires both its GUI hooks (`.kiro/hooks/`) and its terminal CLI agent (`~/.aws/amazonq/cli-agents/`), plus MCP, steering, skills, and an `AGENTS.md` instruction file. A project can carry **both** agents (run both installs — they share one `context/` brain and never clobber each other). Restart Kiro to load its hooks.
+```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
+```
 
-**Uninstall** is per-agent and conservative — it never deletes your `context/` memory: `cmk uninstall` removes the Claude Code surface; `cmk uninstall --ide kiro` removes the Kiro surface.
+`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-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.4.0",
+  "version": "0.4.1",
   "description": "cmk — the CLI for claude-memory-kit. Per-project, in-repo memory system for Claude Code.",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
     "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-guard-memory": "./bin/cmk-guard-memory.mjs"
+    "cmk-guard-memory": "./bin/cmk-guard-memory.mjs",
+    "cmk-approve-permission": "./bin/cmk-approve-permission.mjs"
   },
   "files": [
     "bin/",

package/src/approve-permission.mjs

@@ -0,0 +1,92 @@
+// PermissionRequest auto-approve logic — the prompt-free fix (Task 172).
+//
+// Background (the v0.4.1 cut-gate, 2026-06-27). Claude Code 2.1.x tightened
+// permission matching so that neither the kit's `permissions.allow` MCP rules
+// (`mcp__cmk__*` + the specific names, Task 171) NOR a skill's `allowed-tools`
+// grant reliably suppress the per-tool MCP approval prompt or the "Use skill?"
+// prompt — see anthropics/claude-code#17499 (allowed-tools for MCP tools is
+// undocumented/unreliable) and #18837 → #14956 (allowed-tools not enforced).
+// The popup is a CLAUDE CODE change, not a kit regression: the skill + allow-list
+// config has been byte-stable since Task 108/117.
+//
+// The DOCUMENTED, working mechanism is a `PermissionRequest` hook
+// (code.claude.com/docs/en/hooks-guide#auto-approve-specific-permission-prompts):
+// it fires when CC is about to show a permission dialog, and a hook that writes
+// `{"behavior":"allow"}` answers it on the user's behalf — proven live (v041l):
+// the dialog flashes then auto-dismisses, the tool runs, no click required.
+//
+// This module decides — given the hook payload — whether to auto-approve. It
+// approves ONLY the kit's OWN surfaces (its MCP tools + its scaffolded skills),
+// never anything else. Two-layer safety: the wired matcher is already narrow
+// (`mcp__cmk__.*` / `Skill`), and this self-check is the second layer, so even a
+// loose matcher can't make the hook approve a non-kit tool. Returns `null` for
+// anything not kit-owned → the hook stays silent → CC's normal permission flow
+// runs unchanged.
+
+// The kit's own scaffolded skills (template/.claude/skills/<name>). Keep in sync
+// with the Skill(...) entries in settings-hooks.mjs KIT_ALLOW.
+const KIT_SKILLS = Object.freeze(['memory-write', 'memory-search']);
+
+// The allow decision shape CC expects on stdout for a PermissionRequest hook.
+export const ALLOW_DECISION = Object.freeze({
+  hookSpecificOutput: {
+    hookEventName: 'PermissionRequest',
+    decision: { behavior: 'allow' },
+  },
+});
+
+/**
+ * True iff `toolName` is one of the kit's own MCP tools (any `mcp__cmk__<tool>`).
+ */
+function isKitMcpTool(toolName) {
+  return typeof toolName === 'string' && toolName.startsWith('mcp__cmk__');
+}
+
+/**
+ * True iff this is an invocation of one of the kit's own scaffolded skills.
+ * The Skill tool surfaces the skill name either as the tool name's suffix
+ * (`Skill(memory-write)`) or in `tool_input.name`/`tool_input.skill` — accept
+ * either shape so a CC payload-format change doesn't silently stop matching.
+ *
+ * Security boundary: the `tool_input.name`/`skill` fallback is consulted ONLY
+ * when `tool_name` identifies the Skill tool (`Skill` or `Skill(...)`). Without
+ * that gate, a non-Skill request whose `tool_input` merely happened to carry
+ * `{name:"memory-write"}` (e.g. a `Bash` call) would match — defeating the
+ * second layer of defence-in-depth (the matcher is the first). We never read
+ * `tool_input` for a tool that isn't the Skill tool.
+ */
+function isKitSkill(toolName, toolInput) {
+  if (typeof toolName !== 'string') return false;
+  // The documented tool-name form for a skill invocation: `Skill(<name>)`.
+  for (const skill of KIT_SKILLS) {
+    if (toolName === `Skill(${skill})`) return true;
+  }
+  // Only trust the tool_input name shape for an actual Skill-tool request.
+  // (A bare `tool_name === "<skill>"` is NOT matched — it isn't a documented
+  // CC shape and would risk approving any unrelated tool that happened to share
+  // the name.)
+  if (toolName === 'Skill' || toolName.startsWith('Skill(')) {
+    const named = toolInput && (toolInput.name ?? toolInput.skill ?? toolInput.skillName);
+    if (typeof named === 'string' && KIT_SKILLS.includes(named)) return true;
+  }
+  return false;
+}
+
+/**
+ * Decide whether to auto-approve a PermissionRequest for a kit-owned surface.
+ *
+ * @param {object} payload - the hook payload from stdin
+ *   ({ tool_name, tool_input, ... }).
+ * @returns {object|null} the ALLOW_DECISION object to print on stdout, or null
+ *   when the request is NOT for a kit surface (the hook emits nothing → CC's
+ *   normal permission flow proceeds).
+ */
+export function evaluatePermissionRequest(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  const toolName = payload.tool_name;
+  const toolInput = payload.tool_input;
+  if (isKitMcpTool(toolName) || isKitSkill(toolName, toolInput)) {
+    return ALLOW_DECISION;
+  }
+  return null;
+}

package/src/auto-extract.mjs

@@ -858,18 +858,25 @@ export async function runAutoExtract({
         // ceiling is free. Live-test finding (2026-06-01, live-test-4 baseline).
         timeoutMs: 90_000,
       });
-      // Touch the cooldown marker IMMEDIATELY after the Haiku call
-      // resolves — this is the "we spent the budget" signal that
-      // compress-session.mjs reads to skip its own Haiku call within
-      // 120s of ours. Touching on success only (not in the catch below)
-      // would mean a failing Haiku in the auto-extract path doesn't
-      // block compress-session — which would then re-spend the budget
-      // on the failure. The catch path below also touches.
+      // Touch the cooldown marker after a SUCCESSFUL Haiku call — the
+      // "we spent the budget" signal compress-session.mjs reads to skip its
+      // own Haiku call within 120s of ours.
+      //
+      // **Original behavior (pre-Task-167, preserved as decision-trail):** the
+      // catch block below ALSO touched the cooldown ("spent the budget,
+      // succeeded OR failed"), so a failing Haiku here blocked compress-session
+      // for 120s — on the theory that a failure shouldn't let the next caller
+      // re-spend the budget on the same broken call.
+      // **Task 167.F change (D-207, Q5):** the cooldown now fires on SUCCESS
+      // ONLY. A FAILED call did NOT successfully spend the budget — blocking the
+      // next NEEDED compress for 120s after a *transient* failure is the wrong
+      // gate (it was the SECONDARY cause of the 410 KB now.md bloat: after the
+      // dead cron, failed-call cooldowns kept the roll skipped). Correctness >
+      // cost — a transient failure must be free to retry.
       touchCooldownMarker({ projectRoot, now: ts });
     } catch (err) {
-      // Spent the Haiku budget (succeeded OR failed); touch the
-      // cooldown so compress-session skips within 120s.
-      touchCooldownMarker({ projectRoot, now: ts });
+      // Task 167.F: do NOT touch the cooldown on failure (see the success-path
+      // comment above) — a failed call must not block the next compress's retry.
       // Route on the error TYPE — distinguishes "took too long"
       // (HAIKU_TIMEOUT) from "subprocess exited non-zero"
       // (HAIKU_FAILED). Using `instanceof HaikuTimeoutError`

package/src/auto-persona.mjs

@@ -336,12 +336,16 @@ export async function autoPersona(opts = {}) {
       // ceiling, so it passes a generous value — the explicit command can wait.
       timeoutMs,
     });
-    // Spent a Haiku call — refresh the shared cooldown marker so the next
-    // gated caller backs off. (touch even on cooldownMs:0 cycles: the call
+    // Spent a Haiku call SUCCESSFULLY — refresh the shared cooldown marker so the
+    // next gated caller backs off. (touch even on cooldownMs:0 cycles: the call
     // happened, so the marker should reflect it for any LATER gated caller.)
     touchCooldownMarker({ projectRoot, now: ts });
   } catch (err) {
-    touchCooldownMarker({ projectRoot, now: ts });
+    // Task 167.F (D-207, Q5): do NOT touch the cooldown on FAILURE — a failed
+    // Haiku call did not successfully spend the budget, and blocking the next
+    // needed compress for 120s after a transient failure is the wrong gate
+    // (correctness > cost; a transient failure must be free to retry). Original
+    // pre-167 behavior touched here too; preserved as decision-trail.
     return errorResult({
       category: ERROR_CATEGORIES.COMPRESS_FAILED,
       errors: [err?.message ?? String(err)],