claude-mem-lite 3.5.0 → 3.7.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.5.0",
+      "version": "3.7.0",
       "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.5.0",
+  "version": "3.7.0",
   "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))
@@ -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/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();
   }
 }
 

package/hook.mjs

@@ -54,6 +54,7 @@ import {
   bumpCitationAccess,
   computeCiteRecall,
   applyCitationDecay,
+  recordCitationFunnel,
   hasMainThreadAssistantText,
 } from './lib/citation-tracker.mjs';
 import { extractTailAssistantText, extractStructuredSummary } from './lib/summary-extractor.mjs';
@@ -572,6 +573,10 @@ async function handleStop() {
                 for (const id of citeBackIds) citedMain.add(id);
                 const r = applyCitationDecay(db, project, injected, citedMain, sessionId);
                 debugLog('DEBUG', 'handleStop', `citation-decay: touched=${r.touched} promoted=${r.promoted} demoted=${r.demoted}`);
+                // R1: persist this session's invocation→cite funnel row. touched =
+                // obs resolved this run (denominator), promoted = obs cited this run
+                // (numerator). Idempotent (touched is 0 on re-fire) + best-effort.
+                recordCitationFunnel(db, project, sessionId, r.touched, r.promoted);
               }
             }
           } catch (e) { debugCatch(e, 'handleStop-citation-decay'); }

package/install.mjs

@@ -2,7 +2,7 @@
 // claude-mem-lite Installer — Smart install/uninstall/status/doctor
 
 import { execSync, execFileSync } from 'child_process';
-import { readFileSync, writeFileSync, existsSync, rmSync, mkdirSync, copyFileSync, cpSync, renameSync, symlinkSync, unlinkSync, readdirSync, statSync, lstatSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, rmSync, mkdirSync, mkdtempSync, copyFileSync, cpSync, renameSync, symlinkSync, unlinkSync, readdirSync, statSync, lstatSync } from 'fs';
 import { join, resolve, dirname, isAbsolute } from 'path';
 import { homedir, tmpdir } from 'os';
 import { fileURLToPath, pathToFileURL } from 'url';
@@ -41,6 +41,8 @@ import { scanPluginCacheHookPollution } from './plugin-cache-guard.mjs';
 import { SOURCE_FILES, HOOK_SCRIPT_FILES } from './source-files.mjs';
 import { probeBetterSqlite3Binding, ensureBetterSqlite3Working } from './lib/binding-probe.mjs';
 import { sweepStaleTestFixtures } from './lib/tmp-fixture-sweep.mjs';
+import { acquireLock } from './lib/proc-lock.mjs';
+import { atomicWriteFileSync } from './lib/atomic-write.mjs';
 
 // Re-export for backward compatibility — tests/install-hook-scripts.test.mjs
 // and any external consumers still import HOOK_SCRIPT_FILES from install.mjs.
@@ -1807,11 +1809,11 @@ function readSettings() {
 }
 
 function writeSettings(settings) {
-  const settingsDir = dirname(SETTINGS_PATH);
-  if (!existsSync(settingsDir)) mkdirSync(settingsDir, { recursive: true });
-  const tmp = SETTINGS_PATH + '.tmp';
-  writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
-  renameSync(tmp, SETTINGS_PATH);
+  // Atomic (pid-unique temp + rename) with a one-time .bak: settings.json is the
+  // user's Claude Code config. The old fixed ".tmp" name let concurrent installs
+  // clobber each other's temp mid-write, and there was no recovery artifact if a
+  // hook-merge bug dropped user config. atomicWriteFileSync handles dir creation.
+  atomicWriteFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n', { backup: true });
 }
 
 // ─── Cleanup Stale Files ─────────────────────────────────────────────────────
@@ -1919,8 +1921,7 @@ async function manualUpdate() {
 // buggy on disk.
 async function repair() {
   console.log('\nclaude-mem-lite repair — re-syncing from latest GitHub release\n');
-  const stagingDir = join(tmpdir(), `claude-mem-lite-repair-${Date.now()}`);
-  mkdirSync(stagingDir, { recursive: true });
+  const stagingDir = mkdtempSync(join(tmpdir(), 'claude-mem-lite-repair-'));
   try {
     const tarballUrl = 'https://api.github.com/repos/sdsrss/claude-mem-lite/tarball';
     const tarballPath = join(stagingDir, 'release.tgz');
@@ -2027,13 +2028,27 @@ function regenerateLockfile() {
 
 // ─── Main ───────────────────────────────────────────────────────────────────
 
+// Cross-process gate around the install write phase. repair() is intentionally
+// NOT locked here: it spawns `install.mjs install` as a child, which takes this
+// lock — locking the parent too would deadlock. A live peer (another session's
+// install/self-heal) holds it → skip rather than race into a torn install. Lock
+// path is shared with hook-update.installExtractedRelease (both env-aware).
+async function runLockedInstall() {
+  const release = acquireLock(join(MEM_DATA_DIR, 'runtime', 'install.lock'));
+  if (!release) {
+    console.log('[install] Another install/repair is in progress — skipping to avoid a torn write.');
+    return;
+  }
+  try { await install(); } finally { release(); }
+}
+
 export async function main(argv = process.argv.slice(2)) {
   cmd = argv[0];
   flags = new Set(argv.slice(1));
 
   switch (cmd) {
     case 'install':
-      await install();
+      await runLockedInstall();
       break;
     case 'uninstall':
       await uninstall();
@@ -2064,7 +2079,7 @@ export async function main(argv = process.argv.slice(2)) {
     default:
       if (IS_NPX) {
         // npx claude-mem-lite (no args) → auto install
-        await install();
+        await runLockedInstall();
       } 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

package/lib/atomic-write.mjs

@@ -0,0 +1,38 @@
+// lib/atomic-write.mjs — crash-safe file writes with optional one-time backup.
+//
+// Why: several write paths mutate user-global config that, if torn or clobbered,
+// breaks the user outside the plugin's control — most acutely ~/.claude.json
+// (the WHOLE Claude Code config) in hook-update's post-update MCP dedup, and
+// ~/.claude/settings.json in install. A plain writeFileSync can leave a
+// half-written file on crash, and a fixed ".tmp" name races concurrent writers.
+// This writes to a pid-unique temp then renames (atomic on POSIX), and can drop
+// a one-time ".bak" so a logic bug in the caller's merge is recoverable.
+
+import { writeFileSync, renameSync, existsSync, copyFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/**
+ * Atomically write `data` to `filePath` (temp + rename). Optionally back up the
+ * existing file once to `<filePath>.bak` before the first overwrite.
+ * @param {string} filePath
+ * @param {string} data
+ * @param {object} [opts]
+ * @param {boolean} [opts.backup=false]  Create <filePath>.bak if absent and the
+ *   target exists, before writing. Only the first call creates it, so the backup
+ *   preserves the last-known-good rather than being overwritten each run.
+ */
+export function atomicWriteFileSync(filePath, data, { backup = false } = {}) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  if (backup && existsSync(filePath) && !existsSync(filePath + '.bak')) {
+    try { copyFileSync(filePath, filePath + '.bak'); } catch { /* best-effort backup */ }
+  }
+
+  // pid-unique temp: a fixed ".tmp" name lets two concurrent installs clobber
+  // each other's temp mid-write. Same-dir temp keeps the rename atomic (no
+  // cross-device move).
+  const tmp = `${filePath}.tmp-${process.pid}`;
+  writeFileSync(tmp, data);
+  renameSync(tmp, filePath);
+}

package/lib/citation-tracker.mjs

@@ -544,3 +544,96 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
   try { txn(); } catch (e) { debugCatch(e, 'applyCitationDecay-txn'); return empty; }
   return { promoted, demoted, touched };
 }
+
+/**
+ * R1 — persist one accumulating per-session row of the invocation→cite funnel.
+ * Fed by applyCitationDecay's return: `injectedDelta` = obs RESOLVED this Stop
+ * (touched), `citedDelta` = obs CITED this Stop (promoted). Idempotent against
+ * Stop multi-fire by construction — a re-fired Stop re-resolves nothing (touched
+ * is 0 for already-decided obs), so the no-op gate below skips it. A later turn
+ * that resolves NEW injections accumulates onto the same (project, session) row.
+ *
+ * Unlike the per-obs cited_count/decay_seen_count counters (lifetime-cumulative,
+ * session breakdown lost), this preserves the per-session series that
+ * computeCitationFunnelTrend reads back as a trend. Telemetry only — every write
+ * is wrapped so a citation_log failure can never break the Stop handler.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} project
+ * @param {string} sessionId — memory_session_id of the resolved session
+ * @param {number} injectedDelta — obs resolved this run (applyCitationDecay.touched)
+ * @param {number} citedDelta — obs cited this run (applyCitationDecay.promoted)
+ */
+export function recordCitationFunnel(db, project, sessionId, injectedDelta, citedDelta) {
+  if (!db || !project || !sessionId) return;
+  const inj = Number(injectedDelta) || 0;
+  if (inj <= 0) return; // nothing resolved this run → no row noise
+  const cited = Math.max(0, Number(citedDelta) || 0);
+  try {
+    db.prepare(`
+      INSERT INTO citation_log (project, memory_session_id, resolved_at, injected_n, cited_n)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(project, memory_session_id) DO UPDATE SET
+        injected_n = injected_n + excluded.injected_n,
+        cited_n = cited_n + excluded.cited_n,
+        resolved_at = excluded.resolved_at
+    `).run(project, sessionId, Date.now(), inj, cited);
+  } catch (e) { debugCatch(e, 'recordCitationFunnel'); }
+}
+
+/**
+ * R1 — read the per-session invocation→cite funnel as a windowed trend.
+ * `window` aggregates [now-days, now]; `prior` aggregates [now-2*days, now-days)
+ * so `delta_pt` shows whether invocation effectiveness is rising or falling.
+ * `sessions` is the most-recent `limit` rows (per-session rate for the table view).
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {{days?: number, limit?: number, project?: string|null}} [opts]
+ * @returns {{window_days: number, sessions: Array, window: {injected:number,cited:number,rate:number}, prior: {injected:number,cited:number,rate:number}, delta_pt: number|null}}
+ */
+export function computeCitationFunnelTrend(db, { days = 7, limit = 10, project = null } = {}) {
+  const rate = (cited, inj) => (inj > 0 ? cited / inj : 0);
+  const empty = {
+    window_days: days,
+    sessions: [],
+    window: { injected: 0, cited: 0, rate: 0 },
+    prior: { injected: 0, cited: 0, rate: 0 },
+    delta_pt: null,
+  };
+  if (!db) return empty;
+  try {
+    const now = Date.now();
+    const windowStart = now - days * 86400000;
+    const priorStart = now - 2 * days * 86400000;
+    const projClause = project ? 'AND project = ?' : '';
+
+    const sessions = db.prepare(`
+      SELECT project, memory_session_id, resolved_at, injected_n, cited_n
+        FROM citation_log
+       WHERE 1=1 ${projClause}
+    ORDER BY resolved_at DESC
+       LIMIT ?
+    `).all(...(project ? [project, limit] : [limit]))
+      .map(r => ({ ...r, rate: rate(r.cited_n, r.injected_n) }));
+
+    const agg = (fromTs, toTs) => {
+      const params = toTs === null ? [fromTs] : [fromTs, toTs];
+      if (project) params.push(project);
+      const upper = toTs === null ? '' : 'AND resolved_at < ?';
+      const row = db.prepare(`
+        SELECT COALESCE(SUM(injected_n), 0) AS injected, COALESCE(SUM(cited_n), 0) AS cited
+          FROM citation_log
+         WHERE resolved_at >= ? ${upper} ${projClause}
+      `).get(...params);
+      return { injected: row.injected, cited: row.cited, rate: rate(row.cited, row.injected) };
+    };
+
+    const windowAgg = agg(windowStart, null);
+    const priorAgg = agg(priorStart, windowStart);
+    const delta_pt = priorAgg.injected > 0
+      ? Number(((windowAgg.rate - priorAgg.rate) * 100).toFixed(1))
+      : null;
+
+    return { window_days: days, sessions, window: windowAgg, prior: priorAgg, delta_pt };
+  } catch (e) { debugCatch(e, 'computeCitationFunnelTrend'); return empty; }
+}

package/lib/err-sampler.mjs

@@ -17,6 +17,7 @@
 
 import { appendFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
+import { scrubSecrets } from '../secret-scrub.mjs';
 
 const DAY_MS = 86400000;
 
@@ -47,11 +48,14 @@ export function maybeSampleError(e, ctx, dbDir) {
     const errDir = join(dbDir, 'errors');
     if (!existsSync(errDir)) mkdirSync(errDir, { recursive: true, mode: 0o700 });
 
+    // Scrub BEFORE truncating: a connection string / Authorization header / 401
+    // body can ride along in an error message or stack frame. Scrub the full
+    // string first so a secret straddling the slice boundary is still caught.
     const line = JSON.stringify({
       ts: new Date().toISOString(),
-      ctx: String(ctx || '').slice(0, 120),
-      msg: String(e?.message ?? e ?? '').slice(0, 500),
-      stack: typeof e?.stack === 'string' ? e.stack.split('\n').slice(0, 6).join('\n') : undefined,
+      ctx: scrubSecrets(String(ctx || '')).slice(0, 120),
+      msg: scrubSecrets(String(e?.message ?? e ?? '')).slice(0, 500),
+      stack: typeof e?.stack === 'string' ? scrubSecrets(e.stack.split('\n').slice(0, 6).join('\n')) : undefined,
     }) + '\n';
 
     appendFileSync(join(errDir, `${today()}.jsonl`), line, { mode: 0o600 });

package/lib/lesson-idents.mjs

@@ -0,0 +1,32 @@
+// lib/lesson-idents.mjs — pure, zero-dependency extractor of code identifiers a
+// lesson names, for the bind-salience PostToolUse "dropped a required reference"
+// check (scripts/post-tool-recall.js). Imported by hot standalone hooks → NO
+// heavy imports (lesson #8447): regex over a string only.
+//
+// Identifier shapes: backtick-quoted, camelCase, snake_case, length >= MIN_LEN.
+// These name functions/columns a lesson tells you to keep (recoverChildrenOf,
+// compressed_into). Plain prose ("recover", "delete") is intentionally excluded.
+
+const MIN_LEN = 5;
+const BACKTICK = /`([A-Za-z_][A-Za-z0-9_]*)`/g;
+const CAMEL = /\b([a-z][a-z0-9]*[A-Z][A-Za-z0-9]*)\b/g;
+const SNAKE = /\b([a-z][a-z0-9]*(?:_[a-z0-9]+)+)\b/g;
+
+export function extractIdents(text) {
+  const s = text || '';
+  if (!s) return [];
+  const out = new Set();
+  for (const re of [BACKTICK, CAMEL, SNAKE]) {
+    for (const m of s.matchAll(re)) if (m[1].length >= MIN_LEN) out.add(m[1]);
+  }
+  return [...out];
+}
+
+// Of the identifiers a lesson names, keep only those literally present in the
+// pre-edit file — so the PostToolUse check flags "you removed X" and never
+// "you didn't add X that was never here" (the false positive). '' content → [].
+export function presentIdents(lessonText, content) {
+  const c = content || '';
+  if (!c) return [];
+  return extractIdents(lessonText).filter((id) => c.includes(id));
+}

package/lib/proc-lock.mjs

@@ -0,0 +1,112 @@
+// lib/proc-lock.mjs — best-effort inter-process advisory lock (O_EXCL file).
+//
+// Why: multiple Claude Code sessions can fire SessionStart hooks (and their
+// self-heal / auto-update write paths) at the same instant. install(),
+// install.mjs repair, and hook-update.installExtractedRelease all rename source
+// files into the live install dir; two of them interleaving produces a torn /
+// mixed-version install (server vN + hook vN+1). The launcher's 6h cooldown
+// only RATE-LIMITS re-spawns — it is not mutual exclusion (two processes can
+// both observe "no recent attempt" and both spawn). This gives the write paths
+// a real cross-process gate.
+//
+// Semantics: acquireLock() atomically creates the lock file with O_EXCL. If it
+// already exists it is stolen only when STALE (holder's timestamp older than
+// staleMs, or the recorded pid is provably dead on this host). A live holder →
+// acquire returns null and the caller no-ops (someone else is already doing the
+// write). Release unlinks the file. Crash-safe: a crashed holder's lock ages
+// out via staleMs so the next session reclaims it.
+
+import { writeFileSync, readFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+// 5 min: comfortably longer than any install/update write phase (npm install in
+// staging is timeout-capped at 60s) but short enough that a crashed holder does
+// not block self-heal for long.
+const DEFAULT_STALE_MS = 5 * 60 * 1000;
+
+function pidAlive(pid) {
+  if (typeof pid !== 'number' || pid <= 0) return false;
+  try {
+    // Signal 0 = existence check, no signal delivered. EPERM means the process
+    // exists but is owned by another user (still "alive" for our purposes).
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
+function isStale(lockPath, staleMs, now) {
+  try {
+    const { pid, ts } = JSON.parse(readFileSync(lockPath, 'utf8'));
+    if (typeof ts === 'number' && now() - ts > staleMs) return true;
+    // Same-host fast reclaim: holder pid is gone. Cross-host (shared homedir)
+    // the pid is meaningless, but ts-staleness above still reclaims it.
+    if (typeof pid === 'number' && !pidAlive(pid)) return true;
+    return false;
+  } catch {
+    return true; // unparseable / unreadable lock → treat as stale and reclaim
+  }
+}
+
+function makeRelease(lockPath) {
+  let released = false;
+  return function release() {
+    if (released) return;
+    released = true;
+    try { unlinkSync(lockPath); } catch { /* already gone — fine */ }
+  };
+}
+
+/**
+ * Try to acquire an advisory lock. Non-blocking.
+ * @param {string} lockPath  Absolute path to the lock file.
+ * @param {object} [opts]
+ * @param {number} [opts.staleMs]  Age after which a held lock is stolen.
+ * @param {() => number} [opts.now]  Clock injection seam (tests).
+ * @returns {(() => void)|null}  A release() fn, or null if a live peer holds it.
+ */
+export function acquireLock(lockPath, { staleMs = DEFAULT_STALE_MS, now = Date.now } = {}) {
+  try { mkdirSync(dirname(lockPath), { recursive: true }); } catch { /* best-effort */ }
+  const payload = JSON.stringify({ pid: process.pid, ts: now() });
+  try {
+    writeFileSync(lockPath, payload, { flag: 'wx' }); // O_EXCL — atomic create
+    return makeRelease(lockPath);
+  } catch (e) {
+    if (e.code !== 'EEXIST') return null; // permission / fs error → fail closed
+    if (!isStale(lockPath, staleMs, now)) return null; // live peer holds it
+    // Stale: steal it. unlink + re-create exclusively; lose the race → null.
+    try { unlinkSync(lockPath); } catch { /* raced */ }
+    try {
+      writeFileSync(lockPath, payload, { flag: 'wx' });
+      return makeRelease(lockPath);
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * Run `fn` while holding the lock; release in a finally. No-op if not acquired.
+ * @returns {{acquired: boolean, result?: any}}
+ */
+export function withLock(lockPath, fn, opts) {
+  const release = acquireLock(lockPath, opts);
+  if (!release) return { acquired: false };
+  try {
+    return { acquired: true, result: fn() };
+  } finally {
+    release();
+  }
+}
+
+/** Async variant of withLock — awaits `fn`. */
+export async function withLockAsync(lockPath, fn, opts) {
+  const release = acquireLock(lockPath, opts);
+  if (!release) return { acquired: false };
+  try {
+    return { acquired: true, result: await fn() };
+  } finally {
+    release();
+  }
+}

package/mem-cli.mjs

@@ -10,7 +10,7 @@ import { TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
 import { _resetVocabCache } from './tfidf.mjs';
 import { autoBoostIfNeeded, reRankWithContext, markSuperseded } from './server-internals.mjs';
 import { searchObservationsHybrid, countSearchTotal, attachBodyTokens } from './search-engine.mjs';
-import { deepSearch, resolveDeepMode, shouldEscalateToDeep, autoDeepLlmReady, hasEscalatableCorpus } from './deep-search.mjs';
+import { deepSearch, resolveDeepMode, shouldEscalateToDeep, autoDeepLlmReady } from './deep-search.mjs';
 import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
@@ -40,6 +40,7 @@ import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentT
 import { buildSearchFtsQuery, parseDateBounds, computePerSourceWindow, effectiveObsFtsQuery, searchSessionsFts, searchPromptsFts, normalizeCrossSourceScores, applyUserSort, applyTierFilter } from './lib/search-core.mjs';
 import { AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import { countRecentHookErrors } from './lib/hook-telemetry.mjs';
+import { computeCitationFunnelTrend } from './lib/citation-tracker.mjs';
 import { aggregateMetrics } from './lib/metrics.mjs';
 import {
   insertDeferred, listOpenWithOrdinal, dropDeferred,
@@ -226,7 +227,7 @@ async function cmdSearch(db, args, { llm } = {}) {
     } else {
       obsResults = searchObservationsHybrid(db, obsCtx);
       if (obsCtx.orFallbackFired) orFallbackFired = true;
-      if (deepMode === 'auto' && autoDeepLlmReady(process.env, llm) && shouldEscalateToDeep(obsResults, obsCtx) && hasEscalatableCorpus(db, project || null)) {
+      if (deepMode === 'auto' && autoDeepLlmReady(process.env, llm) && shouldEscalateToDeep(obsResults, obsCtx, { db, project: project || null })) {
         process.stderr.write(`[mem] auto-escalated to deep search (weak results: ${obsResults.length} hits)\n`);
         obsResults = await runDeep({ auto: true });
         isDeep = true;
@@ -2313,8 +2314,12 @@ function cmdCitationStats(db, args) {
     ? `${pollutedRows.n} obs have cited_count > decay_seen_count (pre-v34 backfill — invariant holds for new data).`
     : null;
 
+  // R1: per-session invocation→cite funnel trend (citation_log). Same `days` window
+  // as the per-project cite rate above; funnel.prior/delta_pt show the direction.
+  const funnel = computeCitationFunnelTrend(db, { days });
+
   if (json) {
-    out(JSON.stringify({ window_days: days, per_project: perProject, decay_queue: decayQueue, promoted, demoted, data_pollution_note: dataPollutionNote }, null, 2));
+    out(JSON.stringify({ window_days: days, per_project: perProject, decay_queue: decayQueue, promoted, demoted, data_pollution_note: dataPollutionNote, funnel }, null, 2));
     return;
   }
 
@@ -2325,6 +2330,28 @@ function cmdCitationStats(db, args) {
     out(`  ${r.project.padEnd(34)} ${String(rate).padStart(6)}   cited:${r.cited}/${r.resolved}   at_risk:${r.at_risk}`);
   }
   out('');
+
+  // R1: invocation→cite funnel — per-session trend + window-vs-prior direction.
+  out(`Invocation→cite funnel (recent sessions, injected→cited; rate window ${days}d):`);
+  if (funnel.sessions.length === 0) {
+    out('  (no resolved sessions in window)');
+  } else {
+    for (const s of funnel.sessions) {
+      const day = s.resolved_at ? new Date(s.resolved_at).toISOString().slice(0, 10) : '—'.repeat(10);
+      const pct = (s.rate * 100).toFixed(1) + '%';
+      out(`  ${day}  ${(s.project || '').padEnd(28)} inj ${String(s.injected_n).padStart(3)}  cited ${String(s.cited_n).padStart(3)}  ${pct.padStart(6)}`);
+    }
+  }
+  let trendLine = `window rate ${(funnel.window.rate * 100).toFixed(1)}%  cited ${funnel.window.cited}/${funnel.window.injected}`;
+  if (funnel.delta_pt === null) {
+    trendLine += '  (no prior-window data)';
+  } else {
+    const arrow = funnel.delta_pt > 0 ? '↑' : funnel.delta_pt < 0 ? '↓' : '→';
+    const sign = funnel.delta_pt > 0 ? '+' : '';
+    trendLine += `  (prior ${days}d ${(funnel.prior.rate * 100).toFixed(1)}%)  ${arrow} ${sign}${funnel.delta_pt}pt`;
+  }
+  out(trendLine);
+  out('');
   out('Active decay queue (uncited_streak >= 2, next miss → demote):');
   if (decayQueue.length === 0) out('  (none)');
   for (const r of decayQueue) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.5.0",
+  "version": "3.7.0",
   "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).",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -69,7 +69,10 @@
     "lib/file-intel.mjs",
     "lib/reread-guard.mjs",
     "lib/metrics.mjs",
+    "lib/lesson-idents.mjs",
     "lib/binding-probe.mjs",
+    "lib/proc-lock.mjs",
+    "lib/atomic-write.mjs",
     "lib/mem-override.mjs",
     "lib/save-observation.mjs",
     "lib/observation-write.mjs",
@@ -131,6 +134,7 @@
     "scripts/post-tool-use.sh",
     "scripts/user-prompt-search.js",
     "scripts/pre-tool-recall.js",
+    "scripts/post-tool-recall.js",
     "scripts/pre-skill-bridge.js",
     "scripts/prompt-search-utils.mjs",
     "scripts/hook-launcher.mjs",

package/schema.mjs

@@ -6,7 +6,7 @@ import Database from 'better-sqlite3';
 import { homedir } from 'os';
 import { join } from 'path';
 import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, chmodSync } from 'fs';
-import { OBS_FTS_COLUMNS } from './utils.mjs';
+import { OBS_FTS_COLUMNS, debugCatch } from './utils.mjs';
 
 // DATA location — DB, managed resources, registry DB, runtime/. Honors
 // CLAUDE_MEM_DIR so users can relocate state to a larger/faster volume.
@@ -71,7 +71,24 @@ export const CODE_DIR = join(homedir(), '.claude-mem-lite');
 // legacy trigger on existing DBs. LATEST_MIGRATION_COLUMN unchanged (no new column).
 // v37 (D#26): adds user_prompts.cc_session_id (additive, nullable). LATEST_MIGRATION_COLUMN
 // MOVES to it so the half-migrated-DB self-heal fast-path covers the new column.
-export const CURRENT_SCHEMA_VERSION = 37;
+// v38 (R1): citation_log table — per-session invocation→cite funnel telemetry. One
+// accumulating row per resolved session (injected_n / cited_n), written by
+// recordCitationFunnel from applyCitationDecay's touched/promoted at Stop. Turns the
+// per-obs cite counters (lifetime-cumulative) into a trendable per-session series so
+// `citation-stats` can answer "is memory invocation effectiveness rising or falling".
+// New TABLE (not a column) reached via CORE_SCHEMA's CREATE TABLE IF NOT EXISTS on the
+// forced migration pass; LATEST_MIGRATION_COLUMN unchanged (no new column) — same
+// pattern as v35/v36.
+// v39 (audit P1-5): migration_cleanups table — a sentinel registry that makes the
+// one-shot DATA cleanups (orphan deletes, project-name normalization) RETRYABLE.
+// They previously ran inside the version-gated migration body and were swallowed
+// on failure AFTER the version stamp committed, so a failed cleanup could never
+// re-run (the fast-path then skipped the whole body). They now run via
+// runDeferredCleanups() on every ensureDb, each gated by a done-marker row: a
+// failure leaves the marker unset and retries on the next open. New TABLE via
+// CORE_SCHEMA on the forced pass; LATEST_MIGRATION_COLUMN unchanged (no new
+// column) — same pattern as v35/v36/v38.
+export const CURRENT_SCHEMA_VERSION = 39;
 
 // Sentinel column for the LATEST migration set. The fast-path uses this to
 // self-heal half-migrated DBs — schema_version bumped but column ALTERs rolled
@@ -168,6 +185,20 @@ const CORE_SCHEMA = `
     created_at_epoch INTEGER,
     PRIMARY KEY (project, type, session_id)
   );
+
+  CREATE TABLE IF NOT EXISTS citation_log (
+    project TEXT NOT NULL,
+    memory_session_id TEXT NOT NULL,
+    resolved_at INTEGER,
+    injected_n INTEGER NOT NULL DEFAULT 0,
+    cited_n INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (project, memory_session_id)
+  );
+
+  CREATE TABLE IF NOT EXISTS migration_cleanups (
+    name TEXT PRIMARY KEY,
+    done_at_epoch INTEGER NOT NULL
+  );
 `;
 
 // Column migrations (idempotent — only swallow "duplicate column" errors)
@@ -539,18 +570,8 @@ export function initSchema(db) {
     }
   } catch { /* non-critical — migration can retry on next open */ }
 
-  // v35 (v2.87.0) P1: one-shot cleanup of orphaned observation_files. Same root
-  // cause as the v28 observation_vectors cleanup below — until the warm-start
-  // fast-path FK fix (initSchema early returns now restore foreign_keys=ON),
-  // ensureDb() handles ran with FK OFF, so ON DELETE CASCADE never fired and
-  // junction rows leaked (live DB: 6440/9569 = 67% orphans). Idempotent (NOT IN
-  // is empty on a clean DB); runs once per version bump via the fast-path gate.
-  try {
-    db.prepare(`
-      DELETE FROM observation_files
-      WHERE obs_id NOT IN (SELECT id FROM observations)
-    `).run();
-  } catch { /* non-critical — table-missing path handled by earlier CREATE */ }
+  // observation_files orphan cleanup moved to runDeferredCleanups() (audit P1-5):
+  // it now runs retryably outside the version fast-path. See DEFERRED_CLEANUPS.
 
   // Observation vectors table for TF-IDF vector search
   db.exec(`
@@ -565,16 +586,7 @@ export function initSchema(db) {
 
   db.exec(`CREATE INDEX IF NOT EXISTS idx_obs_vectors_version ON observation_vectors(vocab_version)`);
 
-  // v28 (v2.47) P0-1: one-shot cleanup of orphaned observation_vectors.
-  // Live DBs accumulated 44% orphans even with ON DELETE CASCADE because
-  // early migrations ran with `foreign_keys=OFF` and deletes skipped cascade.
-  // Idempotent (NOT IN is empty on a clean DB), runs once per ensureDb().
-  try {
-    db.prepare(`
-      DELETE FROM observation_vectors
-      WHERE observation_id NOT IN (SELECT id FROM observations)
-    `).run();
-  } catch { /* non-critical — table-missing path handled by earlier CREATE */ }
+  // observation_vectors orphan cleanup moved to runDeferredCleanups() (audit P1-5).
 
   // Persisted vocabulary for stable TF-IDF vector indexing
   db.exec(`
@@ -588,46 +600,9 @@ export function initSchema(db) {
   `);
   db.exec('CREATE INDEX IF NOT EXISTS idx_vocab_state_version ON vocab_state(version)');
 
-  // Project name normalization: migrate short names ("mem") to canonical form ("projects--mem")
-  // Strategy: exact suffix match first, then substring match for package-name aliases
-  // Idempotent: only runs when short-name records exist
-  try {
-    const shortProjects = db.prepare(`
-      SELECT DISTINCT project FROM observations
-      WHERE project NOT LIKE '%--_%' AND project != '' AND project IS NOT NULL
-      UNION
-      SELECT DISTINCT project FROM sdk_sessions
-      WHERE project NOT LIKE '%--_%' AND project != '' AND project IS NOT NULL
-    `).all();
-    if (shortProjects.length > 0) {
-      const normalize = db.transaction(() => {
-        for (const { project: shortName } of shortProjects) {
-          // Strategy 1: exact suffix match (e.g., "mem" → "projects--mem")
-          let canonical = db.prepare(
-            `SELECT project FROM observations WHERE project LIKE ? GROUP BY project ORDER BY COUNT(*) DESC LIMIT 1`
-          ).get(`%--${shortName}`);
-          // Strategy 2: substring match for aliases (e.g., "claude-mem-lite" → match project containing "mem")
-          // Extract the most distinctive token from the short name for fuzzy matching
-          if (!canonical) {
-            const tokens = shortName.split(/[-_.]/).filter(t => t.length >= 5);
-            for (const token of tokens) {
-              canonical = db.prepare(
-                `SELECT project FROM observations WHERE project LIKE ? AND project LIKE '%--_%'
-                 GROUP BY project ORDER BY COUNT(*) DESC LIMIT 1`
-              ).get(`%${token}%`);
-              if (canonical) break;
-            }
-          }
-          if (canonical) {
-            for (const table of ['observations', 'sdk_sessions', 'session_summaries']) {
-              db.prepare(`UPDATE ${table} SET project = ? WHERE project = ?`).run(canonical.project, shortName);
-            }
-          }
-        }
-      });
-      normalize();
-    }
-  } catch { /* non-critical — normalization can retry on next open */ }
+  // Project-name normalization moved to runDeferredCleanups() (audit P1-5) — it
+  // now retries on a later open if it fails, instead of being lost behind the
+  // version fast-path. See DEFERRED_CLEANUPS.
 
   // ─── v29 (v2.57.x): session-id mix invariant + lesson-retry stats ─────────
   //
@@ -787,6 +762,96 @@ export function auditSessionConsistency(db, { graceMinutes = 5 } = {}) {
   };
 }
 
+// ─── Deferred one-shot cleanups (retryable) ─────────────────────────────────
+// Idempotent DATA cleanups that must survive a transient failure. They run on
+// EVERY ensureDb (after initSchema), each gated by a row in migration_cleanups:
+// a cleanup that throws leaves its marker unset and retries on the next open —
+// unlike the old version-gated body, where a swallowed failure committed
+// alongside the version stamp and the fast-path then skipped it forever (P1-5).
+const DEFERRED_CLEANUPS = [
+  {
+    // v35 (v2.87.0): orphaned observation_files. ON DELETE CASCADE didn't fire
+    // while early warm-start handles ran with foreign_keys OFF, so junction rows
+    // leaked. Idempotent (NOT IN is empty on a clean DB).
+    name: 'orphan-observation-files',
+    run: (db) => db.prepare(
+      `DELETE FROM observation_files WHERE obs_id NOT IN (SELECT id FROM observations)`
+    ).run(),
+  },
+  {
+    // v28 (v2.47) P0-1: orphaned observation_vectors — same FK-OFF root cause.
+    name: 'orphan-observation-vectors',
+    run: (db) => db.prepare(
+      `DELETE FROM observation_vectors WHERE observation_id NOT IN (SELECT id FROM observations)`
+    ).run(),
+  },
+  {
+    // Project-name normalization: migrate short names ("mem") to canonical
+    // ("projects--mem"). Exact suffix match first, then distinctive-token
+    // substring. Idempotent: only acts on remaining short-name records.
+    name: 'normalize-project-names',
+    run: (db) => {
+      const shortProjects = db.prepare(`
+        SELECT DISTINCT project FROM observations
+        WHERE project NOT LIKE '%--_%' AND project != '' AND project IS NOT NULL
+        UNION
+        SELECT DISTINCT project FROM sdk_sessions
+        WHERE project NOT LIKE '%--_%' AND project != '' AND project IS NOT NULL
+      `).all();
+      if (shortProjects.length === 0) return;
+      const normalize = db.transaction(() => {
+        for (const { project: shortName } of shortProjects) {
+          let canonical = db.prepare(
+            `SELECT project FROM observations WHERE project LIKE ? GROUP BY project ORDER BY COUNT(*) DESC LIMIT 1`
+          ).get(`%--${shortName}`);
+          if (!canonical) {
+            const tokens = shortName.split(/[-_.]/).filter(t => t.length >= 5);
+            for (const token of tokens) {
+              canonical = db.prepare(
+                `SELECT project FROM observations WHERE project LIKE ? AND project LIKE '%--_%'
+                 GROUP BY project ORDER BY COUNT(*) DESC LIMIT 1`
+              ).get(`%${token}%`);
+              if (canonical) break;
+            }
+          }
+          if (canonical) {
+            for (const table of ['observations', 'sdk_sessions', 'session_summaries']) {
+              db.prepare(`UPDATE ${table} SET project = ? WHERE project = ?`).run(canonical.project, shortName);
+            }
+          }
+        }
+      });
+      normalize();
+    },
+  },
+];
+
+/**
+ * Run registered one-shot data cleanups that haven't completed yet. Each is
+ * gated by a row in migration_cleanups, so a transient failure retries on the
+ * next open instead of being silently lost behind the schema-version fast-path
+ * (audit P1-5). Best-effort: never throws — callers open the DB regardless.
+ */
+export function runDeferredCleanups(db) {
+  let done;
+  try {
+    done = new Set(db.prepare('SELECT name FROM migration_cleanups').all().map(r => r.name));
+  } catch {
+    return; // table not present yet (pre-migration open) — nothing to do
+  }
+  const mark = db.prepare('INSERT OR IGNORE INTO migration_cleanups (name, done_at_epoch) VALUES (?, ?)');
+  for (const { name, run } of DEFERRED_CLEANUPS) {
+    if (done.has(name)) continue;
+    try {
+      run(db);
+      mark.run(name, Date.now());
+    } catch (e) {
+      // Leave the marker unset → retried next open. Surface for observability.
+      debugCatch(e, `deferred-cleanup:${name}`);
+    }
+  }
+}
+
 /**
  * Ensure DB directory, database file, and all tables exist.
  * Safe to call from any process (hook or server). Idempotent.

package/scoring-sql.mjs

@@ -3,6 +3,31 @@
 
 import { buildNotLowSignalSql } from './lib/low-signal-patterns.mjs';
 
+// ─── Why these multipliers exist (read before "simplifying" them) ────────────
+//
+// The recency-decay, type-quality, project-boost, importance, cite, and noise
+// multipliers below encode PRODUCT PRIORS: recent / same-project / important /
+// high-signal-type / frequently-cited memories are more relevant to the CURRENT
+// dev session. A periodic audit tends to flag them as "0-lift dead weight" —
+// resist that on benchmark evidence alone. Measured (audit ②, obs #8773):
+//   * benchmark.mjs --matrix (micro-fixture, now models the full FULL_SCORE
+//     chain): type-quality is the TOP contributor (drop-type ΔnDCG=0.0082,
+//     ΔMRR=0.0166), decay +0.0043 nDCG, importance +0.0012; the chain lifts
+//     hybrid over bm25_only by +0.0093 nDCG / +0.0166 MRR (net 0 queries hurt).
+//     project, access and lesson read exactly 0 — but that is STRUCTURAL: the
+//     fixture is single-project, access_count=0, and has 0 lesson_learned rows,
+//     so it cannot vary those three axes.
+//   * longmemeval.mjs --temporal (n=500, real dates): bit-identical to uniform —
+//     LongMemEval-S windows (mean 27.9d, 74% <30d) are far shorter than these
+//     half-lives, so decay moves no rank there either.
+// Where a multiplier reads 0 it is a benchmark-MISMATCH artifact (the instrument
+// can't vary that axis), NOT proven dead weight. Decision: KEEP them; do NOT
+// delete on "0 lift". Guardrail: the ci-gate `hybrid_over_bm25 >= -0.05` floor
+// (benchmark/ci-gate.mjs) covers the full modelled chain
+// (decay/type/project/importance/access/lesson); cite + noise live on the
+// injection path (hook-memory.mjs) with no recall-benchmark coverage. Genuine
+// validation of the prior-encoding axes needs a labeled real-dev-memory eval.
+
 // ─── Type-Differentiated Recency Decay ──────────────────────────────────────
 
 /** Recency half-life per observation type (in milliseconds) */

package/scripts/post-tool-recall.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// scripts/post-tool-recall.js — PostToolUse companion to pre-tool-recall.js for
+// the bind-salience forcing-function (component 2). After an Edit/Write, if a
+// lesson surfaced for this file named an identifier that was present BEFORE the
+// edit (recorded in the cooldown by pre-tool-recall.js) and is now GONE, emit a
+// one-line non-blocking nudge. Only active under CLAUDE_MEM_SALIENCE=bind.
+//
+// Catches "you removed a required reference" lessons. It does NOT catch "you
+// failed to ADD a call" (the identifier was never in the pre-edit file →
+// presentIdents excluded it); that class is carried by the pre-edit
+// BIND_DIRECTIVE, not here. See the spec's component-2 limits.
+//
+// Safety: readonly, no DB, exit 0 always. cooldownPathFor mirrors
+// pre-tool-recall.js (inlined per the #8447 fast-path convention).
+
+import { existsSync, readFileSync } from 'fs';
+import { basename, join } from 'path';
+import { homedir } from 'os';
+
+const SALIENCE_BIND = process.env.CLAUDE_MEM_SALIENCE === 'bind';
+
+const DATA_DIR = process.env.CLAUDE_MEM_DIR || join(homedir(), '.claude-mem-lite');
+const RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || join(DATA_DIR, 'runtime');
+const LEGACY_COOLDOWN_PATH = join(RUNTIME_DIR, 'pre-recall-cooldown.json');
+
+function cooldownPathFor(sessionId) {
+  if (!sessionId) return LEGACY_COOLDOWN_PATH;
+  const safe = String(sessionId).replace(/[^a-zA-Z0-9_.-]/g, '-').slice(0, 64);
+  return join(RUNTIME_DIR, `pre-recall-cooldown-${safe}.json`);
+}
+
+async function main() {
+  if (!SALIENCE_BIND) return;
+  if (process.env.CLAUDE_MEM_HOOK_RUNNING) return;
+  let input = '';
+  for await (const chunk of process.stdin) input += chunk;
+  let filePath, sessionId;
+  try {
+    const e = JSON.parse(input);
+    filePath = e.tool_input?.file_path;
+    sessionId = e.session_id || null;
+  } catch { return; }
+  if (!filePath) return;
+
+  const cdPath = cooldownPathFor(sessionId);
+  if (!existsSync(cdPath)) return;
+  let entry;
+  try { entry = JSON.parse(readFileSync(cdPath, 'utf8'))[filePath]; } catch { return; }
+  const idents = entry && entry.lessonIdents;
+  if (!idents || typeof idents !== 'object') return;
+
+  let post;
+  try { post = readFileSync(filePath, 'utf8'); } catch { return; }
+
+  const dropped = [];
+  for (const [obsId, tokens] of Object.entries(idents)) {
+    for (const t of tokens) if (!post.includes(t)) dropped.push({ obsId, token: t });
+  }
+  if (!dropped.length) return;
+
+  const lines = ['[mem] PostToolUse recall — system-injected context, continue your planned action:'];
+  for (const d of dropped.slice(0, 3)) {
+    lines.push(`[mem] ⚠ your edit to ${basename(filePath)} dropped \`${d.token}\` flagged by #${d.obsId} — if intentional say so, else re-check before moving on.`);
+  }
+  process.stdout.write(JSON.stringify({
+    suppressOutput: true,
+    hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: lines.join('\n') },
+  }));
+}
+
+main().catch(() => {}).finally(() => process.exit(0));

package/scripts/pre-tool-recall.js

@@ -13,6 +13,7 @@ import { citeFactorClause } from '../scoring-sql.mjs';
 import { fileIntelFor } from '../lib/file-intel.mjs';
 import { shouldWarnReread, buildRereadWarning, readFileMeta } from '../lib/reread-guard.mjs';
 import { recordMetric } from '../lib/metrics.mjs';
+import { presentIdents } from '../lib/lesson-idents.mjs';
 
 // CLAUDE_MEM_DIR matches schema.mjs / main CLI — one env var sandboxes the
 // whole system. CLAUDE_MEM_DB_PATH / CLAUDE_MEM_RUNTIME_DIR remain as
@@ -40,7 +41,14 @@ const COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes (used only for legacy fallback)
 // restores the pre-v2.98 passive behavior.
 const SALIENCE_LEGACY = process.env.CLAUDE_MEM_SALIENCE === 'legacy'
   || process.env.CLAUDE_MEM_SALIENCE === '0';
+const SALIENCE_BIND = process.env.CLAUDE_MEM_SALIENCE === 'bind';
 const ACK_DIRECTIVE = "apply each lesson to this edit or rule it out — state '#NN applied' or '#NN n/a — <reason>' in your next user-facing message.";
+// v-bind salience forcing-function (#8771 audit: ack ≠ act). Instead of a cheap
+// '#NN applied / n/a' verdict, demand the model bind the lesson to the concrete
+// line it's editing and quote the satisfying edit line. Selected by
+// CLAUDE_MEM_SALIENCE=bind; default stays ACK_DIRECTIVE.
+const BIND_DIRECTIVE = "For each lesson: state the one concrete check it forces on the line(s) you're editing, quote the edit line that satisfies it, then report '#NN: <check> — pass' or '#NN: n/a — <why this edit can't reach it>'.";
+const ACTIVE_DIRECTIVE = SALIENCE_BIND ? BIND_DIRECTIVE : ACK_DIRECTIVE;
 const STALE_MS = 10 * 60 * 1000;   // 10 minutes cleanup threshold for legacy file
 // Feature ① (file intelligence): on the first Read of a file each session, inject
 // its approximate token size + a one-line summary so the agent can decide to read
@@ -238,7 +246,7 @@ try {
             hookEventName: 'PreToolUse',
             additionalContext: [
               '[mem] PreToolUse recall — system-injected context, continue your planned action:',
-              `[mem] ⚠ Lessons ${idList} were shown when you Read ${basename(filePath)} — ${ACK_DIRECTIVE}`,
+              `[mem] ⚠ Lessons ${idList} were shown when you Read ${basename(filePath)} — ${ACTIVE_DIRECTIVE}`,
             ].join('\n'),
           },
         }));
@@ -434,7 +442,7 @@ try {
       // Read keeps the quiet form; its forcing-function fires at the later Edit
       // via the Read→Edit ack nudge above.
       if (!isRead && !SALIENCE_LEGACY) {
-        lines.push(`[mem] ⚠ Before this edit: ${ACK_DIRECTIVE}`);
+        lines.push(`[mem] ⚠ Before this edit: ${ACTIVE_DIRECTIVE}`);
       }
     } else if (!isRead && process.env.CLAUDE_MEM_PRETOOL_NUDGE === '1') {
       // R-4: Edit/Write empty → short backfill reminder. OPT-IN (default off) as
@@ -474,10 +482,27 @@ try {
     // full re-read of the unchanged file can be flagged. Read-only, session-scoped;
     // one stat + bounded read, first-read only.
     const rereadMeta = (isRead && !REREAD_GUARD_OFF && isSessionScoped) ? readFileMeta(filePath) : null;
+    // bind salience (component 2): record the identifiers each lesson NAMES that
+    // ALSO appear in the current (pre-edit) file, so post-tool-recall.js can flag
+    // an edit that drops one. Only under =bind with lessons — keeps the default
+    // path free of the extra file read. Bounded read; never throws.
+    let lessonIdents;
+    if (SALIENCE_BIND && allRows.length > 0) {
+      try {
+        const pre = readFileSync(filePath, 'utf8').slice(0, 256 * 1024);
+        const acc = {};
+        for (const r of allRows) {
+          const present = presentIdents(`${r.lesson_learned || ''} ${r.title || ''}`, pre);
+          if (present.length) acc[r.id] = present;
+        }
+        if (Object.keys(acc).length) lessonIdents = acc;
+      } catch { /* unreadable pre-edit file — skip the diff check */ }
+    }
     cooldown[filePath] = {
       ts: now,
       lessonIds: allRows.map(r => r.id),
       mode: isRead ? 'read' : 'edit',
+      ...(lessonIdents ? { lessonIdents } : {}),
       ...(rereadMeta ? { reread: { mtimeMs: rereadMeta.mtimeMs, tokens: rereadMeta.tokens, full: isFullRead } } : {}),
     };
     writeCooldown(cooldownPath, cooldown, isSessionScoped);

package/server.mjs

@@ -10,7 +10,7 @@ import { resolveProject as _resolveProjectShared } from './project-utils.mjs';
 import { ensureDb, DB_PATH, DB_DIR, REGISTRY_DB_PATH } from './schema.mjs';
 import { reRankWithContext, markSuperseded, autoBoostIfNeeded, runIdleCleanup, buildServerInstructions } from './server-internals.mjs';
 import { searchObservationsHybrid, countSearchTotal, attachBodyTokens } from './search-engine.mjs';
-import { deepSearch, resolveDeepMode, shouldEscalateToDeep, autoDeepLlmReady, hasEscalatableCorpus } from './deep-search.mjs';
+import { deepSearch, resolveDeepMode, shouldEscalateToDeep, autoDeepLlmReady } from './deep-search.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
 import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentTimeline, fetchTimelineWindow } from './lib/timeline-core.mjs';
 import { buildSearchFtsQuery, parseDateBounds, computePerSourceWindow, effectiveObsFtsQuery, searchSessionsFts, searchPromptsFts, normalizeCrossSourceScores, applyUserSort, applyTierFilter } from './lib/search-core.mjs';
@@ -61,8 +61,19 @@ let db;
 try {
   db = ensureDb();
 } catch (firstErr) {
+  // WAL-delete recovery is ONLY safe for genuine corruption. On a transient
+  // error (SQLITE_BUSY) or the forward-version guard throw, deleting the WAL
+  // would discard committed-but-uncheckpointed transactions — silent data loss.
+  // Restrict the rm to corruption signatures; otherwise fail fast, WAL intact.
+  const sig = `${firstErr.code || ''} ${firstErr.message || ''}`;
+  const isCorruption = /SQLITE_CORRUPT|SQLITE_NOTADB|malformed|not a database|disk image/i.test(sig);
+  if (!isCorruption) {
+    console.error(`[claude-mem-lite] FATAL: Database cannot be opened: ${firstErr.message}`);
+    console.error(`[claude-mem-lite] Left WAL/SHM intact (not a corruption error). If this persists, retry or reinstall: node install.mjs install`);
+    process.exit(1);
+  }
   // Recovery: remove WAL/SHM files (corrupt WAL is the most common cause) and retry
-  debugLog('WARN', 'server', `DB open failed, attempting WAL recovery: ${firstErr.message}`);
+  debugLog('WARN', 'server', `DB corruption detected, attempting WAL recovery: ${firstErr.message}`);
   try { rmSync(DB_PATH + '-wal', { force: true }); } catch {}
   try { rmSync(DB_PATH + '-shm', { force: true }); } catch {}
   try {
@@ -412,7 +423,7 @@ async function runSearchPipeline(db, args, { llm, rerankLlm } = {}) {
         // results is already obs-only here (sessions/prompts pushed below), but the
         // filter makes the invariant explicit and robust to future reordering.
         const obsCountBeforeEscalation = results.length;
-        if (deepMode === 'auto' && autoDeepLlmReady(process.env, llm) && shouldEscalateToDeep(results.filter(r => r.source === 'obs'), ctx) && hasEscalatableCorpus(db, args.project || null)) {
+        if (deepMode === 'auto' && autoDeepLlmReady(process.env, llm) && shouldEscalateToDeep(results.filter(r => r.source === 'obs'), ctx, { db, project: args.project || null })) {
           await runDeepInto({ auto: true });
           isDeep = true;
           escalated = true;

package/source-files.mjs

@@ -59,11 +59,20 @@ export const SOURCE_FILES = [
   'lib/file-intel.mjs',
   'lib/reread-guard.mjs',
   'lib/metrics.mjs',
+  // v3.6.x: bind-salience producer — extracts identifiers a lesson names that
+  // are present in the pre-edit file (component 2). Imported ONLY by
+  // scripts/pre-tool-recall.js; kept here for the same reason as file-intel.mjs.
+  'lib/lesson-idents.mjs',
   // v2.71.x: better-sqlite3 ABI probe + auto-rebuild. Shared by install.mjs
   // (post-`npm install` verify) and scripts/launch.mjs (pre-server-launch
   // self-heal after Node ABI changes). Missing from manifest → auto-update
   // ships a stale install that FATALs on first DB open after Node upgrade.
   'lib/binding-probe.mjs',
+  // audit P0/P1: inter-process install lock + atomic config writes — imported by
+  // install.mjs (settings.json + install lock) and hook-update.mjs (.claude.json
+  // + auto-update lock). Must ship or a partial install/update skips them.
+  'lib/proc-lock.mjs',
+  'lib/atomic-write.mjs',
   // v2.41 god-module split — mem-cli.mjs router + per-cmd handlers under cli/
   'cli/common.mjs',
   'cli/fts-check.mjs',
@@ -149,6 +158,7 @@ export const HOOK_SCRIPT_FILES = [
   'user-prompt-search.js',
   'prompt-search-utils.mjs',
   'pre-tool-recall.js',
+  'post-tool-recall.js',
   'pre-skill-bridge.js',
   // v2.84: self-heal wrapper that detects ERR_MODULE_NOT_FOUND under the
   // install dir and runs install.mjs repair before retrying the entry.