@lh8ppl/claude-memory-kit 0.1.0 → 0.1.2

package/src/spawn-bin.mjs

@@ -0,0 +1,83 @@
+// spawn-bin.mjs — cross-platform subprocess spawning that AVOIDS the
+// `shell:true` + args-array combination (self-test finding #4).
+//
+// Why this exists
+// ---------------
+// Spawning an npm-global bin (claude, memsearch, cmk-*) needs `shell:true` on
+// Windows so the `.cmd` shim resolves through cmd.exe — Node won't auto-resolve
+// `.cmd`/`.bat` without a shell (CVE-2024-27980 hardening). But `shell:true`
+// WITH an args array is doubly bad:
+//   1. Node emits DEP0190 ("passing args to a child process with shell:true …
+//      arguments are not escaped, only concatenated").
+//   2. The args ARE concatenated unescaped, so a path containing a space
+//      (e.g. `--mcp-config C:\Users\First Last\…\empty-mcp.json` under tmpdir)
+//      is re-tokenized by cmd.exe and breaks parsing — silently failing
+//      auto-extract/compression for any Windows user whose profile has a space.
+//
+// The fix: never pass an args array together with shell:true.
+//   - POSIX: spawn(bin, args, {shell:false}) — Node resolves PATH directly and
+//     passes argv safely. No shell, no concatenation.
+//   - Windows: shell:true with a SINGLE pre-quoted command string (no args
+//     array) — clears DEP0190 and lets us quote each arg so spaces survive.
+//
+// The kit's spawn args are controlled (flags + filesystem paths, never
+// user-supplied shell text), so cmd.exe double-quoting is sufficient: inside
+// double-quotes cmd.exe treats &|<>^ as literal; `%` is the only residual
+// special char and kit paths/flags never contain it.
+
+import { spawn, spawnSync } from 'node:child_process';
+
+/**
+ * Quote one argument for a cmd.exe command line. Quotes args that contain a
+ * space or a double-quote, AND empty-string args (an unquoted empty arg would
+ * vanish and shift the next token into its value slot — the compressor passes
+ * `--allowed-tools ''`). Embedded double-quotes are doubled.
+ */
+function quoteWinArg(s) {
+  const str = String(s);
+  if (str === '' || /[\s"]/.test(str)) {
+    // Double embedded double-quotes, AND double any trailing backslash run so
+    // a quoted value ending in `\` (e.g. a directory path with a space) does
+    // NOT escape the closing quote — the classic Windows CommandLineToArgv /
+    // cmd.exe footgun (`"C:\dir\"` parses as `C:\dir"`).
+    const escaped = str.replace(/"/g, '""').replace(/(\\+)$/, '$1$1');
+    return `"${escaped}"`;
+  }
+  return str;
+}
+
+/**
+ * Build the single cmd.exe command string for a Windows `shell:true` spawn.
+ * Exported for direct unit testing of the quoting (platform-independent).
+ */
+export function winCommandLine(bin, args = []) {
+  return [bin, ...args].map(quoteWinArg).join(' ');
+}
+
+/**
+ * Spawn a bin cross-platform without ever pairing `shell:true` with an args
+ * array. `deps` allows tests to inject a recording spawn + force a platform:
+ *   deps.spawnImpl — defaults to node:child_process spawn (compressor injects
+ *                    its own for the kill-chain / testability).
+ *   deps.platform  — defaults to process.platform.
+ * Returns whatever the spawn impl returns (a ChildProcess in production).
+ */
+export function spawnBin(bin, args = [], opts = {}, deps = {}) {
+  const { spawnImpl = spawn, platform = process.platform } = deps;
+  // spawn-discipline: ignore pass-through helper — timeout/kill is the
+  // caller's contract (compressor terminateSubprocess + setTimeout; doctor
+  // timeout:3500), not this wrapper's.
+  if (platform === 'win32') {
+    return spawnImpl(winCommandLine(bin, args), { ...opts, shell: true });
+  }
+  return spawnImpl(bin, args, { ...opts, shell: false });
+}
+
+/** Synchronous twin of spawnBin (for one-shot checks like `cmk doctor`'s memsearch probe). */
+export function spawnBinSync(bin, args = [], opts = {}, deps = {}) {
+  const { spawnImpl = spawnSync, platform = process.platform } = deps;
+  if (platform === 'win32') {
+    return spawnImpl(winCommandLine(bin, args), { ...opts, shell: true });
+  }
+  return spawnImpl(bin, args, { ...opts, shell: false });
+}

package/src/subcommands.mjs

@@ -19,6 +19,7 @@ import { reindex as reindexAction } from './reindex.mjs';
 import { openIndexDb } from './index-db.mjs';
 import { reindexBoot, reindexFull } from './index-rebuild.mjs';
 import { search as searchAction, SEARCH_MODES } from './search.mjs';
+import { memoryWrite } from './memory-write.mjs';
 import { runMcpServer } from './mcp-server.mjs';
 import { dailyDistill } from './daily-distill.mjs';
 import { weeklyCurate } from './weekly-curate.mjs';
@@ -50,7 +51,7 @@ import { overrideTrust as overrideTrustAction } from './trust.mjs';
 import { resolveConflictQueue, mergeScratchpadBullets } from './conflict-queue.mjs';
 import { resolveReviewQueue } from './review-queue.mjs';
 import { createInterface } from 'node:readline';
-import { resolve as resolvePath, join } from 'node:path';
+import { resolve as resolvePath, join, basename } from 'node:path';
 
 const NOTICE_PREFIX = 'not yet implemented in v0.1.0';
 
@@ -62,14 +63,53 @@ const NOTICE_PREFIX = 'not yet implemented in v0.1.0';
  * replaced / upgraded / downgrade-blocked / forced-downgrade / unchanged).
  */
 async function runInstall(options /* , command */) {
-  const result = await installAction({ force: !!(options && options.force) });
-  const parts = [
-    `scaffolded ${result.created.length} file(s)`,
-    result.skipped.length ? `skipped ${result.skipped.length} existing` : null,
-    `.gitignore=${result.gitignore.action}`,
-    `CLAUDE.md=${result.claudeMd.action}`,
-  ].filter(Boolean);
-  console.log('cmk install: ' + parts.join(', '));
+  // commander maps `--no-hooks` to options.hooks === false.
+  const noHooks = !!(options && options.hooks === false);
+  const verbose = !!(options && options.verbose);
+  const result = await installAction({ force: !!(options && options.force), noHooks });
+
+  // Outcome over inventory (self-test UX finding): state the resulting state +
+  // next action, not a file tally. The old "scaffolded 5, skipped 4 existing"
+  // read like a problem on a FRESH folder — the "skipped" are the cross-project
+  // user tier at ~/.claude-memory-kit/ (OUTSIDE this folder), already on disk.
+  // The full per-tier breakdown is --verbose only.
+  const projectName = basename(resolvePath(process.cwd()));
+  const wired =
+    result.hooks.action === 'wired' || result.hooks.action === 'unchanged';
+  const broughtSomethingNew =
+    result.created.length > 0 ||
+    result.gitignore.action === 'created' ||
+    result.claudeMd.action === 'created';
+
+  if (broughtSomethingNew) {
+    console.log(
+      `cmk install: ${projectName} ready — context/ scaffolded${
+        wired ? ', hooks wired' : ''
+      }.`,
+    );
+  } else {
+    console.log(
+      `cmk install: ${projectName} already set up (your edits preserved)${
+        wired ? ', hooks refreshed' : ''
+      }.`,
+    );
+  }
+  if (wired) {
+    console.log(
+      '  Restart Claude Code to activate. Complete install — no separate /plugin step needed.',
+    );
+  }
+  if (verbose) {
+    console.log(
+      `  files: ${result.created.length} created, ${result.skipped.length} already present` +
+        (result.skipped.length
+          ? ' (incl. the cross-project user tier at ~/.claude-memory-kit/, outside this folder)'
+          : ''),
+    );
+    console.log(
+      `  .gitignore=${result.gitignore.action} · CLAUDE.md=${result.claudeMd.action} · hooks=${result.hooks.action}`,
+    );
+  }
 
   if (result.claudeMd.action === 'downgrade-blocked') {
     console.error(
@@ -168,9 +208,28 @@ function runTrust(id, level /* , options, command */) {
  */
 function runSearch(queryParts, options) {
   const projectRoot = resolvePath(process.cwd());
+  const userDir =
+    process.env.MEMORY_KIT_USER_DIR ?? join(homedir(), '.claude-memory-kit');
   const query = Array.isArray(queryParts) ? queryParts.join(' ') : queryParts;
   const db = openIndexDb({ projectRoot });
   try {
+    // Refresh the index before querying. On a fresh install the FTS5 index
+    // is empty (auto-extract writes facts to MEMORY.md but doesn't reindex,
+    // and the runtime chokidar watcher isn't running for a one-shot CLI
+    // call), so without this `cmk search` returns "no results" for facts
+    // that are sitting right there in the scratchpads (self-test finding
+    // #0). reindexBoot is incremental — mtime/sha1 diff, only changed files
+    // — so it's cheap to run on every search. Degrade gracefully: a reindex
+    // failure falls back to whatever's already indexed rather than crashing
+    // the query.
+    try {
+      reindexBoot({ projectRoot, userDir, db });
+    } catch (err) {
+      console.error(
+        `cmk search: index refresh failed (${err?.message ?? err}); ` +
+          'searching the existing index. Run `cmk reindex --full` if results look stale.',
+      );
+    }
     const r = searchAction({
       db,
       query,
@@ -225,6 +284,67 @@ function runSearch(queryParts, options) {
  * (b) keeping it always-current avoids users having to think about which
  * index to rebuild when.
  */
+/**
+ * `cmk remember <text...>` — explicit durable capture (write-path fix #0b).
+ *
+ * Writes a provenance-tracked bullet to MEMORY.md (the session-start-recalled
+ * layer) through the SAME hardened path as auto-extract: Poison_Guard +
+ * home-path abstraction (#1) + conflict detection + dedup. This is the entry
+ * the scaffolded CLAUDE.md points the agent at INSTEAD of freehand-writing
+ * fact files — which produced wrong-schema, unindexable, username-leaking
+ * files in the self-test. Guaranteed-correct because it never touches raw
+ * frontmatter.
+ *
+ * Tier: v0.1.0 writes tier P (project MEMORY.md). U/L need per-tier scratchpad
+ * routing (same deferral as mk_remember, design §16) — the always-on home-path
+ * abstraction is the privacy net regardless of tier.
+ */
+function runRemember(textParts, options) {
+  const projectRoot = resolvePath(process.cwd());
+  const userDir =
+    process.env.MEMORY_KIT_USER_DIR ?? join(homedir(), '.claude-memory-kit');
+  const text = Array.isArray(textParts) ? textParts.join(' ') : textParts;
+  const tier = options?.tier ?? 'P';
+  if (tier !== 'P') {
+    console.error(
+      `cmk remember: tier '${tier}' not yet supported — v0.1.0 writes the project tier (P). ` +
+        'For machine-only config, edit context.local/machine-paths.md directly (v0.1.x will add --tier routing).',
+    );
+    process.exitCode = 2;
+    return;
+  }
+  const trust = options?.trust ?? 'high';
+  const section = options?.section ?? 'Active Threads';
+  const r = memoryWrite({
+    action: 'add',
+    text,
+    tier,
+    scratchpad: 'MEMORY.md',
+    section,
+    trust,
+    source: 'user-explicit',
+    projectRoot,
+    userDir,
+  });
+  if (r.action === 'error') {
+    for (const e of r.errors ?? [`error (${r.errorCategory})`]) {
+      console.error(`cmk remember: ${e}`);
+    }
+    process.exitCode = 2;
+    return;
+  }
+  if (r.action === 'queued') {
+    console.log(
+      `cmk remember: queued for review — a higher-trust fact already covers this. ` +
+        `Resolve with \`cmk queue conflicts\` (${r.path}).`,
+    );
+    return;
+  }
+  console.log(
+    `cmk remember: saved to P/MEMORY.md (${section})${r.id ? ` [${r.id}]` : ''}`,
+  );
+}
+
 function runReindex(options /* , command */) {
   const projectRoot = resolvePath(process.cwd());
   const userDir = join(homedir(), '.claude-memory-kit');
@@ -1007,10 +1127,12 @@ function stub(name, milestone, extra) {
 export const subcommands = [
   {
     name: 'install',
-    description: 'cross-OS one-shot install — scaffold 3-tier dirs + inject .gitignore + drop kit CLAUDE.md block',
+    description: 'cross-OS one-shot install — scaffold 3-tier dirs + inject .gitignore + drop kit CLAUDE.md block + wire Claude Code hooks',
     milestone: 3,
     optionSpec: [
       { flags: '--force', description: 'allow downgrade of an existing newer-version CLAUDE.md block' },
+      { flags: '--no-hooks', description: 'scaffold only; do NOT wire hooks into .claude/settings.json' },
+      { flags: '--verbose', description: 'show the per-tier created/skipped file breakdown' },
     ],
     action: runInstall,
   },
@@ -1026,6 +1148,18 @@ export const subcommands = [
     milestone: 14,
     action: runInitUserTier,
   },
+  {
+    name: 'remember',
+    description: 'explicitly capture a durable fact to MEMORY.md (Poison_Guard + home-path abstraction + dedup; the safe alternative to hand-writing fact files)',
+    milestone: 24,
+    argSpec: [{ flags: '<text...>', description: 'the fact to remember' }],
+    optionSpec: [
+      { flags: '--tier <tier>', description: 'P (default; U/L are v0.1.x)' },
+      { flags: '--trust <level>', description: 'high | medium | low (default: high)' },
+      { flags: '--section <name>', description: 'MEMORY.md section (default: Active Threads)' },
+    ],
+    action: runRemember,
+  },
   {
     name: 'search',
     description: 'search memory — hybrid keyword + optional semantic',

package/src/write-fact.mjs

@@ -19,6 +19,8 @@ import { VALID_TIERS, resolveTierRoot, resolveFactDir } from './tier-paths.mjs';
 import { parse, format } from './frontmatter.mjs';
 import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
+import { sanitizeHomePaths } from './sanitize.mjs';
+import { checkPoisonGuard, logPoisonGuardRejection } from './poison-guard.mjs';
 
 const VALID_TYPES = new Set(['user', 'feedback', 'project', 'reference']);
 const VALID_WRITE_SOURCES = new Set([
@@ -148,7 +150,48 @@ export function writeFact(opts = {}) {
     });
   }
 
-  const id = opts.id ?? generateId(opts.tier, opts.body);
+  // Privacy (write-path fix #1): abstract absolute home-dir paths to `~` in
+  // committed/shared tiers (P/U) so a fact never ships the local username
+  // and stays portable. Local tier (L) keeps machine-specific paths verbatim
+  // — that's its purpose. The id hashes the SANITIZED body, so dedup keys on
+  // what actually lands on disk.
+  let { body, title } = opts;
+  if (opts.tier === 'P' || opts.tier === 'U') {
+    body = sanitizeHomePaths(body);
+    title = sanitizeHomePaths(title);
+  }
+
+  // Poison_Guard (write-path fix #1): fact files previously bypassed the
+  // secret/poison screen that scratchpad writes get via memoryWrite. Screen
+  // the (sanitized) body before any disk write; a rejection logs the redacted
+  // excerpt to .locks/poison-guard.log and returns a poison_guard error.
+  const guard = checkPoisonGuard(body);
+  if (guard.rejected) {
+    // Best-effort log; guard on projectRoot so a U-tier write with no
+    // project context can't turn a clean rejection into a crash.
+    if (guard.pattern_id !== 'schema' && opts.projectRoot) {
+      logPoisonGuardRejection({
+        projectRoot: opts.projectRoot,
+        ts: opts.createdAt ?? nowIso(),
+        pattern_id: guard.pattern_id,
+        source_file: `write-fact:${opts.type}_${opts.slug}`,
+        source_line: 1,
+        redacted_excerpt: guard.redacted_excerpt,
+      });
+    }
+    return errorResult({
+      category: ERROR_CATEGORIES.POISON_GUARD,
+      errors: [`Poison_Guard rejected write: pattern_id=${guard.pattern_id}`],
+      pattern_id: guard.pattern_id,
+      redacted_excerpt: guard.redacted_excerpt,
+      id: null,
+      path: null,
+    });
+  }
+
+  // Use the sanitized body/title for id, frontmatter, and the file body.
+  const factOpts = { ...opts, body, title };
+  const id = opts.id ?? generateId(opts.tier, body);
   const createdAt = opts.createdAt ?? nowIso();
   const tierRoot = resolveTierRoot(opts);
   const factDir = resolveFactDir(opts.tier, tierRoot);
@@ -198,8 +241,8 @@ export function writeFact(opts = {}) {
   }
 
   mkdirSync(factDir, { recursive: true });
-  const frontmatter = buildFrontmatterObject(opts, { id, createdAt });
-  writeFileSync(path, format({ frontmatter, body: `\n${opts.body}\n` }), 'utf8');
+  const frontmatter = buildFrontmatterObject(factOpts, { id, createdAt });
+  writeFileSync(path, format({ frontmatter, body: `\n${factOpts.body}\n` }), 'utf8');
 
   return { action: 'created', id, path };
 }

package/template/.gitignore.fragment

@@ -1,12 +1,12 @@
-# claude-memory-kit — added by `cmk install`. Do not edit by hand;
-# `cmk install` refreshes these lines idempotently. Remove via
-# `cmk uninstall`.
-
-# Local-tier (per-machine, never committed)
-context.local/
-
-# SQLite + FTS5 read cache (regenerable from markdown)
-context/.index/
-
-# Run-time locks + transient state
-context/.locks/
+# claude-memory-kit — added by `cmk install`. Do not edit by hand;
+# `cmk install` refreshes these lines idempotently. Remove via
+# `cmk uninstall`.
+
+# Local-tier (per-machine, never committed)
+context.local/
+
+# SQLite + FTS5 read cache (regenerable from markdown)
+context/.index/
+
+# Run-time locks + transient state
+context/.locks/

package/template/CLAUDE.md.template

@@ -1,49 +1,53 @@
-## Memory System — claude-memory-kit
-
-This project uses **claude-memory-kit** for per-project, in-repo memory that survives session boundaries. Memory lives in `context/` (committed) and `context.local/` (gitignored). Cross-project memory lives at `~/.claude-memory-kit/` (or `$MEMORY_KIT_USER_DIR`).
-
-> v0.1.0 is under active development. This block is the runtime contract. Specific mechanisms (auto-extract, memory-write skill, MCP search) come online incrementally — `cmk doctor` will tell you which layers are active in the current install. Full architecture: <https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/journey/v0.1.0-build-log.md>
-
-### Where memory lives
-
-| Tier | Path | Travels with `git clone`? |
-| --- | --- | --- |
-| **User** | `~/.claude-memory-kit/` | No — machine-local, cross-project |
-| **Project** | `<repo>/context/` | **Yes** — committed |
-| **Local** | `<repo>/context.local/` | No — gitignored, per-machine |
-
-Precedence at session start: local > project > user (most-specific wins, others are logged as shadowed).
-
-### How memory works
-
-- **Session start** — the kit injects a frozen snapshot (≤10 KB) from the three tiers into Claude's context. Loaded once, never mutated mid-session — preserves the prefix cache.
-- **During the session** — durable facts get captured automatically by the Stop hook + `memory-write` skill (once Layer 4 is live). The user can also explicitly say "remember this", "from now on", "we decided X".
-- **End of session** — the rolling-window pipeline compresses `sessions/now.md` into a daily summary. Cron jobs distill into `recent.md` and `archive.md` over time (Layer 6, optional).
-
-### Health checks (when `cmk doctor` is live)
-
-Health checks (HC-1..HC-8) verify each layer is wired correctly: install integrity, hook registration, transcript capture freshness, INDEX accuracy, cron registration, semantic search backend, native Auto Memory coexistence. See [`docs/adr/`](docs/adr/) and [`specs/v0.1.0/design.md`](specs/v0.1.0/design.md) for the full contract.
-
-### Memory write rules (for Claude)
-
-When you learn something durable about this project or the user:
-
-1. **Working state** (current threads, today's environment, open decisions) → write to `context/MEMORY.md` (≤2,500 chars). Consolidate at the cap.
-2. **Typed durable fact** (user role / project decision / feedback / external reference) → create `context/memory/<type>_<slug>.md` with full YAML frontmatter; add a one-line entry to `context/memory/INDEX.md`.
-3. **Cross-project lesson** → user-tier `~/.claude-memory-kit/LESSONS.md` (via `cmk lessons promote`).
-4. **Never duplicate** between scratchpad and granular archive. If a working-state item becomes durable, MOVE it.
-5. **Confirm silently.** Frozen-snapshot semantics mean the write takes effect next session.
-
-### Privacy
-
-Anything inside `<private>...</private>` tags in a user prompt is stripped before any disk write — never persisted in any form. Per-fact `private: true` frontmatter excludes a fact from the session-start digest.
-
-### Uninstall / remove this block
-
-This block is managed by `cmk install`. To remove it cleanly:
-
-```bash
-cmk uninstall
-```
-
-Everything outside the `claude-memory-kit:start` / `:end` markers is byte-preserved.
+## Memory System — claude-memory-kit
+
+This project uses **claude-memory-kit** for per-project, in-repo memory that survives session boundaries. Memory lives in `context/` (committed) and `context.local/` (gitignored). Cross-project memory lives at `~/.claude-memory-kit/` (or `$MEMORY_KIT_USER_DIR`).
+
+> v0.1.0 is under active development. This block is the runtime contract. Specific mechanisms (auto-extract, memory-write skill, MCP search) come online incrementally — `cmk doctor` will tell you which layers are active in the current install. Full architecture: <https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/journey/v0.1.0-build-log.md>
+
+### Where memory lives
+
+| Tier | Path | Travels with `git clone`? |
+| --- | --- | --- |
+| **User** | `~/.claude-memory-kit/` | No — machine-local, cross-project |
+| **Project** | `<repo>/context/` | **Yes** — committed |
+| **Local** | `<repo>/context.local/` | No — gitignored, per-machine |
+
+Precedence at session start: local > project > user (most-specific wins, others are logged as shadowed).
+
+### How memory works
+
+- **Session start** — the kit injects a frozen snapshot (≤10 KB) from the three tiers into Claude's context. Loaded once, never mutated mid-session — preserves the prefix cache.
+- **During the session** — durable facts get captured automatically by the Stop hook + `memory-write` skill (once Layer 4 is live). The user can also explicitly say "remember this", "from now on", "we decided X".
+- **End of session** — the rolling-window pipeline compresses `sessions/now.md` into a daily summary. Cron jobs distill into `recent.md` and `archive.md` over time (Layer 6, optional).
+
+### Health checks (when `cmk doctor` is live)
+
+Health checks (HC-1..HC-8) verify each layer is wired correctly: install integrity, hook registration, transcript capture freshness, INDEX accuracy, cron registration, semantic search backend, native Auto Memory coexistence. See [`docs/adr/`](docs/adr/) and [`specs/v0.1.0/design.md`](specs/v0.1.0/design.md) for the full contract.
+
+### Memory write rules (for Claude)
+
+Most capture is automatic — the Stop hook extracts durable facts each turn, no action needed. When you want to capture something **explicitly**:
+
+1. **Use `cmk remember "<the fact>"`** — do NOT hand-write files under `context/memory/`. The command routes through the kit's safe write path: it screens for secrets (Poison_Guard), abstracts machine-specific home paths to `~` (so a committed fact never leaks the local username), dedups, and writes the correct schema. Hand-writing fact files bypasses all of that and produces files the index can't read.
+   ```bash
+   cmk remember "We deploy with Kamal to Hetzner; never to Vercel."
+   cmk remember "Lior prefers terse responses, no preamble." --trust high
+   ```
+2. **Machine-specific config** (absolute tool paths that only make sense on this machine) → put it in `context.local/machine-paths.md` (gitignored, never committed). `cmk remember` writes the committed project tier; for machine-only paths, edit the local tier directly.
+3. **Cross-project lesson** (true on every project, not just this one) → `cmk lessons promote <id>` moves a project fact to the user tier (`~/.claude-memory-kit/`).
+4. **Confirm silently.** Don't announce captures. Frozen-snapshot semantics mean a write takes effect next session.
+
+### Privacy
+
+- Anything inside `<private>...</private>` tags in a user prompt is stripped before any disk write — never persisted in any form.
+- `cmk remember` (and auto-extract) abstract absolute home-dir paths (`C:\Users\you\…`, `/home/you/…`, `/Users/you/…`) to `~` before writing to a committed/shared tier, so a fact never ships your username and stays portable across machines. Genuinely machine-specific paths belong in `context.local/` (gitignored).
+
+### Uninstall / remove this block
+
+This block is managed by `cmk install`. To remove it cleanly:
+
+```bash
+cmk uninstall
+```
+
+Everything outside the `claude-memory-kit:start` / `:end` markers is byte-preserved.