claude-mem-lite 3.6.0 → 3.7.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.6.0",
+      "version": "3.7.1",
       "source": "./",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark)."
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.6.0",
+  "version": "3.7.1",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"

package/README.md

@@ -144,7 +144,7 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
 
 ## Requirements
 
-- **Node.js** >= 18
+- **Node.js** >= 20
 - **Claude Code** CLI installed and configured (`claude` command available)
 - **SQLite3** support (provided by `better-sqlite3`, compiled on install)
 - **Platform**: Linux or macOS (see [Platform Support](#platform-support))
@@ -582,7 +582,7 @@ claude-mem-lite/
   commands/
     mem.md           # /mem command definition
   server.mjs           # MCP server: tool definitions, FTS5 search, database init
-  server-internals.mjs # Extracted search helpers: re-ranking, PRF, concept expansion
+  search-scoring.mjs # Extracted search helpers: re-ranking, PRF, concept expansion
   hook.mjs             # Claude Code hooks: episode capture, error recall, session management
   hook-llm.mjs         # Background LLM workers: episode extraction, session summaries
   hook-shared.mjs      # Shared hook infrastructure: session management, DB access, LLM calls
@@ -632,17 +632,25 @@ claude-mem-lite/
 
 ## Search Quality
 
-Benchmarked on 200 observations across 30 queries (standard + hard-negative categories):
-
-| Metric | Score |
-|--------|-------|
-| Recall@10 | 0.88 |
-| Precision@10 | 0.96 |
-| nDCG@10 | 0.95 |
-| MRR@10 | 0.95 |
-| P95 search latency | 0.15ms |
-
-The benchmark suite runs as a CI gate (`npm run benchmark:gate`) to prevent search quality regressions.
+Benchmarked on 200 observations across 30 queries (standard + hard-negative categories),
+measuring the **production-hybrid** retriever (FTS5 BM25 + TF-IDF vector + RRF) — the path
+`mem_search` / `recall` actually use. The CI gate (`npm run benchmark:gate`) runs this same
+path and fails on regression.
+
+| Metric | Score (production-hybrid) |
+|--------|---------------------------|
+| Recall@10 | 0.90 |
+| Precision@10 | 0.79 |
+| nDCG@10 | 0.97 |
+| MRR@10 | 0.97 |
+| P95 search latency | ~3ms |
+
+> **Note on the path measured.** Earlier versions of this table reported the *lexical*
+> FTS-only path (Precision@10 0.96, P95 0.15ms). The hybrid vector arm trades raw
+> precision@10 for higher recall / nDCG / MRR by surfacing semantically-related candidates
+> beyond exact lexical matches; the gate now measures the hybrid path so these numbers
+> reflect real `mem_search` behavior. For field-comparable recall, see the LongMemEval
+> section below.
 
 ### Recall on LongMemEval (standard benchmark)
 

package/README.zh-CN.md

@@ -524,7 +524,7 @@ claude-mem-lite/
   commands/
     mem.md           # /mem 命令定义
   server.mjs           # MCP 服务器：工具定义、FTS5 搜索、数据库初始化
-  server-internals.mjs # 搜索辅助模块：重排序、PRF、概念扩展
+  search-scoring.mjs # 搜索辅助模块：重排序、PRF、概念扩展
   hook.mjs             # Claude Code 钩子：episode 捕获、错误回忆、会话管理
   hook-llm.mjs         # 后台 LLM worker：episode 提取、会话摘要
   hook-shared.mjs      # 共享钩子基础设施：会话管理、数据库访问、LLM 调用

package/deep-search.mjs

@@ -103,7 +103,9 @@ export function autoDeepLlmReady(env = process.env, injectedLlm) {
  * an LLM, so the decision itself is free — only a positive verdict costs a
  * Haiku call (the escalation).
  *
- * Weak when: too few results (count below minResults floor).
+ * Weak when: too few results (count below minResults floor) AND the corpus is
+ * large enough that deep search could plausibly find more (see corpus guard
+ * below).
  *
  * NOTE: ctx.orFallbackFired was intentionally removed as an escalation trigger.
  * orFallbackFired fires on SUCCESSFUL AND→OR recovery — when the fallback
@@ -114,17 +116,37 @@ export function autoDeepLlmReady(env = process.env, injectedLlm) {
  * fails, OR also fails) is still caught: if OR recovers nothing, count is 0-2
  * → escalates on count alone.
  *
+ * Corpus guard (folded in): the count-based trigger above is correct for a real
+ * corpus, but on a near-empty / brand-new / benchmark project EVERY 0-hit query
+ * looks "weak", so a caller that only checks the count would auto-escalate (and
+ * fire a Haiku rewrite) on a store HyDE/multi-query can't possibly rescue — the
+ * "[mem] auto-escalated … 0 hits" spam. hasEscalatableCorpus used to be a
+ * SEPARATE function each caller had to remember to AND in; folding it in here
+ * means passing `db` self-suppresses escalation when the corpus is too small,
+ * without changing the (correct) count trigger for real corpora. Backward-
+ * compatible: callers that omit `db` keep the pure count behaviour (and may
+ * still AND hasEscalatableCorpus themselves — double-gating with the same
+ * predicate is idempotent, never a regression).
+ *
  * @param {Array} results  normal-search rows
  * @param {object} ctx     the hybrid ctx the engine mutated (unused; kept for
  *                         backward-compat with callers that pass it)
  * @param {object} [opts]
  * @param {number} [opts.minResults=AUTO_DEEP_MIN_RESULTS]
+ * @param {Database} [opts.db]  open handle — when given, the corpus-size guard is
+ *                              evaluated here so escalation is suppressed on a
+ *                              too-small store. Omit to keep pure count behaviour.
+ * @param {string} [opts.project]  project scope for the corpus count (when db given)
+ * @param {number} [opts.minCorpus=AUTO_DEEP_MIN_CORPUS]  corpus-size floor (when db given)
  * @returns {boolean}
  */
-export function shouldEscalateToDeep(results, _ctx, { minResults = AUTO_DEEP_MIN_RESULTS } = {}) {
+export function shouldEscalateToDeep(results, _ctx, { minResults = AUTO_DEEP_MIN_RESULTS, db, project = null, minCorpus = AUTO_DEEP_MIN_CORPUS } = {}) {
   const n = Array.isArray(results) ? results.length : 0;
-  if (n < minResults) return true;
-  return false;
+  if (n >= minResults) return false;
+  // Count is weak. If a db was supplied, also require an escalatable corpus —
+  // this is the fold-in that stops 0-hit escalation on a near-empty store.
+  if (db && !hasEscalatableCorpus(db, project, minCorpus)) return false;
+  return true;
 }
 
 /**

package/hook-update.mjs

@@ -13,6 +13,8 @@ import { debugCatch, debugLog } from './utils.mjs';
 // extracted tarball's own source-files.mjs inside installExtractedRelease.
 // See loadReleaseManifest below.
 import { SOURCE_FILES as LOCAL_SOURCE_FILES, HOOK_SCRIPT_FILES as LOCAL_HOOK_SCRIPT_FILES } from './source-files.mjs';
+import { acquireLock } from './lib/proc-lock.mjs';
+import { atomicWriteFileSync } from './lib/atomic-write.mjs';
 
 // ── Configuration ──────────────────────────────────────────
 const GITHUB_REPO = 'sdsrss/claude-mem-lite';
@@ -379,6 +381,16 @@ export function validateExtractedTarball(sourceDir, expectedVersion, expectedNam
 // the target's node_modules untouched. Dependency bumps still flow through the
 // GitHub-tarball path (downloadAndInstall), which keeps skipNpmInstall=false.
 export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR, opts = {}) {
+  // Cross-process lock: concurrent SessionStart self-heals / auto-updates must
+  // not interleave the rename loop below (→ mixed-version install). A live peer
+  // holding the lock means an install is already in flight — skip rather than
+  // race. Shared path with install.mjs so direct install + repair + auto-update
+  // are mutually exclusive.
+  const release = acquireLock(join(STATE_DIR, 'runtime', 'install.lock'));
+  if (!release) {
+    debugLog('DEBUG', 'hook-update', 'installExtractedRelease: another install/update is in progress — skipping');
+    return false;
+  }
   const ts = `${Date.now()}-${process.pid}`;
   const stagingDir = join(targetDir, `.update-staging-${ts}`);
   const backupDir = join(targetDir, `.update-backup-${ts}`);
@@ -439,7 +451,9 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
             debugLog('DEBUG', 'hook-update', `Post-update: removed stale global MCP "${k}"`);
           }
         }
-        if (changed) writeFileSync(claudeJsonPath, JSON.stringify(cfg, null, 2) + '\n');
+        // Atomic + one-time backup: ~/.claude.json is the user's ENTIRE Claude
+        // Code config; a torn write here breaks them outside our control.
+        if (changed) atomicWriteFileSync(claudeJsonPath, JSON.stringify(cfg, null, 2) + '\n', { backup: true });
       }
     } catch (e) { debugCatch(e, 'post-update-mcp-dedup'); }
 
@@ -477,6 +491,8 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
     try { rmSync(stagingDir, { recursive: true, force: true }); } catch {}
     try { rmSync(backupDir, { recursive: true, force: true }); } catch {}
     return false;
+  } finally {
+    release();
   }
 }