claude-mem-lite 3.51.0 → 3.52.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.51.0",
+      "version": "3.52.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.51.0",
+  "version": "3.52.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/hook.mjs

@@ -72,6 +72,7 @@ import { handleLLMOptimize } from './hook-optimize.mjs';
 import { silentAutoAdopt } from './adopt-cli.mjs';
 import { emitV270UpgradeBanner } from './lib/upgrade-banner.mjs';
 import { loadCiteBackForEpisode, extractCiteBackSignals, buildUnsavedBugfixHint, countUnsavedBugfixShape, buildCiteRecallNudge as libBuildCiteRecallNudge, nextCiteLowStreak } from './lib/cite-back-hint.mjs';
+import { detectUnpersistedDecision } from './lib/persist-reminder.mjs';
 // plugin-cache-guard.mjs loaded dynamically — pre-2.31.2 installs that auto-upgraded
 // from an older hook-update.mjs SOURCE_FILES (which did not list this module) would
 // crash on static import. Degrade gracefully to no-op when the module is absent.
@@ -88,7 +89,12 @@ import { getVocabulary } from './tfidf.mjs';
 // Prevent recursive hooks from background claude -p calls
 // Background workers (llm-episode, llm-summary) are exempt — they're ours
 const event = process.argv[2];
-const BG_EVENTS = new Set(['llm-episode', 'llm-summary', 'auto-compress', 'llm-optimize', 'auto-maintain']);
+// Events allowed to run under CLAUDE_MEM_HOOK_RUNNING=1 (the recursion guard at
+// the dispatch below exits everything else). EVERY spawnBackground/queue* event
+// MUST be listed here — a missing entry makes the detached worker exit(0)
+// silently, which looks identical to "worker ran and found nothing" from the
+// outside (live-probe catch, 2026-07-18: enrich-save no-oped on this line).
+const BG_EVENTS = new Set(['llm-episode', 'llm-summary', 'auto-compress', 'llm-optimize', 'auto-maintain', 'enrich-save']);
 
 // Respect Claude Code plugin disable state even when legacy settings.json hooks remain.
 // install.mjs writes direct hooks into ~/.claude/settings.json, so disabling the plugin
@@ -711,7 +717,21 @@ async function handleStop() {
             let priorStreak = 0;
             try { priorStreak = JSON.parse(readFileSync(dest, 'utf8')).lowStreak || 0; } catch {}
             const lowStreak = nextCiteLowStreak(priorStreak, stats);
-            const payload = { ...stats, ...bugfixStats, lowStreak, project, savedAt: Date.now() };
+            // G3: finalized-in-conversation + zero deliberate persistence →
+            // decisionSignal rides the payload; next SessionStart reminds once.
+            let decisionSignal = null;
+            try {
+              const promptRows = db.prepare(`
+                SELECT prompt_text FROM user_prompts
+                WHERE content_session_id = ? ORDER BY prompt_number ASC LIMIT 200
+              `).all(sessionId);
+              const d = detectUnpersistedDecision({
+                prompts: promptRows.map((r) => r.prompt_text),
+                transcriptPath,
+              });
+              if (d.fire) decisionSignal = d.signal;
+            } catch (e) { debugCatch(e, 'handleStop-persist-reminder'); }
+            const payload = { ...stats, ...bugfixStats, lowStreak, decisionSignal, project, savedAt: Date.now() };
             writeFileSync(dest, JSON.stringify(payload), { mode: 0o600 });
           } catch (e) { debugCatch(e, 'handleStop-cite-recall-persist'); }
         }
@@ -1587,6 +1607,28 @@ async function handleUserPrompt() {
   }
 }
 
+// ─── Save-Enrich (Background Worker, G1+G2) ─────────────────────────────────
+
+/**
+ * Detached worker spawned by the save surfaces (lib/save-enrich.mjs
+ * queueSaveEnrich): one Haiku call backfills lesson (obligated types) +
+ * search_aliases, fill-only-empty. Silent on any failure.
+ */
+async function handleEnrichSave(rawId) {
+  const id = parseInt(rawId, 10);
+  if (!Number.isInteger(id) || id <= 0) return;
+  const db = openDb();
+  if (!db) return;
+  try {
+    const { executeSaveEnrich } = await import('./lib/save-enrich.mjs');
+    await executeSaveEnrich(db, id);
+  } catch (e) {
+    debugCatch(e, 'enrich-save');
+  } finally {
+    try { db.close(); } catch {}
+  }
+}
+
 // ─── Auto-Compress (Background Worker) ───────────────────────────────────────
 
 /**
@@ -1694,6 +1736,7 @@ try {
     case 'llm-episode':      await handleLLMEpisode(); break;
     case 'llm-summary':      await handleLLMSummary(); break;
     case 'auto-compress':    handleAutoCompress(); break;
+    case 'enrich-save':      await handleEnrichSave(process.argv[3]); break;
     case 'auto-maintain':    handleAutoMaintain(); break;
     case 'llm-optimize':   await handleLLMOptimize(); break;
     // Detached update refresh spawned by handleSessionStart (audit P3d) — does the

package/lib/cite-back-hint.mjs

@@ -247,6 +247,12 @@ export function buildCiteRecallNudge(project, runtimeDir, env = process.env) {
     if (typeof data.unsaved === 'number' && data.unsaved > 0) {
       lines.push(`[mem] Last session: ${data.unsaved} unsaved bugfix-shape edit(s) — if any was a real fix, save now: /lesson --file <path> "<root cause + fix>"`);
     }
+    // G3 third gate: the prior session finalized a decision in conversation
+    // ("${data.decisionSignal}") but made no mem_save/mem_defer write — surface
+    // once while the handoff context still makes recovery actionable.
+    if (typeof data.decisionSignal === 'string' && data.decisionSignal.length > 0) {
+      lines.push(`[mem] ⚠ Last session mentioned a finalized decision ("${data.decisionSignal}") but persisted nothing — if it should survive /clear, capture it now: mem_save(type="decision", …) or mem_defer.`);
+    }
     return lines.join('\n');
   } catch { return ''; }
 }

package/lib/persist-reminder.mjs

@@ -0,0 +1,86 @@
+// Unpersisted-decision reminder — G3 (roadmap 2026-07-18).
+//
+// The write-side other half of the D#92 incident: that deferred item was
+// recoverable only because the originating session VOLUNTARILY wrote a defer
+// detail. When a session finalizes something in conversation (定稿/拍板/
+// approved/…) and makes no deliberate persistence call, /clear loses it —
+// tasks/ and docs/ are gitignored local files with no cross-session search
+// face. This module detects the shape at Stop; the payload rides
+// cite-recall-<project>.json and the NEXT SessionStart surfaces ONE reminder
+// line (that is the moment recovery is actionable — the handoff still carries
+// the context). Remind-only by design: false positives cost one line, so the
+// signal list stays conservative and never auto-writes anything.
+
+import { readFileSync, existsSync } from 'fs';
+
+// Distinctive finalization word forms (CJK + EN). Deliberately NOT included:
+// "方案 A 定" and bare "定" (too FP-prone), bare "ok/好" (noise). The list is
+// remind-only, so precision beats recall here.
+const FINALIZATION_FORMS = [
+  '定稿', '拍板', '敲定', '批准', '采纳',
+];
+const FINALIZATION_EN_RE = /\bapproved?\b|\bsign(?:ed)?[\s-]?off\b|\bfinali[sz]ed?\b|writing-plans/i;
+
+/**
+ * Scan user prompts for a finalization signal.
+ * @param {string[]} prompts
+ * @returns {string|null} the matched form (for quoting in the reminder), or null
+ */
+export function detectFinalization(prompts) {
+  for (const p of prompts || []) {
+    if (typeof p !== 'string' || !p) continue;
+    for (const form of FINALIZATION_FORMS) {
+      if (p.includes(form)) return form;
+    }
+    const m = p.match(FINALIZATION_EN_RE);
+    if (m) return m[0];
+  }
+  return null;
+}
+
+// Deliberate-persistence calls, transcript-side. Mirrors the tool-name/idiom
+// sets in lib/cite-back-hint.mjs (countUnsavedBugfixShape) but counts ANY
+// mem_save/mem_defer — a decision can legitimately land as any type.
+const PERSIST_TOOL_NAMES = new Set([
+  'mem_save', 'mem_defer',
+  'mcp__claude_mem_lite__mem_save', 'mcp__claude_mem_lite__mem_defer',
+  'mcp__plugin_claude-mem-lite_mem-lite__mem_save',
+  'mcp__plugin_claude-mem-lite_mem-lite__mem_defer',
+]);
+const PERSIST_CLI_RE = /(?:cli\.mjs|claude-mem-lite)['"]?\s+(?:save\b|defer\s+add\b)/;
+
+/**
+ * Count deliberate persistence calls (mem_save / mem_defer tool_use, CLI
+ * `save` / `defer add`) in the session transcript. 0 on missing/unreadable.
+ */
+export function countDeliberatePersistence(transcriptPath) {
+  if (!transcriptPath || !existsSync(transcriptPath)) return 0;
+  let raw;
+  try { raw = readFileSync(transcriptPath, 'utf8'); } catch { return 0; }
+  let count = 0;
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (entry.type !== 'assistant' && entry.message?.role !== 'assistant') continue;
+    const content = entry.message?.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (block.type !== 'tool_use') continue;
+      if (PERSIST_TOOL_NAMES.has(block.name)) { count++; continue; }
+      if (block.name === 'Bash' && PERSIST_CLI_RE.test(block.input?.command || '')) count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * The G3 gate: finalization signal present AND zero deliberate persistence.
+ * @returns {{fire: boolean, signal: string|null}}
+ */
+export function detectUnpersistedDecision({ prompts, transcriptPath }) {
+  const signal = detectFinalization(prompts);
+  if (!signal) return { fire: false, signal: null };
+  if (countDeliberatePersistence(transcriptPath) > 0) return { fire: false, signal };
+  return { fire: true, signal };
+}

package/lib/save-enrich.mjs

@@ -0,0 +1,163 @@
+// Save-time background enrichment — G1+G2 (roadmap 2026-07-18).
+//
+// The v3.49 save-nudge REMINDS the caller to write a lesson; nothing backfills
+// when the nudge is ignored (14d live: 20.7% of bugfix/decision writes are
+// lessonless, worsening), and manual saves NEVER carry search_aliases at
+// creation — the paraphrase-recall gap stays open until the next daily
+// llm-optimize pass ("saved yesterday, need it today" is the highest-value
+// window). This module closes both at the source with ONE Haiku call: distill
+// lesson_learned (obligated types only) + search_aliases (every manual save),
+// executed by a detached worker so the save path itself stays zero-latency.
+//
+// Contract (empty-overwrite is the historical audit main-class — R1/R4):
+//   • FILL-ONLY-EMPTY: never replaces a caller-written lesson or aliases filled
+//     by a concurrent optimize pass (re-checked inside a BEGIN IMMEDIATE txn).
+//   • Touches ONLY lesson_learned / search_aliases / text (alias append) —
+//     title/narrative/type/importance/concepts/facts stay byte-identical.
+//   • Never sets optimized_at: the daily wide re-enrich stays the safety net.
+//   • Silent degradation: no Haiku, bad JSON, ineligible row → row unchanged.
+//
+// Kill switch: CLAUDE_MEM_SKIP_SAVE_ENRICH=1 (naming mirrors SKIP_COMPRESS /
+// SKIP_OPTIMIZE). VITEST is gated out: e2e suites run hundreds of saves and a
+// dev machine with a logged-in claude CLI would fire that many REAL LLM calls.
+
+import { spawn } from 'child_process';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { scrubSecrets, cjkBigrams, truncate, debugCatch } from '../utils.mjs';
+import { scrubRecord } from './scrub-record.mjs';
+
+export const ENRICH_OBLIGATED_TYPES = new Set(['bugfix', 'decision']);
+
+const HOOK_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', 'hook.mjs');
+
+/**
+ * Trigger predicate for the save surfaces (CLI cmdSave / MCP mem_save).
+ * Every genuinely-new manual save qualifies (aliases are always missing at
+ * creation); env gates and dedup hits opt out.
+ */
+export function shouldQueueSaveEnrich(saveResult, env = process.env) {
+  if (!saveResult || saveResult.kind !== 'saved') return false;
+  if (env.CLAUDE_MEM_SKIP_SAVE_ENRICH === '1') return false;
+  if (env.VITEST) return false;
+  return true;
+}
+
+/**
+ * Spawn the detached enrichment worker (`node hook.mjs enrich-save <id>`).
+ * Fire-and-forget; never throws into the save path.
+ */
+export function queueSaveEnrich(id) {
+  try {
+    const child = spawn(process.execPath, [HOOK_PATH, 'enrich-save', String(id)], {
+      detached: true,
+      stdio: 'ignore',
+      env: { ...process.env, CLAUDE_MEM_HOOK_RUNNING: '1' },
+    });
+    child.on('error', (err) => { debugCatch(err, 'queueSaveEnrich'); });
+    child.unref();
+    return true;
+  } catch (err) {
+    debugCatch(err, 'queueSaveEnrich');
+    return false;
+  }
+}
+
+/**
+ * Worker body: one Haiku call → fill-only-empty backfill.
+ * @param {import('better-sqlite3').Database} db
+ * @param {number} id observation id
+ * @param {{callJson?: Function}} [opts] injectable LLM for tests
+ * @returns {Promise<{enriched: boolean, reason?: string}>}
+ */
+export async function executeSaveEnrich(db, id, { callJson } = {}) {
+  const row = db.prepare(`
+    SELECT id, type, title, narrative, text, lesson_learned, search_aliases,
+           superseded_at, compressed_into
+    FROM observations WHERE id = ?
+  `).get(id);
+  if (!row || row.superseded_at || row.compressed_into) {
+    return { enriched: false, reason: 'ineligible' };
+  }
+  const wantLesson = ENRICH_OBLIGATED_TYPES.has(row.type)
+    && !(row.lesson_learned && row.lesson_learned.trim());
+  const wantAliases = !(row.search_aliases && row.search_aliases.trim());
+  if (!wantLesson && !wantAliases) return { enriched: false, reason: 'complete' };
+
+  const call = callJson || (await import('../haiku-client.mjs')).callModelJSON;
+  const prompt = `A coding memory was just saved. Enrich its retrievability. Return ONLY valid JSON, no markdown fences.
+
+Title: ${truncate(row.title || '(untitled)', 200)}
+Context: ${truncate(row.narrative || row.text || '(none)', 500)}
+Type: ${row.type || 'change'}
+
+JSON: {"lesson_learned":"the transferable insight (root cause + fix, or constraint + tradeoff) in 1-2 sentences — or 'none' if routine","search_aliases":["alt phrasing","synonym","spelled-out jargon","CJK term if a key domain word has one"]}
+search_aliases: 3-6 terms a user might search for the SAME memory that are NOT already in the title.`;
+
+  let parsed = null;
+  try {
+    parsed = await call(prompt, 'haiku', { timeout: 15000, maxTokens: 400 });
+  } catch (e) { debugCatch(e, 'save-enrich-llm'); }
+  if (!parsed || typeof parsed !== 'object') return { enriched: false, reason: 'llm-null' };
+
+  const lesson = wantLesson
+    && typeof parsed.lesson_learned === 'string'
+    && parsed.lesson_learned.trim().length > 0
+    && parsed.lesson_learned.trim().toLowerCase() !== 'none'
+    ? scrubSecrets(parsed.lesson_learned).slice(0, 500) : null;
+  const aliasArr = wantAliases && Array.isArray(parsed.search_aliases)
+    ? parsed.search_aliases.filter((a) => typeof a === 'string' && a.trim().length > 0).slice(0, 6)
+    : [];
+  if (!lesson && aliasArr.length === 0) return { enriched: false, reason: 'nothing-usable' };
+
+  // Fill-only-empty under BEGIN IMMEDIATE: a concurrent daily-optimize pass (or
+  // a caller's mem_update) may have filled either field between spawn and now —
+  // read-then-modify without the immediate lock is exactly sqlite gotcha #5.
+  let enriched = false;
+  const txn = db.transaction(() => {
+    const fresh = db.prepare(`
+      SELECT lesson_learned, search_aliases, text, superseded_at, compressed_into
+      FROM observations WHERE id = ?
+    `).get(id);
+    if (!fresh || fresh.superseded_at || fresh.compressed_into) return;
+    const sets = [];
+    const vals = [];
+    if (lesson && !(fresh.lesson_learned && fresh.lesson_learned.trim())) {
+      const safe = scrubRecord('observations', { lesson_learned: lesson });
+      sets.push('lesson_learned = ?');
+      vals.push(safe.lesson_learned);
+    }
+    if (aliasArr.length && !(fresh.search_aliases && fresh.search_aliases.trim())) {
+      // APPEND aliases (+ CJK bigrams) to the existing FTS text — never rebuild
+      // it (the alias-backfill branch invariant: rebuilding from concepts/facts
+      // would drop the original narrative terms on manual saves).
+      const searchAliases = aliasArr.join(' ');
+      const appendedText = [fresh.text || '', searchAliases, cjkBigrams(searchAliases)]
+        .filter(Boolean).join(' ');
+      const safe = scrubRecord('observations', { search_aliases: searchAliases, text: appendedText });
+      sets.push('search_aliases = ?', 'text = ?');
+      vals.push(safe.search_aliases, safe.text);
+    }
+    if (sets.length === 0) return;
+    db.prepare(`UPDATE observations SET ${sets.join(', ')} WHERE id = ?`).run(...vals, id);
+    enriched = true;
+  });
+  try {
+    txn.immediate();
+  } catch (e) {
+    debugCatch(e, 'save-enrich-txn');
+    return { enriched: false, reason: 'txn-failed' };
+  }
+
+  if (enriched) {
+    // Refresh the TF-IDF vector so backfilled lesson/aliases reach the vector
+    // arm too (single source: hook-optimize's rebuildVector; lazy import keeps
+    // the save surfaces from loading the optimize stack for the predicate).
+    try {
+      const { rebuildVector } = await import('../hook-optimize.mjs');
+      const full = db.prepare('SELECT * FROM observations WHERE id = ?').get(id);
+      if (full) rebuildVector(db, id, full);
+    } catch (e) { debugCatch(e, 'save-enrich-vector'); }
+  }
+  return { enriched };
+}

package/mem-cli.mjs

@@ -58,6 +58,7 @@ import {
   searchDeferredWork, formatDeferredSearchTrailer,
   formatDeferListRow, countStaleOpen, formatDeferStaleHint,
 } from './lib/deferred-work.mjs';
+import { shouldQueueSaveEnrich, queueSaveEnrich } from './lib/save-enrich.mjs';
 
 // ─── Commands ────────────────────────────────────────────────────────────────
 
@@ -960,7 +961,11 @@ function cmdSave(db, args) {
   const supersededNote = result.supersededIds && result.supersededIds.length > 0
     ? ` Superseded: ${result.supersededIds.map(i => `#${i}`).join(', ')}.`
     : '';
-  out(`[mem] Saved #${result.id} [${result.type}] "${truncate(result.title, 80)}" (project: ${result.project})${lessonNote}${closedNote}${supersededNote}${buildLessonNudge({ type: result.type, id: result.id, lessonCaptured: result.lessonCaptured, surface: 'cli' })}`);
+  // G1+G2: detached backfill worker (lesson for obligated types + aliases for
+  // every save) — fill-only-empty, so an agent acting on the nudge still wins.
+  const enrichNote = shouldQueueSaveEnrich(result) && queueSaveEnrich(result.id)
+    ? ' (background enrichment queued)' : '';
+  out(`[mem] Saved #${result.id} [${result.type}] "${truncate(result.title, 80)}" (project: ${result.project})${lessonNote}${closedNote}${supersededNote}${enrichNote}${buildLessonNudge({ type: result.type, id: result.id, lessonCaptured: result.lessonCaptured, surface: 'cli' })}`);
 }
 
 // ─── cmdDefer (sub-dispatch: add | list | drop) ──────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.51.0",
+  "version": "3.52.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",
@@ -95,6 +95,8 @@
     "lib/stats-core.mjs",
     "lib/obs-types.mjs",
     "lib/save-nudge.mjs",
+    "lib/save-enrich.mjs",
+    "lib/persist-reminder.mjs",
     "lib/maintain-core.mjs",
     "lib/dedup-constants.mjs",
     "lib/deferred-work.mjs",

package/server.mjs

@@ -56,6 +56,7 @@ import {
   searchDeferredWork, formatDeferredSearchTrailer,
   formatDeferListRow, countStaleOpen, formatDeferStaleHint,
 } from './lib/deferred-work.mjs';
+import { shouldQueueSaveEnrich, queueSaveEnrich } from './lib/save-enrich.mjs';
 import { _resetVocabCache } from './tfidf.mjs';
 import { createRequire } from 'module';
 
@@ -799,7 +800,11 @@ server.registerTool(
       ? ` Superseded: ${result.supersededIds.map(i => `#${i}`).join(', ')}.`
       : '';
     const nudge = buildLessonNudge({ type: result.type, id: result.id, lessonCaptured: result.lessonCaptured, surface: 'mcp' });
-    return { content: [{ type: 'text', text: `Saved as observation #${result.id} [${result.type}] in project "${project}".${lessonNote}${closedNote}${supersededNote}${nudge}` }] };
+    // G1+G2: detached backfill worker (lesson for obligated types + aliases for
+    // every save) — fill-only-empty, so an agent acting on the nudge still wins.
+    const enrichNote = shouldQueueSaveEnrich(result) && queueSaveEnrich(result.id)
+      ? ' (background enrichment queued)' : '';
+    return { content: [{ type: 'text', text: `Saved as observation #${result.id} [${result.type}] in project "${project}".${lessonNote}${closedNote}${supersededNote}${enrichNote}${nudge}` }] };
   })
 );
 

package/source-files.mjs

@@ -175,6 +175,8 @@ export const SOURCE_FILES = [
   // (mem_save) and mem-cli.mjs (cmdSave). Missing it breaks both save surfaces on
   // auto-update.
   'lib/save-nudge.mjs',
+  'lib/save-enrich.mjs',
+  'lib/persist-reminder.mjs',
   // P10 dedup/merge threshold constants — single source of truth for the Jaccard
   // dedup/merge cutoffs. Statically imported by hook.mjs, hook-llm.mjs,
   // hook-optimize.mjs, mem-cli.mjs, server.mjs, and the save/maintain cores;