claude-mem-lite 2.71.4 → 2.73.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.71.4",
+      "version": "2.73.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.4",
+  "version": "2.73.0",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/adopt-cli.mjs

@@ -192,9 +192,22 @@ function statusAll() {
 /**
  * cmdUnadopt — precise removal of sentinel section + plugin doc.
  * Exit code stays 0: unadopt is idempotent; "absent" isn't an error.
+ *
+ * Flags:
+ *   --all       Operate on every memdir under ~/.claude/projects/*\/memory/
+ *   --status    Read-only: list currently-adopted memdirs (mirrors `adopt --status`).
+ *   --dry-run   Preview what would be removed; no filesystem writes.
+ *
+ * Pre-fix history: unrecognized flags (e.g. `--status` extrapolated from `adopt --status`,
+ * or `--dry-run` extrapolated from `adopt --dry-run`) were silently ignored and the
+ * destructive default ran anyway, removing the sentinel block when the user expected
+ * a read-only probe.
  */
 export function cmdUnadopt(args = []) {
+  if (hasFlag(args, '--status')) return statusAll();
+
   const all = hasFlag(args, '--all');
+  const dryRun = hasFlag(args, '--dry-run');
   const targets = all
     ? listAllMemdirs().map((m) => m.memdir)
     : [memdirPath(detectCwd())];
@@ -206,6 +219,13 @@ export function cmdUnadopt(args = []) {
 
   let removed = 0, absent = 0;
   for (const memdir of targets) {
+    if (dryRun) {
+      const adopted = isAdopted(memdir, PLUGIN_SLUG);
+      const action = adopted ? 'would-remove' : 'absent';
+      log(`[unadopt --dry-run] ${memdir} → ${action}`);
+      if (adopted) removed++; else absent++;
+      continue;
+    }
     const r = removePluginSection(memdir, PLUGIN_SLUG);
     removePluginDoc(memdir, PLUGIN_SLUG);
     if (r.action === 'removed') removed++;
@@ -214,5 +234,6 @@ export function cmdUnadopt(args = []) {
   }
 
   log('');
-  log(`[unadopt] ${targets.length} target(s): ${removed} removed, ${absent} absent`);
+  const verb = dryRun ? 'would remove' : 'removed';
+  log(`[unadopt${dryRun ? ' --dry-run' : ''}] ${targets.length} target(s): ${removed} ${verb}, ${absent} absent`);
 }

package/cli/activity.mjs

@@ -20,7 +20,7 @@ function formatActivityResults(rows) {
 export async function cmdActivity(db, args) {
   const sub = args[0];
   if (!sub) {
-    fail('[mem] Usage: claude-mem-lite activity <save|search|recent|show> ...');
+    fail('[mem] Usage: claude-mem-lite activity <save|search|recent|show|delete> ...');
     return;
   }
 
@@ -105,7 +105,11 @@ export async function cmdActivity(db, args) {
       return;
     }
     const row = getEvent(db, id);
-    out(row ? JSON.stringify(row, null, 2) : 'Not found');
+    if (row) {
+      out(JSON.stringify(row, null, 2));
+    } else {
+      out(`[mem] activity show: event #${id} Not found`);
+    }
     return;
   }
 

package/cli/fts-check.mjs

@@ -7,10 +7,16 @@ import { parseArgs, out, fail } from './common.mjs';
 export function cmdFtsCheck(db, args) {
   const { positional } = parseArgs(args);
   const action = positional[0];
-  if (!action || !['check', 'rebuild'].includes(action)) {
+  if (!action) {
     fail('[mem] Usage: claude-mem-lite fts-check <check|rebuild>');
     return;
   }
+  if (!['check', 'rebuild'].includes(action)) {
+    // Tell the user what was wrong rather than dumping the usage — they passed
+    // something concrete, the error should name the invalid token.
+    fail(`[mem] Invalid action "${action}". Use: check, rebuild`);
+    return;
+  }
 
   if (action === 'check') {
     const result = checkFTSIntegrity(db);

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

@@ -1057,18 +1057,21 @@ async function cleanupHooks() {
 // ─── Status ─────────────────────────────────────────────────────────────────
 
 async function status() {
-  console.log('\nclaude-mem-lite status\n');
+  // Dogfood-8: support --json so CI / setup scripts can probe install state
+  // without scraping text. Collect each check as a structured record first,
+  // then print text OR JSON. Text path keeps identical wording so existing
+  // users / docs / screenshots stay correct.
+  const json = flags.has('--json');
+  const checks = [];
+  const push = (level, key, message, extra = {}) => checks.push({ level, key, message, ...extra });
 
   // MCP
   try {
     const list = execFileSync('claude', ['mcp', 'list'], { encoding: 'utf8' });
-    if (list.includes('mem:') || list.includes('mem ')) {
-      ok('MCP server: registered');
-    } else {
-      fail('MCP server: not registered');
-    }
+    const registered = list.includes('mem:') || list.includes('mem ');
+    push(registered ? 'ok' : 'fail', 'mcp', registered ? 'MCP server: registered' : 'MCP server: not registered', { registered });
   } catch {
-    warn('Could not check MCP status');
+    push('warn', 'mcp', 'Could not check MCP status', { registered: null });
   }
 
   // Hooks
@@ -1077,34 +1080,29 @@ async function status() {
   const pluginDisabled = isPluginExplicitlyDisabled(settings);
   const pluginEnabled = settings.enabledPlugins?.[PLUGIN_KEY] === true;
 
-  if (pluginEnabled) {
-    ok('Plugin: enabled in settings');
-  } else if (pluginDisabled) {
-    warn('Plugin: disabled in settings');
-  } else {
-    warn('Plugin: not present in enabledPlugins');
-  }
+  if (pluginEnabled) push('ok', 'plugin', 'Plugin: enabled in settings', { enabled: true, disabled: false });
+  else if (pluginDisabled) push('warn', 'plugin', 'Plugin: disabled in settings', { enabled: false, disabled: true });
+  else push('warn', 'plugin', 'Plugin: not present in enabledPlugins', { enabled: false, disabled: false });
 
   if (hasHooks && pluginDisabled) {
-    warn('Hooks: still configured in settings.json while plugin is disabled (runtime ignores them; run cleanup-hooks or uninstall to clean up)');
+    push('warn', 'hooks', 'Hooks: still configured in settings.json while plugin is disabled (runtime ignores them; run cleanup-hooks or uninstall to clean up)', { configured: true });
   } else if (hasHooks) {
-    ok('Hooks: configured');
+    push('ok', 'hooks', 'Hooks: configured', { configured: true });
   } else if (pluginDisabled) {
-    ok('Hooks: not configured');
+    push('ok', 'hooks', 'Hooks: not configured', { configured: false });
   } else {
-    fail('Hooks: not configured');
+    push('fail', 'hooks', 'Hooks: not configured', { configured: false });
   }
 
   // Plugin cache pollution: populated hooks.json in cache AND install.mjs-managed
   // settings.json hooks → runtime registers both → duplicate firing.
   const polluted = scanPluginCacheHookPollution();
   if (polluted.length > 0 && hasHooks) {
-    fail(`Plugin cache: stale hooks.json in version(s) ${polluted.join(', ')} — duplicate firing alongside settings.json (run 'install' to auto-clear)`);
+    push('fail', 'plugin_cache', `Plugin cache: stale hooks.json in version(s) ${polluted.join(', ')} — duplicate firing alongside settings.json (run 'install' to auto-clear)`, { polluted_versions: polluted });
   } else if (polluted.length > 0) {
-    // plugin-only mode (no settings.json hooks) — cache hooks.json is the sole source, expected
-    ok(`Plugin cache: ${polluted.length} version(s) with hooks.json (plugin-only mode)`);
+    push('ok', 'plugin_cache', `Plugin cache: ${polluted.length} version(s) with hooks.json (plugin-only mode)`, { polluted_versions: polluted });
   } else if (pluginEnabled || hasHooks) {
-    ok('Plugin cache: no stale hooks.json (no duplicate firing)');
+    push('ok', 'plugin_cache', 'Plugin cache: no stale hooks.json (no duplicate firing)', { polluted_versions: [] });
   }
 
   // Database
@@ -1115,35 +1113,67 @@ async function status() {
       const obs = db.prepare('SELECT COUNT(*) as c FROM observations').get();
       const sess = db.prepare('SELECT COUNT(*) as c FROM session_summaries').get();
       db.close();
-      ok(`Database: ${obs.c} observations, ${sess.c} sessions`);
+      push('ok', 'database', `Database: ${obs.c} observations, ${sess.c} sessions`, { exists: true, observations: obs.c, sessions: sess.c });
     } catch (e) {
-      warn('Database: exists but check failed — ' + e.message);
+      push('warn', 'database', 'Database: exists but check failed — ' + e.message, { exists: true, error: e.message });
     }
   } else {
-    warn('Database: not found');
+    push('warn', 'database', 'Database: not found', { exists: false });
   }
 
   // CLI
   try {
     execFileSync('claude-mem-lite', ['--help'], { encoding: 'utf8', timeout: 5000, stdio: 'pipe' });
-    ok('CLI: claude-mem-lite command available');
+    push('ok', 'cli', 'CLI: claude-mem-lite command available', { available: true });
   } catch {
-    warn('CLI: command not on PATH — run install again to create symlink');
+    push('warn', 'cli', 'CLI: command not on PATH — run install again to create symlink', { available: false });
   }
 
   // Old system
   const vectorDb = join(OLD_DATA_DIR, 'vector-db');
   if (existsSync(vectorDb)) {
-    warn('Old vector-db still exists (can be removed)');
+    push('warn', 'old_data', 'Old vector-db still exists (can be removed)', { vector_db_exists: true });
   }
 
+  if (json) {
+    const out = {};
+    for (const c of checks) {
+      const { level, key, message, ...extra } = c;
+      out[key] = { level, message, ...extra };
+    }
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  console.log('\nclaude-mem-lite status\n');
+  for (const c of checks) {
+    if (c.level === 'ok') ok(c.message);
+    else if (c.level === 'warn') warn(c.message);
+    else fail(c.message);
+  }
   console.log('');
 }
 
 // ─── Doctor ─────────────────────────────────────────────────────────────────
 
 async function doctor() {
-  console.log('\nclaude-mem-lite doctor\n');
+  // Dogfood-9: structured --json output for CI / wrapper scripts that want to
+  // act on individual checks (e.g. "fail my deploy if FTS5 integrity not ok").
+  // Implementation strategy: shadow ok/warn/fail/log inside doctor() so every
+  // existing call site automatically captures into `checks`, and route final
+  // output to JSON or text. Mirror install.mjs::status() shape — { key: {...} }
+  // would lose ordering, so use a flat array of { level, message } objects
+  // (doctor checks are ordered by significance: deps → server → DB → drift).
+  const json = flags.has('--json');
+  const checks = [];
+  if (!json) console.log('\nclaude-mem-lite doctor\n');
+
+  // Shadow file-level helpers so every call site auto-records.
+  const ok   = (msg) => { checks.push({ level: 'ok',   message: msg }); if (!json) console.log(`  ✓ ${msg}`); };
+  const warn = (msg) => { checks.push({ level: 'warn', message: msg }); if (!json) console.log(`  ⚠ ${msg}`); };
+  const fail = (msg) => { checks.push({ level: 'fail', message: msg }); if (!json) console.log(`  ✗ ${msg}`); };
+  const log  = (msg) => { if (!json) console.log(`  ${msg}`); };
+
   let issues = 0;
   let warnings = 0;
   // Doctor-local ⚠ helper: visually identical to the file-level `warn`, but
@@ -1151,7 +1181,7 @@ async function doctor() {
   // "warnings present". Used for informational ⚠ checks; the two ⚠ paths
   // that ALSO bump `issues` (stale procs, dev drift) keep using the file-level
   // `warn` directly to avoid double-counting.
-  const dwarn = (msg) => { warnings++; console.log(`  ⚠ ${msg}`); };
+  const dwarn = (msg) => { warnings++; warn(msg); };
 
   // Node version
   const nodeVer = process.version;
@@ -1398,7 +1428,16 @@ async function doctor() {
     } catch {}
   }
 
-  console.log(`\n  ${buildDoctorSummary(issues, warnings)}\n`);
+  if (json) {
+    console.log(JSON.stringify({
+      issues,
+      warnings,
+      summary: buildDoctorSummary(issues, warnings),
+      checks,
+    }, null, 2));
+  } else {
+    console.log(`\n  ${buildDoctorSummary(issues, warnings)}\n`);
+  }
   // Diagnostic-tool exit-code contract: any ✗-level finding must propagate non-zero
   // so CI / wrapper scripts (`claude-mem-lite doctor || alert`) actually trip. Keeps
   // ⚠-only states at exit 0 (#8268 already established the visual ⚠ vs counted-issue
@@ -1532,7 +1571,12 @@ function writeSettings(settings) {
 // ─── Cleanup Stale Files ─────────────────────────────────────────────────────
 
 function cleanup() {
-  console.log('\nclaude-mem-lite cleanup\n');
+  // Dogfood-7 addition: --dry-run lists which files would be removed without
+  // touching disk. Useful before running cleanup on a remote/CI machine where
+  // accidentally pruning the wrong file would be costly. Doctor reports stale
+  // file counts and points users here; --dry-run lets them confirm the list.
+  const dryRun = flags.has('--dry-run');
+  console.log(`\nclaude-mem-lite cleanup${dryRun ? ' (--dry-run)' : ''}\n`);
   let removed = 0;
 
   // Clean .update-staging-* / .update-backup-* in INSTALL_DIR
@@ -1540,6 +1584,11 @@ function cleanup() {
   if (existsSync(INSTALL_DIR)) {
     for (const f of readdirSync(INSTALL_DIR)) {
       if (stalePatterns.some(p => f.startsWith(p))) {
+        if (dryRun) {
+          ok(`Would remove: ${f}`);
+          removed++;
+          continue;
+        }
         try {
           rmSync(join(INSTALL_DIR, f), { recursive: true, force: true });
           ok(`Removed: ${f}`);
@@ -1556,6 +1605,11 @@ function cleanup() {
   if (existsSync(runtimeDir)) {
     for (const f of readdirSync(runtimeDir)) {
       if (f.startsWith('pending-') || f.startsWith('ep-flush-')) {
+        if (dryRun) {
+          ok(`Would remove: runtime/${f}`);
+          removed++;
+          continue;
+        }
         try {
           rmSync(join(runtimeDir, f), { force: true });
           ok(`Removed: runtime/${f}`);
@@ -1567,7 +1621,8 @@ function cleanup() {
     }
   }
 
-  console.log(`\n  ${removed === 0 ? 'No stale files found.' : `Removed ${removed} stale file(s).`}\n`);
+  const verb = dryRun ? 'would be removed' : 'removed';
+  console.log(`\n  ${removed === 0 ? 'No stale files found.' : `${removed} stale file(s) ${verb}.`}\n`);
 }
 
 // ─── Manual Update ───────────────────────────────────────────────────────────
@@ -1707,6 +1762,13 @@ export async function main(argv = process.argv.slice(2)) {
         // npx claude-mem-lite (no args) → auto install
         await install();
       } else {
+        // Name the unknown token before the usage block. Pre-fix `install frobnicate`
+        // dumped usage silently, which read like the user had typed nothing — they had
+        // no idea their command was rejected.
+        if (cmd) {
+          console.error(`[install] Unknown command: "${cmd}"`);
+          process.exitCode = 1;
+        }
         console.log(`
 claude-mem-lite — Lightweight memory system for Claude Code
 
@@ -1715,9 +1777,9 @@ Usage:
   node install.mjs install --dev      Install dev mode (symlinks to dev dir)
   node install.mjs uninstall          Remove (keep data)
   node install.mjs uninstall --purge  Remove and delete all data
-  node install.mjs status             Show current status
-  node install.mjs doctor             Diagnose issues
-  node install.mjs cleanup            Remove stale temp/staging files
+  node install.mjs status             Show current status (use --json for structured output)
+  node install.mjs doctor             Diagnose issues (use --json for structured output)
+  node install.mjs cleanup            Remove stale temp/staging files (use --dry-run to preview)
   node install.mjs cleanup-hooks      Remove only claude-mem-lite hooks from settings.json
   node install.mjs self-update         Check for and install updates
   node install.mjs release            Sync versions (plugin/marketplace/CLAUDE.md) + regen lockfile via npm@10.9.2 (use --no-lock to skip lock regen)

package/mem-cli.mjs

@@ -104,13 +104,16 @@ function cmdSearch(db, args) {
   }
 
   // Warn if obs-only filters used with non-observation source
-  if (source && source !== 'observations' && (type || tier || minImportance)) {
-    const ignored = [type && '--type', tier && '--tier', minImportance && '--importance'].filter(Boolean);
+  if (source && source !== 'observations' && (type || tier || minImportance || branch)) {
+    const ignored = [type && '--type', tier && '--tier', minImportance && '--importance', branch && '--branch'].filter(Boolean);
     process.stderr.write(`[mem] Note: ${ignored.join(', ')} only apply to observations, ignored for --source ${source}\n`);
   }
 
-  // When --type/--tier/--importance (obs-only fields) is specified, implicitly restrict to observations
-  const effectiveSource = source || ((type || tier || minImportance) ? 'observations' : null);
+  // When --type/--tier/--importance/--branch (obs-only fields) is specified, implicitly restrict to observations.
+  // --branch was previously cross-source: sessions/prompts have no branch column, so a query like
+  // `search "cache" --branch main` would include unrelated session/prompt rows, surprising users
+  // who passed --branch expecting a branch-scoped result.
+  const effectiveSource = source || ((type || tier || minImportance || branch) ? 'observations' : null);
 
   // Cross-source mode: each source needs more candidates than the final limit
   // so the post-merge sort has room to pick the best from each (paired-path with
@@ -392,9 +395,21 @@ function cmdRecent(db, args) {
   const project = flags.project ? resolveProject(db, flags.project) : inferProject();
   const jsonOutput = flags.json === true || flags.json === 'true';
 
+  // `recent --type bugfix` previously parsed as a silent no-op — users naturally
+  // try this for "show recent bugfixes". Mirror cmdSearch's enum validation.
+  const type = flags.type || null;
+  if (type) {
+    const validObsTypes = new Set(['decision', 'bugfix', 'feature', 'refactor', 'discovery', 'change']);
+    if (!validObsTypes.has(type)) {
+      fail(`[mem] Invalid --type "${type}". Valid: ${[...validObsTypes].join(', ')}`);
+      return;
+    }
+  }
+
   const params = [];
   const wheres = ['COALESCE(compressed_into, 0) = 0', 'superseded_at IS NULL'];
   if (project) { wheres.push('project = ?'); params.push(project); }
+  if (type) { wheres.push('type = ?'); params.push(type); }
   params.push(limit);
 
   const rows = db.prepare(`
@@ -409,6 +424,7 @@ function cmdRecent(db, args) {
     out(JSON.stringify({
       project: project || null,
       limit,
+      type: type || null,
       total: rows.length,
       results: rows.map(r => ({
         id: r.id,
@@ -1010,6 +1026,13 @@ function cmdDeferAdd(db, args) {
     fail('[mem] Usage: claude-mem-lite defer add "<title>" [--priority 1|2|3] [--detail T] [--files f1,f2] [--project P]');
     return;
   }
+  // Mirror MCP memDeferSchema.title (z.string().min(1).max(200)). CLI used to
+  // accept multi-line / 1000-char titles, then `defer list` would render them
+  // as one wrapped row that pushed every other item off-screen.
+  if (title.length > 200) {
+    fail(`[mem] defer add: title too long (${title.length} chars, max 200). Move detail to --detail "<text>".`);
+    return;
+  }
   const priority = flags.priority !== undefined ? parseInt(flags.priority, 10) : 2;
   if (![1, 2, 3].includes(priority)) {
     fail(`[mem] Invalid --priority "${flags.priority}". Must be 1 (low), 2 (normal), or 3 (urgent).`);
@@ -1054,7 +1077,7 @@ function cmdDeferList(db, args) {
 function cmdDeferDrop(db, args) {
   const { positional, flags } = parseArgs(args);
   if (positional.length === 0) {
-    fail('[mem] Usage: claude-mem-lite defer drop <id-or-D#N> --reason "<reason>" [--project P]');
+    fail('[mem] Usage: claude-mem-lite defer drop <id-or-D#N>[,id2,...] --reason "<reason>" [--project P]');
     return;
   }
   const reason = flags.reason;
@@ -1062,26 +1085,34 @@ function cmdDeferDrop(db, args) {
     fail('[mem] defer drop requires --reason "<non-empty string>"');
     return;
   }
-  const rawTok = positional[0];
-  // Accept both bare integer (ordinal) and "D#N" string. Mirrors the MCP
-  // mem_defer_drop input contract (server.mjs:1025) by using the same
-  // single-element resolveDeferredIds call.
-  const token = /^\d+$/.test(rawTok) ? parseInt(rawTok, 10) : rawTok;
+  // Accept either a single token or a comma-separated batch. `save --closes-deferred`
+  // already accepts the batch form (cmdSave uses resolveDeferredIds on a split list);
+  // drop now mirrors that ergonomic so users can prune multiple items in one call
+  // without N shell invocations.
+  const rawTokens = positional.join(' ').split(',').map(s => s.trim()).filter(Boolean);
+  const tokens = rawTokens.map(t => /^\d+$/.test(t) ? parseInt(t, 10) : t);
   const project = flags.project ? resolveProject(db, flags.project) : inferProject();
 
-  let realId;
+  let realIds;
   try {
-    [realId] = resolveDeferredIds(db, project, [token]);
+    realIds = resolveDeferredIds(db, project, tokens);
   } catch (e) {
     fail(`[mem] defer drop: ${e.message}`);
     return;
   }
-  const r = dropDeferred(db, realId, reason);
-  if (r.changed === 0) {
-    out(`[mem] D#${realId} was not in 'open' status — drop is a no-op.`);
-    return;
+  const dropped = [];
+  const noop = [];
+  for (const realId of realIds) {
+    const r = dropDeferred(db, realId, reason);
+    if (r.changed === 0) noop.push(realId);
+    else dropped.push(realId);
+  }
+  if (dropped.length > 0) {
+    out(`[mem] Dropped ${dropped.map(id => `D#${id}`).join(', ')} in project "${project}". Reason: ${reason.trim()}`);
+  }
+  if (noop.length > 0) {
+    out(`[mem] No-op (not in 'open' status): ${noop.map(id => `D#${id}`).join(', ')}`);
   }
-  out(`[mem] Dropped D#${realId} in project "${project}". Reason: ${reason.trim()}`);
 }
 
 // N-1: Quality-focused stats for R-2 A/B baseline.
@@ -1563,7 +1594,15 @@ function cmdUpdate(db, args) {
 
   const updates = [];
   const params = [];
-  if (flags.title !== undefined) { updates.push('title = ?'); params.push(scrubSecrets(flags.title)); }
+  if (flags.title !== undefined) {
+    // Reject empty title — clears the observation's identifier and would render it
+    // as `(untitled)` in every listing. Almost always an accidental shell-stripped arg.
+    if (typeof flags.title === 'string' && flags.title.trim() === '') {
+      fail('[mem] --title cannot be empty. Pass a non-empty string or omit the flag to leave the title unchanged.');
+      return;
+    }
+    updates.push('title = ?'); params.push(scrubSecrets(flags.title));
+  }
   if (flags.narrative !== undefined) { updates.push('narrative = ?'); params.push(scrubSecrets(flags.narrative)); }
   if (flags.type) {
     const validTypes = new Set(['decision', 'bugfix', 'feature', 'refactor', 'discovery', 'change']);
@@ -1581,7 +1620,18 @@ function cmdUpdate(db, args) {
     }
     updates.push('importance = ?'); params.push(imp);
   }
-  if (flags.lesson !== undefined || flags['lesson-learned'] !== undefined) { updates.push('lesson_learned = ?'); params.push(scrubSecrets(flags.lesson ?? flags['lesson-learned'] ?? '')); }
+  if (flags.lesson !== undefined || flags['lesson-learned'] !== undefined) {
+    const rawLesson = flags.lesson ?? flags['lesson-learned'] ?? '';
+    // Mirror cmdSave's 500-char cap — pre-fix `update --lesson <501-char>` was silently
+    // accepted, letting overlong lessons leak into the DB through the update path
+    // even though save's path rejected them. MCP memSaveSchema also caps at 500.
+    if (typeof rawLesson === 'string' && rawLesson.length > 500) {
+      fail(`[mem] --lesson too long (${rawLesson.length} chars, max 500).`);
+      return;
+    }
+    updates.push('lesson_learned = ?');
+    params.push(scrubSecrets(rawLesson));
+  }
   if (flags.concepts !== undefined) { updates.push('concepts = ?'); params.push(flags.concepts); }
 
   if (updates.length === 0) {
@@ -1632,7 +1682,16 @@ function cmdExport(db, args) {
 
   const project = flags.project ? resolveProject(db, flags.project) : null;
   if (project) { wheres.push('project = ?'); params.push(project); }
-  if (flags.type) { wheres.push('type = ?'); params.push(flags.type); }
+  if (flags.type) {
+    // Reject unknown types — silently returning [] for `--type bogus` looked like a
+    // legitimate empty filter result, hiding the typo. Mirrors cmdSearch / cmdSave / cmdUpdate.
+    const validObsTypes = new Set(['decision', 'bugfix', 'feature', 'refactor', 'discovery', 'change']);
+    if (!validObsTypes.has(flags.type)) {
+      fail(`[mem] Invalid --type "${flags.type}". Valid: ${[...validObsTypes].join(', ')}`);
+      return;
+    }
+    wheres.push('type = ?'); params.push(flags.type);
+  }
   let exportFromEpoch = null;
   let exportToEpoch = null;
   if (flags.from) {
@@ -1690,8 +1749,18 @@ function cmdExport(db, args) {
 function cmdCompress(db, args) {
   const { flags } = parseArgs(args);
   const preview = flags.execute !== true && flags.execute !== 'true';
-  const ageDaysRaw = parseInt(flags['age-days'], 10);
-  const ageDays = Number.isFinite(ageDaysRaw) && ageDaysRaw >= 1 ? ageDaysRaw : 30;
+  // Reject malformed --age-days explicitly. The prior fallback (`|| 30`) silently used
+  // the default whenever the value parsed as NaN or <1, so users typing `--age-days abc`
+  // got the 30-day cutoff without knowing their input was discarded.
+  let ageDays = 30;
+  if (flags['age-days'] !== undefined) {
+    const parsed = parseInt(flags['age-days'], 10);
+    if (!Number.isFinite(parsed) || parsed < 1) {
+      fail(`[mem] Invalid --age-days "${flags['age-days']}". Must be a positive integer.`);
+      return;
+    }
+    ageDays = parsed;
+  }
   const cutoff = Date.now() - ageDays * 86400000;
   const project = flags.project ? resolveProject(db, flags.project) : null;
   const projectFilter = project ? 'AND project = ?' : '';
@@ -2084,6 +2153,20 @@ function cmdRegistry(_memDb, args) {
     return;
   }
 
+  // `--type` and `--resource-type` are both constrained to skill|agent across
+  // registry sub-actions. Validating once here means search/list/import/remove
+  // all reject typos like `--type sklil` instead of silently returning
+  // "No resources found." (which looked like the registry was empty for that
+  // type, not like a typo).
+  if (flags.type !== undefined && flags.type !== 'skill' && flags.type !== 'agent') {
+    fail(`[mem] Invalid --type "${flags.type}". Use: skill, agent`);
+    return;
+  }
+  if (flags['resource-type'] !== undefined && flags['resource-type'] !== 'skill' && flags['resource-type'] !== 'agent') {
+    fail(`[mem] Invalid --resource-type "${flags['resource-type']}". Use: skill, agent`);
+    return;
+  }
+
   try {
     if (action === 'search') {
       const query = flags.query || positional.slice(1).join(' ');
@@ -2199,7 +2282,9 @@ function cmdRegistry(_memDb, args) {
       const resourceType = flags['resource-type'];
       if (!name || !resourceType) { fail('[mem] Usage: claude-mem-lite registry remove --name N --resource-type skill|agent'); return; }
       const result = rdb.prepare('DELETE FROM resources WHERE type = ? AND name = ?').run(resourceType, name);
-      out(result.changes > 0 ? `[mem] Removed: ${resourceType}:${name}` : '[mem] Not found.');
+      out(result.changes > 0
+        ? `[mem] Removed: ${resourceType}:${name}`
+        : `[mem] Not found: ${resourceType}:${name}`);
       return;
     }
 
@@ -2286,7 +2371,7 @@ Commands:
     --project P         Filter by project
     --from DATE         Start date (YYYY-MM-DD or ISO 8601)
     --to DATE           End date (YYYY-MM-DD or ISO 8601)
-    --importance N      Minimum importance (1-3)
+    --importance N      Minimum importance (1=routine, 2=notable, 3=critical)
     --branch B          Filter by git branch
     --offset N          Skip first N results (pagination)
     --tier T            Filter by tier (working|active|archive, observations only)
@@ -2298,7 +2383,8 @@ Commands:
   recent [N]            Show N most recent observations (default 10)
     --limit N           Sibling-parity alias for [N] (max 1000)
     --project P         Filter by project
-    --json              Output as JSON: {project,limit,total,results:[…]}
+    --type T            Filter obs type (bugfix|decision|discovery|feature|refactor|change)
+    --json              Output as JSON: {project,limit,type,total,results:[…]}
 
   recall <file>         Show observations related to a file
     --limit N           Max results (default 10)
@@ -2328,22 +2414,22 @@ Commands:
   save "<text>"         Save a new observation
     --type T            Observation type (default: discovery)
     --title T           Title (auto-generated if omitted)
-    --importance N      1-3 (default: 2)
+    --importance N      1=routine, 2=notable, 3=critical (default: 2)
     --project P         Project name
     --files f1,f2       Comma-separated file paths
     --lesson T          Lesson learned (≤500 chars; alias: --lesson-learned)
     --closes-deferred 1,D#42  Close deferred items in same transaction
 
   defer <action>        First-class deferred work (v2.70+)
-    add "<title>"       Mark deferred work for next session
-      --priority N      1-3 (default 2)
+    add "<title>"       Mark deferred work for next session (≤200 chars)
+      --priority N      1=low, 2=normal, 3=urgent (default: 2)
       --detail T        Constraint + why deferred
       --files f1,f2     Comma-separated file paths
       --project P       Project name
     list                List open deferred items
       --limit N         Max results (default 10)
       --project P       Filter by project
-    drop <D#N|ordinal>  Drop a deferred item (no fix needed)
+    drop <D#N|ordinal>[,...]  Drop one or more deferred items (no fix needed)
       --reason "..."    Required audit trail
 
   delete <id1,id2,...>  Delete observations by ID
@@ -2352,7 +2438,7 @@ Commands:
   update <id>           Update an existing observation
     --title T           New title
     --type T            New type
-    --importance N      New importance (1-3)
+    --importance N      New importance (1=routine, 2=notable, 3=critical)
     --lesson T          Add/update lesson learned (alias: --lesson-learned)
     --narrative T       New narrative
     --concepts T        Space-separated concept tags
@@ -2383,6 +2469,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
@@ -2449,6 +2537,8 @@ Commands:
 
   unadopt               Precise removal of the sentinel block + plugin_claude_mem_lite.md.
     --all               Unadopt every project
+    --status            Read-only: list adopted projects (same as adopt --status)
+    --dry-run           Preview what would be removed; no filesystem writes
 
   memdir-audit          Audit memdir feedback_*.md / project_*.md for the
                         body-structure contract (**Why:** + **How to apply:**).
@@ -2549,16 +2639,30 @@ async function cmdImportJsonl(db, argv) {
   if (files.length === 0) { out('[mem] No .jsonl files found.'); return; }
 
   const { importJsonl } = await import('./lib/import-jsonl.mjs');
-  let totalPrompts = 0, totalObs = 0, totalSkip = 0, totalOrphans = 0;
+  let totalPrompts = 0, totalObs = 0, totalSkip = 0, totalOrphans = 0, errorCount = 0;
   for (const f of files) {
-    const r = await importJsonl(db, f, { project });
+    // Per-file isolation: one unreadable file (EACCES, EBUSY, mid-batch IO error)
+    // shouldn't crash the whole import — readFileSync inside importJsonl would
+    // otherwise throw an unhandled exception with a node stack trace, leaving
+    // earlier successes uncommitted-looking from the user's perspective.
+    let r;
+    try {
+      r = await importJsonl(db, f, { project });
+    } catch (e) {
+      errorCount++;
+      // e.message for node fs errors already begins with the code (e.g. "EACCES: permission denied, ...");
+      // don't double-prefix.
+      process.stderr.write(`[mem] ${f}: import failed — ${e.message}\n`);
+      continue;
+    }
     totalPrompts += r.prompts;
     totalObs += r.observations;
     totalSkip += r.skipped;
     totalOrphans += r.orphans || 0;
     out(`[mem] ${f}: +${r.prompts} prompts, +${r.observations} observations, ${r.orphans || 0} orphan tool_use, ${r.skipped} skipped`);
   }
-  out(`[mem] Total: ${totalPrompts} prompts, ${totalObs} observations, ${totalOrphans} orphan tool_use, ${totalSkip} skipped from ${files.length} file(s).`);
+  const errorTail = errorCount > 0 ? `, ${errorCount} file(s) errored` : '';
+  out(`[mem] Total: ${totalPrompts} prompts, ${totalObs} observations, ${totalOrphans} orphan tool_use, ${totalSkip} skipped from ${files.length} file(s)${errorTail}.`);
   if (totalPrompts > 0 || totalObs > 0) {
     out(`[mem] Try: claude-mem-lite recent 5 --project ${project}`);
   }
@@ -2617,6 +2721,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');
@@ -2645,25 +2750,67 @@ async function cmdOptimize(db, args) {
   }
   // R-7 micro: --scope wide targets bugfix/refactor/feature/decision with narrative but no
   // lesson_learned (the "Haiku judged 'none'" cases). Default 'narrow' preserves old behavior.
+  // Validate explicitly so `--scope wlde` (typo) doesn't silently become narrow and waste an LLM run.
   const scopeIdx = args.indexOf('--scope');
-  const reenrichScope = scopeIdx >= 0 && args[scopeIdx + 1] === 'wide' ? 'wide' : 'narrow';
+  let reenrichScope = 'narrow';
+  if (scopeIdx >= 0 && args[scopeIdx + 1] !== undefined) {
+    const raw = args[scopeIdx + 1];
+    if (raw !== 'narrow' && raw !== 'wide') {
+      fail(`[mem] Invalid --scope "${raw}". Use: narrow, wide`);
+      return;
+    }
+    reenrichScope = raw;
+  }
+  // --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) {
@@ -2722,7 +2869,11 @@ export async function run(argv) {
   const JSON_SUPPORTED_CMDS = new Set([
     'search', 'context', 'recent', 'recall', 'timeline', 'stats', 'browse', 'export',
   ]);
-  if (cmdArgs.includes('--json') && !JSON_SUPPORTED_CMDS.has(cmd)) {
+  // `doctor --benchmark` already emits JSON on its own — don't print the misleading
+  // "doctor outputs text" note for that subpath. Without --benchmark, doctor is text
+  // and the note is still useful.
+  const doctorBenchmark = cmd === 'doctor' && cmdArgs.includes('--benchmark');
+  if (cmdArgs.includes('--json') && !JSON_SUPPORTED_CMDS.has(cmd) && !doctorBenchmark) {
     process.stderr.write(`[mem] Note: --json is supported only on: ${[...JSON_SUPPORTED_CMDS].join(', ')}. "${cmd}" outputs text.\n`);
   }
 
@@ -2756,6 +2907,19 @@ export async function run(argv) {
         out('[mem] Run "claude-mem-lite help" for usage');
         process.exitCode = 1;
     }
+  } catch (e) {
+    // SQLITE_BUSY / SQLITE_LOCKED + extended variants (SQLITE_BUSY_SNAPSHOT,
+    // SQLITE_BUSY_RECOVERY, SQLITE_LOCKED_SHAREDCACHE…). All mean the same thing
+    // to the user: writer contention past the 5s busy_timeout. Pre-fix this
+    // raised an unhandled SqliteError with a node stack trace.
+    const code = e && typeof e.code === 'string' ? e.code : '';
+    if (code === 'SQLITE_BUSY' || code === 'SQLITE_LOCKED' ||
+        code.startsWith('SQLITE_BUSY_') || code.startsWith('SQLITE_LOCKED_')) {
+      process.stderr.write(`[mem] Database busy — another process held the writer past the 5s timeout. Retry shortly.\n`);
+      process.exitCode = 1;
+      return;
+    }
+    throw e;
   } finally {
     try { db.close(); } catch {}
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.71.4",
+  "version": "2.73.0",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/schema.mjs

@@ -696,7 +696,10 @@ export function ensureDb() {
   const db = new Database(DB_PATH);
   try { chmodSync(DB_PATH, 0o600); } catch {}
   db.pragma('journal_mode = WAL');
-  db.pragma('busy_timeout = 3000');
+  // 5000ms matches the MCP server (server.mjs) — 3000ms wasn't enough under realistic
+  // concurrency (parallel CLI saves + a long-running FTS rebuild can push individual
+  // transactions past 3s, triggering SQLITE_BUSY on the third caller).
+  db.pragma('busy_timeout = 5000');
   db.pragma('synchronous = NORMAL');
   db.pragma('foreign_keys = OFF'); // Enabled after dedup migration
 

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/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 = {