@lh8ppl/claude-memory-kit 0.1.1 → 0.1.2

package/package.json

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

package/src/compressor.mjs

@@ -28,6 +28,7 @@
 // never needs Read either — the turn content arrives in the prompt).
 
 import { spawn as defaultSpawn } from 'node:child_process';
+import { spawnBin } from './spawn-bin.mjs';
 import { writeFileSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -203,25 +204,24 @@ export class HaikuViaAnthropicApi extends CompressorBackend {
     const env = { ...process.env };
     delete env.CLAUDECODE;
 
-    // shell:true required on Windows so that .cmd shims (claude.cmd)
-    // resolve through cmd.exe. Without it, node's spawn fails with
-    // EINVAL/ENOENT because it won't auto-resolve .cmd extensions
-    // (CVE-2024-27980 hardening). On Linux/macOS shell:true is a
-    // no-op for argv-style invocation when the arguments don't contain
-    // shell metacharacters — ours don't (the prompt goes via stdin).
+    // spawnBin handles the Windows .cmd-shim problem WITHOUT the
+    // `shell:true` + args-array combo that broke paths with spaces (#4):
+    // POSIX spawns argv-style (shell:false); Windows builds a single
+    // pre-quoted command string so `--mcp-config C:\Users\First Last\…`
+    // survives cmd.exe tokenization. See spawn-bin.mjs. `windowsHide`
+    // still suppresses the transient cmd.exe console flash on Windows.
     // spawn-discipline: caller-managed terminateSubprocess (kit's kill-chain helper) + setTimeout (per design §8.5; PR-A composition-verification instance #4; substance pinned by tests/cli-compressor-timeout.test.js + tests/spawn-smoke-kill-chain.test.js). The function signature `timeoutMs` parameter (line 162) is the caller-supplied bound; the setTimeout below (search "Timeout timer") fires the kill chain.
-    const child = this._spawn(this._bin, args, {
-      cwd: tmpdir(), // OS-native temp dir; replaces `/tmp` which fails to resolve on Windows
-      env,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      shell: true,
-      // Suppress the transient cmd.exe console window on Windows —
-      // every shell:true spawn flashes a window otherwise (visible
-      // to the user when auto-extract / compress-session fires
-      // dozens of times per session). stdio is piped so we still
-      // capture the child's output through the regular handlers.
-      windowsHide: true,
-    });
+    const child = spawnBin(
+      this._bin,
+      args,
+      {
+        cwd: tmpdir(), // OS-native temp dir; replaces `/tmp` which fails to resolve on Windows
+        env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+      },
+      { spawnImpl: this._spawn },
+    );
 
     const cleanupSandbox = () => {
       // Single-use sandbox: the directory and the empty-mcp.json file

package/src/doctor.mjs

@@ -38,7 +38,7 @@ import {
   statSync,
   writeFileSync,
 } from 'node:fs';
-import { spawnSync } from 'node:child_process';
+import { spawnBinSync } from './spawn-bin.mjs';
 import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
 import { nowIso } from './audit-log.mjs';
@@ -62,7 +62,10 @@ async function hc1Memsearch() {
   // semantic requires a separate `pip install memsearch[onnx]`.
   // `requiresInstall: true` so the CLI prompts before auto-installing.
   try {
-    const r = spawnSync('memsearch', ['--version'], {
+    // spawnBinSync resolves the Windows .cmd shim without `shell:true`+args
+    // (no DEP0190; #4). memsearch's only arg is `--version` (no spaces), so
+    // the quoting is a no-op here — the win is dropping the deprecated combo.
+    const r = spawnBinSync('memsearch', ['--version'], {
       encoding: 'utf8',
       // M1 fix (skill-review 2026-05-28): 3.5s tolerates Windows
       // cold-Python startup (AV scan + .pyc generation on first hit
@@ -71,7 +74,6 @@ async function hc1Memsearch() {
       // still fits comfortably inside the 5s NFR budget. Timeout →
       // 'skip' so cmk doctor completes regardless.
       timeout: 3_500,
-      shell: process.platform === 'win32',
     });
     if (r.status === 0) {
       return {

package/src/index-rebuild.mjs

@@ -367,14 +367,36 @@ export function reindexBoot({ projectRoot, userDir, db, now }) {
 
   for (const source of sources) {
     filesScanned++;
-    const content = readFileSync(source.path, 'utf8');
-    const sha1 = sha1OfContent(content);
     const relPath = relativeSource(source.path, { projectRoot, userDir });
     const existing = db
-      .prepare('SELECT sha1 FROM files WHERE path = ?')
+      .prepare('SELECT mtime, sha1 FROM files WHERE path = ?')
       .get(relPath);
+    // Fast path: if the file's mtime matches the checkpoint, the content is
+    // unchanged — skip the read + sha1 entirely. This realizes design §9.2's
+    // "mtime+sha1 diff" intent (the prior impl sha1'd every file on every
+    // call) and is what makes reindexBoot cheap enough to run before every
+    // `cmk search` (finding #0) even as the memory corpus grows.
+    let mtime = null;
+    try {
+      mtime = Math.floor(statSync(source.path).mtimeMs);
+    } catch {
+      // stat failed (file vanished mid-walk); fall through to the read,
+      // which surfaces the error naturally.
+    }
+    if (existing && mtime !== null && existing.mtime === mtime) {
+      continue; // unchanged (mtime match — no read needed)
+    }
+    // Caveat: a content change that PRESERVES the old mtime (e.g. a restore
+    // tool that sets --times) is missed until the next real change or a
+    // `reindex --full`. Negligible in practice — the kit always writes a
+    // fresh mtime after the indexed one — and standard for mtime-based diffs.
+    //
+    // mtime differs (or no checkpoint) — confirm via sha1 so a mere mtime
+    // touch (content identical) doesn't trigger a needless reindex.
+    const content = readFileSync(source.path, 'utf8');
+    const sha1 = sha1OfContent(content);
     if (existing && existing.sha1 === sha1) {
-      continue; // unchanged
+      continue; // content unchanged despite mtime touch
     }
     const n = txn(source);
     filesReindexed++;

package/src/inject-context.mjs

@@ -84,17 +84,20 @@ const TIER_BUDGETS = Object.freeze({
 });
 
 // Per-tier reading plan. The hook reads the scratchpads allowed at that
-// tier (per SCRATCHPADS_BY_TIER) plus the tier's INDEX file, plus — for
-// the project tier — the most recent rolling-window day file.
+// tier (per SCRATCHPADS_BY_TIER) plus — for the project tier — the most
+// recent rolling-window day file.
+//
+// INDEX.md is deliberately NOT in the snapshot (#R, 2026-05-30). It is a
+// pointer/reference doc that self-declares "NOT auto-loaded at session
+// start" in its own template body — injecting it both violated that
+// contract and pushed ~2 KB of reference prose into Claude's context,
+// crowding out real facts. It stays on disk for lookup via `cmk search` /
+// the granular archive; it is not session-start content.
 function plannedFilesForTier(tier, tierRoot) {
   const files = [];
   for (const name of SCRATCHPADS_BY_TIER[tier]) {
     files.push(join(tierRoot, name));
   }
-  // INDEX: P/L use memory/INDEX.md; U uses fragments/INDEX.md (per
-  // resolveFactDir asymmetry in tier-paths.mjs).
-  const indexDir = tier === 'U' ? 'fragments' : 'memory';
-  files.push(join(tierRoot, indexDir, 'INDEX.md'));
   if (tier === 'P') {
     const sessionsDir = join(tierRoot, 'sessions');
     const latest = latestDaySession(sessionsDir);
@@ -138,10 +141,145 @@ function tierDirExists(tier, tierRoot) {
   return existsSync(tierRoot) && statSync(tierRoot).isDirectory();
 }
 
+// The all-zero sha1 is the kit's template-seed sentinel: every scaffolded
+// placeholder bullet (in machine-paths/overrides/SOUL/USER/HABITS/LESSONS)
+// carries `sha1: 0000…0000` + `at: 2020-01-01T…`. A real captured fact
+// always has a real content sha1. We use this to distinguish "scaffolding
+// the user never replaced" from "a fact worth injecting".
+const SEED_SHA1_RE = /sha1:\s*0{40}/;
+
+// All HTML-comment handling below uses STRING SCANNING (indexOf/startsWith),
+// never a regex tag-filter. Regex-based HTML-comment stripping is fragile by
+// nature (it can't see newlines, leaves partial `<!--`, etc. — flagged by
+// CodeQL's js/bad-tag-filter). String scanning is both more robust and not a
+// tag-filter, so it sidesteps that whole class.
+
+// True if `line`, ignoring surrounding whitespace, is exactly one self-
+// contained HTML comment (`<!-- … -->`) — e.g. a per-bullet provenance line.
+function isCommentOnlyLine(line) {
+  if (typeof line !== 'string') return false;
+  const t = line.trim();
+  return t.startsWith('<!--') && t.endsWith('-->') && t.length >= 7;
+}
+
+// Remove every self-contained `<!-- … -->` span WITHIN a single line, by
+// scanning for delimiter pairs. An unterminated `<!--` (no `-->` on this
+// line) is left in place for the multi-line state machine to handle.
+function stripInlineComments(line) {
+  let out = '';
+  let i = 0;
+  for (;;) {
+    const open = line.indexOf('<!--', i);
+    if (open === -1) return out + line.slice(i);
+    const close = line.indexOf('-->', open + 4);
+    if (close === -1) return out + line.slice(i); // unterminated; leave it
+    out += line.slice(i, open);
+    i = close + 3;
+  }
+}
+
+// Is `bulletLine` a placeholder/seed bullet that should NOT be injected?
+// Primary signal: a following provenance comment carrying the all-zero seed
+// sha1 (every scaffolded template bullet has it; a real captured fact never
+// does). Secondary: the `(example)` marker — but ONLY in the template's
+// exact `(P-XXXXXXXX) (example) …` shape (right after the citation id), so a
+// real fact whose text merely mentions "(example)" is not mis-dropped.
+function isSeedBullet(bulletLine, nextLine) {
+  if (/^\s*-\s+\([PUL]-[A-Za-z0-9]{8}\)\s+\(example\)/.test(bulletLine)) {
+    return true;
+  }
+  const prov = isCommentOnlyLine(nextLine) ? nextLine : '';
+  return SEED_SHA1_RE.test(prov);
+}
+
+// Remove HTML comments robustly, including the kit templates' multi-line
+// format-explanation headers that ILLUSTRATIVELY embed a single-line
+// `<!-- source… -->` example inside the outer `<!-- … -->` block (a naive
+// "first <!-- to first -->" pass closes on that inner `-->` and orphans the
+// tail). We strip inline comments first (killing the nested one) and only
+// then walk the now-cleanly-delimited multi-line blocks. All string-scan.
+function stripHtmlComments(text) {
+  // Pass 1 — remove every self-contained `<!-- … -->` on a single line.
+  const lines = text.split('\n').map(stripInlineComments);
+  // Pass 2 — remove multi-line blocks (each now free of any inner `-->`).
+  const out = [];
+  let inBlock = false;
+  for (let line of lines) {
+    if (inBlock) {
+      const close = line.indexOf('-->');
+      if (close === -1) continue; // still inside the block; drop the line
+      inBlock = false;
+      line = line.slice(close + 3);
+    }
+    const open = line.indexOf('<!--');
+    if (open !== -1) {
+      inBlock = true;
+      line = line.slice(0, open);
+    }
+    if (line.trim() !== '' || out.length === 0 || out[out.length - 1] !== '') {
+      out.push(line.replace(/[ \t]+$/, ''));
+    }
+  }
+  return out.join('\n');
+}
+
+// Clean a scratchpad body for INJECTION (not for on-disk storage — the
+// files keep their human-editing headers). Self-test finding #R: the raw
+// bodies are ~70% template-comment noise + placeholder seed bullets that
+// bury (and crowd out) the real captured facts, so the model concludes
+// "no real facts populated yet". This strips:
+//   1. placeholder seed bullets (all-zero sha1 / `(example)`) + their
+//      provenance comment line, and
+//   2. ALL remaining `<!-- -->` comments (multi-line format-explanation
+//      headers AND per-bullet provenance — the fact text + its `(P-…)`
+//      citation id carry everything the model needs to read & cite).
+// Whitespace is normalized so stripped regions don't leave holes.
+//
+// Known limitation (rare): a captured fact whose TEXT contains a literal
+// `<!--`/`-->` (e.g. a note about HTML/templating) has that fragment
+// stripped from the INJECTED view. The on-disk fact and the search index
+// are unaffected — only the session-start snapshot loses the literal
+// comment markers. Accepted as a rare edge vs. the cost of distinguishing
+// real comments from comment-shaped fact text.
+function cleanScratchpadBody(body) {
+  // Normalize CRLF so user-edited (Windows) scratchpads don't leave stray
+  // \r after comment/seed stripping.
+  const lines = body.replace(/\r\n/g, '\n').split('\n');
+  const kept = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (
+      /^\s*-\s/.test(line) &&
+      ID_TOKEN_RE.test(line) &&
+      isSeedBullet(line, lines[i + 1])
+    ) {
+      if (isCommentOnlyLine(lines[i + 1])) i++;
+      continue;
+    }
+    kept.push(line);
+  }
+  // Step 2 — strip all remaining comments (format headers + real-bullet
+  // provenance), then normalize whitespace.
+  return stripHtmlComments(kept.join('\n'))
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/^\n+|\n+$/g, '');
+}
+
+// After cleaning, does a body carry any real content — i.e. a non-blank
+// line that isn't a markdown heading? A body of only headings (every
+// bullet was a stripped seed) is pure scaffolding and must NOT contribute
+// a tier block (otherwise the model sees an empty "## …" skeleton).
+function hasRealContent(cleaned) {
+  return cleaned
+    .split('\n')
+    .some((l) => l.trim() !== '' && !/^#{1,6}\s/.test(l));
+}
+
 // Read the snapshot-eligible content for one tier as a single string. If
-// no tier files exist (or the tier dir itself is absent), returns ''. The
-// per-file content is wrapped in a fenced header so the snapshot is
-// self-describing to whoever reads Claude's context window.
+// no tier files exist (or the tier dir itself is absent), returns ''. Each
+// file body is cleaned for injection (see cleanScratchpadBody); files that
+// reduce to scaffolding-only contribute nothing, and a tier whose every
+// file is scaffolding-only is excluded entirely (no header, no skeleton).
 function readTierBlock(tier, tierRoot) {
   if (!tierDirExists(tier, tierRoot)) return '';
   const sections = [];
@@ -154,7 +292,9 @@ function readTierBlock(tier, tierRoot) {
       continue;
     }
     if (body.trim() === '') continue;
-    sections.push(body);
+    const cleaned = cleanScratchpadBody(body);
+    if (!hasRealContent(cleaned)) continue;
+    sections.push(cleaned);
   }
   if (sections.length === 0) return '';
   const header = `<!-- cmk: ${TIER_LABELS[tier]} tier (${tier}) -->`;

package/src/mcp-server.mjs

@@ -34,6 +34,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { resolve as resolvePath, isAbsolute } from 'node:path';
 import { openIndexDb } from './index-db.mjs';
+import { reindexBoot } from './index-rebuild.mjs';
 import { search, SEARCH_MODES } from './search.mjs';
 import { memoryWrite } from './memory-write.mjs';
 import { ID_PATTERN, resolveTierRoot } from './tier-paths.mjs';
@@ -451,6 +452,22 @@ export function buildMcpServer({ projectRoot, userDir, db, semanticBackend }) {
  */
 export async function runMcpServer({ projectRoot, userDir, db: dbOverride, semanticBackend } = {}) {
   const db = dbOverride ?? openIndexDb({ projectRoot });
+  // Refresh the index at server startup so mk_search sees facts already on
+  // disk — same fresh-install gap as `cmk search` (self-test finding #0):
+  // nothing reindexes for a just-installed project, so without this the
+  // model's first mk_search returns empty for facts sitting in the
+  // scratchpads. Incremental (mtime/sha1 diff) + best-effort; in-session
+  // freshness for facts written AFTER startup is the runtime watcher's job
+  // (future). The in-process buildMcpServer tests bypass this path.
+  if (projectRoot) {
+    try {
+      reindexBoot({ projectRoot, userDir, db });
+    } catch (err) {
+      process.stderr.write(
+        `cmk-mcp-server: startup index refresh failed: ${err?.message ?? err}\n`,
+      );
+    }
+  }
   const server = buildMcpServer({ projectRoot, userDir, db, semanticBackend });
   const transport = new StdioServerTransport();
 

package/src/memory-write.mjs

@@ -57,6 +57,7 @@ import { appendScratchpadBullet } from './scratchpad.mjs';
 import { parseBulletProvenance } from './provenance.mjs';
 import { checkPoisonGuard, logPoisonGuardRejection } from './poison-guard.mjs';
 import { detectConflicts, writeConflictEntry } from './conflict-queue.mjs';
+import { sanitizeHomePaths } from './sanitize.mjs';
 
 const VALID_ACTIONS = new Set(['add', 'replace', 'remove']);
 
@@ -252,8 +253,20 @@ function doAdd(opts) {
   if (errors.length > 0) {
     return errorResult({ category: ERROR_CATEGORIES.SCHEMA, errors });
   }
+  // Privacy (write-path fix #1): abstract home-dir paths to `~` for
+  // committed/shared tiers (P/U) BEFORE the bullet is screened, conflict-
+  // checked, dedup-keyed, and written — so a captured fact never ships the
+  // local username and stays portable. Local tier (L) keeps machine paths
+  // verbatim (its purpose). Everything downstream uses `addOpts`.
+  const sanitizedText =
+    opts.tier === 'P' || opts.tier === 'U'
+      ? sanitizeHomePaths(opts.text)
+      : opts.text;
+  const addOpts =
+    sanitizedText === opts.text ? opts : { ...opts, text: sanitizedText };
+
   const poisonResult = runPoisonGuard({
-    text: opts.text,
+    text: addOpts.text,
     projectRoot: opts.projectRoot,
     source: opts.source,
     sessionId: opts.sessionId,
@@ -276,7 +289,7 @@ function doAdd(opts) {
     userDir: opts.userDir,
   });
   const conflict = detectConflicts({
-    newText: opts.text,
+    newText: addOpts.text,
     newTrust,
     scratchpadPath,
     sectionTitle: opts.section,
@@ -296,14 +309,14 @@ function doAdd(opts) {
     // appendScratchpadBullet would have used, then route to the queue.
     // (Task 25b fix: generateId is positional `(tier, text)`, not
     // named-args — Task 25 originally called it as an object.)
-    const proposedId = generateId(opts.tier, opts.text);
+    const proposedId = generateId(addOpts.tier, addOpts.text);
     const ts = opts.now ?? nowIso();
     return writeConflictEntry({
       tier: opts.tier,
       projectRoot: opts.projectRoot,
       userDir: opts.userDir,
       newId: proposedId,
-      newText: opts.text,
+      newText: addOpts.text,
       newTrust,
       existingId: conflict.existingId,
       existingText: conflict.existingText,
@@ -313,7 +326,7 @@ function doAdd(opts) {
       detectedAt: ts,
     });
   }
-  return appendBulletGuarded(opts);
+  return appendBulletGuarded(addOpts);
 }
 
 function appendBulletGuarded(opts) {

package/src/sanitize.mjs

@@ -0,0 +1,39 @@
+// sanitize.mjs — privacy sanitizers applied before durable writes to a
+// committed/shared tier. Sibling to poison-guard.mjs, but where Poison_Guard
+// REJECTS a write (secrets/poison), these REWRITE it (privacy abstraction).
+//
+// Write-path fix #1 (the self-test privacy leak): a durable fact written to a
+// committed project tier carried the local username inside an absolute
+// interpreter path (C:\Users\<you>\...\python.exe), shipping it to git and
+// making the fact non-portable. sanitizeHomePaths abstracts the home-dir
+// prefix to `~` — killing the username leak AND making the fact portable
+// across machines — while preserving everything after the home dir.
+//
+// Applied to P (committed) and U (cross-project) tier writes. NOT to L
+// (local, gitignored) — machine-specific absolute paths are the whole point
+// of the local tier, so they stay verbatim there.
+
+// Each pattern matches an absolute home-directory prefix up to (but not
+// including) the next path separator / whitespace / quote, so the remainder
+// of the path is preserved. Username char class excludes separators, spaces,
+// quotes, and shell/redirect metacharacters.
+const USER = "[^\\\\/\\s\"'`<>|]+";
+// Case-INSENSITIVE: Windows + macOS filesystems are case-insensitive, so a
+// fact may carry `c:\users\you\…` or `/users/you`; the `i` flag keeps the
+// privacy abstraction from being bypassed by lowercasing.
+const HOME_PATH_PATTERNS = [
+  new RegExp(`[A-Za-z]:[\\\\/]Users[\\\\/]${USER}`, 'gi'), // Windows C:\Users\name (either slash)
+  new RegExp(`/Users/${USER}`, 'gi'), // macOS /Users/name
+  new RegExp(`/home/${USER}`, 'gi'), // Linux /home/name
+];
+
+/**
+ * Abstract absolute home-directory prefixes to `~`. Returns non-string input
+ * unchanged (callers may pass undefined for optional fields).
+ */
+export function sanitizeHomePaths(text) {
+  if (typeof text !== 'string') return text;
+  let out = text;
+  for (const re of HOME_PATH_PATTERNS) out = out.replace(re, '~');
+  return out;
+}

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';
 
@@ -64,20 +65,49 @@ const NOTICE_PREFIX = 'not yet implemented in v0.1.0';
 async function runInstall(options /* , command */) {
   // 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 });
-  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}`,
-    `hooks=${result.hooks.action}`,
-  ].filter(Boolean);
-  console.log('cmk install: ' + parts.join(', '));
 
-  if (result.hooks.action === 'wired' || result.hooks.action === 'unchanged') {
+  // 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(
-      '  hooks wired into .claude/settings.json — restart Claude Code to activate. ' +
-        'This is a COMPLETE install; no separate /plugin step is needed.',
+      '  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}`,
     );
   }
 
@@ -178,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,
@@ -235,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');
@@ -1022,6 +1132,7 @@ export const subcommands = [
     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,
   },
@@ -1037,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/CLAUDE.md.template

@@ -26,17 +26,21 @@ Health checks (HC-1..HC-8) verify each layer is wired correctly: install integri
 
 ### Memory write rules (for Claude)
 
-When you learn something durable about this project or the user:
+Most capture is automatic — the Stop hook extracts durable facts each turn, no action needed. When you want to capture something **explicitly**:
 
-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.
+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. Per-fact `private: true` frontmatter excludes a fact from the session-start digest.
+- 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