claude-mem-lite 2.64.0 → 2.66.0

package/.claude-plugin/marketplace.json

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

package/install.mjs

@@ -1438,6 +1438,11 @@ async function doctor() {
   }
 
   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
+  // separation; this propagates that count to the shell).
+  if (issues > 0) process.exitCode = 1;
 }
 
 // ─── Settings helpers ───────────────────────────────────────────────────────

package/mem-cli.mjs

@@ -39,7 +39,12 @@ function cmdSearch(db, args) {
   }
 
   const rawLimit = flags.limit !== undefined ? parseInt(flags.limit, 10) : NaN;
-  const limit = Number.isInteger(rawLimit) ? Math.max(1, rawLimit) : 20;
+  // Distinguish missing/non-integer (use default) from non-positive (silently clamping to 1
+  // produced confusing "Found 1 of 44 result" output for --limit 0/-N — warn instead).
+  if (flags.limit !== undefined && (!Number.isInteger(rawLimit) || rawLimit < 1)) {
+    process.stderr.write(`[mem] Invalid --limit "${flags.limit}" (must be a positive integer); using default 20\n`);
+  }
+  const limit = Number.isInteger(rawLimit) && rawLimit >= 1 ? rawLimit : 20;
   const type = flags.type || null;
   const validObsTypes = new Set(['decision', 'bugfix', 'feature', 'refactor', 'discovery', 'change']);
   if (type && !validObsTypes.has(type)) {
@@ -53,13 +58,22 @@ function cmdSearch(db, args) {
   if (dateTo && flags.to && /^\d{4}-\d{2}-\d{2}$/.test(flags.to)) dateTo += 86400000 - 1;
   if (flags.from && isNaN(dateFrom)) { fail(`[mem] Invalid --from date: "${flags.from}". Use YYYY-MM-DD or ISO 8601.`); return; }
   if (flags.to && isNaN(dateTo)) { fail(`[mem] Invalid --to date: "${flags.to}". Use YYYY-MM-DD or ISO 8601.`); return; }
+  // Inverted range silently returns 0 rows; warn so users see the cause, don't error
+  // (a deliberate "search for nothing in this window" is not malformed input).
+  if (dateFrom !== null && dateTo !== null && dateFrom > dateTo) {
+    process.stderr.write(`[mem] Note: --from "${flags.from}" is after --to "${flags.to}"; this range is empty\n`);
+  }
   const minImportance = flags.importance !== undefined ? parseInt(flags.importance, 10) : null;
   if (minImportance !== null && (isNaN(minImportance) || minImportance < 1 || minImportance > 3)) {
     fail(`[mem] Invalid --importance "${flags.importance}". Must be 1, 2, or 3.`);
     return;
   }
   const branch = flags.branch || null;
-  const offset = Math.max(0, parseInt(flags.offset, 10) || 0);
+  const rawOffset = flags.offset !== undefined ? parseInt(flags.offset, 10) : NaN;
+  if (flags.offset !== undefined && (!Number.isInteger(rawOffset) || rawOffset < 0)) {
+    process.stderr.write(`[mem] Invalid --offset "${flags.offset}" (must be a non-negative integer); using 0\n`);
+  }
+  const offset = Number.isInteger(rawOffset) && rawOffset >= 0 ? rawOffset : 0;
   const tier = flags.tier || null;
   if (tier && !['working', 'active', 'archive'].includes(tier)) {
     fail(`[mem] Invalid --tier "${tier}". Use: working, active, archive`);
@@ -338,7 +352,9 @@ function cmdSearch(db, args) {
   }
 
   const countLabel = total > paged.length ? `${paged.length} of ${total}` : `${paged.length}`;
-  out(`[mem] Found ${countLabel} result${paged.length !== 1 ? 's' : ''} for "${query}"${fallbackHint}:${hasMixed ? ' (# observation, S# session, P# prompt)' : ''}`);
+  // Pluralize on total — "Found 1 of 44 result" reads wrong; the population (44) drives
+  // grammatical number, not the page slice (1).
+  out(`[mem] Found ${countLabel} result${total !== 1 ? 's' : ''} for "${query}"${fallbackHint}:${hasMixed ? ' (# observation, S# session, P# prompt)' : ''}`);
   for (const r of paged) {
     const timeStr = showTime && r.created_at_epoch ? ` (${relativeTime(r.created_at_epoch)})` : '';
     if (r._source === 'session') {
@@ -406,7 +422,10 @@ function cmdRecall(db, args) {
 
   const filename = basename(file);
   const rawLimit = flags.limit !== undefined ? parseInt(flags.limit, 10) : NaN;
-  const limit = Number.isInteger(rawLimit) ? Math.max(1, rawLimit) : 10;
+  if (flags.limit !== undefined && (!Number.isInteger(rawLimit) || rawLimit < 1)) {
+    process.stderr.write(`[mem] Invalid --limit "${flags.limit}" (must be a positive integer); using default 10\n`);
+  }
+  const limit = Number.isInteger(rawLimit) && rawLimit >= 1 ? rawLimit : 10;
   const includeNoise = flags['include-noise'] === true || flags['include-noise'] === 'true';
 
   // Search via observation_files junction table for indexed filename lookups
@@ -602,8 +621,19 @@ function cmdGet(db, args) {
 
 function cmdTimeline(db, args) {
   const { positional, flags } = parseArgs(args);
-  const before = parseInt(flags.before, 10) || 5;
-  const after = parseInt(flags.after, 10) || 5;
+  // parseInt('-5') === -5 is truthy, so `|| 5` doesn't rescue negative input.
+  // Match cmdSearch's warn-then-default pattern for consistency across CLI flags.
+  const parseWindow = (label, raw) => {
+    if (raw === undefined) return 5;
+    const n = parseInt(raw, 10);
+    if (!Number.isInteger(n) || n < 0) {
+      process.stderr.write(`[mem] Invalid --${label} "${raw}" (must be a non-negative integer); using default 5\n`);
+      return 5;
+    }
+    return n;
+  };
+  const before = parseWindow('before', flags.before);
+  const after = parseWindow('after', flags.after);
   const project = flags.project ? resolveProject(db, flags.project) : null;
 
   // Parse --anchor, accepting P#/S#/# prefix so callers can paste search-result IDs verbatim.
@@ -967,6 +997,9 @@ async function cmdStats(db, args) {
   const compressedCount = db.prepare(
     `SELECT COUNT(*) as c FROM observations WHERE compressed_into IS NOT NULL ${projectFilter}`
   ).get(...baseParams);
+  const supersededOnlyCount = db.prepare(
+    `SELECT COUNT(*) as c FROM observations WHERE superseded_at IS NOT NULL AND compressed_into IS NULL ${projectFilter}`
+  ).get(...baseParams);
 
   // Tier distribution (aligned with MCP mem_stats)
   const tierCtx = { now, currentProject: project || inferProject(), currentSessionId: '' };
@@ -1005,7 +1038,11 @@ async function cmdStats(db, args) {
   out(`  Compressed: ${compressedCount.c}`);
   if (noiseRatio > 0.6) out('  ⚠️ High noise ratio — consider running mem compress');
   out('');
-  out('Tier distribution:');
+  // Tier counts only live (uncompressed, non-superseded) observations — surface the
+  // full decomposition so live + compressed + superseded = Total adds up cleanly.
+  const tierTotal = (tierMap.working ?? 0) + (tierMap.active ?? 0) + (tierMap.archive ?? 0);
+  const supersededLabel = supersededOnlyCount.c > 0 ? ` + ${supersededOnlyCount.c} superseded` : '';
+  out(`Tier distribution (live ${tierTotal}, excludes ${compressedCount.c} compressed${supersededLabel}):`);
   out(`  🔴 Working: ${tierMap.working ?? 0} | 🟡 Active: ${tierMap.active ?? 0} | 🔵 Archive: ${tierMap.archive ?? 0}`);
 }
 
@@ -1297,16 +1334,21 @@ 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); }
+  let exportFromEpoch = null;
+  let exportToEpoch = null;
   if (flags.from) {
-    const epoch = new Date(flags.from).getTime();
-    if (isNaN(epoch)) { fail(`[mem] Invalid --from date: "${flags.from}". Use YYYY-MM-DD or ISO 8601.`); return; }
-    wheres.push('created_at_epoch >= ?'); params.push(epoch);
+    exportFromEpoch = new Date(flags.from).getTime();
+    if (isNaN(exportFromEpoch)) { fail(`[mem] Invalid --from date: "${flags.from}". Use YYYY-MM-DD or ISO 8601.`); return; }
+    wheres.push('created_at_epoch >= ?'); params.push(exportFromEpoch);
   }
   if (flags.to) {
-    let epoch = new Date(flags.to).getTime();
-    if (isNaN(epoch)) { fail(`[mem] Invalid --to date: "${flags.to}". Use YYYY-MM-DD or ISO 8601.`); return; }
-    if (/^\d{4}-\d{2}-\d{2}$/.test(flags.to)) epoch += 86400000 - 1;
-    wheres.push('created_at_epoch <= ?'); params.push(epoch);
+    exportToEpoch = new Date(flags.to).getTime();
+    if (isNaN(exportToEpoch)) { fail(`[mem] Invalid --to date: "${flags.to}". Use YYYY-MM-DD or ISO 8601.`); return; }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(flags.to)) exportToEpoch += 86400000 - 1;
+    wheres.push('created_at_epoch <= ?'); params.push(exportToEpoch);
+  }
+  if (exportFromEpoch !== null && exportToEpoch !== null && exportFromEpoch > exportToEpoch) {
+    process.stderr.write(`[mem] Note: --from "${flags.from}" is after --to "${flags.to}"; this range is empty\n`);
   }
 
   const rawLimit = flags.limit !== undefined ? parseInt(flags.limit, 10) : NaN;
@@ -1324,7 +1366,13 @@ function cmdExport(db, args) {
   `).all(...params, limit);
 
   if (rows.length === 0) {
-    out('[mem] No observations found matching criteria');
+    // Empty result must respect the requested format so `export … | jq` works:
+    //   json  → "[]" (valid empty array)
+    //   jsonl → 0 lines (valid empty file)
+    // The friendly note goes to stderr so it doesn't poison stdout for callers
+    // piping to a parser.
+    if (format === 'json') out('[]');
+    process.stderr.write('[mem] No observations found matching criteria\n');
     return;
   }
 
@@ -1442,7 +1490,7 @@ function cmdMaintain(db, args) {
   const { positional, flags } = parseArgs(args);
   const action = positional[0];
   if (!action || !['scan', 'execute'].includes(action)) {
-    fail('[mem] Usage: claude-mem-lite maintain <scan|execute> [--ops cleanup,decay,boost,dedup,purge_stale,rebuild_vectors] [--project P] [--retain-days N] [--merge-ids keepId:removeId,...]');
+    fail("[mem] Usage: claude-mem-lite maintain <scan|execute> [--ops cleanup,decay,boost,dedup,purge_stale,rebuild_vectors] [--project P] [--retain-days N] [--merge-ids keepId:removeId,...] — 'scan' previews, 'execute' applies.");
     return;
   }
 
@@ -2278,6 +2326,17 @@ export async function run(argv) {
     return;
   }
 
+  // --json contract surfacing: only `search` and `context` actually emit JSON;
+  // historically `recent --json | jq` etc. silently produced text, breaking
+  // automation. Emit a one-line stderr note when --json is passed to a command
+  // that doesn't honor it. Stdout output and exit code are unchanged so existing
+  // text-parsing callers keep working — the note lives in stderr for scripts to
+  // detect the gap.
+  const JSON_SUPPORTED_CMDS = new Set(['search', 'context']);
+  if (cmdArgs.includes('--json') && !JSON_SUPPORTED_CMDS.has(cmd)) {
+    process.stderr.write(`[mem] Note: --json is supported only on: ${[...JSON_SUPPORTED_CMDS].join(', ')}. "${cmd}" outputs text.\n`);
+  }
+
   try {
     switch (cmd) {
       case 'search':    cmdSearch(db, cmdArgs); break;

package/nlp.mjs

@@ -117,10 +117,17 @@ export function extractCjkKeywords(text) {
 export function extractCjkLikePatterns(query) {
   if (!query || !/[\u4e00-\u9fff\u3400-\u4dbf]{2,}/.test(query)) return [];
   const keywords = extractCjkKeywords(query);
-  // Bigrams for unmatched CJK portions
+  // Bigrams for unmatched CJK portions \u2014 but only from pure-CJK whitespace tokens.
+  // Mixed-script tokens (e.g. "xyzAbc\u4e0d\u5b58\u5728neverhit") behave as identifier-like
+  // literals; LIKE-OR'ing the CJK-suffix bigrams matches unrelated docs containing
+  // common fragments. Mirrors the FTS-side guard in sanitizeFtsQuery.
   let remainder = query;
   for (const w of keywords) remainder = remainder.split(w).join(' ');
-  const bigrams = cjkBigrams(remainder).split(' ').filter(Boolean);
+  const pureCjkOnly = remainder
+    .split(/\s+/)
+    .filter(t => /[\u4e00-\u9fff\u3400-\u4dbf]/.test(t) && !/[A-Za-z0-9]/.test(t))
+    .join(' ');
+  const bigrams = pureCjkOnly ? cjkBigrams(pureCjkOnly).split(' ').filter(Boolean) : [];
   return [...new Set([...keywords, ...bigrams])];
 }
 
@@ -255,7 +262,16 @@ export function sanitizeFtsQuery(query) {
   // Individual CJK chars ("系","统") are too noisy; bigrams ("系统") capture compound words.
   // Skip bigrams when CJK synonym extraction already produced meaningful tokens —
   // bigrams joined with AND would make the query too restrictive.
-  const bigrams = cjkExtracted ? null : cjkBigrams(cleaned);
+  // Also skip for mixed-script tokens (e.g. "xyzAbc不存在neverhit"): the latin portion
+  // is already a strong literal anchor; bigramming the CJK suffix lets short fragments
+  // like "存在" match alone after AND→OR fallback, exploding recall onto unrelated docs.
+  let bigrams = null;
+  if (!cjkExtracted) {
+    const pureCjkTokens = tokens.filter(t =>
+      /[一-鿿㐀-䶿]/.test(t) && !/[A-Za-z0-9]/.test(t)
+    );
+    if (pureCjkTokens.length > 0) bigrams = cjkBigrams(pureCjkTokens.join(' '));
+  }
   const bigramSet = new Set(bigrams ? bigrams.split(' ').filter(b => b && !CJK_STOP_WORDS.has(b)) : []);
   const hasBigrams = bigramSet.size > 0;
   const finalTokens = [];

package/package.json

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

package/secret-scrub.mjs

@@ -7,7 +7,19 @@ export const SECRET_PATTERNS = [
   // Key-value assignments: password=xxx, token=xxx, api_key=xxx, secret=xxx, etc.
   // Excludes code-like values: null, undefined, true, false, None, empty, function calls (word()),
   // and short values (<6 chars) that are typically variable names not secrets.
-  [/(\b(?:password|passwd|token|api[_-]?key|api[_-]?secret|secret[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret|auth[_-]?token|bearer)\s*[=:]\s*)(?!process\.env\.)(?!new\s)(?!\w+\()(?!(?:null|undefined|true|false|None|nil|empty|""|''|0)\b)[^\s,;'"}\]]{6,}/gi, '$1***'],
+  //
+  // Split into two patterns so prose mentions don't get scrubbed:
+  //   1. Bare credential nouns (password|passwd|token|bearer) commonly appear in
+  //      English prose — "Marker token: xyzpdq", "the bearer: alice". We require
+  //      the keyword NOT to be preceded by an English-word + horizontal-space
+  //      (the prose mention shape). Code/config has the keyword at start-of-line,
+  //      after a separator, or in object-literal context — none of which match
+  //      "letter-then-space" preceding the keyword.
+  //   2. Structured keys (api_key, auth_token, …) keep the original behavior —
+  //      a separator/compound key is unambiguous config syntax even when
+  //      preceded by prose ("see auth_token: shhhhhh").
+  [/((?<![A-Za-z][ \t])\b(?:password|passwd|token|bearer)\s*[=:]\s*)(?!process\.env\.)(?!new\s)(?!\w+\()(?!(?:null|undefined|true|false|None|nil|empty|""|''|0)\b)[^\s,;'"}\]]{6,}/gi, '$1***'],
+  [/(\b(?:api[_-]?key|api[_-]?secret|secret[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret|auth[_-]?token)\s*[=:]\s*)(?!process\.env\.)(?!new\s)(?!\w+\()(?!(?:null|undefined|true|false|None|nil|empty|""|''|0)\b)[^\s,;'"}\]]{6,}/gi, '$1***'],
   // AWS access keys (AKIA...)
   [/\bAKIA[A-Z0-9]{16}\b/g, '***'],
   // OpenAI / Anthropic keys (sk-...) — specific prefixes have lower length threshold

package/server.mjs

@@ -1005,6 +1005,9 @@ server.registerTool(
     const compressedCount = db.prepare(`
       SELECT COUNT(*) as c FROM observations WHERE compressed_into IS NOT NULL ${projectFilter}
     `).get(...baseParams);
+    const supersededOnlyCount = db.prepare(`
+      SELECT COUNT(*) as c FROM observations WHERE superseded_at IS NOT NULL AND compressed_into IS NULL ${projectFilter}
+    `).get(...baseParams);
 
     // Tier distribution
     const tierCtx = { now: Date.now(), currentProject: args.project || inferProject(), currentSessionId: '' };
@@ -1038,7 +1041,9 @@ server.registerTool(
       `  Compressed: ${compressedCount.c}`,
       ...(noiseRatio > 0.6 ? ['  ⚠️ High noise ratio — consider running mem_compress'] : []),
       '',
-      'Tier distribution:',
+      // Tier counts only live (uncompressed, non-superseded) observations — surface
+      // the full decomposition so live + compressed + superseded = Total adds up cleanly.
+      `Tier distribution (live ${(tierMap.working ?? 0) + (tierMap.active ?? 0) + (tierMap.archive ?? 0)}, excludes ${compressedCount.c} compressed${supersededOnlyCount.c > 0 ? ` + ${supersededOnlyCount.c} superseded` : ''}):`,
       `  🔴 Working: ${tierMap.working ?? 0} | 🟡 Active: ${tierMap.active ?? 0} | 🔵 Archive: ${tierMap.archive ?? 0}`,
     ];