claude-mem-lite 2.28.2 → 2.30.0

package/scripts/pre-tool-recall.js

@@ -7,8 +7,10 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { basename, join } from 'path';
 import { homedir } from 'os';
 
-const DB_PATH = join(homedir(), '.claude-mem-lite', 'claude-mem-lite.db');
-const RUNTIME_DIR = join(homedir(), '.claude-mem-lite', 'runtime');
+// CLAUDE_MEM_DB_PATH / CLAUDE_MEM_RUNTIME_DIR env overrides allow tests and debug tools to
+// point the hook at an isolated DB + cooldown dir without touching the user's real state.
+const DB_PATH = process.env.CLAUDE_MEM_DB_PATH || join(homedir(), '.claude-mem-lite', 'claude-mem-lite.db');
+const RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || join(homedir(), '.claude-mem-lite', 'runtime');
 const COOLDOWN_PATH = join(RUNTIME_DIR, 'pre-recall-cooldown.json');
 const COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
 const STALE_MS = 10 * 60 * 1000;   // 10 minutes cleanup threshold
@@ -88,34 +90,55 @@ try {
     // 60-day lookback to avoid surfacing ancient observations
     const cutoff = Date.now() - 60 * 86400000;
 
+    // Surface actionable lessons first, then high-importance bugfix/decision observations.
+    // Priority: 1) observations with lesson_learned (most actionable for preventing repeat bugs)
+    //           2) bugfix/decision types with importance>=2 (contextual history)
+    // Skip pure change/discovery without lessons — they add noise without actionable value.
     const rows = db.prepare(`
       SELECT DISTINCT o.id, o.type, o.title, o.lesson_learned
       FROM observations o
       JOIN observation_files of2 ON of2.obs_id = o.id
       WHERE o.project = ?
         AND o.importance >= 2
-        AND o.lesson_learned IS NOT NULL
-        AND o.lesson_learned != ''
         AND COALESCE(o.compressed_into, 0) = 0
         AND o.superseded_at IS NULL
         AND o.created_at_epoch > ?
         AND (of2.filename = ? OR of2.filename LIKE ? ESCAPE '\\')
-      ORDER BY o.created_at_epoch DESC
+        AND (
+          (o.lesson_learned IS NOT NULL AND o.lesson_learned != '')
+          OR o.type IN ('bugfix', 'decision')
+        )
+      ORDER BY
+        CASE WHEN o.lesson_learned IS NOT NULL AND o.lesson_learned != '' THEN 0 ELSE 1 END,
+        o.created_at_epoch DESC
       LIMIT 2
     `).all(project, cutoff, filePath, likePattern);
 
     if (rows.length > 0) {
       console.log(`[mem] Lessons for ${fname}:`);
       for (const r of rows) {
-        const lesson = r.lesson_learned.length > 120
-          ? r.lesson_learned.slice(0, 117) + '...'
-          : r.lesson_learned;
-        console.log(`  #${r.id} [${r.type}] ${lesson}`);
+        if (r.lesson_learned) {
+          const lesson = r.lesson_learned.length > 120
+            ? r.lesson_learned.slice(0, 117) + '...'
+            : r.lesson_learned;
+          console.log(`  #${r.id} [${r.type}] ${lesson}`);
+        } else {
+          const title = (r.title || '').length > 120
+            ? r.title.slice(0, 117) + '...'
+            : (r.title || '');
+          console.log(`  #${r.id} [${r.type}] ${title}`);
+        }
       }
-      // Update cooldown
-      cooldown[filePath] = now;
-      writeCooldown(cooldown);
+    } else {
+      // R-4: emit a short backfill reminder instead of staying silent.
+      // Two goals: (1) Claude sees that the system actually ran, (2) Claude is
+      // nudged to mem_save a lesson when solving a non-obvious bug. The reminder
+      // is one line to minimize per-Edit context cost.
+      console.log(`[mem] No prior lessons for ${fname} — if you solve a non-obvious bug here, run: claude-mem-lite save --type bugfix --lesson "<one-line root cause + fix>"`);
     }
+    // Cooldown applies to BOTH branches so the reminder doesn't spam every Edit.
+    cooldown[filePath] = now;
+    writeCooldown(cooldown);
   } catch {
     // Silent failure — never block editing
   } finally {

package/scripts/prompt-search-utils.mjs

@@ -25,12 +25,32 @@ export function shouldSkip(text) {
 // ─── Intent Detection ───────────────────────────────────────────────────────
 
 export const INTENTS = [
-  // Error/debug intent
-  { pattern: /error|bug|crash|broken|fail|fix|报错|出错|错误|崩溃|修复/i, type: 'bugfix', limit: 3 },
-  // Decision/architecture intent (before recall — "为什么...之前" is a decision question, not recall)
-  { pattern: /why|decided|architecture|design|为什么|决定|架构|设计/i, type: 'decision', limit: 3 },
+  // Error/debug intent — highest priority, most actionable
+  // CJK: 不工作/有问题/挂了 from real prompts; 异常/失败/排查/定位/诊断 from dev vocabulary
+  { pattern: /error|bug|crash|broken|fail(?:ed|ing|ure)?|fix(?:ed|ing)?|debug|调试|报错|出错|错误|崩溃|修复|故障|不工作|有问题|出了问题|挂了|异常|失败|解决|排查|定位|诊断/i, type: 'bugfix', limit: 3 },
+  // Test intent — test failures surface bugfix memories
+  // CJK: 跑测试/写测试/测试用例/覆盖率 from real prompts
+  { pattern: /\btest(?:s|ing)?\b|spec\b|assert|单元测试|测试失败|test fail|测试|跑测试|写测试|测试用例|覆盖率/i, type: 'bugfix', limit: 3 },
+  // Review/audit intent — from real data: 审查(6x), 检查(9x), 审核, 代码审核
+  { pattern: /\breview\b|audit|inspect|审查|审核|检查|代码审核|审阅|code.?review/i, type: 'discovery', limit: 3 },
+  // Refactor intent — surface past refactor decisions and patterns
+  // CJK: 拆分/提取/简化/解耦/清理 from real prompts; 优化代码 = refactor (not perf)
+  { pattern: /refactor|restructur|cleanup|clean up|重构|整理|代码质量|拆分|提取|简化|解耦|清理/i, type: 'refactor', limit: 3 },
+  // Performance intent — before decision (so "slow" doesn't get classified as decision)
+  // CJK: 卡顿/超时/内存泄漏/优化 from real prompts; 加速/提速 from dev vocabulary
+  { pattern: /performance|perf\b|slow|latency|bottleneck|optimiz|性能|慢|延迟|耗时|效率低|卡顿|超时|内存泄漏|优化|加速|提速/i, type: 'discovery', limit: 3 },
+  // Decision/architecture intent
+  // CJK: 方案/原因/考虑/权衡/思路 from real prompts
+  { pattern: /why\b|decided|architecture|design\b|为什么|决定|架构|设计|方案|原因|考虑|权衡|思路/i, type: 'decision', limit: 3 },
+  // Database/schema intent — surface migration decisions
+  // CJK: 索引/查询/建表/改表 from dev vocabulary
+  { pattern: /schema|migration|数据库|迁移|database\b|表结构|字段|索引|查询|建表|改表/i, type: 'decision', limit: 3 },
+  // Implementation intent — surface related feature history (no type filter for broader recall)
+  // CJK: 开发/编写/创建/构建/做一个/写一个 from real prompts
+  { pattern: /implement|feature\b|add\s+(?:a\s+)?new|实现|添加|新功能|新增|开发|编写|创建|构建|做一个|加一个|写一个/i, type: null, limit: 3 },
   // Recall/history intent (catch-all temporal, lowest priority)
-  { pattern: /before|previously|last time|remember|之前|上次|以前|记得/i, type: null, limit: 5, useRecent: true },
+  // CJK: 刚才/历史/回顾 from real prompts
+  { pattern: /before|previously|last time|remember|之前|上次|以前|记得|刚才|历史|回顾/i, type: null, limit: 5, useRecent: true },
 ];
 
 export function detectIntent(text) {
@@ -42,15 +62,15 @@ export function detectIntent(text) {
   if (matches.length === 0) return null;
   if (matches.length === 1) return matches[0];
 
-  // Disambiguation: specifically when bugfix and recall both match, use
-  // position-based resolution — the pattern appearing earlier in text wins.
+  // Disambiguation: when recall intent overlaps with an actionable intent,
+  // use position-based resolution — the pattern appearing earlier in text wins.
   // "I remember we fixed..." → recall leads. "fix the bug from before" → bugfix leads.
   const first = matches[0];
-  const second = matches[1];
-  if (first.type === 'bugfix' && second.useRecent) {
-    const bugPos = text.search(first.pattern);
-    const recallPos = text.search(second.pattern);
-    if (recallPos < bugPos) return second;
+  const recallMatch = matches.find(m => m.useRecent);
+  if (recallMatch && first !== recallMatch) {
+    const actionPos = text.search(first.pattern);
+    const recallPos = text.search(recallMatch.pattern);
+    if (recallPos < actionPos) return recallMatch;
   }
   return first;
 }
@@ -112,8 +132,13 @@ export function matchRegistrySkillName(text, skillNames) {
 
 // ─── File Path Detection ─────────────────────────────────────────────────────
 
-/** Detect file paths in text */
+/** Detect file paths in text — excludes URLs and pure version numbers */
 export function extractFiles(text) {
   const matches = text.match(/[\w./-]+\.\w{1,10}/g) || [];
-  return matches.filter(m => m.includes('.') && !m.startsWith('http'));
+  return matches.filter(m =>
+    m.includes('.') &&
+    !m.startsWith('http') &&
+    !m.includes('//') &&
+    !/^\d+\.\d+$/.test(m)  // Exclude pure version numbers like "3.14" (not paths like "1.0/config.json")
+  );
 }

package/scripts/user-prompt-search.js

@@ -4,7 +4,7 @@
 // Lightweight: only imports schema.mjs and utils.mjs, no MCP SDK
 
 import { ensureDb, DB_DIR, REGISTRY_DB_PATH } from '../schema.mjs';
-import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject, OBS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, isPathConfined } from '../utils.mjs';
+import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject, OBS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, isPathConfined, notLowSignalTitleClause } from '../utils.mjs';
 import { writeFileSync, readFileSync, existsSync, renameSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
@@ -27,6 +27,8 @@ function searchByFts(db, queryText, project, limit, typeFilter) {
 
   const typeClause = typeFilter ? 'AND o.type = ?' : '';
   const now = Date.now();
+  // R1: notLowSignalTitleClause() excludes hook-llm degraded titles
+  // ("Modified X", "Worked on X", "Reviewed N files:", raw error logs).
   const sql = `
     SELECT o.id, o.type, o.title, o.lesson_learned,
            ${OBS_BM25}
@@ -40,6 +42,7 @@ function searchByFts(db, queryText, project, limit, typeFilter) {
       AND o.importance >= 1
       AND o.created_at_epoch > ?
       AND COALESCE(o.compressed_into, 0) = 0
+      AND ${notLowSignalTitleClause('o')}
       ${typeClause}
     ORDER BY relevance
     LIMIT ?
@@ -75,6 +78,7 @@ function searchByFile(db, files, project, limit) {
     const escaped = basename.replace(/%/g, '\\%').replace(/_/g, '\\_');
     const likePattern = `%${escaped}`;
 
+    // R1: exclude LOW_SIGNAL degraded titles from file-level recall.
     const rows = db.prepare(`
       SELECT DISTINCT o.id, o.type, o.title, o.lesson_learned
       FROM observations o
@@ -84,6 +88,7 @@ function searchByFile(db, files, project, limit) {
         AND COALESCE(o.compressed_into, 0) = 0
         AND o.created_at_epoch > ?
         AND (of2.filename = ? OR of2.filename LIKE ? ESCAPE '\\')
+        AND ${notLowSignalTitleClause('o')}
       ORDER BY o.created_at_epoch DESC
       LIMIT ?
     `).all(project, cutoff, file, likePattern, limit);
@@ -102,6 +107,9 @@ function searchByFile(db, files, project, limit) {
 
 function searchRecent(db, project, limit) {
   const cutoff = Date.now() - LOOKBACK_MS;
+  // R1: exclude LOW_SIGNAL degraded titles from "recent" recall intent
+  // (e.g. when user asks "what did I do earlier"). Unqualified alias because
+  // this query selects directly from observations with no join.
   return db.prepare(`
     SELECT id, type, title, lesson_learned
     FROM observations
@@ -109,6 +117,7 @@ function searchRecent(db, project, limit) {
       AND importance >= 1
       AND COALESCE(compressed_into, 0) = 0
       AND created_at_epoch > ?
+      AND ${notLowSignalTitleClause('')}
     ORDER BY created_at_epoch DESC
     LIMIT ?
   `).all(project, cutoff, limit);

package/server.mjs

@@ -4,12 +4,14 @@
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.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 } from './utils.mjs';
+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 { resolveProject as _resolveProjectShared } from './project-utils.mjs';
 import { ensureDb, DB_PATH, REGISTRY_DB_PATH, checkFTSIntegrity, rebuildFTS } from './schema.mjs';
 import { reRankWithContext, markSuperseded, extractPRFTerms, expandQueryByConcepts, autoBoostIfNeeded, runIdleCleanup } from './server-internals.mjs';
 import { computeTier, TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
-import { memSearchSchema, memRecentSchema, memTimelineSchema, memGetSchema, memDeleteSchema, memSaveSchema, memStatsSchema, memCompressSchema, memMaintainSchema, memUpdateSchema, memExportSchema, memRecallSchema, memFtsCheckSchema, memRegistrySchema, memBrowseSchema, memUseSchema } from './tool-schemas.mjs';
+import { memSearchSchema, memRecentSchema, memTimelineSchema, memGetSchema, memDeleteSchema, memSaveSchema, memStatsSchema, memCompressSchema, memMaintainSchema, memOptimizeSchema, memUpdateSchema, memExportSchema, memRecallSchema, memFtsCheckSchema, memRegistrySchema, memBrowseSchema, memUseSchema } from './tool-schemas.mjs';
+import { optimizePreview, optimizeRun } from './hook-optimize.mjs';
 import { basename, join } from 'path';
 import { homedir } from 'os';
 import { ensureRegistryDb, upsertResource } from './registry.mjs';
@@ -110,12 +112,14 @@ const server = new McpServer(
       'mem_save: Save non-obvious insights (bugfix lessons, architecture decisions).',
       'Search tips: short keywords (2-3 words), filter with obs_type when relevant.',
       '',
-      'WHEN TO USE (proactive triggers):',
-      '  • Before fixing a bug → recall the file: claude-mem-lite recall "file.mjs"',
-      '  • Encountering an error → search for similar: claude-mem-lite search "error message" --type bugfix',
-      '  • Starting work on a module → recall past decisions: claude-mem-lite search "module-name" --type decision',
-      '  • After solving a non-obvious problem → save the lesson: mem_save with lesson_learned',
-      '  • When hook-injected context mentions a relevant ID → get details: claude-mem-lite get ID',
+      'WHEN TO USE (proactive triggers during coding):',
+      '  • About to Edit/Write a file → mem_recall(file="path") FIRST — past bugfixes & lessons',
+      '  • Test failure or error → mem_search(query="error keywords", obs_type="bugfix")',
+      '  • Before refactoring → mem_search(query="module-name", obs_type="refactor") for past decisions',
+      '  • Starting new feature → mem_search(query="feature area") for prior art & patterns',
+      '  • After fixing a tricky bug → mem_save(type="bugfix", lesson_learned="root cause & fix")',
+      '  • After architecture decision → mem_save(type="decision", lesson_learned="rationale")',
+      '  • Hook-injected context mentions #ID → mem_get(ids=[ID]) for full details',
       '',
       'Decision rules (use INSTEAD OF multi-step search):',
       '  • "what happened recently?" → mem_recent (NOT search with empty query)',
@@ -151,26 +155,32 @@ function safeHandler(fn) {
 
 // Score expression variants for FTS5 queries (see Scoring Model Constants above)
 // TYPE_QUALITY_CASE demotes bugfix (×0.6) and promotes decision/discovery (×1.5/1.3)
+// R-3: lesson_learned presence adds ×1.3 boost — empirical +6.3pp hit-rate lift on bugfix.
 const FULL_SCORE = `${OBS_BM25}
   * (1.0 + EXP(-0.693 * (? - MAX(o.created_at_epoch, COALESCE(o.last_accessed_at, o.created_at_epoch))) / ${TYPE_DECAY_CASE}))
   * ${TYPE_QUALITY_CASE}
   * (CASE WHEN ? IS NOT NULL AND o.project = ? THEN 2.0 ELSE 1.0 END)
   * (0.5 + 0.5 * COALESCE(o.importance, 1))
-  * (1.0 + 0.1 * LN(1 + COALESCE(o.access_count, 0)))`;
+  * (1.0 + 0.1 * LN(1 + COALESCE(o.access_count, 0)))
+  * (1.0 + 0.3 * (o.lesson_learned IS NOT NULL))`;
 
 const SIMPLE_SCORE = `${OBS_BM25}
   * (1.0 + EXP(-0.693 * (? - MAX(o.created_at_epoch, COALESCE(o.last_accessed_at, o.created_at_epoch))) / ${TYPE_DECAY_CASE}))
   * ${TYPE_QUALITY_CASE}
-  * (0.5 + 0.5 * COALESCE(o.importance, 1))`;
+  * (0.5 + 0.5 * COALESCE(o.importance, 1))
+  * (1.0 + 0.3 * (o.lesson_learned IS NOT NULL))`;
 
 /**
  * Build an FTS5 observation search query.
  * @param {'full'|'simple'} scoring - full includes project boost + access bonus
- * @param {object} opts - { multiplier, withSnippet, withOffset }
+ * @param {object} opts - { multiplier, withSnippet, withOffset, includeNoise }
+ *   includeNoise=true keeps hook-llm fallback titles ("Modified X", "Worked on X", etc.);
+ *   default false mirrors the filter already applied in hook-memory.mjs / user-prompt-search.js.
  */
-function buildObsFtsQuery(scoring, { multiplier, withSnippet, withOffset } = {}) {
+function buildObsFtsQuery(scoring, { multiplier, withSnippet, withOffset, includeNoise } = {}) {
   const scoreExpr = scoring === 'full' ? FULL_SCORE : SIMPLE_SCORE;
   const mult = multiplier ? ` * ${multiplier}` : '';
+  const lowSignalClause = includeNoise ? '' : `AND ${notLowSignalTitleClause('o')}`;
   return `
     SELECT o.id, o.type, o.title, o.subtitle, o.project, o.created_at, o.importance,
            o.files_modified,
@@ -187,6 +197,7 @@ function buildObsFtsQuery(scoring, { multiplier, withSnippet, withOffset } = {})
       AND (? IS NULL OR o.created_at_epoch <= ?)
       AND (? IS NULL OR COALESCE(o.importance, 1) >= ?)
       AND (? IS NULL OR o.branch = ?)
+      ${lowSignalClause}
     ORDER BY score
     LIMIT ?${withOffset ? ' OFFSET ?' : ''}`;
 }
@@ -221,12 +232,14 @@ function ftsRowToResult(r, { scoreMultiplier, snippet } = {}) {
 function searchObservations(ctx) {
   const { ftsQuery, args, epochFrom, epochTo, perSourceLimit, perSourceOffset, currentProject, limit } = ctx;
   const results = [];
+  // R-1: hide hook-llm fallback titles unless caller explicitly opts in via include_noise=true.
+  const includeNoise = args.include_noise === true;
 
   if (ftsQuery) {
     const now = Date.now();
     const projectBoost = args.project ? null : currentProject;
 
-    const rows = db.prepare(buildObsFtsQuery('full', { withSnippet: true, withOffset: true }))
+    const rows = db.prepare(buildObsFtsQuery('full', { withSnippet: true, withOffset: true, includeNoise }))
       .all(...buildObsFtsParams({ now, projectBoost, ftsQuery, args, epochFrom, epochTo, limit: perSourceLimit, offset: perSourceOffset }));
     for (const r of rows) results.push(ftsRowToResult(r, { snippet: true }));
 
@@ -235,7 +248,7 @@ function searchObservations(ctx) {
       const orQuery = relaxFtsQueryToOr(ftsQuery);
       if (orQuery) {
         try {
-          const orRows = db.prepare(buildObsFtsQuery('full', { multiplier: 0.5, withSnippet: true, withOffset: true }))
+          const orRows = db.prepare(buildObsFtsQuery('full', { multiplier: 0.5, withSnippet: true, withOffset: true, includeNoise }))
             .all(...buildObsFtsParams({ now, projectBoost, ftsQuery: orQuery, args, epochFrom, epochTo, limit: perSourceLimit, offset: perSourceOffset }));
           for (const r of orRows) results.push(ftsRowToResult(r, { snippet: true }));
         } catch (e) { debugCatch(e, 'searchObservations-or-fallback'); }
@@ -245,8 +258,8 @@ function searchObservations(ctx) {
     // Two-phase query expansion for sparse results (only when well below limit)
     if (rows.length > 0 && results.length < Math.ceil(limit / 2)) {
       const existingIds = new Set(results.map(r => r.id));
-      expandObsByConceptCo(ctx, now, existingIds, results);
-      expandObsByPRF(ctx, now, rows.length, existingIds, results);
+      expandObsByConceptCo(ctx, now, existingIds, results, includeNoise);
+      expandObsByPRF(ctx, now, rows.length, existingIds, results, includeNoise);
     }
 
     // Vector search + RRF hybrid merge
@@ -275,6 +288,9 @@ function searchObservations(ctx) {
                   if (epochTo !== null && obs.created_at_epoch > epochTo) continue;
                   if (args.importance && (obs.importance ?? 1) < args.importance) continue;
                   if (args.branch && obs.branch !== args.branch) continue;
+                  // R-1: parity with FTS5 WHERE — vector path must also reject LOW_SIGNAL titles
+                  // so RRF cannot re-admit what the SQL clause excluded.
+                  if (!includeNoise && obs.title && LOW_SIGNAL_TITLE.test(obs.title)) continue;
                   resultMap.set(vr.id, { source: 'obs', id: obs.id, type: obs.type, title: obs.title, subtitle: obs.subtitle, project: obs.project, date: obs.created_at, importance: obs.importance, files_modified: obs.files_modified, snippet: '' });
                 }
               }
@@ -294,6 +310,7 @@ function searchObservations(ctx) {
               if (epochTo !== null && obs.created_at_epoch > epochTo) continue;
               if (args.importance && (obs.importance ?? 1) < args.importance) continue;
               if (args.branch && obs.branch !== args.branch) continue;
+              if (!includeNoise && obs.title && LOW_SIGNAL_TITLE.test(obs.title)) continue;
               results.push({ source: 'obs', id: obs.id, type: obs.type, title: obs.title, subtitle: obs.subtitle, project: obs.project, date: obs.created_at, importance: obs.importance, files_modified: obs.files_modified, score: -vr.similarity, snippet: '' });
             }
           }
@@ -325,14 +342,14 @@ function searchObservations(ctx) {
   return results;
 }
 
-function expandObsByConceptCo(ctx, now, existingIds, results) {
+function expandObsByConceptCo(ctx, now, existingIds, results, includeNoise = false) {
   const { ftsQuery, args, epochFrom, epochTo, limit } = ctx;
   if (results.length >= Math.ceil(limit / 2)) return;
   const expanded = expandQueryByConcepts(db, ftsQuery, args.project);
   if (expanded.length === 0) return;
   const expansionFts = expanded.map(c => `"${c.replace(/"/g, '""')}"`).join(' OR ');
   try {
-    const expRows = db.prepare(buildObsFtsQuery('simple'))
+    const expRows = db.prepare(buildObsFtsQuery('simple', { includeNoise }))
       .all(...buildObsFtsParams({ now, ftsQuery: expansionFts, args, epochFrom, epochTo, limit }));
     for (const r of expRows) {
       if (!existingIds.has(r.id)) {
@@ -343,7 +360,7 @@ function expandObsByConceptCo(ctx, now, existingIds, results) {
   } catch (e) { debugLog('WARN', 'mem_search', `concept expansion error: ${e.message}`); }
 }
 
-function expandObsByPRF(ctx, now, primaryCount, existingIds, results) {
+function expandObsByPRF(ctx, now, primaryCount, existingIds, results, includeNoise = false) {
   const { ftsQuery, args, epochFrom, epochTo, limit } = ctx;
   if (primaryCount < 3) return;
   const topResults = db.prepare(`
@@ -358,7 +375,7 @@ function expandObsByPRF(ctx, now, primaryCount, existingIds, results) {
   if (prfTerms.length === 0) return;
   const prfFts = prfTerms.map(t => `"${t.replace(/"/g, '""')}"`).join(' OR ');
   try {
-    const prfRows = db.prepare(buildObsFtsQuery('simple'))
+    const prfRows = db.prepare(buildObsFtsQuery('simple', { includeNoise }))
       .all(...buildObsFtsParams({ now, ftsQuery: prfFts, args, epochFrom, epochTo, limit }));
     for (const r of prfRows) {
       if (!existingIds.has(r.id)) {
@@ -453,6 +470,35 @@ function searchPrompts(ctx) {
     for (const r of rows) {
       results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, score: r.score });
     }
+    // CJK LIKE fallback: FTS5 unicode61 can't tokenize CJK substrings in prompts
+    if (rows.length === 0 && args.query) {
+      const cjkPatterns = extractCjkLikePatterns(args.query);
+      if (cjkPatterns.length > 0) {
+        const likeConds = cjkPatterns.map(() => 'p.prompt_text LIKE ?');
+        const likeParams = cjkPatterns.map(p => `%${p}%`);
+        const fallbackRows = db.prepare(`
+          SELECT p.id, p.prompt_text, p.content_session_id, p.created_at
+          FROM user_prompts p
+          JOIN sdk_sessions s ON p.content_session_id = s.content_session_id
+          WHERE (${likeConds.join(' OR ')})
+            AND p.prompt_text NOT LIKE '<task-notification>%'
+            AND (? IS NULL OR s.project = ?)
+            AND (? IS NULL OR p.created_at_epoch >= ?)
+            AND (? IS NULL OR p.created_at_epoch <= ?)
+          ORDER BY p.created_at_epoch DESC
+          LIMIT ? OFFSET ?
+        `).all(
+          ...likeParams,
+          args.project ?? null, args.project ?? null,
+          epochFrom, epochFrom,
+          epochTo, epochTo,
+          perSourceLimit, perSourceOffset
+        );
+        for (const r of fallbackRows) {
+          results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, score: 0 });
+        }
+      }
+    }
   } else if (searchType === 'prompts') {
     const params = [];
     const wheres = [];
@@ -524,7 +570,7 @@ function formatSearchOutput(paginatedResults, args, ftsQuery, totalCount, isCros
 server.registerTool(
   'mem_search',
   {
-    description: 'Search project memory for past bugfixes, decisions, and discoveries. Use when: encountering a familiar error, investigating a module before changes, or looking for prior art on a problem. Returns compact index (use mem_get for full details).',
+    description: 'Search project memory for past bugfixes, decisions, and discoveries. Use proactively when: encountering an error (search with obs_type="bugfix"), investigating a module before changes, or looking for prior art. Returns compact index (use mem_get for full details).',
     inputSchema: memSearchSchema,
   },
   safeHandler(async (args) => {
@@ -699,7 +745,7 @@ server.registerTool(
 server.registerTool(
   'mem_timeline',
   {
-    description: 'Browse observations as a timeline around an anchor point. Use when: exploring what happened before/after a specific observation, understanding the sequence of changes that led to a bug, or reviewing a session chronologically.',
+    description: 'Browse observations as a timeline around an anchor point. Accepts anchor ID or a query string to auto-find the anchor via FTS. Use when: exploring what happened before/after a specific observation, understanding the sequence of changes that led to a bug, or reviewing a session chronologically. Example: mem_timeline(query="FTS5 search bug") or mem_timeline(anchor=42).',
     inputSchema: memTimelineSchema,
   },
   safeHandler(async (args) => {
@@ -802,7 +848,7 @@ server.registerTool(
 server.registerTool(
   'mem_get',
   {
-    description: 'Get full details for one or more records by ID. Use when: hook-injected context mentions a relevant observation ID, or after mem_search to drill into specific results for narrative, lesson_learned, and file details.',
+    description: 'Get full details for one or more records by ID. Use when: hook-injected context mentions a relevant observation ID, or after mem_search to drill into specific results for narrative, lesson_learned, and file details. For session results (S#15), pass source="session". For prompt results (P#22), pass source="prompt".',
     inputSchema: memGetSchema,
   },
   safeHandler(async (args) => {
@@ -925,7 +971,7 @@ server.registerTool(
 server.registerTool(
   'mem_save',
   {
-    description: 'Save a memory/observation. Use when: solving a non-obvious bug (save the lesson), making an architecture decision, discovering something not obvious from code alone, or when the user asks to remember something.',
+    description: 'Save a memory/observation with optional lesson_learned. Use after: solving a non-obvious bug (pass lesson_learned="root cause & fix"), making an architecture decision (pass lesson_learned="rationale"), or discovering something not obvious from code. Also when user asks to remember something.',
     inputSchema: memSaveSchema,
   },
   safeHandler(async (args) => {
@@ -960,18 +1006,20 @@ server.registerTool(
 
     const safeContent = scrubSecrets(args.content);
     const safeTitle = scrubSecrets(title);
+    const safeLesson = args.lesson_learned ? scrubSecrets(args.lesson_learned) : null;
     const minhashSig = computeMinHash(safeTitle + ' ' + safeContent);
     // Append CJK bigrams to text field for FTS5 indexing of Chinese content
-    const bigramText = cjkBigrams(safeTitle + ' ' + safeContent);
+    const indexText = [safeTitle, safeContent, safeLesson].filter(Boolean).join(' ');
+    const bigramText = cjkBigrams(indexText);
     const textField = bigramText ? safeContent + ' ' + bigramText : safeContent;
 
     // Atomic: insert observation + observation_files + TF-IDF vector in one transaction
     const saveFiles = args.files || [];
     const saveTx = db.transaction(() => {
       const result = db.prepare(`
-        INSERT INTO observations (memory_session_id, project, text, type, title, narrative, concepts, facts, files_read, files_modified, importance, minhash_sig, branch, created_at, created_at_epoch)
-        VALUES (?, ?, ?, ?, ?, ?, '', '', '[]', ?, ?, ?, ?, ?, ?)
-      `).run(sessionId, project, textField, type, safeTitle, safeContent, JSON.stringify(saveFiles), args.importance ?? 2, minhashSig, getCurrentBranch(), now.toISOString(), now.getTime());
+        INSERT INTO observations (memory_session_id, project, text, type, title, narrative, concepts, facts, files_read, files_modified, importance, minhash_sig, lesson_learned, branch, created_at, created_at_epoch)
+        VALUES (?, ?, ?, ?, ?, ?, '', '', '[]', ?, ?, ?, ?, ?, ?, ?)
+      `).run(sessionId, project, textField, type, safeTitle, safeContent, JSON.stringify(saveFiles), args.importance ?? 2, minhashSig, safeLesson, getCurrentBranch(), now.toISOString(), now.getTime());
       const savedId = Number(result.lastInsertRowid);
 
       // Populate observation_files junction table
@@ -998,7 +1046,8 @@ server.registerTool(
     });
     const result = saveTx();
 
-    return { content: [{ type: 'text', text: `Saved as observation #${result.lastInsertRowid} [${type}] in project "${project}".` }] };
+    const lessonNote = safeLesson ? ` 💡lesson captured` : '';
+    return { content: [{ type: 'text', text: `Saved as observation #${result.lastInsertRowid} [${type}] in project "${project}".${lessonNote}` }] };
   })
 );
 
@@ -1486,6 +1535,50 @@ server.registerTool(
   })
 );
 
+// ─── Tool: mem_optimize ────────────────────────────────────────────────────
+
+server.registerTool(
+  'mem_optimize',
+  {
+    description: 'LLM-powered database optimization: re-enrich degraded records, normalize concepts, merge related observations, smart-compress old data. Use when: database quality seems low, search results are noisy, or for periodic deep maintenance.',
+    inputSchema: memOptimizeSchema,
+  },
+  safeHandler(async (args) => {
+    const action = args.action || 'preview';
+
+    if (action === 'preview') {
+      const preview = optimizePreview(db);
+      const lines = [
+        `🔍 LLM Optimization Preview:`,
+        `  Re-enrich candidates: ${preview.reenrich}`,
+        `  Normalize: ${preview.normalizeGateOpen ? `${preview.normalize} unique concepts` : 'gate closed (7-day interval)'}`,
+        `  Cluster-merge candidates: ${preview.clusterMerge} clusters`,
+        `  Smart-compress candidates: ${preview.smartCompress} clusters`,
+        `  Total: ${preview.total} items`,
+      ];
+      return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+
+    const force = action === 'run_all';
+    const results = await optimizeRun(db, {
+      tasks: args.tasks,
+      maxItems: args.max_items || 15,
+      force,
+    });
+
+    const lines = ['🔧 LLM Optimization Results:'];
+    if (results.reenrich) lines.push(`  Re-enrich: ${results.reenrich.processed || 0} processed, ${results.reenrich.skipped || 0} skipped`);
+    if (results.normalize) {
+      if (results.normalize.skipped) lines.push(`  Normalize: skipped (${results.normalize.reason})`);
+      else lines.push(`  Normalize: ${results.normalize.processed || 0} updated, ${results.normalize.groups || 0} synonym groups`);
+    }
+    if (results.clusterMerge) lines.push(`  Cluster-merge: ${results.clusterMerge.merged || 0} merged of ${results.clusterMerge.processed || 0} clusters`);
+    if (results.smartCompress) lines.push(`  Smart-compress: ${results.smartCompress.compressed || 0} compressed of ${results.smartCompress.processed || 0} clusters`);
+
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+  })
+);
+
 // ─── Tool: mem_registry ─────────────────────────────────────────────────────
 
 server.registerTool(
@@ -1872,7 +1965,7 @@ server.registerTool(
 server.registerTool(
   'mem_recall',
   {
-    description: 'Recall observations related to a file. Use when: about to edit a file, investigating a file with past issues, or before refactoring to recall past bugfixes, decisions, and context.',
+    description: 'Recall observations related to a file. ALWAYS use before editing a file with known issues. Also use when: investigating a file, or before refactoring to recall past bugfixes, decisions, and context.',
     inputSchema: memRecallSchema,
   },
   safeHandler(async (args) => {

package/skill.md

@@ -1,35 +1,22 @@
 ---
 name: mem
-description: Search and manage project memory (observations, sessions, prompts)
+description: "Use when: querying past work, managing memories, checking project history, or saving session findings"
 ---
 
-# Memory Skill
-
-Search and browse your project memory efficiently.
+# Memory
 
 ## Commands
 
-- `/mem search <query>` — FTS5 full-text search across all memories
-- `/mem recent [n]` — Show recent N observations (default 10)
-- `/mem save <text>` — Save a manual memory/note
-- `/mem stats` — Show memory statistics
-- `/mem timeline <query>` — Browse timeline around a matching observation
-
-## Efficient Search Workflow (3 steps, saves 10x tokens)
-
-1. **Search** → `mem_search(query="...")` → get compact ID index
-2. **Browse** → `mem_timeline(anchor=ID)` → see surrounding context
-3. **Detail** → `mem_get(ids=[...])` → get full content for specific IDs
-
-## Instructions
-
-When the user invokes `/mem`, parse their intent:
+- `/mem search <query>` — FTS5 full-text search
+- `/mem recent [n]` — Recent observations (default 5)
+- `/mem recall <file>` — File history before editing
+- `/mem timeline <id>` — Browse around an observation
+- `/mem save <text>` — Save a note
+- `/mem stats` — Memory statistics
+- `/mem cleanup [Nd]` — Purge stale data
 
-- `/mem search <query>` → call `mem_search` with the query
-- `/mem recent` or `/mem recent 20` → call `mem_search` with no query, limit=N
-- `/mem save <text>` → call `mem_save` with the text as content
-- `/mem stats` → call `mem_stats`
-- `/mem timeline <query>` → call `mem_timeline` with the query
-- `/mem <query>` (no subcommand) → treat as search, call `mem_search`
+## Efficient Workflow (saves 10x tokens)
 
-Always use the compact index from mem_search first, then mem_get for details only when needed. This minimizes token usage.
+1. `mem_search(query)` → compact ID index
+2. `mem_timeline(anchor=ID)` → surrounding context
+3. `mem_get(ids=[...])` → full content only when needed