@lh8ppl/claude-memory-kit 0.3.0 → 0.3.2

package/src/subcommands.mjs

@@ -27,12 +27,14 @@ import { weeklyCurate } from './weekly-curate.mjs';
 import { autoPersona } from './auto-persona.mjs';
 import { exportPersona, importPersona } from './persona-portability.mjs';
 import { setNativeAutoMemory, nativeMemoryInstallNote } from './native-memory.mjs';
-import { rememberRich, richFactTitle, nonProjectTierNote } from './remember-core.mjs';
+import { rememberRich, richFactTitle, nonProjectTierNote, prepareNearDupGuard } from './remember-core.mjs';
 import { getObservations, citeLink, buildTimeline, recentActivity } from './read-core.mjs';
 import { readHookStdin } from './read-hook-stdin.mjs';
 import { runLazyCompress } from './lazy-compress.mjs';
 import { runDoctor } from './doctor.mjs';
 import { importAnthropicMemory } from './import-anthropic-memory.mjs';
+import { configGet, configSet, configShowOrigin } from './config-core.mjs';
+import { importClaudeMd } from './import-claude-md.mjs';
 import { extractTranscript, discoverSessions } from './transcripts.mjs';
 import { runRepair } from './repair.mjs';
 import { runRoll, ROLL_SCOPES } from './roll.mjs';
@@ -60,6 +62,8 @@ 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 { spawnSync } from 'node:child_process';
+import { checkKitBinding } from './native-binding.mjs';
 import { resolve as resolvePath, join, basename } from 'node:path';
 
 const NOTICE_PREFIX = 'not yet implemented';
@@ -97,7 +101,71 @@ export function formatSemanticSummary(semantic, { noHooks = false } = {}) {
  * summary, and reports the CLAUDE.md action (created / appended /
  * replaced / upgraded / downgrade-blocked / forced-downgrade / unchanged).
  */
-async function runInstall(options /* , command */) {
+// Task 141a (D-129): the install-time binding ask. npm 12 blocks
+// better-sqlite3's binding build on a fresh `npm install -g` — the user's
+// 2026-06-12 steer: ask AT INSTALL, never leave it to a secondary command.
+// Interactive consent is required because the fix is itself an
+// `npm install -g` (the design §14 ask-before-install rule); non-interactive
+// runs print the command instead. All deps injectable for tests.
+async function offerBindingFix(nativeBinding, options, { log, logError }) {
+  if (!nativeBinding || nativeBinding.ok) return;
+  const remedy = nativeBinding.remedy;
+  logError(
+    `  warning: better-sqlite3's native binding is unavailable (${nativeBinding.reason}).`,
+  );
+  logError(
+    '  Most common cause: npm 12 blocks dependency install scripts by default (a Node major upgrade is the other). Search/reindex cannot work until the binding is rebuilt.',
+  );
+  // An explicit askImpl implies a consent channel exists (the test seam /
+  // programmatic caller); only the readline default needs a real TTY.
+  const interactive =
+    options?.interactive ?? (options?.askImpl ? true : process.stdin.isTTY === true);
+  const askFn =
+    options?.askImpl ??
+    (interactive
+      ? (question) =>
+          new Promise((resolveAnswer) => {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            rl.question(question, (answer) => {
+              rl.close();
+              resolveAnswer(answer);
+            });
+          })
+      : null);
+  if (!interactive || !askFn) {
+    logError(`  Fix it any time with: ${remedy}`);
+    return;
+  }
+  const answer = String(await askFn(`  Fix it now by running \`${remedy}\`? [Y/n] `))
+    .trim()
+    .toLowerCase();
+  const yes = answer === '' || answer === 'y' || answer === 'yes';
+  if (!yes) {
+    log(`  Skipped. Fix it any time with: ${remedy}`);
+    return;
+  }
+  const fixRunner =
+    options?.fixRunner ??
+    ((cmd) =>
+      // Constant command under shell:true (npm is npm.cmd on Windows); the
+      // 10-min ceiling mirrors buildDefaultNpmRunner's spawn discipline.
+      spawnSync(cmd, { stdio: 'inherit', shell: true, timeout: 600_000 }));
+  const r = fixRunner(remedy);
+  const reProbe = options?.reProbe ?? checkKitBinding;
+  const after = r.status === 0 ? reProbe() : { ok: false };
+  if (after.ok) {
+    log('  Binding rebuilt — search is ready.');
+  } else {
+    logError(`  The binding is still unavailable — run it manually later: ${remedy}`);
+  }
+}
+
+// Exported for tests (Task 141a) — dep-injectable (cwd / userTier / log /
+// logError / bindingProbe / askImpl / fixRunner / reProbe / interactive) on
+// the runImportClaudeMd pattern. Defaults unchanged for production.
+export async function runInstall(options /* , command */) {
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
   // commander maps `--no-hooks` to options.hooks === false.
   const noHooks = !!(options && options.hooks === false);
   const verbose = !!(options && options.verbose);
@@ -110,6 +178,9 @@ async function runInstall(options /* , command */) {
     // to options.withSemantic.
     withSemantic: !!(options && options.withSemantic),
     noSemantic: !!(options && options.semantic === false),
+    projectRoot: options?.cwd,
+    userTier: options?.userTier,
+    bindingProbe: options?.bindingProbe,
   });
 
   // Outcome over inventory (self-test UX finding): state the resulting state +
@@ -117,7 +188,7 @@ async function runInstall(options /* , command */) {
   // 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 projectName = basename(result.projectRoot);
   const wired =
     result.hooks.action === 'wired' || result.hooks.action === 'unchanged';
   const broughtSomethingNew =
@@ -126,20 +197,20 @@ async function runInstall(options /* , command */) {
     result.claudeMd.action === 'created';
 
   if (broughtSomethingNew) {
-    console.log(
+    log(
       `cmk install: ${projectName} ready — context/ scaffolded${
         wired ? ', hooks wired' : ''
       }.`,
     );
   } else {
-    console.log(
+    log(
       `cmk install: ${projectName} already set up (your edits preserved)${
         wired ? ', hooks refreshed' : ''
       }.`,
     );
   }
   if (wired) {
-    console.log(
+    log(
       '  Restart Claude Code to activate. Complete install — no separate /plugin step needed.',
     );
   }
@@ -147,35 +218,39 @@ async function runInstall(options /* , command */) {
   // Auto Memory by default; surface the one-command opt-out (null when already
   // opted out, so we don't nag).
   const nativeNote = nativeMemoryInstallNote(result.projectRoot);
-  if (nativeNote) console.log(nativeNote);
+  if (nativeNote) log(nativeNote);
   // Task 46: semantic-recall outcome (pure formatter, Task 125.4 — testable
   // without spawning install; the error case returns null because enableSemantic
   // errors already land in result.errors and print through the error path).
   const semanticLine = formatSemanticSummary(result.semantic, { noHooks });
-  if (semanticLine) console.log(semanticLine);
+  if (semanticLine) log(semanticLine);
   if (verbose) {
-    console.log(
+    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(
+    log(
       `  .gitignore=${result.gitignore.action} · CLAUDE.md=${result.claudeMd.action} · hooks=${result.hooks.action}`,
     );
   }
 
   if (result.claudeMd.action === 'downgrade-blocked') {
-    console.error(
+    logError(
       `  warning: CLAUDE.md already has a newer kit block (v${result.claudeMd.oldVersion}). ` +
         `Re-run with --force to downgrade.`
     );
   }
 
   if (result.errors.length > 0) {
-    for (const e of result.errors) console.error(`  error: ${e.path}: ${e.error}`);
+    for (const e of result.errors) logError(`  error: ${e.path}: ${e.error}`);
     process.exitCode = 1;
   }
+
+  // Task 141a: the binding ask comes LAST — it's the one thing the user may
+  // still need to act on, and the tail of install output is what gets read.
+  await offerBindingFix(result.nativeBinding, options, { log, logError });
 }
 
 /**
@@ -656,7 +731,10 @@ export function parseFactInput(options, { readFile, readStdin } = {}) {
   };
 }
 
-export function runRemember(textParts, options, deps = {}) {
+// Task 143: async since the near-dup guard may embed the incoming text
+// (one model call, explicit path only). Commander awaits actions; the
+// terse-path tests were updated to await (contract change, intent preserved).
+export async function runRemember(textParts, options, deps = {}) {
   const projectRoot = deps.projectRoot ?? resolvePath(process.cwd());
   const userDir =
     deps.userDir ?? process.env.MEMORY_KIT_USER_DIR ?? join(homedir(), '.claude-memory-kit');
@@ -717,6 +795,10 @@ export function runRemember(textParts, options, deps = {}) {
   const tier = 'P';
   const trust = options?.trust ?? 'high';
   const section = options?.section ?? 'Active Threads';
+  // Task 143 (D-130): semantic near-dup guard — extra opts only when this
+  // project is semantic-configured and the embedder is available; {} keeps
+  // the literal pipeline (graceful degradation, never blocks capture).
+  const nearDup = await prepareNearDupGuard({ projectRoot, text, ...(deps.nearDupGuard ? { prepareImpl: deps.nearDupGuard.prepareImpl, resolveModeImpl: deps.nearDupGuard.resolveModeImpl } : {}) });
   const r = memoryWrite({
     action: 'add',
     text,
@@ -727,22 +809,23 @@ export function runRemember(textParts, options, deps = {}) {
     source: 'user-explicit',
     projectRoot,
     userDir,
+    ...nearDup,
   });
   if (r.action === 'error') {
     for (const e of r.errors ?? [`error (${r.errorCategory})`]) {
-      console.error(`cmk remember: ${e}`);
+      logError(`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. ` +
+    log(
+      `cmk remember: queued for review — a similar or higher-trust fact already covers this. ` +
         `Resolve with \`cmk queue conflicts\` (${r.path}).`,
     );
     return;
   }
-  console.log(
+  log(
     `cmk remember: saved to P/MEMORY.md (${section})${r.id ? ` [${r.id}]` : ''}`,
   );
 }
@@ -786,6 +869,32 @@ function runReindex(options /* , command */) {
   }
 }
 
+/**
+ * `cmk digest` (Task 147) — print a regenerated, readable render of everything
+ * the kit currently knows, AND sync the append-only context/DECISIONS.md
+ * journal (the permanent decision ledger; D-161). The digest goes to stdout;
+ * the journal is a committed file the sync maintains in place.
+ */
+async function runDigestCli(options) {
+  const projectRoot = resolvePath(process.cwd());
+  const { digest } = await import('./digest.mjs');
+  const { syncDecisionsJournal } = await import('./decisions-journal.mjs');
+
+  // Keep the permanent decision journal current (append-only; best-effort —
+  // a journal hiccup must not break the digest render).
+  const sync = syncDecisionsJournal({ projectRoot });
+
+  console.log(digest({ projectRoot }));
+
+  if (sync.written) {
+    console.log(`\ncontext/DECISIONS.md updated (+${sync.appended} bytes) — the append-only decision journal.`);
+  } else if (sync.error) {
+    console.error(`\n(decision journal not updated: ${sync.error})`);
+  } else {
+    console.log('\ncontext/DECISIONS.md is up to date.');
+  }
+}
+
 /**
  * `cmk forget <id-or-query>` — wired in Task 9. Tombstones the matching
  * fact (moves it to <tier>/<memory|fragments>/archive/tombstones/<id>.md
@@ -1183,12 +1292,93 @@ async function runDoctorCli(/* options */) {
       `Summary: ${counts.pass} pass · ${counts.fail} fail · ${counts.skip} skip (${r.duration_ms}ms)`,
     );
     if (counts.fail > 0) process.exitCode = 1;
+
+    // Task 144 (D-130): the memory-HEALTH section — content quality, not
+    // plumbing. Informational only: read-only, never changes the exit code,
+    // best-effort (a content-stat hiccup must not fail a healthy doctor).
+    try {
+      const { analyzeMemoryHealth, formatMemoryHealth } = await import('./memory-health.mjs');
+      console.log('');
+      console.log(formatMemoryHealth(analyzeMemoryHealth({ projectRoot })));
+    } catch {
+      // informational section only — stay silent on failure
+    }
   } catch (err) {
     console.error(`cmk doctor: unexpected error: ${err?.message ?? err}`);
     process.exitCode = 2;
   }
 }
 
+// Task 129 (D-121): `cmk config` — real, replacing the v0.1.0 stub. Dotted-key
+// get/set/--show-origin over the per-tier settings.json files. Dep-injectable
+// (cwd/userDir/log/logError) on the runImportClaudeMd pattern for testing the
+// CLI surface. The pure resolution/mutation lives in config-core.mjs.
+const TIER_FLAG_TO_NAME = { local: 'local', project: 'project', user: 'user' };
+
+export function runConfigGet(key, options = {}) {
+  const projectRoot = options?.cwd ?? resolvePath(process.cwd());
+  const userDir = options?.userDir ?? join(homedir(), '.claude-memory-kit');
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
+  const r = configGet(key, { projectRoot, userDir });
+  if (!r.found) {
+    logError(`cmk config get: '${key}' is not set in any tier`);
+    process.exitCode = 2;
+    return r;
+  }
+  log(typeof r.value === 'string' ? r.value : JSON.stringify(r.value));
+  return r;
+}
+
+export function runConfigSet(key, value, options = {}) {
+  const projectRoot = options?.cwd ?? resolvePath(process.cwd());
+  const userDir = options?.userDir ?? join(homedir(), '.claude-memory-kit');
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
+  const tier = TIER_FLAG_TO_NAME[options?.tier ?? 'project'] ?? 'project';
+  const r = configSet(key, value, { projectRoot, userDir, tier });
+  if (!r.ok) {
+    logError(`cmk config set: ${r.error}`);
+    process.exitCode = 2;
+    return r;
+  }
+  log(`cmk config set: ${key} = ${value} (${r.tier} tier)`);
+  return r;
+}
+
+export function runConfigShowOrigin(key, options = {}) {
+  const projectRoot = options?.cwd ?? resolvePath(process.cwd());
+  const userDir = options?.userDir ?? join(homedir(), '.claude-memory-kit');
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
+  const r = configShowOrigin(key, { projectRoot, userDir });
+  if (!r.found) {
+    logError(`cmk config --show-origin: '${key}' is not set in any tier`);
+    process.exitCode = 2;
+    return r;
+  }
+  for (const e of r.entries) {
+    const val = typeof e.value === 'string' ? `"${e.value}"` : JSON.stringify(e.value);
+    const note = e.winner ? '' : `   (shadowed by ${e.shadowedBy})`;
+    log(`${e.tier.padEnd(8)} ${e.path}   ${val}${note}`);
+  }
+  return r;
+}
+
+// The parent `cmk config` action: handle the --show-origin flag here; the
+// get/set children carry their own actions (wired in the registry below).
+// Exported for the branch test (the no-subcommand path).
+export function runConfigCli(options /* , command */) {
+  if (options?.showOrigin) {
+    return runConfigShowOrigin(options.showOrigin, options);
+  }
+  const logError = options?.logError ?? console.error;
+  logError(
+    'cmk config: specify a subcommand — `get <key>`, `set <key> <value>`, or `--show-origin <key>`.',
+  );
+  process.exitCode = 2;
+}
+
 async function runRepairCli(options /* , command */) {
   const projectRoot = resolvePath(process.cwd());
   const userDir = join(homedir(), '.claude-memory-kit');
@@ -1304,6 +1494,59 @@ export async function runImportAnthropicMemory(options = {}) {
   }
 }
 
+// Task 142 (D-130): onboard from an existing rules file. Dep-injectable
+// (projectRoot / log / logError / importFn) on the runImportAnthropicMemory
+// pattern so the real CLI path is verifiable in a sandbox. `file` is the
+// optional positional (commander passes it first), defaulting to CLAUDE.md.
+export async function runImportClaudeMd(file, options = {}) {
+  const projectRoot = options?.projectRoot ?? resolvePath(process.cwd());
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
+  const dryRun = options?.dryRun === true;
+  const acceptAll = options?.yes === true;
+  const importFn = options?.importFn ?? importClaudeMd;
+  try {
+    const r = await importFn({ projectRoot, file, dryRun, acceptAll });
+    if (r.action === 'error') {
+      logError(`cmk import-claude-md: error — ${(r.errors ?? []).join('; ')}`);
+      process.exitCode = 2;
+      return r;
+    }
+    if (r.reason === 'no-source') {
+      log(`cmk import-claude-md: no rules file found at ${r.sourcePath}`);
+      return r;
+    }
+    if (r.reason) {
+      // e.g. read-source-failed — completed-with-failure must not print the
+      // success-shaped "applied 0" line (skill-review 2026-06-12 finding).
+      logError(`cmk import-claude-md: ${r.reason} (${r.sourcePath})`);
+      process.exitCode = 2;
+      return r;
+    }
+    const listProposals = () => {
+      for (const p of r.proposals) log(`  + [${p.type}] L${p.line}: ${p.text}`);
+    };
+    if (r.mode === 'dry-run') {
+      log(`cmk import-claude-md: dry-run — ${r.proposals.length} proposal(s), ${r.skipped} duplicate(s) skipped`);
+      listProposals();
+      return r;
+    }
+    if (r.mode === 'requires-confirmation') {
+      log(`cmk import-claude-md: ${r.proposals.length} proposal(s) ready to apply.`);
+      log('  Re-run with --yes to apply, or --dry-run to inspect.');
+      listProposals();
+      return r;
+    }
+    const rejectedNote = r.rejected > 0 ? `, ${r.rejected} rejected by Poison_Guard` : '';
+    const errorNote = r.errors > 0 ? `, ${r.errors} error(s)` : '';
+    log(`cmk import-claude-md: applied ${r.accepted} fact(s), skipped ${r.skipped} duplicate(s)${rejectedNote}${errorNote}`);
+    return r;
+  } catch (err) {
+    logError(`cmk import-claude-md: unexpected error: ${err?.message ?? err}`);
+    process.exitCode = 2;
+  }
+}
+
 async function runTranscriptsDispatch(childName, options) {
   if (childName === 'extract') {
     return runTranscriptsExtract(options);
@@ -1426,7 +1669,10 @@ async function runMcpDispatch(childName) {
     }
     return;
   }
-  console.error(`cmk mcp: ${NOTICE_PREFIX} (unknown sub-verb '${childName}')`);
+  // A bare `cmk mcp` (no sub-verb) reaches here post-Task-129 (the parent
+  // action is now wired) — commander passes an options object, not a string.
+  const verb = typeof childName === 'string' ? childName : '(none)';
+  console.error(`cmk mcp: ${NOTICE_PREFIX} (run \`cmk mcp serve\`; got sub-verb '${verb}')`);
   process.exitCode = 2;
 }
 
@@ -1437,7 +1683,10 @@ async function runQueueDispatch(childName) {
   if (childName === 'review') {
     return runQueueReview();
   }
-  console.log(`cmk queue: ${NOTICE_PREFIX} (unknown sub-verb '${childName}')`);
+  // A bare `cmk queue` reaches here post-Task-129 (parent action wired);
+  // commander passes an options object, not a string sub-verb.
+  const verb = typeof childName === 'string' ? childName : '(none)';
+  console.log(`cmk queue: ${NOTICE_PREFIX} (run \`cmk queue review\` or \`cmk queue conflicts\`; got '${verb}')`);
   process.exitCode = 2;
 }
 
@@ -1796,29 +2045,40 @@ export const subcommands = [
     milestone: 37,
     action: runDoctorCli,
   },
+  {
+    name: 'digest',
+    description: 'print a readable digest of everything in memory + sync the append-only DECISIONS.md decision journal',
+    milestone: 147,
+    action: runDigestCli,
+  },
   {
     name: 'config',
-    description: 'settings access (per design §7.2)',
-    milestone: 'v0.1.x',
+    description: 'read/write kit settings (context/settings.json) without hand-editing JSON',
+    milestone: 129,
     optionSpec: [
-      { flags: '--show-origin <key>', description: 'print where each value comes from (project / user / local tier)' },
+      { flags: '--show-origin <key>', description: 'print every tier that defines a setting (winner + shadowed) — the "where did this come from?" debug surface' },
     ],
     children: [
       {
         name: 'get',
-        description: 'print the resolved value of a setting',
-        argSpec: [{ flags: '<key>', description: 'setting key (dotted path)' }],
+        description: 'print the resolved value of a setting (dotted key; local > project > user)',
+        argSpec: [{ flags: '<key>', description: 'setting key (dotted path, e.g. search.default_mode)' }],
+        action: (key, options) => runConfigGet(key, options),
       },
       {
         name: 'set',
-        description: 'set a setting in the current tier',
+        description: 'set a setting in the project tier (or --local)',
         argSpec: [
           { flags: '<key>', description: 'setting key (dotted path)' },
-          { flags: '<value>', description: 'new value' },
+          { flags: '<value>', description: 'new value (true/false/number coerced; else string)' },
+        ],
+        optionSpec: [
+          { flags: '--local', description: 'write to the local tier (context.local/, gitignored) instead of project' },
         ],
+        action: (key, value, options) => runConfigSet(key, value, { tier: options?.local ? 'local' : 'project' }),
       },
     ],
-    action: stub('config', 'v0.1.x'),
+    action: runConfigCli,
   },
   {
     name: 'import-anthropic-memory',
@@ -1830,6 +2090,19 @@ export const subcommands = [
     ],
     action: runImportAnthropicMemory,
   },
+  {
+    name: 'import-claude-md',
+    description: 'onboard from an existing rules file (CLAUDE.md / .cursorrules / AGENTS.md) — parse it into typed facts through the safe write path',
+    milestone: 142,
+    argSpec: [
+      { flags: '[file]', description: 'rules file to import, relative to the project root (default: CLAUDE.md)' },
+    ],
+    optionSpec: [
+      { flags: '--dry-run', description: 'preview the typed proposals without modifying files' },
+      { flags: '--yes', description: 'apply every proposal without prompting (apply requires explicit --yes)' },
+    ],
+    action: runImportClaudeMd,
+  },
   {
     name: 'transcripts',
     description: "extract clean markdown transcripts from Claude Code session jsonls under ~/.claude/projects/",

package/src/transcript-index.mjs

@@ -15,7 +15,7 @@
 //   chunkTranscript(text) → [{heading, body, sourceLine, chunkIdx}]  (pure)
 //   syncTranscriptChunks({db, projectRoot, now?}) → {files, chunks}
 
-import { createHash } from 'node:crypto';
+import { hashContent } from './content-hash.mjs';
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
@@ -57,8 +57,11 @@ export function chunkTranscript(text) {
   return chunks;
 }
 
+// Transcript-chunk fingerprint for the `files`-table diff key (column name
+// `sha1` kept for checkpoint back-compat; algorithm is SHA-256 via hashContent,
+// D-149). Self-heals on the first post-upgrade boot like the observation index.
 function sha1(text) {
-  return createHash('sha1').update(text, 'utf8').digest('hex');
+  return hashContent(text);
 }
 
 // Task 126 (D-119) — the raw-tier scope covers BOTH halves of the session

package/src/write-fact.mjs

@@ -21,6 +21,7 @@ import { reindex } from './reindex.mjs';
 import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
 import { sanitizeHomePaths } from './sanitize.mjs';
+import { sanitizePrivacyTags } from './privacy.mjs';
 import { checkPoisonGuard, logPoisonGuardRejection } from './poison-guard.mjs';
 
 const VALID_TYPES = new Set(['user', 'feedback', 'project', 'reference']);
@@ -157,6 +158,14 @@ export function writeFact(opts = {}) {
   // — that's its purpose. The id hashes the SANITIZED body, so dedup keys on
   // what actually lands on disk.
   let { body, title } = opts;
+  // Privacy: strip <private>…</private> FIRST, on EVERY tier (cut-gate
+  // v0.3.1 finding — the tag was honored only by the UserPromptSubmit hook,
+  // so a fact written via cmk remember/mk_remember/import kept the secret).
+  // Runs before home-path sanitization, Poison_Guard, and id-generation, so
+  // the redacted body is what gets screened, hashed (dedup keys on what
+  // lands), and written.
+  body = sanitizePrivacyTags(body);
+  title = sanitizePrivacyTags(title);
   if (opts.tier === 'P' || opts.tier === 'U') {
     body = sanitizeHomePaths(body);
     title = sanitizeHomePaths(title);
@@ -252,10 +261,32 @@ export function writeFact(opts = {}) {
   // 2026-06-03 — "users should get it working from the start"). Best-effort: the
   // fact is already durably on disk, so an index-rebuild hiccup must not turn a
   // successful capture into an error — the next reindex/search self-heals.
+  //
+  // D-152: the failure is OBSERVABLE, not silently swallowed. A detached
+  // auto-extract child whose reindex was killed mid-rebuild (hook ceiling) used
+  // to leave INDEX.md lagging with ZERO trace — so a stale committed INDEX was
+  // undiagnosable (the user caught a 5-fact lag in the cut-gate). On throw we
+  // now record an INDEX_REBUILD_FAILED audit entry; HC-4 still detects the drift
+  // and `cmk reindex` corrects it. The `_reindexFn` seam is test-only.
+  const doReindex = opts._reindexFn ?? reindex;
   try {
-    reindex({ tier: opts.tier, projectRoot: opts.projectRoot, userDir: opts.userDir, warn: () => {} });
-  } catch {
-    // index rebuild is best-effort; capture already succeeded
+    doReindex({ tier: opts.tier, projectRoot: opts.projectRoot, userDir: opts.userDir, warn: () => {} });
+  } catch (reindexErr) {
+    // index rebuild is best-effort; capture already succeeded — but leave a
+    // trace so a lagging committed INDEX is diagnosable, never silent.
+    try {
+      appendAuditEntry(tierRoot, {
+        ts: createdAt,
+        action: 'index-rebuild-failed',
+        tier: opts.tier,
+        id,
+        reasonCode: REASON_CODES.INDEX_REBUILD_FAILED,
+        paths: { after: path },
+        extra: { error: String(reindexErr?.message ?? reindexErr) },
+      });
+    } catch {
+      // even the audit append is best-effort; the fact is already on disk
+    }
   }
 
   // Default create-audit (Task 123.A / D-103). writeFact is the single boundary

package/template/.claude/skills/memory-search/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-search
-description: Searches the project's deep memory archive (claude-memory-kit) and returns a curated summary of relevant facts, decisions, and history. Use when the answer may already be recorded from a past session — "what did we decide about X", "why did we do Y", "have we seen this error before", "how did we solve this last time", "what's our convention for Z" — or before re-deriving any project knowledge, setup, or prior decision from the code. The session-start memory snapshot is a bounded hot index, not everything; this skill reaches the rest. Skip when the question is purely about current code state (use Read/Grep), about this conversation only, or the user asked to ignore memory.
+description: Searches the project's recorded memory (claude-memory-kit) — decisions, conventions, architecture, the reasoning behind choices, and where things live — and returns a curated, cited summary. Fire whenever the answer might be something the project already established in past work, HOWEVER the question is phrased — any prior decision, convention, rationale, or "how/where/why is it this way" question, including oblique or roundabout asks ("why is everything so spread out?", "remind me what we settled on for X", "how come these files are tiny?"). Also fire when a "[claude-memory-kit] Memory available" hint appears on the prompt. The examples are illustrative, not a checklist — prefer recalling over re-deriving an answer from the code. The session-start snapshot is a bounded index; this skill reaches the rest. Skip only when the question is purely about uncommitted or just-edited live code that memory cannot know, concerns this conversation only, or the user asked to ignore memory.
 context: fork
 allowed-tools: mcp__cmk__mk_search mcp__cmk__mk_get mcp__cmk__mk_timeline mcp__cmk__mk_recent_activity Bash(cmk search *) Bash(cmk get *) Bash(cmk timeline *) Bash(cmk recent-activity *)
 ---

package/template/.gitattributes.fragment

@@ -0,0 +1,16 @@
+# claude-memory-kit — added by `cmk install`. Do not edit by hand;
+# `cmk install` refreshes these lines idempotently. Remove via
+# `cmk uninstall`.
+#
+# Force LF on the COMMITTED memory files. The kit's frontmatter parser uses
+# a strict-LF boundary and split('\n') readers; default Windows git
+# (autocrlf=true) rewrites line endings at clone, which made every fact
+# invisible to search on a Windows checkout (D-126). The read side now
+# self-heals (tolerant CRLF reads), but pinning LF here PREVENTS the
+# mangling so it never has to.
+#
+# Scoped to the text extensions the kit actually commits (.md + .json) under
+# context/ — NOT a blanket `context/** text`, so a future committed binary
+# under context/ is never force-normalized + corrupted.
+context/**/*.md text eol=lf
+context/**/*.json text eol=lf

package/template/CLAUDE.md.template

@@ -26,7 +26,7 @@ The `cmk doctor` health checks verify each layer is wired correctly: install int
 
 ### Recalling memory (for Claude)
 
-The snapshot injected at session start is a **bounded hot index, not everything** — there is a deeper, queryable archive. When a question is "what did we decide / what's our X / how does the user work / what's the setup," **query your memory instead of re-deriving the answer from scratch**:
+The snapshot injected at session start is a **bounded hot index, not everything** — there is a deeper, queryable archive. When a question is "what did we decide / what's our X / how does the user work / what's the setup / **how is this project structured or built / where does X live / what's the architecture**," **query your memory instead of re-deriving the answer from scratch** — the structure is a recorded decision, recall it before re-reading the files to reconstruct it:
 
 - **`cmk search "<topic>"`** — find any captured fact (decisions, preferences, config, lessons) across the project + user tiers.
 - **`context/memory/<type>_<slug>.md`** — the granular fact archive with full **Why / How** rationale (`context/memory/INDEX.md` lists them).