@lh8ppl/claude-memory-kit 0.2.1 → 0.2.3

package/README.md

@@ -6,10 +6,10 @@
 
 - **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.
-- **Auto-extract on every assistant turn** — a background `claude --print` subagent reads each turn and saves durable facts (decisions, preferences, environment) to memory. No manual writes needed.
-- **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.
-- **Search + MCP** — `cmk search "<term>"` (keyword/hybrid over facts + scratchpads); `cmk mcp` exposes the same to Claude Code as tools.
-- **Bounded by compression** — session → daily → weekly Haiku rollups (cron or lazy-on-read) keep the snapshot small as history grows.
+- **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.
+- **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/hybrid over facts + scratchpads). `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.
 - **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 install, hook wiring, distill freshness, INDEX consistency, cron registration, and stale locks.
 
@@ -26,7 +26,7 @@ cmk install        # scaffolds context/ + the memory-write skill AND wires the l
 cmk doctor         # verify, then restart Claude Code
 ```
 
-`cmk install` is a complete entry point: it scaffolds `context/`, drops the `memory-write` skill 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`. No separate `/plugin` step needed. Use `cmk install --no-hooks` for a scaffold-only install.
+`cmk install` is a complete entry point: it scaffolds `context/`, drops the `memory-write` skill 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. No separate `/plugin` step needed. Use `cmk install --no-hooks` to skip the hooks + MCP wiring (scaffold-only).
 
 > 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`.
 
@@ -51,9 +51,10 @@ Most-used commands (full list via `cmk --help`):
 | `cmk doctor` | Run HC-1..HC-9 health checks, surface repair commands |
 | `cmk repair --hooks` / `--locks` / `--index` / `--all` | Idempotent self-repair |
 | `cmk search "<query>" [--mode keyword\|semantic\|hybrid]` | Search accumulated memory (keyword default) |
+| `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 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 (preserves audit trail) |
+| `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) |

package/bin/cmk-capture-prompt.mjs

@@ -11,7 +11,6 @@
 // transcript, emit {"continue": true}. Always exit 0 — a hook that errors
 // would interrupt the user mid-prompt.
 
-import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
@@ -19,35 +18,36 @@ function emitContinue() {
   process.stdout.write('{"continue": true}');
 }
 
-let rawInput = '';
-try {
-  rawInput = readFileSync(0, 'utf8');
-} catch {
-  emitContinue();
-  process.exit(0);
-}
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const readHookStdinPath = join(__dirname, '..', 'src', 'read-hook-stdin.mjs');
+const modulePath = join(__dirname, '..', 'src', 'capture-prompt.mjs');
 
-let payload;
+let readHookStdin;
+let capturePrompt;
 try {
-  payload = rawInput.trim() === '' ? {} : JSON.parse(rawInput);
+  ({ readHookStdin } = await import(pathToFileURL(readHookStdinPath).href));
+  ({ capturePrompt } = await import(pathToFileURL(modulePath).href));
 } catch (err) {
   process.stderr.write(
-    `cmk-capture-prompt: failed to parse stdin JSON: ${err?.message ?? err}\n`,
+    `cmk-capture-prompt: failed to load modules: ${err?.message ?? err}\n`,
   );
   emitContinue();
   process.exit(0);
 }
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const modulePath = join(__dirname, '..', 'src', 'capture-prompt.mjs');
+// Drain the hook payload — but NOT on an interactive TTY (a manual run):
+// a blocking stdin read would hang forever on a console that never sends EOF, before
+// any body runs (Task 101; DECISION-LOG 2026-06-06). readHookStdin returns ''
+// for a TTY so a manual invocation finishes instead of hanging.
+const rawInput = readHookStdin({ isTTY: process.stdin.isTTY });
 
-let capturePrompt;
+let payload;
 try {
-  ({ capturePrompt } = await import(pathToFileURL(modulePath).href));
+  payload = rawInput.trim() === '' ? {} : JSON.parse(rawInput);
 } catch (err) {
   process.stderr.write(
-    `cmk-capture-prompt: failed to load module: ${err?.message ?? err}\n`,
+    `cmk-capture-prompt: failed to parse stdin JSON: ${err?.message ?? err}\n`,
   );
   emitContinue();
   process.exit(0);

package/bin/cmk-capture-turn.mjs

@@ -13,7 +13,7 @@
 // append to transcripts, spawn detached auto-extract, emit
 // {"continue": true}, exit 0 within ~50ms (NFR-1). Always exit 0.
 
-import { readFileSync, existsSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
@@ -21,27 +21,9 @@ function emitContinue() {
   process.stdout.write('{"continue": true}');
 }
 
-let raw = '';
-try {
-  raw = readFileSync(0, 'utf8');
-} catch {
-  emitContinue();
-  process.exit(0);
-}
-
-let payload;
-try {
-  payload = raw.trim() === '' ? {} : JSON.parse(raw);
-} catch (err) {
-  process.stderr.write(
-    `cmk-capture-turn: failed to parse stdin JSON: ${err?.message ?? err}\n`,
-  );
-  emitContinue();
-  process.exit(0);
-}
-
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+const readHookStdinPath = join(__dirname, '..', 'src', 'read-hook-stdin.mjs');
 const modulePath = join(__dirname, '..', 'src', 'capture-turn.mjs');
 
 // Auto-extract path: env override → sibling cmk-auto-extract.mjs (ships
@@ -53,12 +35,31 @@ const autoExtractPath =
     ? join(__dirname, 'cmk-auto-extract.mjs')
     : null);
 
+let readHookStdin;
 let captureTurn;
 try {
+  ({ readHookStdin } = await import(pathToFileURL(readHookStdinPath).href));
   ({ captureTurn } = await import(pathToFileURL(modulePath).href));
 } catch (err) {
   process.stderr.write(
-    `cmk-capture-turn: failed to load module: ${err?.message ?? err}\n`,
+    `cmk-capture-turn: failed to load modules: ${err?.message ?? err}\n`,
+  );
+  emitContinue();
+  process.exit(0);
+}
+
+// Drain the hook payload — but NOT on an interactive TTY (a manual run):
+// a blocking stdin read would hang forever on a console that never sends EOF, before
+// any body runs (Task 101; DECISION-LOG 2026-06-06). readHookStdin returns ''
+// for a TTY so a manual invocation finishes instead of hanging.
+const raw = readHookStdin({ isTTY: process.stdin.isTTY });
+
+let payload;
+try {
+  payload = raw.trim() === '' ? {} : JSON.parse(raw);
+} catch (err) {
+  process.stderr.write(
+    `cmk-capture-turn: failed to parse stdin JSON: ${err?.message ?? err}\n`,
   );
   emitContinue();
   process.exit(0);

package/bin/cmk-compress-session.mjs

@@ -43,8 +43,8 @@ try {
 }
 
 // Drain the hook payload so Claude Code's pipe closes cleanly — but NOT when
-// stdin is an interactive TTY (a manual run): readFileSync(0) would block
-// forever on a console that never sends EOF, hanging before any of the body
+// stdin is an interactive TTY (a manual run): a blocking stdin read would hang
+// forever on a console that never sends EOF, before any of the body
 // runs (DECISION-LOG 2026-06-06). The payload is discarded; we read state from
 // disk. readHookStdin returns '' for a TTY so a manual invocation finishes.
 readHookStdin({ isTTY: process.stdin.isTTY });

package/bin/cmk-inject-context.mjs

@@ -14,19 +14,13 @@
 // unconditionally — a throwing SessionStart hook would interrupt
 // session start, worse than an empty additionalContext.
 
-import { readFileSync, existsSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-// Drain stdin so callers blocking on EPIPE don't hang.
-try {
-  readFileSync(0, 'utf8');
-} catch {
-  // stdin not connected; fine.
-}
-
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+const readHookStdinPath = join(__dirname, '..', 'src', 'read-hook-stdin.mjs');
 const modulePath = join(__dirname, '..', 'src', 'inject-context.mjs');
 
 // Resolve the sibling lazy-compress bin (ships in this same bin/ dir) so
@@ -39,14 +33,14 @@ const compressLazyPath =
     ? join(__dirname, 'cmk-compress-lazy.mjs')
     : null);
 
+let readHookStdin;
 let injectContext;
 try {
+  ({ readHookStdin } = await import(pathToFileURL(readHookStdinPath).href));
   ({ injectContext } = await import(pathToFileURL(modulePath).href));
 } catch (err) {
   process.stderr.write(
-    `cmk-inject-context: failed to load module at ${modulePath}: ${
-      err?.message ?? String(err)
-    }\n`,
+    `cmk-inject-context: failed to load modules: ${err?.message ?? String(err)}\n`,
   );
   process.stdout.write(
     JSON.stringify({
@@ -59,6 +53,12 @@ try {
   process.exit(0);
 }
 
+// Drain stdin so callers blocking on EPIPE don't hang — but NOT on an
+// interactive TTY (a manual run): a blocking stdin read would hang forever on a
+// console that never sends EOF (Task 101; DECISION-LOG 2026-06-06). The payload
+// is discarded; readHookStdin returns '' for a TTY so a manual run finishes.
+readHookStdin({ isTTY: process.stdin.isTTY });
+
 try {
   const r = injectContext({ cwd: process.cwd(), compressLazyPath });
   process.stdout.write(JSON.stringify(r.hookOutput));

package/bin/cmk-observe-edit.mjs

@@ -11,37 +11,38 @@
 // must never surface in the user's session. The append is
 // fire-and-forget by design.
 
-import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-let raw = '';
-try {
-  raw = readFileSync(0, 'utf8');
-} catch {
-  process.exit(0);
-}
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const readHookStdinPath = join(__dirname, '..', 'src', 'read-hook-stdin.mjs');
+const modulePath = join(__dirname, '..', 'src', 'observe-edit.mjs');
 
-let payload;
+let readHookStdin;
+let observeEdit;
 try {
-  payload = raw.trim() === '' ? {} : JSON.parse(raw);
+  ({ readHookStdin } = await import(pathToFileURL(readHookStdinPath).href));
+  ({ observeEdit } = await import(pathToFileURL(modulePath).href));
 } catch (err) {
   process.stderr.write(
-    `cmk-observe-edit: failed to parse stdin JSON: ${err?.message ?? err}\n`,
+    `cmk-observe-edit: failed to load modules: ${err?.message ?? err}\n`,
   );
   process.exit(0);
 }
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const modulePath = join(__dirname, '..', 'src', 'observe-edit.mjs');
+// Drain the hook payload — but NOT on an interactive TTY (a manual run):
+// a blocking stdin read would hang forever on a console that never sends EOF, before
+// any body runs (Task 101; DECISION-LOG 2026-06-06). readHookStdin returns ''
+// for a TTY so a manual invocation finishes instead of hanging.
+const raw = readHookStdin({ isTTY: process.stdin.isTTY });
 
-let observeEdit;
+let payload;
 try {
-  ({ observeEdit } = await import(pathToFileURL(modulePath).href));
+  payload = raw.trim() === '' ? {} : JSON.parse(raw);
 } catch (err) {
   process.stderr.write(
-    `cmk-observe-edit: failed to load module: ${err?.message ?? err}\n`,
+    `cmk-observe-edit: failed to parse stdin JSON: ${err?.message ?? err}\n`,
   );
   process.exit(0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lh8ppl/claude-memory-kit",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "cmk — the CLI for claude-memory-kit. Per-project, in-repo memory system for Claude Code.",
   "type": "module",
   "bin": {

package/src/audit-log.mjs

@@ -30,6 +30,7 @@ export const AUDIT_LOG_SCHEMA_VERSION = 1;
 // they come online; the rule is one canonical machine-parseable token per
 // kind of audit event (not a free-text reason field).
 export const REASON_CODES = Object.freeze({
+  FACT_CREATED: 'fact-created', // writeFact: a new fact file was written (Task 123.A — the default create audit; callers emitting a richer code opt out via audit:false)
   DUPLICATE: 'duplicate', // writeFact: same path + same id
   DUPLICATE_ELSEWHERE: 'duplicate-elsewhere', // writeFact: different path + same id
   USER_REQUESTED: 'user-requested', // forget: user-initiated tombstone