@lh8ppl/claude-memory-kit 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,77 @@
+# @lh8ppl/claude-memory-kit
+
+**`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.
+
+## What it does
+
+- **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.
+- **`memory-write` skill** — say "remember this", "from now on", "we decided", or "forget X" and the skill dedups, caps, and writes silently.
+- **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.
+
+## Install — pick ONE route
+
+Each route is complete on its own. **Don't run both** — they wire the same hooks.
+
+### Route A — npm (recommended)
+
+```bash
+npm install -g @lh8ppl/claude-memory-kit
+cd ~/my-project
+cmk install        # scaffolds context/ AND wires the lifecycle hooks into .claude/settings.json
+cmk doctor         # verify, then restart Claude Code
+```
+
+`cmk install` is a complete entry point: it scaffolds `context/` 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.
+
+> 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`.
+
+### Route B — Claude Code plugin marketplace
+
+Inside Claude Code:
+
+```text
+/plugin marketplace add LH8PPL/claude-memory-kit
+/plugin install claude-memory-kit
+```
+
+Then say *"bootstrap the memory system"* to scaffold this project's `context/`. The plugin bundles the hooks + the `bootstrap` and `memory-write` skills, so it's complete without the npm CLI (add the CLI later only if you want `cmk search` / `cmk doctor` / cron).
+
+## CLI
+
+Most-used commands (full list via `cmk --help`):
+
+| Command | Purpose |
+| --- | --- |
+| `cmk install` | Scaffold `context/` + `.gitignore` + CLAUDE.md block + wire hooks (`--no-hooks` for scaffold-only) |
+| `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 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 import-anthropic-memory [--dry-run] [--yes]` | Merge bullets from Anthropic's native auto-memory into MEMORY.md |
+
+## Requirements
+
+- Node.js ≥ 20
+- Claude Code (for the hook-driven auto-memory loop)
+- Optional: Python 3.12+ for Layer 5b semantic search (deferred to a later release; keyword search ships today)
+
+## 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:
+**<https://github.com/LH8PPL/claude-memory-kit>**
+
+## License
+
+MIT © Lior Hollander

package/bin/cmk-auto-extract.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Auto-extract subagent entrypoint — npm-route bin (Task 49, T-037).
+//
+// De-plugin-ified twin of plugin/bin/cmk-auto-extract.mjs (Task 23).
+// NOT declared in package.json `bin` (it's not invoked by Claude Code
+// directly) — it ships in bin/ so the sibling cmk-capture-turn.mjs can
+// spawn it by absolute path. Only the src module paths differ from the
+// plugin copy (../src/ vs ../../packages/cli/src/).
+//
+// Spawned detached by the Stop hook (cmk-capture-turn.mjs):
+//   node <thisfile> <turnFile>
+// argv[2] is the turn buffer file path; cwd / CMK_PROJECT_DIR env gives
+// the project root. Never throws to the parent (the spawn is detached);
+// every error path writes an extract.log entry and exits 0.
+
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const turnFile = process.argv[2];
+const projectRoot = process.env.CMK_PROJECT_DIR ?? process.cwd();
+
+if (!turnFile) {
+  process.stderr.write('cmk-auto-extract: missing turnFile argv[2]\n');
+  process.exit(0);
+}
+
+const autoExtractModulePath = join(__dirname, '..', 'src', 'auto-extract.mjs');
+const compressorModulePath = join(__dirname, '..', 'src', 'compressor.mjs');
+
+let runAutoExtract;
+let HaikuViaAnthropicApi;
+try {
+  ({ runAutoExtract } = await import(pathToFileURL(autoExtractModulePath).href));
+  ({ HaikuViaAnthropicApi } = await import(pathToFileURL(compressorModulePath).href));
+} catch (err) {
+  process.stderr.write(
+    `cmk-auto-extract: failed to load modules: ${err?.message ?? err}\n`,
+  );
+  process.exit(0);
+}
+
+try {
+  const haikuBackend = new HaikuViaAnthropicApi();
+  const r = await runAutoExtract({
+    turnFile,
+    projectRoot,
+    haikuBackend,
+    sessionId: process.env.CMK_SESSION_ID,
+  });
+  process.stderr.write(
+    `cmk-auto-extract: ${r.action} (observations: ${r.observation_count ?? 0}, ms: ${r.duration_ms ?? 0})\n`,
+  );
+} catch (err) {
+  process.stderr.write(
+    `cmk-auto-extract: unexpected error: ${err?.message ?? err}\n`,
+  );
+}
+
+process.exit(0);

package/bin/cmk-capture-prompt.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// UserPromptSubmit hook handler — npm-route bin (Task 49, T-037).
+//
+// De-plugin-ified twin of plugin/bin/cmk-capture-prompt.mjs (Task 19).
+// Ships in the @lh8ppl/claude-memory-kit npm package so `cmk install`
+// can wire a PATH-resolved `cmk-capture-prompt` command. Only the src
+// module path differs from the plugin copy (../src/ vs ../../packages/cli/src/).
+//
+// Protocol: payload arrives on stdin as JSON ({prompt, session_id, ...}).
+// Sanitize <private> blocks, preserve <retain> tags, append to the daily
+// 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';
+
+function emitContinue() {
+  process.stdout.write('{"continue": true}');
+}
+
+let rawInput = '';
+try {
+  rawInput = readFileSync(0, 'utf8');
+} catch {
+  emitContinue();
+  process.exit(0);
+}
+
+let payload;
+try {
+  payload = rawInput.trim() === '' ? {} : JSON.parse(rawInput);
+} catch (err) {
+  process.stderr.write(
+    `cmk-capture-prompt: failed to parse stdin JSON: ${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');
+
+let capturePrompt;
+try {
+  ({ capturePrompt } = await import(pathToFileURL(modulePath).href));
+} catch (err) {
+  process.stderr.write(
+    `cmk-capture-prompt: failed to load module: ${err?.message ?? err}\n`,
+  );
+  emitContinue();
+  process.exit(0);
+}
+
+try {
+  capturePrompt({ payload, projectRoot: process.cwd() });
+} catch (err) {
+  process.stderr.write(
+    `cmk-capture-prompt: handler failed: ${err?.message ?? err}\n`,
+  );
+}
+
+emitContinue();
+process.exit(0);

package/bin/cmk-capture-turn.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// Stop hook handler — npm-route bin (Task 49, T-037).
+//
+// De-plugin-ified twin of plugin/bin/cmk-capture-turn.mjs (Task 21).
+// Ships in the @lh8ppl/claude-memory-kit npm package so `cmk install`
+// can wire a PATH-resolved `cmk-capture-turn` command. Two differences
+// from the plugin copy:
+//   1. src module path resolves ../src/ (not ../../packages/cli/src/).
+//   2. the detached auto-extract subagent resolves to the sibling
+//      cmk-auto-extract.mjs in THIS bin/ dir (it ships alongside).
+//
+// Protocol: payload arrives on stdin as JSON. Honor stop_hook_active,
+// 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 { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+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 modulePath = join(__dirname, '..', 'src', 'capture-turn.mjs');
+
+// Auto-extract path: env override → sibling cmk-auto-extract.mjs (ships
+// in this same bin/ dir). Absent only in a corrupt install; the spawn
+// step is skipped if missing.
+const autoExtractPath =
+  process.env.CMK_AUTO_EXTRACT_PATH ??
+  (existsSync(join(__dirname, 'cmk-auto-extract.mjs'))
+    ? join(__dirname, 'cmk-auto-extract.mjs')
+    : null);
+
+let captureTurn;
+try {
+  ({ captureTurn } = await import(pathToFileURL(modulePath).href));
+} catch (err) {
+  process.stderr.write(
+    `cmk-capture-turn: failed to load module: ${err?.message ?? err}\n`,
+  );
+  emitContinue();
+  process.exit(0);
+}
+
+try {
+  captureTurn({ payload, projectRoot: process.cwd(), autoExtractPath });
+} catch (err) {
+  process.stderr.write(
+    `cmk-capture-turn: handler failed: ${err?.message ?? err}\n`,
+  );
+}
+
+emitContinue();
+process.exit(0);

package/bin/cmk-compress-session.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// SessionEnd hook handler — npm-route bin (Task 49, T-037).
+//
+// De-plugin-ified twin of plugin/bin/cmk-compress-session.mjs (Task 22).
+// Ships in the @lh8ppl/claude-memory-kit npm package so `cmk install`
+// can wire a PATH-resolved `cmk-compress-session` command. Only the src
+// module paths differ from the plugin copy (../src/ vs ../../packages/cli/src/).
+//
+// Protocol: drain stdin, resolve project root from CMK_PROJECT_DIR env
+// or cwd, run compressSession() with a real HaikuViaAnthropicApi, emit
+// {"continue": true}. Always exit 0 — a crashed SessionEnd hook would
+// block the user from closing their terminal.
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+function emitContinue() {
+  process.stdout.write('{"continue": true}');
+}
+
+let rawInput = '';
+try {
+  rawInput = readFileSync(0, 'utf8');
+} catch {
+  // stdin not connected — fine; SessionEnd still proceeds.
+}
+void rawInput;
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const compressSessionModulePath = join(__dirname, '..', 'src', 'compress-session.mjs');
+const compressorModulePath = join(__dirname, '..', 'src', 'compressor.mjs');
+
+let compressSession;
+let HaikuViaAnthropicApi;
+try {
+  ({ compressSession } = await import(pathToFileURL(compressSessionModulePath).href));
+  ({ HaikuViaAnthropicApi } = await import(pathToFileURL(compressorModulePath).href));
+} catch (err) {
+  process.stderr.write(
+    `cmk-compress-session: failed to load modules: ${err?.message ?? err}\n`,
+  );
+  emitContinue();
+  process.exit(0);
+}
+
+const projectRoot = process.env.CMK_PROJECT_DIR ?? process.cwd();
+
+try {
+  const backend = new HaikuViaAnthropicApi();
+  const r = await compressSession({ projectRoot, backend });
+  process.stderr.write(
+    `cmk-compress-session: ${r.action}${r.reason ? ` (${r.reason})` : ''}${r.bytesIn ? ` (in: ${r.bytesIn}b, out: ${r.bytesOut}b)` : ''} ms: ${r.duration_ms ?? 0}\n`,
+  );
+} catch (err) {
+  process.stderr.write(
+    `cmk-compress-session: unexpected error: ${err?.message ?? err}\n`,
+  );
+}
+
+emitContinue();
+process.exit(0);

package/bin/cmk-inject-context.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// SessionStart hook handler — npm-route bin (Task 49, T-037).
+//
+// De-plugin-ified twin of plugin/bin/cmk-inject-context.mjs (Task 18).
+// This copy lives in the published @lh8ppl/claude-memory-kit npm package
+// (declared in package.json `bin`), so `cmk install` can wire a
+// PATH-resolved `cmk-inject-context` hook command into settings.json
+// WITHOUT the plugin's `${CLAUDE_PLUGIN_ROOT}` / bash dependency. The
+// only difference from the plugin copy is the src module path: here it
+// resolves ../src/ (bin/ → src/), not ../../packages/cli/src/.
+//
+// Protocol: payload arrives on stdin as JSON (drained, not consumed).
+// Emit the Anthropic SessionStart hookOutput JSON on stdout. Exit 0
+// unconditionally — a throwing SessionStart hook would interrupt
+// session start, worse than an empty additionalContext.
+
+import { readFileSync } 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 modulePath = join(__dirname, '..', 'src', 'inject-context.mjs');
+
+let injectContext;
+try {
+  ({ 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`,
+  );
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: '',
+      },
+    }),
+  );
+  process.exit(0);
+}
+
+try {
+  const r = injectContext({ cwd: process.cwd() });
+  process.stdout.write(JSON.stringify(r.hookOutput));
+  process.exit(0);
+} catch (err) {
+  process.stderr.write(
+    `cmk-inject-context: handler failed: ${err?.message ?? String(err)}\n`,
+  );
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: '',
+      },
+    }),
+  );
+  process.exit(0);
+}

package/bin/cmk-observe-edit.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// PostToolUse hook handler — npm-route bin (Task 49, T-037).
+//
+// De-plugin-ified twin of plugin/bin/cmk-observe-edit.mjs (Task 20).
+// Ships in the @lh8ppl/claude-memory-kit npm package so `cmk install`
+// can wire a PATH-resolved `cmk-observe-edit` command (registered
+// async: true in the hooks block). Only the src module path differs
+// from the plugin copy (../src/ vs ../../packages/cli/src/).
+//
+// All errors are swallowed + logged to stderr — a hook child crashing
+// 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);
+}
+
+let payload;
+try {
+  payload = raw.trim() === '' ? {} : JSON.parse(raw);
+} catch (err) {
+  process.stderr.write(
+    `cmk-observe-edit: failed to parse stdin JSON: ${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');
+
+let observeEdit;
+try {
+  ({ observeEdit } = await import(pathToFileURL(modulePath).href));
+} catch (err) {
+  process.stderr.write(
+    `cmk-observe-edit: failed to load module: ${err?.message ?? err}\n`,
+  );
+  process.exit(0);
+}
+
+try {
+  observeEdit({ payload, projectRoot: process.cwd() });
+} catch (err) {
+  process.stderr.write(
+    `cmk-observe-edit: handler failed: ${err?.message ?? err}\n`,
+  );
+}
+
+process.exit(0);

package/bin/cmk.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
-// cmk — claude-memory-kit CLI entry point.
-// Thin shim: defers all argv parsing + dispatch to src/index.mjs.
-// Kept thin so the bin file rarely needs to change once installed.
-
-import { run } from '../src/index.mjs';
-
-run(process.argv).catch((err) => {
-  console.error('cmk: unexpected error');
-  console.error(err && err.stack ? err.stack : err);
-  process.exit(1);
-});
+// cmk — claude-memory-kit CLI entry point.
+// Thin shim: defers all argv parsing + dispatch to src/index.mjs.
+// Kept thin so the bin file rarely needs to change once installed.
+
+import { run } from '../src/index.mjs';
+
+run(process.argv).catch((err) => {
+  console.error('cmk: unexpected error');
+  console.error(err && err.stack ? err.stack : err);
+  process.exit(1);
+});

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@lh8ppl/claude-memory-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "cmk — the CLI for claude-memory-kit. Per-project, in-repo memory system for Claude Code.",
   "type": "module",
   "bin": {
     "cmk": "./bin/cmk.mjs",
     "cmk-daily-distill": "./bin/cmk-daily-distill.mjs",
     "cmk-weekly-curate": "./bin/cmk-weekly-curate.mjs",
-    "cmk-compress-lazy": "./bin/cmk-compress-lazy.mjs"
+    "cmk-compress-lazy": "./bin/cmk-compress-lazy.mjs",
+    "cmk-inject-context": "./bin/cmk-inject-context.mjs",
+    "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"
   },
   "files": [
     "bin/",
@@ -40,6 +45,9 @@
     "url": "https://github.com/LH8PPL/claude-memory-kit.git",
     "directory": "packages/cli"
   },
+  "bugs": {
+    "url": "https://github.com/LH8PPL/claude-memory-kit/issues"
+  },
   "keywords": [
     "claude",
     "claude-code",

package/src/audit-log.mjs

@@ -44,6 +44,7 @@ export const REASON_CODES = Object.freeze({
   IMPORT_SKIPPED_DUPLICATE: 'import-skipped-duplicate', // import-anthropic-memory: candidate canonicalize-matched existing fact, skipped (Task 38)
   REPAIR_HOOKS_APPLIED: 'repair-hooks-applied', // cmk repair --hooks: settings.json updated with canonical kit hooks (Task 39)
   REPAIR_HOOKS_NOOP: 'repair-hooks-noop', // cmk repair --hooks: settings.json already canonical, no-op (Task 39)
+  INSTALL_HOOKS_WIRED: 'install-hooks-wired', // cmk install: settings.json wired with npm-route hooks (Task 49). NOTE: no NOOP counterpart — install audits only on change, to keep re-runs byte-idempotent (the audit.log is append-only).
   REPAIR_LOCK_REMOVED: 'repair-lock-removed', // cmk repair --locks: stale lock unlinked (Task 39)
 });