claude-mem-lite 2.49.1 → 2.51.0

package/.claude-plugin/marketplace.json

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

package/install.mjs

@@ -25,10 +25,115 @@ const MARKETPLACE_KEY = 'sdsrss';
 const PLUGIN_KEY = `claude-mem-lite@${MARKETPLACE_KEY}`;
 const NPM_INSTALL_CMD = 'npm install --omit=dev --no-audit --no-fund';
 
+import { createRequire } from 'module';
+
 import { RESOURCE_METADATA } from './install-metadata.mjs';
 import { scanPluginCacheHookPollution } from './plugin-cache-guard.mjs';
 import { SOURCE_FILES } from './source-files.mjs';
 
+/**
+ * Hook scripts that non-dev install must copy into ~/.claude-mem-lite/scripts/
+ * to keep settings.json hook commands resolvable. Single source of truth so
+ * adding a new PreToolUse/PostToolUse hook script can't drift from the install
+ * copy block (which previously hand-listed only 3 of these and silently
+ * dropped pre-tool-recall.js + pre-skill-bridge.js — every fresh install left
+ * settings.json pointing at non-existent files).
+ */
+export const HOOK_SCRIPT_FILES = [
+  'post-tool-use.sh',
+  'user-prompt-search.js',
+  'prompt-search-utils.mjs',
+  'pre-tool-recall.js',
+  'pre-skill-bridge.js',
+];
+
+export function copyHookScripts(srcDir, destDir) {
+  for (const name of HOOK_SCRIPT_FILES) {
+    const src = join(srcDir, name);
+    if (existsSync(src)) copyFileSync(src, join(destDir, name));
+  }
+}
+
+/**
+ * Move legacy `~/.claude-mem/claude-mem.db` (+ -wal/-shm sidecars) to
+ * timestamped `*.legacy-backup-<ms>` files inside `newDir`. The legacy DB
+ * carries v16 schema (schema_versions plural table); the new claude-mem-lite
+ * code expects v28 (schema_version singular + memory_session_id column) and
+ * MIGRATIONS[] has no v16→v28 bridge — so loading the legacy DB FATALs on
+ * first launch. Backing up rather than copying-as-current lets the new
+ * install create a fresh v28 DB while preserving legacy bytes for recovery.
+ *
+ * Returns: {action: 'noop'|'skip'|'backed-up', backupPath?}
+ *   - noop: no legacy DB found
+ *   - skip: working `claude-mem-lite.db` already exists in newDir
+ *   - backed-up: legacy files renamed to `<newDir>/claude-mem-lite.db.legacy-backup-<ts>` etc.
+ */
+export function migrateLegacyClaudeMemData(oldDir, newDir, opts = {}) {
+  const legacyDb = join(oldDir, 'claude-mem.db');
+  const targetDb = join(newDir, 'claude-mem-lite.db');
+  if (!existsSync(legacyDb)) return { action: 'noop' };
+  if (existsSync(targetDb)) return { action: 'skip' };
+
+  if (!existsSync(newDir)) mkdirSync(newDir, { recursive: true });
+  const ts = opts.now ?? Date.now();
+  const backupPath = join(newDir, `claude-mem-lite.db.legacy-backup-${ts}`);
+  renameSync(legacyDb, backupPath);
+  for (const ext of ['-wal', '-shm']) {
+    const src = legacyDb + ext;
+    if (existsSync(src)) renameSync(src, join(newDir, `claude-mem-lite.db${ext}.legacy-backup-${ts}`));
+  }
+  return { action: 'backed-up', backupPath };
+}
+
+/**
+ * Probe better-sqlite3's native binding by importing it from `installDir`'s
+ * node_modules and opening an in-memory DB. Returns {ok, error?}. `npm install`
+ * exits 0 even when the prebuilt .node binary mismatches the running Node ABI
+ * (e.g. NODE_MODULE_VERSION 137 on Node v24), so install must verify before
+ * declaring success — otherwise the next launch FATALs with "Could not locate
+ * the bindings file".
+ */
+export async function probeBetterSqlite3Binding(installDir) {
+  try {
+    const localRequire = createRequire(join(installDir, 'package.json'));
+    const Database = localRequire('better-sqlite3');
+    const db = new Database(':memory:');
+    db.close();
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+/**
+ * Verify better-sqlite3 binding works in `installDir`; if not, run
+ * `npm rebuild better-sqlite3` and re-probe. Returns
+ * { ok: true, action: 'verified' | 'rebuilt' } on success or
+ * { ok: false, error } if rebuild can't fix it. The `probe` and `rebuild`
+ * deps are injectable so this can be unit-tested without a real npm
+ * subprocess.
+ */
+export async function ensureBetterSqlite3Working(installDir, deps = {}) {
+  const probe = deps.probe || (() => probeBetterSqlite3Binding(installDir));
+  const rebuild = deps.rebuild || (async () => {
+    execSync('npm rebuild better-sqlite3', { cwd: installDir, stdio: 'pipe' });
+  });
+
+  const first = await probe();
+  if (first.ok) return { ok: true, action: 'verified' };
+
+  try {
+    await rebuild();
+  } catch (e) {
+    return { ok: false, error: `rebuild failed: ${e.message}` };
+  }
+
+  const second = await probe();
+  if (second.ok) return { ok: true, action: 'rebuilt' };
+
+  return { ok: false, error: second.error || first.error };
+}
+
 /**
  * Derive invocation_name from resource name when metadata doesn't provide one.
  * Rules:
@@ -265,13 +370,9 @@ async function install() {
         copyFileSync(src, dst);
       }
     }
-    // Copy scripts
-    const postToolSrc = join(PROJECT_DIR, 'scripts', 'post-tool-use.sh');
-    if (existsSync(postToolSrc)) copyFileSync(postToolSrc, join(scriptsDir, 'post-tool-use.sh'));
-    const promptSearchSrc = join(PROJECT_DIR, 'scripts', 'user-prompt-search.js');
-    if (existsSync(promptSearchSrc)) copyFileSync(promptSearchSrc, join(scriptsDir, 'user-prompt-search.js'));
-    const promptSearchUtilsSrc = join(PROJECT_DIR, 'scripts', 'prompt-search-utils.mjs');
-    if (existsSync(promptSearchUtilsSrc)) copyFileSync(promptSearchUtilsSrc, join(scriptsDir, 'prompt-search-utils.mjs'));
+    // Copy hook scripts (settings.json hook commands point at these — must
+    // stay in sync with HOOK_SCRIPT_FILES manifest)
+    copyHookScripts(join(PROJECT_DIR, 'scripts'), scriptsDir);
     // Ensure bash script is executable
     try { execFileSync('chmod', ['+x', join(scriptsDir, 'post-tool-use.sh')], { stdio: 'pipe' }); } catch {}
     // Copy commands directory
@@ -314,6 +415,18 @@ async function install() {
       fail('npm install failed: ' + e.message);
       process.exit(1);
     }
+    // npm install exits 0 even when the better-sqlite3 prebuilt .node binary
+    // mismatches the running Node ABI (e.g. NODE_MODULE_VERSION 137 on Node v24).
+    // Probe and auto-rebuild before declaring success — otherwise the next
+    // launch FATALs with "Could not locate the bindings file".
+    const verify = await ensureBetterSqlite3Working(INSTALL_DIR);
+    if (verify.ok) {
+      ok(`better-sqlite3: ${verify.action}`);
+    } else {
+      fail(`better-sqlite3 binding unusable after rebuild: ${verify.error}`);
+      log('Try manually: cd ' + INSTALL_DIR + ' && npm rebuild better-sqlite3 --build-from-source');
+      process.exit(1);
+    }
   }
 
   // 2b. Create global CLI symlink (claude-mem-lite command)
@@ -542,30 +655,19 @@ async function install() {
   writeSettings(settings);
   ok('Hooks configured (PreToolUse, PostToolUse, SessionStart, Stop, UserPromptSubmit)');
 
-  // 5. Migrate from old ~/.claude-mem/ if needed
-  if (existsSync(join(OLD_DATA_DIR, 'claude-mem.db')) && !existsSync(DB_PATH) && !existsSync(join(DATA_DIR, 'claude-mem.db'))) {
-    log('Detected old ~/.claude-mem/ directory, migrating to ~/.claude-mem-lite/...');
-    try {
-      if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
-      // Migrate database and WAL/SHM files (copy as claude-mem-lite.db)
-      const srcDb = join(OLD_DATA_DIR, 'claude-mem.db');
-      if (existsSync(srcDb)) copyFileSync(srcDb, DB_PATH);
-      for (const ext of ['-wal', '-shm']) {
-        const src = join(OLD_DATA_DIR, 'claude-mem.db' + ext);
-        if (existsSync(src)) copyFileSync(src, DB_PATH + ext);
-      }
-      // Migrate runtime directory
-      const oldRuntime = join(OLD_DATA_DIR, 'runtime');
-      const newRuntime = join(DATA_DIR, 'runtime');
-      if (existsSync(oldRuntime) && !existsSync(newRuntime)) {
-        cpSync(oldRuntime, newRuntime, { recursive: true });
-      }
-      ok('Data migrated from ~/.claude-mem/ → ~/.claude-mem-lite/');
-      log('Old ~/.claude-mem/ preserved (remove manually when ready)');
-    } catch (e) {
-      warn('Migration failed: ' + e.message);
-      log('You can copy manually: cp ~/.claude-mem/claude-mem.db ~/.claude-mem-lite/claude-mem-lite.db');
+  // 5. Legacy ~/.claude-mem/ → ~/.claude-mem-lite/ — back up, don't reuse.
+  // The legacy DB is schema v16 (schema_versions plural) and there's no
+  // bridge in MIGRATIONS[] to v28. Reusing it FATALs on first launch with
+  // "no such column: memory_session_id". Rename to a timestamped backup
+  // so the new install creates a fresh v28 DB.
+  try {
+    const r = migrateLegacyClaudeMemData(OLD_DATA_DIR, DATA_DIR);
+    if (r.action === 'backed-up') {
+      ok(`Legacy ~/.claude-mem/ DB backed up to ${r.backupPath}`);
+      log('New v28 DB will be created on first launch (legacy schema is incompatible).');
     }
+  } catch (e) {
+    warn('Legacy DB backup failed: ' + e.message);
   }
 
   // 5b. Rename claude-mem.db → claude-mem-lite.db in same directory

package/mem-cli.mjs

@@ -5,6 +5,7 @@
 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, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, DEFAULT_DECAY_HALF_LIFE_MS, getCurrentBranch, notLowSignalTitleClause, LOW_SIGNAL_TITLE } 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';
@@ -240,9 +241,14 @@ function cmdSearch(db, args) {
         ORDER BY score
         LIMIT ? OFFSET ?
       `).all(...promptParams);
-      for (const r of promptRows) results.push({ ...r, _source: 'prompt' });
+      // CJK precision filter (read-path parity with server.mjs): unicode61
+      // degrades bigram queries to single-char AND, letting common-char
+      // Chinese prose leak through. Drop rows that miss < 20% of query
+      // bigrams/keywords as contiguous substrings.
+      const keptPromptRows = promptRows.filter(r => cjkPrecisionOk(query, r.prompt_text));
+      for (const r of keptPromptRows) results.push({ ...r, _source: 'prompt' });
       // CJK LIKE fallback: FTS5 unicode61 can't tokenize CJK substrings in prompts
-      if (promptRows.length === 0) {
+      if (keptPromptRows.length === 0) {
         const cjkPatterns = extractCjkLikePatterns(query);
         if (cjkPatterns.length > 0) {
           const likeConds = cjkPatterns.map(() => 'p.prompt_text LIKE ?');
@@ -263,7 +269,12 @@ function cmdSearch(db, args) {
             ORDER BY p.created_at_epoch DESC
             LIMIT ? OFFSET ?
           `).all(...likeParams);
-          for (const r of fallbackRows) results.push({ ...r, _source: 'prompt', score: 0 });
+          // CJK precision filter applies here too: the LIKE fallback is just
+          // OR'd substring bigrams; without the precision gate it re-admits
+          // the same common-char noise the FTS path dropped (this was the
+          // actual leak source — FTS returned 0, fallback filled 20).
+          const keptFallback = fallbackRows.filter(r => cjkPrecisionOk(query, r.prompt_text));
+          for (const r of keptFallback) results.push({ ...r, _source: 'prompt', score: 0 });
         }
       }
     } catch { /* prompt FTS may not exist in older DBs */ }

package/nlp.mjs

@@ -124,6 +124,58 @@ export function extractCjkLikePatterns(query) {
   return [...new Set([...keywords, ...bigrams])];
 }
 
+/**
+ * Post-FTS precision filter for CJK queries.
+ *
+ * Background: FTS5 unicode61 tokenizer splits every CJK character into its
+ * own token. An application-layer bigram query like "我是" then reduces to
+ * (我 AND 是) at match time — matching any document that happens to contain
+ * both chars anywhere, which is extremely permissive in Chinese prose.
+ *
+ * Precision check: given the raw query and a candidate result's full text,
+ * require that at least `threshold` fraction of the query's CJK bigrams
+ * (or dictionary words, if any matched) appear as contiguous substrings in
+ * the result. Non-CJK queries bypass this filter entirely.
+ *
+ * Applied only to the prompts/user-prompt path — observations have richer
+ * rerank + low-signal filtering that already control noise there. Also,
+ * obs-side synonym expansion ("查询"→"(查询 OR query OR search)") is a
+ * legitimate recall mechanism that this filter would break.
+ *
+ * Threshold default 0.2 is tunable via `CLAUDE_MEM_CJK_PREC_MIN` env var.
+ * Explicit threshold arg still overrides the env value — tests and in-code
+ * callers with domain context stay authoritative.
+ *
+ * Default was tuned from 0.3 → 0.2 after a 20-query production-DB fixture
+ * showed 0.3 over-rejected legitimate multi-bigram queries whose dict-
+ * keyword coverage was incomplete (e.g. "同义词扩展" — neither compound
+ * is in CJK_COMPOUNDS → 4 bigrams required, single-keyword match only
+ * 25% < 30% rejected 19/20 real hits). At 0.2, pure-noise reduction stays
+ * ≥85% on noise fixture while SIG-6 recall recovered to 100%.
+ *
+ * @param {string} query Raw query text
+ * @param {string} text Candidate result text
+ * @param {number} [threshold] Fraction of patterns that must match. If
+ *   omitted, reads CLAUDE_MEM_CJK_PREC_MIN (default 0.2).
+ * @returns {boolean}
+ */
+export function cjkPrecisionOk(query, text, threshold) {
+  if (threshold === undefined) {
+    const envVal = process.env.CLAUDE_MEM_CJK_PREC_MIN;
+    const parsed = envVal ? parseFloat(envVal) : NaN;
+    threshold = Number.isFinite(parsed) && parsed >= 0 && parsed <= 1 ? parsed : 0.2;
+  }
+  if (!query || !text) return true;
+  if (!/[一-鿿㐀-䶿]{2,}/.test(query)) return true;
+  const keywords = extractCjkKeywords(query);
+  const required = keywords.length > 0
+    ? keywords
+    : cjkBigrams(query).split(' ').filter(b => b && !CJK_STOP_WORDS.has(b));
+  if (required.length === 0) return true;
+  const hit = required.filter(w => text.includes(w)).length;
+  return (hit / required.length) >= threshold;
+}
+
 // ─── FTS5 Token Formatting ──────────────────────────────────────────────────
 
 // Format a term for FTS5: quote if it contains spaces, hyphens, or special chars

package/package.json

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

package/scripts/user-prompt-search.js

@@ -5,6 +5,7 @@
 
 import { ensureDb, DB_DIR, REGISTRY_DB_PATH } from '../schema.mjs';
 import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject, OBS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, notLowSignalTitleClause, noisePenaltyClause } from '../utils.mjs';
+import { cjkPrecisionOk } from '../nlp.mjs';
 import { writeFileSync, readFileSync, existsSync, renameSync } from 'fs';
 import { join } from 'path';
 import Database from 'better-sqlite3';
@@ -242,7 +243,11 @@ function searchByUserPrompts(db, queryText, project, limit) {
     }
   }
 
-  return rows;
+  // CJK precision filter (parity with server.mjs + mem-cli.mjs): unicode61
+  // FTS degrades CJK bigram queries to single-char AND, letting any prose
+  // sharing common chars leak through. Drop rows that miss < 20% of query
+  // bigrams/keywords as contiguous substrings. Non-CJK queries bypass.
+  return rows.filter(r => cjkPrecisionOk(queryText, r.prompt_text));
 }
 
 function searchRecent(db, project, limit) {

package/server.mjs

@@ -6,7 +6,7 @@ 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, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, getCurrentBranch, DEFAULT_DECAY_HALF_LIFE_MS, isPathConfined, notLowSignalTitleClause, LOW_SIGNAL_TITLE } from './utils.mjs';
-import { extractCjkLikePatterns } from './nlp.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, extractPRFTerms, expandQueryByConcepts, autoBoostIfNeeded, runIdleCleanup, buildServerInstructions } from './server-internals.mjs';
@@ -463,11 +463,15 @@ function searchPrompts(ctx) {
       epochTo, epochTo,
       perSourceLimit, perSourceOffset
     );
-    for (const r of rows) {
+    // CJK precision filter: unicode61 FTS degrades CJK bigram queries to
+    // single-char AND, letting any prose sharing common chars leak through.
+    // Require ≥30% of query's CJK bigrams/keywords as contiguous substrings.
+    const keptRows = args.query ? rows.filter(r => cjkPrecisionOk(args.query, r.prompt_text)) : rows;
+    for (const r of keptRows) {
       results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, created_at_epoch: r.created_at_epoch, score: r.score });
     }
     // CJK LIKE fallback: FTS5 unicode61 can't tokenize CJK substrings in prompts
-    if (rows.length === 0 && args.query) {
+    if (keptRows.length === 0 && args.query) {
       const cjkPatterns = extractCjkLikePatterns(args.query);
       if (cjkPatterns.length > 0) {
         const likeConds = cjkPatterns.map(() => 'p.prompt_text LIKE ?');
@@ -490,7 +494,13 @@ function searchPrompts(ctx) {
           epochTo, epochTo,
           perSourceLimit, perSourceOffset
         );
-        for (const r of fallbackRows) {
+        // Parity with mem-cli.mjs: the LIKE fallback is an OR'd bigram
+        // substring scan with no scoring gate. The precision filter must
+        // apply here too — without it, queries whose FTS set is empty
+        // re-admit the full common-char noise band that FTS would have
+        // dropped downstream anyway.
+        const keptFallback = args.query ? fallbackRows.filter(r => cjkPrecisionOk(args.query, r.prompt_text)) : fallbackRows;
+        for (const r of keptFallback) {
           results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, created_at_epoch: r.created_at_epoch, score: 0 });
         }
       }