claude-mem-lite 2.72.0 → 2.73.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.72.0",
+      "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.72.0",
+  "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/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
@@ -2451,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:**).
@@ -2551,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}`);
   }
@@ -2648,8 +2750,17 @@ 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.
@@ -2758,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`);
   }
 
@@ -2792,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.72.0",
+  "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