claude-mem-lite 2.71.3 → 2.72.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.71.3",
+      "version": "2.72.0",
       "source": "./",
       "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.71.3",
+  "version": "2.72.0",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/bash-utils.mjs

@@ -15,9 +15,25 @@ export function detectBashSignificance(input, response) {
   // Skip error keyword matching when the command is a read/search operation
   // (grep output naturally contains matched keywords like "error")
   const isSearchCmd = /\b(grep|rg|ag|ack|cat|head|tail|less|more|find|locate|wc|file|which|type)\b/i.test(cmd);
-  const isError = !isSearchCmd
+  const looksLikeError = !isSearchCmd
     && /\berror\b|\bERR!|fail(ed|ure)?|exception|panic|traceback|errno|enoent|command not found/i.test(response)
     && response.length > 15;
+  // Green test summary exemption — "0 fail/failed/failures" in test-runner
+  // output (bun/jest/pytest) gets matched by the broad `fail(ed|ure)?` token
+  // above, driving episode.isError=true for passing runs. A live cluster-merge
+  // audit found 5 noise observations with "Error: <test>.ts ... 0 fail" titles
+  // from this path. Flip back to non-error iff a "0 fail" marker is present
+  // AND no hard-error signal (panic / ENOENT / AssertionError / TypeError /
+  // explicit FAIL banner / npm ERR!) coexists in the output.
+  const hasGreenTestSummary = looksLikeError
+    && /\b0\s+(fail|failed|failures)\b/i.test(response);
+  // NOTE: do not add `\bFAIL\s` here — with /i flag it would re-match the
+  // very `0 fail\n` token green-summary is trying to exempt. A real test
+  // failure produces "N fail" (N≥1) which never triggers hasGreenTestSummary,
+  // so a uppercase-FAIL fingerprint isn't needed for correctness.
+  const hasHardErrorSignal = hasGreenTestSummary
+    && /\bERR!|panic|traceback|enoent|command not found|exception|AssertionError|TypeError:|SyntaxError:/i.test(response);
+  const isError = looksLikeError && !(hasGreenTestSummary && !hasHardErrorSignal);
   // Match actual test runner invocations, not commands that merely reference "test" as a keyword
   const isTest = /\b(npm\s+test|npm\s+run\s+test|yarn\s+test|pnpm\s+test|pnpm\s+run\s+test|bun\s+test|go\s+test|cargo\s+test)\b/i.test(cmd)
     || /\b(jest|pytest|vitest|mocha|cypress|playwright)\b/i.test(cmd);

package/hook-optimize.mjs

@@ -74,12 +74,13 @@ export function rebuildVector(db, obsId, textParts) {
  *
  * @param {object} db better-sqlite3 database handle
  * @param {number} limit max candidates to return
- * @param {{ scope?: 'narrow' | 'wide' }} [opts]
+ * @param {{ scope?: 'narrow' | 'wide', project?: string }} [opts] Optional project filter (e.g. inferProject()-resolved name) narrows candidates to a single project — opt-in to preserve prior cross-project default.
  */
-export function findReenrichCandidates(db, limit = 10, { scope = 'narrow' } = {}) {
+export function findReenrichCandidates(db, limit = 10, { scope = 'narrow', project } = {}) {
+  const projectClause = project ? 'AND project = ?' : '';
   if (scope === 'wide') {
-    return db.prepare(`
-      SELECT id, title, narrative, type, subtitle, concepts, facts
+    const stmt = db.prepare(`
+      SELECT id, title, narrative, type, subtitle, concepts, facts, project
       FROM observations
       WHERE COALESCE(compressed_into, 0) = 0
         AND superseded_at IS NULL
@@ -88,14 +89,16 @@ export function findReenrichCandidates(db, limit = 10, { scope = 'narrow' } = {}
         AND (lesson_learned IS NULL OR lesson_learned = '')
         AND LENGTH(COALESCE(narrative, '')) > 100
         AND ${notLowSignalTitleClause('')}
+        ${projectClause}
       ORDER BY
         CASE type WHEN 'decision' THEN 0 WHEN 'bugfix' THEN 1 WHEN 'refactor' THEN 2 ELSE 3 END,
         created_at_epoch DESC
       LIMIT ?
-    `).all(limit);
+    `);
+    return project ? stmt.all(project, limit) : stmt.all(limit);
   }
-  return db.prepare(`
-    SELECT id, title, narrative, type, subtitle
+  const stmt = db.prepare(`
+    SELECT id, title, narrative, type, subtitle, project
     FROM observations
     WHERE COALESCE(compressed_into, 0) = 0
       AND (concepts IS NULL OR concepts = '')
@@ -103,13 +106,15 @@ export function findReenrichCandidates(db, limit = 10, { scope = 'narrow' } = {}
       AND lesson_learned IS NULL
       AND search_aliases IS NULL
       AND optimized_at IS NULL
+      ${projectClause}
     ORDER BY created_at_epoch DESC
     LIMIT ?
-  `).all(limit);
+  `);
+  return project ? stmt.all(project, limit) : stmt.all(limit);
 }
 
-export async function executeReenrich(db, limit = 10, { scope = 'narrow' } = {}) {
-  const candidates = findReenrichCandidates(db, limit, { scope });
+export async function executeReenrich(db, limit = 10, { scope = 'narrow', project } = {}) {
+  const candidates = findReenrichCandidates(db, limit, { scope, project });
   if (candidates.length === 0) return { processed: 0, skipped: 0 };
 
   let processed = 0, skipped = 0;
@@ -206,14 +211,17 @@ export function shouldRunNormalize() {
   }
 }
 
-export function extractUniqueConcepts(db, limit = 500) {
-  const rows = db.prepare(`
+export function extractUniqueConcepts(db, limit = 500, { project } = {}) {
+  const projectClause = project ? 'AND project = ?' : '';
+  const stmt = db.prepare(`
     SELECT concepts FROM observations
     WHERE COALESCE(compressed_into, 0) = 0
       AND concepts IS NOT NULL AND concepts != ''
+      ${projectClause}
     ORDER BY created_at_epoch DESC
     LIMIT 2000
-  `).all();
+  `);
+  const rows = project ? stmt.all(project) : stmt.all();
 
   const conceptSet = new Set();
   for (const row of rows) {
@@ -304,10 +312,10 @@ export function applyNormalization(db, groups) {
   return { updated };
 }
 
-export async function executeNormalize(db, force = false) {
+export async function executeNormalize(db, force = false, { project } = {}) {
   if (!force && !shouldRunNormalize()) return { skipped: true, reason: 'gate' };
 
-  const concepts = extractUniqueConcepts(db);
+  const concepts = extractUniqueConcepts(db, 500, { project });
   if (concepts.length < 5) return { skipped: true, reason: 'too few concepts' };
 
   const groups = await identifySynonymGroups(concepts);
@@ -326,18 +334,21 @@ const MERGE_TIME_WINDOW_MS = 30 * 86400000;
 const MERGE_JACCARD_LOW = 0.4;
 const MERGE_JACCARD_HIGH = 0.85;
 
-export function findMergeCandidates(db, maxClusters = 5) {
+export function findMergeCandidates(db, maxClusters = 5, { project } = {}) {
   const cutoff = Date.now() - MERGE_TIME_WINDOW_MS;
-  const rows = db.prepare(`
-    SELECT id, title, narrative, project, access_count, created_at_epoch, minhash_sig
+  const projectClause = project ? 'AND project = ?' : '';
+  const stmt = db.prepare(`
+    SELECT id, title, narrative, project, type, access_count, created_at_epoch, minhash_sig
     FROM observations
     WHERE COALESCE(compressed_into, 0) = 0
       AND optimized_at IS NULL
       AND title IS NOT NULL AND title != ''
       AND created_at_epoch > ?
+      ${projectClause}
     ORDER BY created_at_epoch DESC
     LIMIT 200
-  `).all(cutoff);
+  `);
+  const rows = project ? stmt.all(cutoff, project) : stmt.all(cutoff);
 
   const used = new Set();
   const clusters = [];
@@ -450,8 +461,8 @@ Return ONLY valid JSON:
   }
 }
 
-export async function executeClusterMerge(db, maxClusters = 5) {
-  const clusters = findMergeCandidates(db, maxClusters);
+export async function executeClusterMerge(db, maxClusters = 5, { project } = {}) {
+  const clusters = findMergeCandidates(db, maxClusters, { project });
   if (clusters.length === 0) return { processed: 0, merged: 0 };
 
   let merged = 0;
@@ -468,17 +479,20 @@ export async function executeClusterMerge(db, maxClusters = 5) {
 const COMPRESS_TIME_SPLIT_MS = 14 * 86400000;
 const COMPRESS_COSINE_THRESHOLD = 0.3;
 
-export function findSmartCompressCandidates(db, ageDays = 30) {
+export function findSmartCompressCandidates(db, ageDays = 30, { project } = {}) {
   const cutoff = Date.now() - ageDays * 86400000;
-  return db.prepare(`
+  const projectClause = project ? 'AND project = ?' : '';
+  const stmt = db.prepare(`
     SELECT id, title, narrative, lesson_learned, project, type, created_at_epoch
     FROM observations
     WHERE COALESCE(compressed_into, 0) = 0
       AND COALESCE(importance, 1) = 1
       AND COALESCE(access_count, 0) = 0
       AND created_at_epoch < ?
+      ${projectClause}
     ORDER BY project, created_at_epoch
-  `).all(cutoff);
+  `);
+  return project ? stmt.all(cutoff, project) : stmt.all(cutoff);
 }
 
 export function clusterForCompression(candidates, db) {
@@ -642,8 +656,8 @@ JSON: {"title":"descriptive summary ≤120 chars","narrative":"comprehensive sum
   }
 }
 
-export async function executeSmartCompress(db, maxClusters = 5) {
-  const candidates = findSmartCompressCandidates(db);
+export async function executeSmartCompress(db, maxClusters = 5, { project } = {}) {
+  const candidates = findSmartCompressCandidates(db, 30, { project });
   if (candidates.length < 3) return { processed: 0, compressed: 0 };
 
   const clusters = clusterForCompression(candidates, db);
@@ -661,23 +675,34 @@ export async function executeSmartCompress(db, maxClusters = 5) {
 
 // ─── Pipeline Orchestrator ──────────────────────────────────────────────────
 
-export function optimizePreview(db) {
-  const reenrich = findReenrichCandidates(db, 1000).length;
+/**
+ * @param {object} db better-sqlite3 database handle
+ * @param {{ project?: string, detail?: boolean }} [opts]
+ *   project: scope all candidate finders to a single project (opt-in; default scans all).
+ *   detail: when true, also return `mergeClusters` / `reenrichSamples` / `compressSamples`
+ *     arrays alongside the aggregate counts so callers (CLI --verbose, MCP detail mode)
+ *     can render auditable previews without re-running the finders. The candidate-count
+ *     arms still call the finders with high limits — detail mode does NOT widen scope,
+ *     it surfaces the same rows the counts already crossed.
+ */
+export function optimizePreview(db, { project, detail = false } = {}) {
+  const reenrichCandidates = findReenrichCandidates(db, 1000, { project });
+  const reenrich = reenrichCandidates.length;
   // R-7: also report the widened-scope candidate count so users can see how many
   // bugfix/refactor/feature/decision observations are eligible for lesson backfill.
-  const reenrichWide = findReenrichCandidates(db, 5000, { scope: 'wide' }).length;
+  const reenrichWide = findReenrichCandidates(db, 5000, { scope: 'wide', project }).length;
 
-  const concepts = extractUniqueConcepts(db);
+  const concepts = extractUniqueConcepts(db, 500, { project });
   const normalizeReady = shouldRunNormalize() && concepts.length >= 5;
 
-  const mergeClusters = findMergeCandidates(db, 50);
+  const mergeClusters = findMergeCandidates(db, 50, { project });
   const clusterMerge = mergeClusters.length;
 
-  const compressCandidates = findSmartCompressCandidates(db);
+  const compressCandidates = findSmartCompressCandidates(db, 30, { project });
   const compressClusters = clusterForCompression(compressCandidates, db);
   const smartCompress = compressClusters.length;
 
-  return {
+  const result = {
     reenrich,
     reenrichWide,
     normalize: normalizeReady ? concepts.length : 0,
@@ -686,6 +711,15 @@ export function optimizePreview(db) {
     smartCompress,
     total: reenrich + (normalizeReady ? 1 : 0) + clusterMerge + smartCompress,
   };
+  if (detail) {
+    // Caps avoid dumping arbitrarily large arrays into CLI/MCP output — 20 picks
+    // a sample size big enough to be auditable but small enough to fit a terminal
+    // page. Callers that need more can drop --verbose and run the finders directly.
+    result.mergeClusters = mergeClusters;
+    result.reenrichSamples = reenrichCandidates.slice(0, 20);
+    result.compressSamples = compressClusters.slice(0, 5);
+  }
+  return result;
 }
 
 /**
@@ -701,8 +735,10 @@ export function optimizePreview(db) {
  * @param {boolean} [opts.force=false] Bypass time-based gates (e.g. normalize interval).
  * @param {'narrow'|'wide'} [opts.reenrichScope='narrow'] Scope for the re-enrich task.
  *   'wide' targets bugfix/refactor/feature/decision with narrative but no lesson (R-7).
+ * @param {string} [opts.project] Filter all tasks to a single project. Opt-in;
+ *   absence preserves the prior all-projects default.
  */
-export async function optimizeRun(db, { tasks, maxItems = 15, force = false, reenrichScope = 'narrow' } = {}) {
+export async function optimizeRun(db, { tasks, maxItems = 15, force = false, reenrichScope = 'narrow', project } = {}) {
   const allTasks = ['re-enrich', 'normalize', 'cluster-merge', 'smart-compress'];
   const selectedTasks = tasks && tasks.length > 0 ? tasks : allTasks;
   // Single-task mode: give that task the full budget. Distribution only makes sense
@@ -716,16 +752,16 @@ export async function optimizeRun(db, { tasks, maxItems = 15, force = false, ree
     try {
       switch (task) {
         case 're-enrich':
-          results.reenrich = await executeReenrich(db, budget.reenrich, { scope: reenrichScope });
+          results.reenrich = await executeReenrich(db, budget.reenrich, { scope: reenrichScope, project });
           break;
         case 'normalize':
-          results.normalize = await executeNormalize(db, force);
+          results.normalize = await executeNormalize(db, force, { project });
           break;
         case 'cluster-merge':
-          results.clusterMerge = await executeClusterMerge(db, budget.clusterMerge);
+          results.clusterMerge = await executeClusterMerge(db, budget.clusterMerge, { project });
           break;
         case 'smart-compress':
-          results.smartCompress = await executeSmartCompress(db, budget.smartCompress);
+          results.smartCompress = await executeSmartCompress(db, budget.smartCompress, { project });
           break;
       }
     } catch (e) {

package/install.mjs

@@ -25,11 +25,10 @@ const MARKETPLACE_KEY = 'sdsrss';
 const PLUGIN_KEY = `claude-mem-lite@${MARKETPLACE_KEY}`;
 const NPM_INSTALL_CMD = 'npm install --omit=dev --no-audit --no-fund';
 
-import { createRequire } from 'module';
-
 import { RESOURCE_METADATA } from './install-metadata.mjs';
 import { scanPluginCacheHookPollution } from './plugin-cache-guard.mjs';
 import { SOURCE_FILES, HOOK_SCRIPT_FILES } from './source-files.mjs';
+import { probeBetterSqlite3Binding, ensureBetterSqlite3Working } from './lib/binding-probe.mjs';
 
 // Re-export for backward compatibility — tests/install-hook-scripts.test.mjs
 // and any external consumers still import HOOK_SCRIPT_FILES from install.mjs.
@@ -37,6 +36,12 @@ import { SOURCE_FILES, HOOK_SCRIPT_FILES } from './source-files.mjs';
 // can share it without a static cycle.
 export { HOOK_SCRIPT_FILES };
 
+// Re-export for backward compatibility — tests/install-bsqlite-probe.test.mjs
+// imports these from install.mjs. The implementation moved to lib/binding-probe.mjs
+// so scripts/launch.mjs can share the probe without importing install.mjs (which
+// pulls heavy install-only deps).
+export { probeBetterSqlite3Binding, ensureBetterSqlite3Working };
+
 export function copyHookScripts(srcDir, destDir) {
   for (const name of HOOK_SCRIPT_FILES) {
     const src = join(srcDir, name);
@@ -75,55 +80,6 @@ export function migrateLegacyClaudeMemData(oldDir, newDir, opts = {}) {
   return { action: 'backed-up', backupPath };
 }
 
-/**
- * Probe better-sqlite3's native binding by importing it from `installDir`'s
- * node_modules and opening an in-memory DB. Returns {ok, error?}. `npm install`
- * exits 0 even when the prebuilt .node binary mismatches the running Node ABI
- * (e.g. NODE_MODULE_VERSION 137 on Node v24), so install must verify before
- * declaring success — otherwise the next launch FATALs with "Could not locate
- * the bindings file".
- */
-export async function probeBetterSqlite3Binding(installDir) {
-  try {
-    const localRequire = createRequire(join(installDir, 'package.json'));
-    const Database = localRequire('better-sqlite3');
-    const db = new Database(':memory:');
-    db.close();
-    return { ok: true };
-  } catch (e) {
-    return { ok: false, error: e.message };
-  }
-}
-
-/**
- * Verify better-sqlite3 binding works in `installDir`; if not, run
- * `npm rebuild better-sqlite3` and re-probe. Returns
- * { ok: true, action: 'verified' | 'rebuilt' } on success or
- * { ok: false, error } if rebuild can't fix it. The `probe` and `rebuild`
- * deps are injectable so this can be unit-tested without a real npm
- * subprocess.
- */
-export async function ensureBetterSqlite3Working(installDir, deps = {}) {
-  const probe = deps.probe || (() => probeBetterSqlite3Binding(installDir));
-  const rebuild = deps.rebuild || (async () => {
-    execSync('npm rebuild better-sqlite3', { cwd: installDir, stdio: 'pipe' });
-  });
-
-  const first = await probe();
-  if (first.ok) return { ok: true, action: 'verified' };
-
-  try {
-    await rebuild();
-  } catch (e) {
-    return { ok: false, error: `rebuild failed: ${e.message}` };
-  }
-
-  const second = await probe();
-  if (second.ok) return { ok: true, action: 'rebuilt' };
-
-  return { ok: false, error: second.error || first.error };
-}
-
 /**
  * Derive invocation_name from resource name when metadata doesn't provide one.
  * Rules:
@@ -421,7 +377,12 @@ async function install() {
   } else {
     log('Ensuring dependencies installed...');
     try {
-      execSync(NPM_INSTALL_CMD, { cwd: INSTALL_DIR, stdio: 'pipe' });
+      // stderr inherited so users see real-time progress (network slowness,
+      // node-gyp compile spinner, prebuild-install fallback messages). With
+      // `stdio: 'pipe'` the install appeared to hang under the 5-min Bash
+      // timeout when better-sqlite3 had no Node v24 prebuild and had to
+      // compile from source — see bug audit 2026-05.
+      execSync(NPM_INSTALL_CMD, { cwd: INSTALL_DIR, stdio: ['ignore', 'pipe', 'inherit'] });
       ok('Dependencies installed');
     } catch (e) {
       fail('npm install failed: ' + e.message);

package/lib/binding-probe.mjs

@@ -0,0 +1,63 @@
+// lib/binding-probe.mjs — better-sqlite3 native binding probe + auto-rebuild.
+//
+// Shared by install.mjs (verify after `npm install`) and scripts/launch.mjs
+// (verify before launching the MCP server). `npm install` exits 0 even when
+// the prebuilt .node binary mismatches the running Node ABI (e.g. ABI v137 on
+// Node v24), and the presence of node_modules/better-sqlite3/ on disk is not
+// sufficient — the binding can be present-but-stale after a Node upgrade.
+
+import { execSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+
+/**
+ * Probe better-sqlite3's native binding by importing it from `installDir`'s
+ * node_modules and opening an in-memory DB. Returns {ok, error?}.
+ *
+ * @param {string} installDir Directory containing node_modules/better-sqlite3
+ * @returns {Promise<{ok: true} | {ok: false, error: string}>}
+ */
+export async function probeBetterSqlite3Binding(installDir) {
+  try {
+    const localRequire = createRequire(join(installDir, 'package.json'));
+    const Database = localRequire('better-sqlite3');
+    const db = new Database(':memory:');
+    db.close();
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+/**
+ * Verify better-sqlite3 binding works in `installDir`; if not, run
+ * `npm rebuild better-sqlite3` and re-probe. Returns
+ * { ok: true, action: 'verified' | 'rebuilt' } on success or
+ * { ok: false, error } if rebuild can't fix it. The `probe` and `rebuild`
+ * deps are injectable so this can be unit-tested without a real npm
+ * subprocess.
+ *
+ * @param {string} installDir Directory containing node_modules/better-sqlite3
+ * @param {{probe?: () => Promise<{ok: boolean, error?: string}>, rebuild?: () => Promise<void>}} [deps]
+ * @returns {Promise<{ok: true, action: 'verified' | 'rebuilt'} | {ok: false, error: string}>}
+ */
+export async function ensureBetterSqlite3Working(installDir, deps = {}) {
+  const probe = deps.probe || (() => probeBetterSqlite3Binding(installDir));
+  const rebuild = deps.rebuild || (async () => {
+    execSync('npm rebuild better-sqlite3', { cwd: installDir, stdio: 'pipe' });
+  });
+
+  const first = await probe();
+  if (first.ok) return { ok: true, action: 'verified' };
+
+  try {
+    await rebuild();
+  } catch (e) {
+    return { ok: false, error: `rebuild failed: ${e.message}` };
+  }
+
+  const second = await probe();
+  if (second.ok) return { ok: true, action: 'rebuilt' };
+
+  return { ok: false, error: second.error || first.error };
+}

package/mem-cli.mjs

@@ -2383,6 +2383,8 @@ Commands:
     --task T            Comma-separated: re-enrich,normalize,cluster-merge,smart-compress
     --max N             Max items per task (1-100, default 15)
     --scope S           re-enrich scope: narrow (default) or wide
+    --project P         Limit to a single project (.|current = inferProject())
+    --verbose / -v      Preview also dumps cluster contents + re-enrich samples
 
   doctor                Environment diagnostics and benchmarks
     --benchmark         Run perf benchmark and emit JSON
@@ -2617,6 +2619,7 @@ async function cmdEnrich(argv) {
 async function cmdOptimize(db, args) {
   const run = args.includes('--run');
   const runAll = args.includes('--run-all');
+  const verbose = args.includes('--verbose') || args.includes('-v');
   // T2-P1-D: --task accepts a single task or a comma-separated list, parity with MCP memOptimizeSchema.tasks.
   const VALID_TASKS = ['re-enrich', 'normalize', 'cluster-merge', 'smart-compress'];
   const taskIdx = args.indexOf('--task');
@@ -2647,23 +2650,56 @@ async function cmdOptimize(db, args) {
   // lesson_learned (the "Haiku judged 'none'" cases). Default 'narrow' preserves old behavior.
   const scopeIdx = args.indexOf('--scope');
   const reenrichScope = scopeIdx >= 0 && args[scopeIdx + 1] === 'wide' ? 'wide' : 'narrow';
+  // --project <name> filters all 4 tasks to one project. Opt-in; absence
+  // preserves prior cross-project default. `.` or `current` auto-resolve via
+  // inferProject() so users don't need to remember the exact name.
+  const projectIdx = args.indexOf('--project');
+  let project;
+  if (projectIdx >= 0 && args[projectIdx + 1]) {
+    const raw = args[projectIdx + 1];
+    project = (raw === '.' || raw === 'current') ? inferProject() : raw;
+  }
 
   if (!run && !runAll) {
-    const preview = optimizePreview(db);
+    const preview = optimizePreview(db, { project, detail: verbose });
     out('[mem] 🔍 LLM Optimization Preview:');
+    if (project) out(`  Project filter: ${project}`);
     out(`  Re-enrich candidates: ${preview.reenrich}${preview.reenrichWide !== undefined && preview.reenrichWide !== null ? `  (wide scope: ${preview.reenrichWide})` : ''}`);
     out(`  Normalize: ${preview.normalizeGateOpen ? `${preview.normalize} unique concepts` : 'gate closed (7-day interval)'}`);
     out(`  Cluster-merge: ${preview.clusterMerge} clusters`);
     out(`  Smart-compress: ${preview.smartCompress} clusters`);
     out(`  Total: ${preview.total} items`);
+    if (verbose) {
+      out('');
+      if (preview.mergeClusters && preview.mergeClusters.length > 0) {
+        out('─── Cluster-merge details ───');
+        for (const [i, cluster] of preview.mergeClusters.entries()) {
+          out(`  Cluster ${i + 1} (${cluster.length} obs, project=${cluster[0]?.project || '?'}):`);
+          for (const obs of cluster) out(`    #${obs.id} [${obs.type || 'change'}] ${truncate(obs.title || '(untitled)', 100)}`);
+        }
+      }
+      if (preview.reenrichSamples && preview.reenrichSamples.length > 0) {
+        out('─── Re-enrich sample (first 20) ───');
+        for (const obs of preview.reenrichSamples) {
+          out(`  #${obs.id} [${obs.type || 'change'}] (project=${obs.project || '?'}) ${truncate(obs.title || '(untitled)', 100)}`);
+        }
+      }
+      if (preview.compressSamples && preview.compressSamples.length > 0) {
+        out('─── Smart-compress sample (first 5 clusters) ───');
+        for (const [i, cluster] of preview.compressSamples.entries()) {
+          out(`  Cluster ${i + 1} (${cluster.observations?.length || 0} obs, project=${cluster.project || '?'})`);
+        }
+      }
+    }
     out('');
     out('Run with --run to execute, --run-all to bypass gates.');
     out('For R-7 backfill: --run --task re-enrich --scope wide --max N');
+    out('Scope: --project <name|.|current> to limit; --verbose for cluster details.');
     return;
   }
 
-  out(`[mem] Running LLM optimization${reenrichScope === 'wide' ? ' (scope: wide)' : ''}...`);
-  const results = await optimizeRun(db, { tasks, maxItems, force: runAll, reenrichScope });
+  out(`[mem] Running LLM optimization${reenrichScope === 'wide' ? ' (scope: wide)' : ''}${project ? ` (project: ${project})` : ''}...`);
+  const results = await optimizeRun(db, { tasks, maxItems, force: runAll, reenrichScope, project });
 
   if (results.reenrich) out(`  Re-enrich: ${results.reenrich.processed || 0} processed, ${results.reenrich.skipped || 0} skipped`);
   if (results.normalize) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.71.3",
+  "version": "2.72.0",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -61,6 +61,7 @@
     "lib/id-routing.mjs",
     "lib/err-sampler.mjs",
     "lib/metrics.mjs",
+    "lib/binding-probe.mjs",
     "lib/mem-override.mjs",
     "lib/save-observation.mjs",
     "lib/deferred-work.mjs",

package/scripts/launch.mjs

@@ -30,6 +30,28 @@ if (!existsSync(join(ROOT, 'node_modules', 'better-sqlite3'))) {
   }
 }
 
+// Verify better-sqlite3 native binding matches the current Node ABI. The
+// directory-presence check above is necessary but not sufficient: a Node
+// version change (e.g. v22 → v24, ABI v127 → v137) leaves node_modules
+// intact but the .node binary stale → server FATALs with "Could not locate
+// the bindings file" on first DB open. Probe + auto-rebuild before launching.
+try {
+  const { ensureBetterSqlite3Working } = await import('../lib/binding-probe.mjs');
+  const verify = await ensureBetterSqlite3Working(ROOT);
+  if (!verify.ok) {
+    process.stderr.write(`[claude-mem-lite] better-sqlite3 binding unusable: ${verify.error}\n`);
+    process.stderr.write(`[claude-mem-lite] Repair: cd "${ROOT}" && npm rebuild better-sqlite3 --build-from-source\n`);
+    process.exit(1);
+  }
+  if (verify.action === 'rebuilt') {
+    process.stderr.write('[claude-mem-lite] Rebuilt better-sqlite3 binding for current Node ABI\n');
+  }
+} catch (e) {
+  // Probe module itself failed to load — fall through to server import and let
+  // the native FATAL surface as before. Don't block launch on a probe regression.
+  process.stderr.write(`[claude-mem-lite] binding probe skipped: ${e.message}\n`);
+}
+
 // Verify MCP SDK is importable (exports mapping intact).
 // Incomplete installs can leave the directory present but package.json missing,
 // causing Node.js to fail resolving subpath exports like /server/mcp.js.

package/server.mjs

@@ -1576,15 +1576,33 @@ server.registerTool(
     const action = args.action || 'preview';
 
     if (action === 'preview') {
-      const preview = optimizePreview(db);
+      const preview = optimizePreview(db, { project: args.project, detail: args.detail === true });
       const lines = [
         `🔍 LLM Optimization Preview:`,
+      ];
+      if (args.project) lines.push(`  Project filter: ${args.project}`);
+      lines.push(
         `  Re-enrich candidates: ${preview.reenrich}`,
         `  Normalize: ${preview.normalizeGateOpen ? `${preview.normalize} unique concepts` : 'gate closed (7-day interval)'}`,
         `  Cluster-merge candidates: ${preview.clusterMerge} clusters`,
         `  Smart-compress candidates: ${preview.smartCompress} clusters`,
         `  Total: ${preview.total} items`,
-      ];
+      );
+      if (args.detail === true) {
+        if (preview.mergeClusters && preview.mergeClusters.length > 0) {
+          lines.push('', '─── Cluster-merge details ───');
+          for (const [i, cluster] of preview.mergeClusters.entries()) {
+            lines.push(`  Cluster ${i + 1} (${cluster.length} obs, project=${cluster[0]?.project || '?'}):`);
+            for (const obs of cluster) lines.push(`    #${obs.id} [${obs.type || 'change'}] ${truncate(obs.title || '(untitled)', 100)}`);
+          }
+        }
+        if (preview.reenrichSamples && preview.reenrichSamples.length > 0) {
+          lines.push('', '─── Re-enrich sample (first 20) ───');
+          for (const obs of preview.reenrichSamples) {
+            lines.push(`  #${obs.id} [${obs.type || 'change'}] (project=${obs.project || '?'}) ${truncate(obs.title || '(untitled)', 100)}`);
+          }
+        }
+      }
       return { content: [{ type: 'text', text: lines.join('\n') }] };
     }
 
@@ -1596,6 +1614,7 @@ server.registerTool(
       // T2-P0-B: scope parity with CLI (--scope wide). When omitted, optimizeRun defaults
       // to narrow via its own code; passing through keeps that fallback intact.
       reenrichScope: args.scope,
+      project: args.project,
     });
 
     const lines = ['🔧 LLM Optimization Results:'];

package/source-files.mjs

@@ -44,6 +44,11 @@ export const SOURCE_FILES = [
   'lib/id-routing.mjs',
   'lib/err-sampler.mjs',
   'lib/metrics.mjs',
+  // v2.71.x: better-sqlite3 ABI probe + auto-rebuild. Shared by install.mjs
+  // (post-`npm install` verify) and scripts/launch.mjs (pre-server-launch
+  // self-heal after Node ABI changes). Missing from manifest → auto-update
+  // ships a stale install that FATALs on first DB open after Node upgrade.
+  'lib/binding-probe.mjs',
   // v2.41 god-module split — mem-cli.mjs router + per-cmd handlers under cli/
   'cli/common.mjs',
   'cli/fts-check.mjs',

package/tool-schemas.mjs

@@ -197,6 +197,8 @@ export const memOptimizeSchema = {
     .describe('Maximum LLM calls across all tasks (default: 15)'),
   scope: z.enum(['narrow', 'wide']).optional().default('narrow')
     .describe("Re-enrich scope: narrow=narrative-only candidates (default); wide=R-7 backfill (bugfix/refactor/feature/decision with narrative but lesson_learned='none'). CLI parity: --scope wide."),
+  project: z.string().optional().describe('Filter all 4 tasks to a single project. Default: scan all projects.'),
+  detail: coerceBool.optional().describe('preview action only — include cluster contents + re-enrich/compress sample arrays alongside aggregate counts.'),
 };
 
 export const memMaintainSchema = {