claude-mem-lite 2.61.0 → 2.62.1

package/.claude-plugin/marketplace.json

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

package/hook-shared.mjs

@@ -4,7 +4,7 @@
 import { execFileSync, spawn } from 'child_process';
 import { randomUUID } from 'crypto';
 import { join } from 'path';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, readdirSync, statSync, unlinkSync } from 'fs';
 import { inferProject, debugCatch } from './utils.mjs';
 import { ensureDb, DB_DIR } from './schema.mjs';
 import { getClaudePath as getClaudePathShared, resolveModel as resolveModelShared, flattenForCLI as _flattenForCLI } from './haiku-client.mjs';
@@ -62,6 +62,37 @@ export const HANDOFF_ANCHOR_MAX_AGE = 72 * 3600000;             // 72h cap on gi
 export const HANDOFF_MATCH_THRESHOLD = 3;                       // min weighted score
 export const CONTINUE_KEYWORDS = /继续|接着|上次|之前的|前面的|刚才|\bcontinue\b|\bresume\b|\bwhere[\s-]+we[\s-]+left\b|\bpick[\s-]+up\b|\bcarry[\s-]+on\b/i;
 
+// Orphan-sweep threshold for `ep-flush-*` / `pending-*` runtime artifacts.
+// handleLLMEpisode's worst-case round-trip is ~60s (delay + LLM call + DB
+// write); 1h leaves a wide safety margin against deleting an in-flight file.
+// Older orphans are crashed workers or pre-shutdown buffers that no live
+// caller will ever pick up, so sweeping them on SessionStart is safe.
+export const ORPHAN_EPISODE_AGE_MS = 60 * 60 * 1000;
+
+// Sweep stale `ep-flush-*` and `pending-*` files in `runtimeDir` whose mtime
+// is older than `ageMs` (default 1h). Returns the number of files removed.
+// fs-only — no DB / no network. Used by handleSessionStart auto-maintain to
+// prevent the doctor "Stale temp files" warning from accumulating across
+// crashes; equivalent to the manual path in `node install.mjs cleanup` but
+// age-gated so concurrent in-flight workers are never raced.
+export function sweepOrphanEpisodeFiles(runtimeDir, { ageMs = ORPHAN_EPISODE_AGE_MS, now = Date.now() } = {}) {
+  let entries;
+  try { entries = readdirSync(runtimeDir); } catch { return 0; }
+  const cutoff = now - ageMs;
+  let count = 0;
+  for (const f of entries) {
+    if (!(f.startsWith('ep-flush-') || f.startsWith('pending-'))) continue;
+    const full = join(runtimeDir, f);
+    try {
+      if (statSync(full).mtimeMs < cutoff) {
+        unlinkSync(full);
+        count++;
+      }
+    } catch { /* concurrent unlink / permission — ignore */ }
+  }
+  return count;
+}
+
 // Ensure runtime directory exists
 try { if (!existsSync(RUNTIME_DIR)) mkdirSync(RUNTIME_DIR, { recursive: true }); } catch {}
 

package/hook.mjs

@@ -40,7 +40,7 @@ import {
   RUNTIME_DIR, EPISODE_BUFFER_SIZE, EPISODE_TIME_GAP_MS,
   SESSION_EXPIRY_MS, STALE_SESSION_MS, STALE_LOCK_MS,
   sessionFile, getSessionId, createSessionId, openDb,
-  spawnBackground,
+  spawnBackground, sweepOrphanEpisodeFiles,
 } from './hook-shared.mjs';
 import { handleLLMEpisode, handleLLMSummary, saveObservation, buildImmediateObservation } from './hook-llm.mjs';
 import { extractCitationsFromTranscript, bumpCitationAccess, computeCiteRecall } from './lib/citation-tracker.mjs';
@@ -885,6 +885,17 @@ async function handleSessionStart() {
           }
         }
 
+        // Orphan sweep: remove `ep-flush-*` / `pending-*` runtime files older
+        // than 1h. handleLLMEpisode normally unlinks its own tmpFile on every
+        // exit path, but a crashed worker (OOM, host reboot, kill -9) leaves
+        // the file behind, and the doctor "Stale temp files" warning then
+        // accumulates indefinitely. fs-only; runs inside the 24h gate so it
+        // shares cadence with the rest of auto-maintain.
+        try {
+          const swept = sweepOrphanEpisodeFiles(RUNTIME_DIR);
+          if (swept > 0) debugLog('DEBUG', 'auto-maintain', `swept ${swept} orphan ep-flush/pending file(s)`);
+        } catch (e) { debugCatch(e, 'auto-maintain-orphan-sweep'); }
+
         // Mark maintenance as done (24h gate) — even though compression runs in background
         writeFileSync(maintainFile, JSON.stringify({ epoch: Date.now() }));
         // Weekly summary grouping runs in background to avoid blocking SessionStart

package/install.mjs

@@ -280,6 +280,19 @@ function ok(msg) { console.log(`  ✓ ${msg}`); }
 function warn(msg) { console.log(`  ⚠ ${msg}`); }
 function fail(msg) { console.log(`  ✗ ${msg}`); }
 
+// Doctor's final summary line. Pure function so the 4-way contract
+// (clean / warnings-only / issues / mixed) is unit-testable without spinning
+// up the full doctor pipeline. `issues` are ✗-level (action required);
+// `warnings` are ⚠-level (informational, "All checks passed!" must NOT lie
+// about them).
+export function buildDoctorSummary(issues, warnings) {
+  const wPlural = warnings === 1 ? '' : 's';
+  if (issues === 0 && warnings === 0) return 'All checks passed!';
+  if (issues === 0) return `All critical checks passed (${warnings} warning${wPlural}).`;
+  const warnSuffix = warnings > 0 ? ` (+${warnings} warning${wPlural})` : '';
+  return `${issues} issue(s) found.${warnSuffix}`;
+}
+
 // Dev installs symlink server.mjs → the project's source file. Used to suppress
 // misleading "first run" messages since hook-update.mjs skips state-writes in
 // this mode (see hook-update.mjs isDevMode).
@@ -1152,6 +1165,13 @@ async function status() {
 async function doctor() {
   console.log('\nclaude-mem-lite doctor\n');
   let issues = 0;
+  let warnings = 0;
+  // Doctor-local ⚠ helper: visually identical to the file-level `warn`, but
+  // bumps `warnings` so the summary line can distinguish "fully green" from
+  // "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}`); };
 
   // Node version
   const nodeVer = process.version;
@@ -1209,7 +1229,7 @@ async function doctor() {
   } else if (hasHooks) {
     ok('Plugin lifecycle: hooks active');
   } else {
-    warn('Plugin lifecycle: hooks not configured');
+    dwarn('Plugin lifecycle: hooks not configured');
   }
 
   // Database
@@ -1232,7 +1252,7 @@ async function doctor() {
             if (healthy) {
               ok('FTS5 integrity: all indexes healthy');
             } else {
-              warn('FTS5 integrity issues detected:');
+              dwarn('FTS5 integrity issues detected:');
               for (const d of details) log(`    ${d}`);
               log('  Attempting FTS5 rebuild...');
               const { rebuilt, errors } = rebuildFTS(rwDb);
@@ -1243,17 +1263,17 @@ async function doctor() {
             rwDb.close();
           }
         } catch (e) {
-          warn('FTS5 integrity check failed: ' + e.message);
+          dwarn('FTS5 integrity check failed: ' + e.message);
         }
       } else {
-        warn('FTS5 index: missing (will be created on server start)');
+        dwarn('FTS5 index: missing (will be created on server start)');
       }
     } catch (e) {
       fail('Database: ' + e.message);
       issues++;
     }
   } else {
-    warn('Database: not found (will be created)');
+    dwarn('Database: not found (will be created)');
   }
 
   // Check for stale processes
@@ -1287,10 +1307,10 @@ async function doctor() {
       // short-circuits before writing state (see hook-update.mjs isDevMode).
       ok('Update state: skipped (dev mode — symlinked install)');
     } else {
-      warn('Update state: no state file (first run?)');
+      dwarn('Update state: no state file (first run?)');
     }
   } catch {
-    warn('Update state: failed to read');
+    dwarn('Update state: failed to read');
   }
 
   // Dev drift: in dev-mode installs, all SOURCE_FILES entries should be
@@ -1310,7 +1330,7 @@ async function doctor() {
     }
     // Prod (all plain) install: no message — dev-drift is a dev-only concern.
   } catch (e) {
-    warn('Dev drift: check failed — ' + e.message);
+    dwarn('Dev drift: check failed — ' + e.message);
   }
 
   // Stale temp files
@@ -1329,12 +1349,12 @@ async function doctor() {
       }
     }
     if (staleCount > 0) {
-      warn(`Stale temp files: ${staleCount} found (run: node install.mjs cleanup)`);
+      dwarn(`Stale temp files: ${staleCount} found (run: node install.mjs cleanup)`);
     } else {
       ok('Stale temp files: none');
     }
   } catch {
-    warn('Stale temp files: check failed');
+    dwarn('Stale temp files: check failed');
   }
 
   // DB stats
@@ -1350,7 +1370,7 @@ async function doctor() {
       db.close();
       ok(`DB stats: ${sizeMB}MB, ${obsCount} observations, ${sessCount} sessions`);
     } catch (e) {
-      warn('DB stats: ' + e.message);
+      dwarn('DB stats: ' + e.message);
     }
   }
 
@@ -1364,14 +1384,14 @@ async function doctor() {
         sizeStr = execFileSync('du', ['-sh', pluginCacheBase], { encoding: 'utf8', timeout: 5000 }).trim().split('\t')[0];
       } catch { sizeStr = '?'; }
       if (versions.length > 3) {
-        warn(`Plugin cache: ${versions.length} versions (${sizeStr}) — run setup.sh or update to auto-prune to 3`);
+        dwarn(`Plugin cache: ${versions.length} versions (${sizeStr}) — run setup.sh or update to auto-prune to 3`);
       } else {
         ok(`Plugin cache: ${versions.length} version(s) (${sizeStr})`);
       }
     } catch {}
   }
 
-  console.log(`\n  ${issues === 0 ? 'All checks passed!' : `${issues} issue(s) found.`}\n`);
+  console.log(`\n  ${buildDoctorSummary(issues, warnings)}\n`);
 }
 
 // ─── Settings helpers ───────────────────────────────────────────────────────

package/mem-cli.mjs

@@ -4,14 +4,14 @@
 
 import { homedir } from 'os';
 import { ensureDb, DB_PATH, REGISTRY_DB_PATH } from './schema.mjs';
-import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject, jaccardSimilarity, computeMinHash, estimateJaccardFromMinHash, scrubSecrets, cjkBigrams, isoWeekKey, COMPRESSED_PENDING_PURGE, OBS_BM25, SESS_BM25, DEFAULT_DECAY_HALF_LIFE_MS, notLowSignalTitleClause } from './utils.mjs';
+import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject, jaccardSimilarity, computeMinHash, estimateJaccardFromMinHash, scrubSecrets, cjkBigrams, isoWeekKey, COMPRESSED_PENDING_PURGE, SESS_BM25, DEFAULT_DECAY_HALF_LIFE_MS, notLowSignalTitleClause } from './utils.mjs';
 import { cjkPrecisionOk } from './nlp.mjs';
 import { extractCjkLikePatterns } from './nlp.mjs';
 import { resolveProject } from './project-utils.mjs';
 import { computeTier, TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
 import { getVocabulary, computeVector, rebuildVocabulary, _resetVocabCache } from './tfidf.mjs';
 import { autoBoostIfNeeded, reRankWithContext, markSuperseded } from './server-internals.mjs';
-import { searchObservationsHybrid } from './search-engine.mjs';
+import { searchObservationsHybrid, findFtsAnchor } from './search-engine.mjs';
 import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
 import { optimizePreview, optimizeRun } from './hook-optimize.mjs';
@@ -663,25 +663,16 @@ function cmdTimeline(db, args) {
     }
   }
 
-  // Support query-based anchor: `timeline --query "search terms"` or positional
-  // Uses recency-weighted BM25 + project filter (aligned with MCP mem_timeline)
+  // Support query-based anchor: `timeline --query "search terms"` or positional.
+  // Routes through shared findFtsAnchor (paired-path with MCP mem_timeline)
+  // so AND→OR fallback semantics match `search` — without this, queries like
+  // "ep-flush leak" miss rows whose title is "ep-flush ... leaked" that
+  // search would otherwise find via OR relaxation.
   const queryStr = flags.query || positional.join(' ');
   if ((!anchorId || isNaN(anchorId)) && queryStr) {
     const ftsQuery = sanitizeFtsQuery(queryStr);
-    if (ftsQuery) {
-      const nowT = Date.now();
-      const match = db.prepare(`
-        SELECT o.id FROM observations_fts
-        JOIN observations o ON observations_fts.rowid = o.id
-        WHERE observations_fts MATCH ?
-          AND (? IS NULL OR o.project = ?)
-          AND COALESCE(o.compressed_into, 0) = 0
-        ORDER BY ${OBS_BM25}
-          * (1.0 + EXP(-0.693 * (? - o.created_at_epoch) / ${DEFAULT_DECAY_HALF_LIFE_MS}.0))
-        LIMIT 1
-      `).get(ftsQuery, project ?? null, project ?? null, nowT);
-      if (match) anchorId = match.id;
-    }
+    const found = findFtsAnchor(db, { ftsQuery, project: project ?? null });
+    if (found) anchorId = found;
   }
 
   // No anchor: show most recent observations (aligned with MCP mem_timeline fallback)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.61.0",
+  "version": "2.62.1",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "engines": {

package/search-engine.mjs

@@ -7,6 +7,7 @@
 
 import {
   OBS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE,
+  DEFAULT_DECAY_HALF_LIFE_MS,
   notLowSignalTitleClause, LOW_SIGNAL_TITLE,
   relaxFtsQueryToOr, debugLog, debugCatch,
 } from './utils.mjs';
@@ -141,6 +142,54 @@ function expandObsByPRF(db, ctx, now, primaryCount, existingIds, results, includ
  *                         perSourceOffset, currentProject, limit, orFallbackFired }
  * @returns {Array} list of result objects (mutated ctx may set orFallbackFired)
  */
+/**
+ * Resolve `timeline --query "..."` / mem_timeline auto-anchor to a single
+ * observation id. Shared between mem-cli.mjs cmdTimeline and server.mjs
+ * mem_timeline so both surfaces use identical AND→OR fallback semantics
+ * (paired-path discipline per #8217).
+ *
+ * Pipeline:
+ *   1. FTS5 MATCH with the sanitized query (AND-by-default), recency-weighted
+ *   2. If AND returns 0 → relaxFtsQueryToOr fallback (mirrors searchObservationsHybrid)
+ *
+ * Returns the matched observation id, or null. Always skips compressed rows.
+ *
+ * @param {Database} db
+ * @param {object} opts
+ * @param {string|null} opts.ftsQuery  pre-sanitized FTS5 query
+ * @param {string|null} [opts.project] restrict to this project (boost-by-membership; null = no filter)
+ * @param {number} [opts.nowT]         Date.now() override (for deterministic tests)
+ * @param {number} [opts.halfLifeMs]   recency half-life (default DEFAULT_DECAY_HALF_LIFE_MS)
+ * @returns {number|null}
+ */
+export function findFtsAnchor(db, { ftsQuery, project = null, nowT = null, halfLifeMs = DEFAULT_DECAY_HALF_LIFE_MS } = {}) {
+  if (!ftsQuery) return null;
+  const now = nowT ?? Date.now();
+  const sql = `
+    SELECT o.id FROM observations_fts
+    JOIN observations o ON observations_fts.rowid = o.id
+    WHERE observations_fts MATCH ?
+      AND (? IS NULL OR o.project = ?)
+      AND COALESCE(o.compressed_into, 0) = 0
+    ORDER BY ${OBS_BM25}
+      * (1.0 + EXP(-0.693 * (? - o.created_at_epoch) / ${halfLifeMs}.0))
+    LIMIT 1
+  `;
+  const stmt = db.prepare(sql);
+  try {
+    const m = stmt.get(ftsQuery, project, project, now);
+    if (m) return m.id;
+  } catch (e) { debugCatch(e, 'findFtsAnchor-and'); }
+  const orQuery = relaxFtsQueryToOr(ftsQuery);
+  if (orQuery && orQuery !== ftsQuery) {
+    try {
+      const m = stmt.get(orQuery, project, project, now);
+      if (m) return m.id;
+    } catch (e) { debugCatch(e, 'findFtsAnchor-or'); }
+  }
+  return null;
+}
+
 export function searchObservationsHybrid(db, ctx) {
   const { ftsQuery, args, epochFrom, epochTo, perSourceLimit, perSourceOffset, currentProject, limit } = ctx;
   const results = [];

package/server.mjs

@@ -5,12 +5,12 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { jaccardSimilarity, truncate, typeIcon, sanitizeFtsQuery, relaxFtsQueryToOr, inferProject, computeMinHash, estimateJaccardFromMinHash, scrubSecrets, cjkBigrams, fmtDate, isoWeekKey, debugLog, debugCatch, COMPRESSED_PENDING_PURGE, OBS_BM25, SESS_BM25, DEFAULT_DECAY_HALF_LIFE_MS, isPathConfined, notLowSignalTitleClause } from './utils.mjs';
+import { jaccardSimilarity, truncate, typeIcon, sanitizeFtsQuery, relaxFtsQueryToOr, inferProject, computeMinHash, estimateJaccardFromMinHash, scrubSecrets, cjkBigrams, fmtDate, isoWeekKey, debugLog, debugCatch, COMPRESSED_PENDING_PURGE, SESS_BM25, DEFAULT_DECAY_HALF_LIFE_MS, isPathConfined, notLowSignalTitleClause } from './utils.mjs';
 import { extractCjkLikePatterns, cjkPrecisionOk } from './nlp.mjs';
 import { resolveProject as _resolveProjectShared } from './project-utils.mjs';
 import { ensureDb, DB_PATH, REGISTRY_DB_PATH } from './schema.mjs';
 import { reRankWithContext, markSuperseded, autoBoostIfNeeded, runIdleCleanup, buildServerInstructions } from './server-internals.mjs';
-import { searchObservationsHybrid } from './search-engine.mjs';
+import { searchObservationsHybrid, findFtsAnchor } from './search-engine.mjs';
 import { effectiveQuiet } from './hook-shared.mjs';
 import { computeTier, TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
 import { memSearchSchema, memRecentSchema, memTimelineSchema, memGetSchema, memDeleteSchema, memSaveSchema, memStatsSchema, memCompressSchema, memMaintainSchema, memOptimizeSchema, memUpdateSchema, memExportSchema, memRecallSchema, memFtsCheckSchema, memRegistrySchema, memBrowseSchema, memUseSchema, tools as TOOL_DEFS } from './tool-schemas.mjs';
@@ -103,7 +103,7 @@ function resolveProject(name) { return _resolveProjectShared(db, name); }
 //   Importance:    0.5 + 0.5 × importance (range 0.5–2.0)
 //   Access bonus:  1 + 0.1 × ln(1 + access_count)
 
-// OBS_BM25, SESS_BM25, TYPE_DECAY_CASE imported from utils.mjs
+// SESS_BM25, TYPE_DECAY_CASE imported from utils.mjs
 const RECENCY_HALF_LIFE_MS = DEFAULT_DECAY_HALF_LIFE_MS;
 
 // ─── MCP Server ─────────────────────────────────────────────────────────────
@@ -612,24 +612,13 @@ server.registerTool(
       }
     }
 
-    // Auto-find anchor via FTS (with recency decay)
+    // Auto-find anchor via FTS (with recency decay). Routes through shared
+    // findFtsAnchor so CLI `timeline --query` and MCP mem_timeline use
+    // identical AND→OR fallback semantics (paired-path per #8217).
     if (!anchorId && args.query) {
       const ftsQuery = sanitizeFtsQuery(args.query);
-      if (ftsQuery) {
-        const nowT = Date.now();
-        const row = db.prepare(`
-          SELECT o.id
-          FROM observations_fts
-          JOIN observations o ON observations_fts.rowid = o.id
-          WHERE observations_fts MATCH ?
-            AND (? IS NULL OR o.project = ?)
-            AND COALESCE(o.compressed_into, 0) = 0
-          ORDER BY ${OBS_BM25}
-            * (1.0 + EXP(-0.693 * (? - o.created_at_epoch) / ${RECENCY_HALF_LIFE_MS}.0))
-          LIMIT 1
-        `).get(ftsQuery, args.project ?? null, args.project ?? null, nowT);
-        if (row) anchorId = row.id;
-      }
+      const found = findFtsAnchor(db, { ftsQuery, project: args.project ?? null });
+      if (found) anchorId = found;
     }
 
     // No anchor: return most recent