claude-mem-lite 2.28.2 → 2.29.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.28.2",
+      "version": "2.29.0",
       "source": "./",
       "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.28.2",
+  "version": "2.29.0",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/commands/mem.md

@@ -1,5 +1,6 @@
 ---
-description: "Search and manage project memory (observations, sessions, prompts). Use when: user asks about past work, wants to find a previous bugfix, check project history, save a decision, or manage stored memories"
+name: mem
+description: "Use when: querying past work, managing memories, or checking project history"
 ---
 
 # Memory

package/commands/memory.md

@@ -1,5 +1,6 @@
 ---
-description: "Save content to memory — with explicit content, instructions, or auto-summarize current session. Use when: the user asks to remember something, after solving a non-obvious problem, or to capture key session findings"
+name: memory
+description: "Use when: user asks to remember something, after solving a non-obvious problem, or to capture key session findings"
 ---
 
 # Memory Save

package/commands/tools.md

@@ -1,5 +1,6 @@
 ---
-description: "Import skills and agents from GitHub repositories into the tool resource registry. Use when: looking for a skill to solve a problem, importing tools from a repo, or managing installed tools"
+name: tools
+description: "Use when: importing skills/agents from GitHub, managing registry resources, or searching for tools to solve a problem"
 ---
 
 # Tool Import

package/commands/update.md

@@ -1,5 +1,6 @@
 ---
-description: "Auto-maintain memory and resource registry — deduplicate, merge, decay, cleanup, reindex. Use when: search results seem noisy, after bulk imports, or during periodic maintenance"
+name: update
+description: "Use when: search results seem noisy, after bulk imports, or for periodic memory/registry maintenance"
 ---
 
 # Memory & Registry Maintenance

package/haiku-client.mjs

@@ -100,6 +100,109 @@ export async function callHaikuJSON(prompt, opts) {
   return parseJsonFromLLM(result.text);
 }
 
+// ─── Model-Selectable API ────────────────────────────────────────────────────
+
+/**
+ * Call LLM with explicit model selection. Supports 'haiku' and 'sonnet'.
+ * Reuses existing API/CLI dual-mode infrastructure.
+ * Never throws — returns null on any error.
+ *
+ * @param {string} prompt The prompt text
+ * @param {'haiku'|'sonnet'} model Model to use (default: 'haiku')
+ * @param {object} [opts] Options
+ * @param {number} [opts.timeout=15000] Timeout in milliseconds
+ * @param {number} [opts.maxTokens=1000] Max tokens in response
+ * @returns {Promise<{text: string}|null>} Response or null on failure
+ */
+export async function callLLMWithModel(prompt, model = 'haiku', { timeout = 15000, maxTokens = 1000 } = {}) {
+  if (!prompt) return null;
+  const resolvedModel = MODEL_MAP[model] ? model : 'haiku';
+  const mode = detectMode();
+
+  try {
+    if (mode === 'api') {
+      return await callModelAPI(prompt, resolvedModel, { timeout, maxTokens });
+    }
+    return callModelCLI(prompt, resolvedModel, { timeout });
+  } catch (e) {
+    debugCatch(e, `callLLMWithModel:${resolvedModel}`);
+    return null;
+  }
+}
+
+/**
+ * Call LLM with model selection and parse JSON response.
+ * @param {string} prompt
+ * @param {'haiku'|'sonnet'} model
+ * @param {object} [opts]
+ * @returns {Promise<object|null>}
+ */
+export async function callModelJSON(prompt, model = 'haiku', opts) {
+  const result = await callLLMWithModel(prompt, model, opts);
+  if (!result?.text) return null;
+  return parseJsonFromLLM(result.text);
+}
+
+async function callModelAPI(prompt, model, { timeout, maxTokens }) {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) return null;
+
+  const modelId = MODEL_MAP[model];
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify({
+        model: modelId,
+        max_tokens: maxTokens,
+        messages: [{ role: 'user', content: prompt }],
+      }),
+      signal: controller.signal,
+    });
+
+    if (!res.ok) {
+      debugLog('WARN', `${model}-api`, `HTTP ${res.status}`);
+      return null;
+    }
+
+    const data = await res.json();
+    const text = data.content?.[0]?.text;
+    return text ? { text } : null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function callModelCLI(prompt, model, { timeout }) {
+  const modelName = MODEL_MAP[model] ? model : 'haiku';
+  try {
+    const result = execFileSync(getClaudePath(), ['-p', '--model', modelName], {
+      input: prompt,
+      timeout,
+      encoding: 'utf8',
+      env: { ...process.env, CLAUDE_MEM_HOOK_RUNNING: '1' },
+      stdio: ['pipe', 'pipe', 'pipe'],
+      cwd: '/tmp',
+    });
+    const text = result.trim();
+    return text ? { text } : null;
+  } catch (e) {
+    const out = e.stdout?.toString?.()?.trim() || e.output?.[1]?.toString?.()?.trim();
+    if (out && out.startsWith('{') && out.endsWith('}')) {
+      try { JSON.parse(out); return { text: out }; } catch {}
+    }
+    debugCatch(e, `${model}-cli`);
+    return null;
+  }
+}
+
 // ─── API Mode ────────────────────────────────────────────────────────────────
 
 async function callHaikuAPI(prompt, { timeout, maxTokens }) {

package/hook-memory.mjs

@@ -6,8 +6,13 @@ import { sanitizeFtsQuery, relaxFtsQueryToOr, debugCatch, OBS_BM25 } from './uti
 const MAX_MEMORY_INJECTIONS = 3;
 const MEMORY_LOOKBACK_MS = 60 * 86400000; // 60 days
 // Aligned with TYPE_QUALITY_CASE: high-signal types > noisy types
-// Bugfix lessons are still surfaced via the separate lesson_learned boost (1.5×)
-const MEMORY_TYPE_BOOST = { decision: 1.5, discovery: 1.3, feature: 1.2, refactor: 1.0, change: 0.8, bugfix: 0.5 };
+// Bugfix raised from 0.5→0.75 to match scoring-sql.mjs; lesson_learned boost (1.5×) stacks
+const MEMORY_TYPE_BOOST = { decision: 1.5, discovery: 1.3, feature: 1.2, refactor: 1.0, change: 0.8, bugfix: 0.75 };
+// Adaptive BM25 thresholds — scale with corpus size to filter noise.
+// Larger corpora produce more weak matches from common words.
+const BM25_THRESHOLD = { TINY: 0, SMALL: 1.5, MEDIUM: 2.5, LARGE: 3.5 };
+// OR fallback max token count — queries with 3+ tokens that fail AND are likely off-topic
+const OR_FALLBACK_MAX_TOKENS = 2;
 
 const FILE_RECALL_LOOKBACK_MS = 60 * 86400000; // 60 days
 const MAX_FILE_RECALL = 2;
@@ -47,18 +52,25 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
       LIMIT 10
     `);
     let rows = selectStmt.all(ftsQuery, project, cutoff);
+    let usedOrFallback = false;
 
-    // OR fallback when AND returns nothing
+    // OR fallback when AND returns nothing — only for short queries (specific enough).
+    // 3+ token queries that fail AND are likely off-topic; OR would match individual common words.
+    // Count original search terms (AND-separated groups), not expanded synonym tokens.
+    const queryTokenCount = ftsQuery.includes(' AND ')
+      ? ftsQuery.split(' AND ').length
+      : ftsQuery.split(/\s+/).filter(t => t && !t.startsWith('(') || !t.endsWith(')')).length;
     if (rows.length === 0) {
       const orQuery = relaxFtsQueryToOr(ftsQuery);
-      if (orQuery) {
-        try { rows = selectStmt.all(orQuery, project, cutoff); } catch {}
+      if (orQuery && queryTokenCount <= OR_FALLBACK_MAX_TOKENS) {
+        try { rows = selectStmt.all(orQuery, project, cutoff); usedOrFallback = true; } catch {}
       }
     }
 
     // Phase 2: Cross-project search for high-value decisions/discoveries
     // These are transferable insights (debugging patterns, architectural reasons, gotchas)
     let crossRows = [];
+    let crossUsedOr = false;
     try {
       const crossStmt = db.prepare(`
         SELECT o.id, o.type, o.title, o.importance, o.lesson_learned, o.project,
@@ -78,40 +90,44 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
       crossRows = crossStmt.all(ftsQuery, project, cutoff);
       if (crossRows.length === 0) {
         const orQuery = relaxFtsQueryToOr(ftsQuery);
-        if (orQuery) {
-          try { crossRows = crossStmt.all(orQuery, project, cutoff); } catch {}
+        if (orQuery && queryTokenCount <= OR_FALLBACK_MAX_TOKENS) {
+          try { crossRows = crossStmt.all(orQuery, project, cutoff); crossUsedOr = true; } catch {}
         }
       }
     } catch (e) { debugCatch(e, 'crossProjectSearch'); }
 
     // Merge and score: same-project full weight, cross-project 0.7x
-    const allRows = [...rows, ...crossRows];
+    // OR-fallback results get 0.4x penalty — they matched individual words, not the full intent
+    const allRows = [...rows.map(r => ({ ...r, _or: usedOrFallback })), ...crossRows.map(r => ({ ...r, _or: crossUsedOr }))];
     const scored = allRows
       .filter(r => !excludeSet.has(r.id))
       .map(r => {
         const crossProjectPenalty = r.project === project ? 1.0 : 0.7;
+        const orFallbackPenalty = r._or ? 0.4 : 1.0;
         return {
           ...r,
           score: Math.abs(r.relevance)
             * (MEMORY_TYPE_BOOST[r.type] || 1.0)
             * (r.lesson_learned ? 1.5 : 1.0)
             * (r.importance >= 2 ? 1.0 : 0.6)
-            * crossProjectPenalty,
+            * crossProjectPenalty
+            * orFallbackPenalty,
         };
       })
       .sort((a, b) => b.score - a.score);
 
-    // Adaptive threshold: BM25 IDF collapses when corpus has <5 observations,
-    // producing scores ~0.00001 even for exact matches. At 5+ obs, IDF provides
-    // meaningful discrimination and the calibrated 1.5 threshold works well.
+    // Adaptive threshold: scales with corpus size to filter noise.
+    // Each result must individually exceed the threshold (not just the top one).
     const obsCount = db.prepare(
       'SELECT COUNT(*) as c FROM observations WHERE project = ? AND COALESCE(compressed_into, 0) = 0',
     ).get(project)?.c || 0;
-    const threshold = obsCount < 5 ? 0 : 1.5;
-    if (scored.length === 0 || scored[0].score < threshold) return [];
+    const { TINY, SMALL, MEDIUM, LARGE } = BM25_THRESHOLD;
+    const threshold = obsCount < 5 ? TINY : obsCount < 100 ? SMALL : obsCount < 500 ? MEDIUM : LARGE;
+    const aboveThreshold = scored.filter(r => r.score >= threshold);
+    if (aboveThreshold.length === 0) return [];
 
     // Update access_count for injected memories
-    const result = scored.slice(0, MAX_MEMORY_INJECTIONS);
+    const result = aboveThreshold.slice(0, MAX_MEMORY_INJECTIONS);
     const now = Date.now();
     const updateStmt = db.prepare('UPDATE observations SET access_count = COALESCE(access_count, 0) + 1, last_accessed_at = ? WHERE id = ?');
     for (const r of result) {

package/hook.mjs

@@ -31,13 +31,14 @@ import { handleLLMEpisode, handleLLMSummary, saveObservation, buildImmediateObse
 import { searchRelevantMemories } from './hook-memory.mjs';
 import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection, extractUnfinishedSummary } from './hook-handoff.mjs';
 import { checkForUpdate } from './hook-update.mjs';
+import { handleLLMOptimize } from './hook-optimize.mjs';
 import { SKIP_TOOLS, SKIP_PREFIXES } from './skip-tools.mjs';
 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']);
+const BG_EVENTS = new Set(['llm-episode', 'llm-summary', 'auto-compress', 'llm-optimize']);
 
 // 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
@@ -122,6 +123,22 @@ function flushEpisode(episode) {
 
   if (isSignificant) {
     spawnBackground('llm-episode', flushFile);
+
+    // P3: Auto-save hint — detect error→fix pattern (error entry followed by Edit/Write)
+    // and nudge Claude to save the lesson for future recall
+    try {
+      const entries = episode.entries || [];
+      const hasError = entries.some(e => e.isError);
+      const hasEdit = entries.some(e => EDIT_TOOLS.has(e.tool));
+      if (hasError && hasEdit && entries.length >= 3) {
+        const editFiles = entries.filter(e => EDIT_TOOLS.has(e.tool)).flatMap(e => e.files || []);
+        const uniqueFiles = [...new Set(editFiles)].slice(0, 3);
+        const filesHint = uniqueFiles.length > 0 ? ` (files: ${uniqueFiles.join(', ')})` : '';
+        process.stdout.write(
+          `[mem] 💡 Error→fix pattern detected${filesHint}. Consider: mem_save(type="bugfix", lesson_learned="root cause & fix")\n`,
+        );
+      }
+    } catch { /* never block on hint */ }
   } else {
     try { unlinkSync(flushFile); } catch {}
   }
@@ -539,6 +556,7 @@ async function handleSessionStart() {
         writeFileSync(maintainFile, JSON.stringify({ epoch: Date.now() }));
         // Weekly summary grouping runs in background to avoid blocking SessionStart
         spawnBackground('auto-compress');
+        if (!process.env.CLAUDE_MEM_SKIP_OPTIMIZE) spawnBackground('llm-optimize');
       } catch (e) { debugCatch(e, 'auto-maintain'); }
     }
 
@@ -1060,6 +1078,7 @@ try {
     case 'llm-episode':      await handleLLMEpisode(); break;
     case 'llm-summary':      await handleLLMSummary(); break;
     case 'auto-compress':    handleAutoCompress(); break;
+    case 'llm-optimize':   await handleLLMOptimize(); break;
   }
 } catch (err) {
   // Always log fatal errors (ungated) with structured format

package/install.mjs

@@ -204,7 +204,7 @@ async function install() {
   const SOURCE_FILES = [
     'cli.mjs', 'server.mjs', 'server-internals.mjs', 'tool-schemas.mjs',
     'hook.mjs', 'hook-shared.mjs', 'hook-llm.mjs', 'hook-memory.mjs', 'skip-tools.mjs',
-    'hook-semaphore.mjs', 'hook-episode.mjs', 'hook-context.mjs', 'hook-handoff.mjs', 'hook-update.mjs',
+    'hook-semaphore.mjs', 'hook-episode.mjs', 'hook-context.mjs', 'hook-handoff.mjs', 'hook-update.mjs', 'hook-optimize.mjs',
     'haiku-client.mjs', 'utils.mjs', 'schema.mjs', 'package.json', 'package-lock.json', 'skill.md',
     'registry.mjs', 'registry-scanner.mjs', 'registry-indexer.mjs',
     'registry-retriever.mjs', 'resource-discovery.mjs',

package/mem-cli.mjs

@@ -5,12 +5,14 @@
 import { homedir } from 'os';
 import { ensureDb, DB_PATH, REGISTRY_DB_PATH, checkFTSIntegrity, rebuildFTS } from './schema.mjs';
 import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject, jaccardSimilarity, computeMinHash, estimateJaccardFromMinHash, scrubSecrets, cjkBigrams, isoWeekKey, COMPRESSED_PENDING_PURGE, OBS_BM25, SESS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, DEFAULT_DECAY_HALF_LIFE_MS, getCurrentBranch } from './utils.mjs';
+import { extractCjkLikePatterns } from './nlp.mjs';
 import { resolveProject } from './project-utils.mjs';
 import { computeTier, TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
 import { getVocabulary, computeVector, vectorSearch, rrfMerge, VECTOR_SCAN_LIMIT, rebuildVocabulary, _resetVocabCache } from './tfidf.mjs';
 import { autoBoostIfNeeded, reRankWithContext, markSuperseded, extractPRFTerms, expandQueryByConcepts } from './server-internals.mjs';
 import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
+import { optimizePreview, optimizeRun } from './hook-optimize.mjs';
 import { basename, join } from 'path';
 import { readFileSync } from 'fs';
 
@@ -280,6 +282,31 @@ function cmdSearch(db, args) {
         LIMIT ? OFFSET ?
       `).all(...promptParams);
       for (const r of promptRows) results.push({ ...r, _source: 'prompt' });
+      // CJK LIKE fallback: FTS5 unicode61 can't tokenize CJK substrings in prompts
+      if (promptRows.length === 0) {
+        const cjkPatterns = extractCjkLikePatterns(query);
+        if (cjkPatterns.length > 0) {
+          const likeConds = cjkPatterns.map(() => 'p.prompt_text LIKE ?');
+          const likeParams = cjkPatterns.map(p => `%${p}%`);
+          if (project) likeParams.push(project);
+          if (dateFrom) likeParams.push(dateFrom);
+          if (dateTo) likeParams.push(dateTo);
+          likeParams.push(effectiveSource ? limit : limit, effectiveSource ? offset : 0);
+          const fallbackRows = db.prepare(`
+            SELECT p.id, p.prompt_text, p.content_session_id, p.created_at, p.created_at_epoch
+            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>%'
+              ${project ? 'AND s.project = ?' : ''}
+              ${dateFrom ? 'AND p.created_at_epoch >= ?' : ''}
+              ${dateTo ? 'AND p.created_at_epoch <= ?' : ''}
+            ORDER BY p.created_at_epoch DESC
+            LIMIT ? OFFSET ?
+          `).all(...likeParams);
+          for (const r of fallbackRows) results.push({ ...r, _source: 'prompt', score: 0 });
+        }
+      }
     } catch { /* prompt FTS may not exist in older DBs */ }
   }
 
@@ -1980,6 +2007,39 @@ async function cmdEnrich(argv) {
   }
 }
 
+async function cmdOptimize(db, args) {
+  const run = args.includes('--run');
+  const runAll = args.includes('--run-all');
+  const taskIdx = args.indexOf('--task');
+  const tasks = taskIdx >= 0 && args[taskIdx + 1] ? [args[taskIdx + 1]] : undefined;
+  const maxIdx = args.indexOf('--max');
+  const maxItems = maxIdx >= 0 ? parseInt(args[maxIdx + 1], 10) || 15 : 15;
+
+  if (!run && !runAll) {
+    const preview = optimizePreview(db);
+    out('[mem] 🔍 LLM Optimization Preview:');
+    out(`  Re-enrich candidates: ${preview.reenrich}`);
+    out(`  Normalize: ${preview.normalizeGateOpen ? `${preview.normalize} unique concepts` : 'gate closed (7-day interval)'}`);
+    out(`  Cluster-merge: ${preview.clusterMerge} clusters`);
+    out(`  Smart-compress: ${preview.smartCompress} clusters`);
+    out(`  Total: ${preview.total} items`);
+    out('');
+    out('Run with --run to execute, --run-all to bypass gates.');
+    return;
+  }
+
+  out('[mem] Running LLM optimization...');
+  const results = await optimizeRun(db, { tasks, maxItems, force: runAll });
+
+  if (results.reenrich) out(`  Re-enrich: ${results.reenrich.processed || 0} processed, ${results.reenrich.skipped || 0} skipped`);
+  if (results.normalize) {
+    if (results.normalize.skipped) out(`  Normalize: skipped (${results.normalize.reason})`);
+    else out(`  Normalize: ${results.normalize.processed || 0} updated, ${results.normalize.groups || 0} synonym groups`);
+  }
+  if (results.clusterMerge) out(`  Cluster-merge: ${results.clusterMerge.merged || 0} merged of ${results.clusterMerge.processed || 0} clusters`);
+  if (results.smartCompress) out(`  Smart-compress: ${results.smartCompress.compressed || 0} compressed of ${results.smartCompress.processed || 0} clusters`);
+}
+
 // ─── Main Entry Point ────────────────────────────────────────────────────────
 
 export async function run(argv) {
@@ -2020,6 +2080,7 @@ export async function run(argv) {
       case 'export':    cmdExport(db, cmdArgs); break;
       case 'compress':  cmdCompress(db, cmdArgs); break;
       case 'maintain':  cmdMaintain(db, cmdArgs); break;
+      case 'optimize':  await cmdOptimize(db, cmdArgs); break;
       case 'fts-check': cmdFtsCheck(db, cmdArgs); break;
       case 'stats':     cmdStats(db, cmdArgs); break;
       case 'context':   cmdContext(db, cmdArgs); break;

package/nlp.mjs

@@ -108,6 +108,22 @@ export function extractCjkKeywords(text) {
   return found;
 }
 
+/**
+ * Extract CJK patterns suitable for SQL LIKE fallback when FTS5 fails on CJK text.
+ * Uses dictionary extraction + bigram fallback for unmatched portions.
+ * @param {string} query Raw query text
+ * @returns {string[]} CJK patterns (≥2 chars each), empty if no CJK content
+ */
+export function extractCjkLikePatterns(query) {
+  if (!query || !/[\u4e00-\u9fff\u3400-\u4dbf]{2,}/.test(query)) return [];
+  const keywords = extractCjkKeywords(query);
+  // Bigrams for unmatched CJK portions
+  let remainder = query;
+  for (const w of keywords) remainder = remainder.split(w).join(' ');
+  const bigrams = cjkBigrams(remainder).split(' ').filter(Boolean);
+  return [...new Set([...keywords, ...bigrams])];
+}
+
 // ─── FTS5 Token Formatting ──────────────────────────────────────────────────
 
 // Format a term for FTS5: quote if it contains spaces, hyphens, or special chars
@@ -166,6 +182,16 @@ export function sanitizeFtsQuery(query) {
       if (cjkWords.length > 0) {
         expandedTokens.push(...cjkWords);
         cjkExtracted = true;
+        // Preserve unmatched CJK portions as bigrams (don't silently drop them)
+        const matched = new Set(cjkWords);
+        let remainder = t;
+        for (const w of matched) remainder = remainder.split(w).join(' ');
+        const gapBigrams = cjkBigrams(remainder);
+        if (gapBigrams) {
+          for (const bg of gapBigrams.split(' ')) {
+            if (bg && !CJK_STOP_WORDS.has(bg) && !matched.has(bg)) expandedTokens.push(bg);
+          }
+        }
         continue;
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.28.2",
+  "version": "2.29.0",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "engines": {
@@ -64,10 +64,6 @@
     "skill.md",
     "commands/mem.md",
     "commands/memory.md",
-    "commands/search.md",
-    "commands/recall.md",
-    "commands/recent.md",
-    "commands/timeline.md",
     "commands/update.md",
     "commands/tools.md",
     "hooks/hooks.json",

package/project-utils.mjs

@@ -20,12 +20,25 @@ export function resolveProject(db, name) {
 
   // Short name: prefer the canonical "parent--name" form (from inferProject())
   // which typically has far more data than manually-saved short names.
+  // 1) Exact suffix match: "mem" → "projects--mem"
   const suffixed = db.prepare(
     'SELECT project FROM observations WHERE project LIKE ? GROUP BY project ORDER BY COUNT(*) DESC LIMIT 1'
   ).get(`%--${name}`);
   if (suffixed) { _cache.set(name, suffixed.project); return suffixed.project; }
 
-  // Fallback: synthesize canonical form from current directory
+  // 2) Prefix-in-suffix match: "code-graph" → "projects--code-graph-mcp"
+  const prefixed = db.prepare(
+    'SELECT project FROM observations WHERE project LIKE ? GROUP BY project ORDER BY COUNT(*) DESC LIMIT 1'
+  ).get(`%--${name}%`);
+  if (prefixed) { _cache.set(name, prefixed.project); return prefixed.project; }
+
+  // 3) Substring match: broader fallback for partial names
+  const substr = db.prepare(
+    'SELECT project FROM observations WHERE project LIKE ? GROUP BY project ORDER BY COUNT(*) DESC LIMIT 1'
+  ).get(`%${name}%`);
+  if (substr) { _cache.set(name, substr.project); return substr.project; }
+
+  // 4) Fallback: synthesize canonical form from current directory
   const inferred = inferProject();
   if (inferred.endsWith(`--${name}`)) { _cache.set(name, inferred); return inferred; }
 

package/schema.mjs

@@ -13,7 +13,7 @@ export const DB_PATH = join(DB_DIR, 'claude-mem-lite.db');
 export const REGISTRY_DB_PATH = join(DB_DIR, 'resource-registry.db');
 
 // Increment when schema changes (tables, columns, indexes, FTS, migrations)
-export const CURRENT_SCHEMA_VERSION = 20;
+export const CURRENT_SCHEMA_VERSION = 21;
 
 const CORE_SCHEMA = `
   CREATE TABLE IF NOT EXISTS sdk_sessions (
@@ -111,6 +111,7 @@ const MIGRATIONS = [
   'ALTER TABLE observations ADD COLUMN superseded_at INTEGER DEFAULT NULL',
   'ALTER TABLE observations ADD COLUMN superseded_by INTEGER DEFAULT NULL',
   'ALTER TABLE observations ADD COLUMN last_accessed_at INTEGER DEFAULT NULL',
+  'ALTER TABLE observations ADD COLUMN optimized_at INTEGER DEFAULT NULL',
 ];
 
 /**

package/scoring-sql.mjs

@@ -41,8 +41,9 @@ export const TYPE_DECAY_CASE = `(
 )`;
 
 /**
- * Type quality multiplier — demotes noisy types (bugfix error logs)
- * and promotes high-signal types (decisions, discoveries).
+ * Type quality multiplier — promotes high-signal types (decisions, discoveries).
+ * Bugfix raised from 0.35→0.75: lesson_learned bugfixes are valuable during
+ * active debugging; raw error logs are filtered by importance, not type penalty.
  * Applied as: BM25 × time_decay × TYPE_QUALITY × project_boost × importance
  */
 export const TYPE_QUALITY_CASE = `(
@@ -52,7 +53,7 @@ export const TYPE_QUALITY_CASE = `(
     WHEN 'feature'   THEN 1.2
     WHEN 'refactor'  THEN 1.0
     WHEN 'change'    THEN 0.8
-    WHEN 'bugfix'    THEN 0.35
+    WHEN 'bugfix'    THEN 0.75
     ELSE 1.0
   END
 )`;

package/scripts/pre-tool-recall.js

@@ -88,29 +88,44 @@ 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;

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/server.mjs

@@ -5,11 +5,13 @@
 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 { 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)',
@@ -453,6 +457,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 +557,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 +732,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 +835,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 +958,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 +993,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 +1033,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 +1522,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 +1952,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

package/synonyms.mjs

@@ -71,6 +71,43 @@ export const SYNONYM_PAIRS = [
   ['debug', 'troubleshoot'],
   ['error', 'failure'],
   ['migrate', 'migration'],
+  // ─── Concurrency & Async ───
+  ['promise', 'async'],
+  ['callback', 'handler'],
+  ['deadlock', 'race condition'],
+  ['mutex', 'lock'],
+  ['semaphore', 'lock'],
+  ['concurrent', 'parallel'],
+  ['thread', 'worker'],
+  ['await', 'async'],
+  // ─── Type System ───
+  ['interface', 'type'],
+  ['generic', 'generics'],
+  ['typedef', 'type'],
+  ['enum', 'enumeration'],
+  // ─── Testing ───
+  ['mock', 'stub'],
+  ['mock', 'fake'],
+  ['fixture', 'testdata'],
+  ['assert', 'assertion'],
+  ['jest', 'vitest'],
+  ['pytest', 'unittest'],
+  ['cypress', 'playwright'],
+  // ─── Networking ───
+  ['http', 'request'],
+  ['rest', 'api'],
+  ['grpc', 'rpc'],
+  ['timeout', 'deadline'],
+  ['retry', 'backoff'],
+  ['cors', 'cross origin'],
+  ['ssl', 'tls'],
+  ['throttle', 'rate limit'],
+  // ─── Build Tools ───
+  ['webpack', 'bundler'],
+  ['vite', 'bundler'],
+  ['rollup', 'bundler'],
+  ['esbuild', 'bundler'],
+  ['transpile', 'compile'],
   // ─── CJK ↔ EN cross-language synonyms ───
   // Authentication & Authorization
   ['认证', 'auth'], ['认证', 'authentication'], ['登录', 'login'], ['登录', 'auth'],
@@ -108,6 +145,16 @@ export const SYNONYM_PAIRS = [
   ['钩子', 'hook'], ['回调', 'callback'],
   ['异步', 'async'], ['同步', 'sync'],
   ['并发', 'concurrent'], ['线程', 'thread'],
+  ['竞态', 'race condition'], ['死锁', 'deadlock'], ['互斥', 'mutex'],
+  ['协程', 'coroutine'], ['事件循环', 'event loop'],
+  ['泛型', 'generic'], ['枚举', 'enum'],
+  ['断言', 'assert'], ['单元测试', 'unit test'], ['集成测试', 'integration test'],
+  ['模拟测试', 'mock'], ['测试覆盖', 'coverage'],
+  ['错误处理', 'error handling'], ['异常捕获', 'try catch'], ['堆栈跟踪', 'stack trace'],
+  ['容错', 'fault tolerance'],
+  ['跨域', 'cors'], ['限流', 'rate limit'], ['熔断', 'circuit breaker'],
+  ['负载均衡', 'load balancing'], ['心跳', 'heartbeat'],
+  ['请求', 'request'], ['失败', 'failure'], ['覆盖率', 'coverage'],
   // Performance
   ['性能', 'performance'], ['性能', 'perf'],
   ['内存', 'memory'], ['泄漏', 'leak'],
@@ -140,6 +187,23 @@ export const SYNONYM_PAIRS = [
   ['安装', 'install'], ['导入', 'import'],
   ['导出', 'export'], ['状态', 'state'],
   ['系统', 'system'], ['算法', 'algorithm'],
+  // Common dev terms (mined from real usage data)
+  ['文件', 'file'], ['代码', 'code'],
+  ['执行', 'execute'], ['执行', 'run'],
+  ['调用', 'call'], ['调用', 'invoke'],
+  ['运行', 'run'], ['运行', 'execute'],
+  ['检查', 'check'], ['检查', 'inspect'],
+  ['分析', 'analyze'], ['分析', 'analysis'],
+  ['项目', 'project'], ['流程', 'workflow'],
+  ['更新', 'update'], ['提示', 'prompt'],
+  ['查找', 'find'], ['记录', 'record'],
+  ['记录', 'log'], ['校验', 'validate'],
+  ['计算', 'compute'], ['计算', 'calculate'],
+  ['单元', 'unit'], ['资源', 'resource'],
+  ['问题', 'issue'], ['问题', 'problem'],
+  ['历史', 'history'], ['描述', 'description'],
+  ['推荐', 'recommend'], ['建议', 'suggestion'],
+  ['智能', 'smart'], ['智能', 'intelligent'],
 ];
 
 // ─── Bidirectional SYNONYM_MAP (case-insensitive) ──────────────────────────────
@@ -168,11 +232,25 @@ export const CJK_COMPOUNDS = new Set([
   '认证', '授权', '加密', '解密', '序列', '并发', '异步', '同步', '线程', '进程',
   '容器', '集群', '服务器', '中间件', '网关', '负载', '监控', '日志', '告警',
   '前端', '后端', '全栈', '响应式', '路由', '状态', '渲染', '样式', '布局',
+  '代码', '文件', '项目', '资源', '单元', '智能',
+  // concurrency & async (extended)
+  '竞态', '死锁', '互斥', '协程', '回调', '事件循环',
+  // type system
+  '泛型', '枚举', '联合类型', '类型推断', '类型守卫', '接口定义',
+  // testing (extended)
+  '单元测试', '集成测试', '端到端', '测试覆盖', '覆盖率', '模拟测试', '断言',
+  // error handling (extended)
+  '错误处理', '异常捕获', '堆栈跟踪', '错误码', '容错', '失败', '请求',
+  // networking
+  '跨域', '限流', '熔断', '负载均衡', '心跳',
   // actions
   '修复', '重构', '优化', '升级', '安装', '卸载', '导入', '导出', '上传', '下载',
   '提交', '推送', '合并', '发布', '上线', '回退', '审查', '审核', '评审',
+  '执行', '调用', '运行', '检查', '分析', '查找', '计算', '校验', '更新', '描述',
   // errors/issues
-  '报错', '崩溃', '泄露', '溢出', '死锁', '超时', '中断', '异常', '故障',
+  '报错', '崩溃', '泄露', '溢出', '超时', '中断', '异常', '故障',
+  // general (tokenization only — keeps CJK segmentation clean)
+  '问题', '使用', '继续', '推荐', '建议', '历史', '记录', '中文', '提示', '流程',
   // architecture
   '架构', '设计', '方案', '规划', '文档', '注释', '版本', '分支', '依赖',
   '性能', '安全', '漏洞', '补丁', '系统', '算法',

package/tool-schemas.mjs

@@ -74,6 +74,7 @@ export const memSaveSchema = {
   project: z.string().optional().describe('Project name (default: inferred from CWD)'),
   importance: coerceInt.pipe(z.number().int().min(1).max(3)).optional().describe('Importance level: 1=routine, 2=notable, 3=critical (default: 2 for explicit saves)'),
   files: z.array(z.string()).optional().describe('File paths associated with this observation'),
+  lesson_learned: z.string().max(500).optional().describe('Key lesson or takeaway (for bugfix: root cause & fix; for decision: rationale)'),
 };
 
 export const memStatsSchema = {
@@ -87,6 +88,15 @@ export const memCompressSchema = {
   project: z.string().optional().describe('Filter by project'),
 };
 
+export const memOptimizeSchema = {
+  action: z.enum(['preview', 'run', 'run_all']).optional().default('preview')
+    .describe('preview=scan candidates, run=execute with limits, run_all=bypass gates'),
+  tasks: z.array(z.enum(['re-enrich', 'normalize', 'cluster-merge', 'smart-compress'])).optional()
+    .describe('Which optimization tasks to run (default: all)'),
+  max_items: coerceInt.pipe(z.number().int().min(1).max(100)).optional().default(15)
+    .describe('Maximum LLM calls across all tasks (default: 15)'),
+};
+
 export const memMaintainSchema = {
   action: z.enum(['scan', 'execute']).describe('scan=analyze candidates, execute=apply changes'),
   operations: z.array(z.enum(['dedup', 'decay', 'cleanup', 'boost', 'purge_stale', 'rebuild_vectors'])).optional()

package/utils.mjs

@@ -9,7 +9,7 @@ import { execSync } from 'child_process';
 // Backward compatibility: all consumers import from utils.mjs
 
 export { DECAY_HALF_LIFE_BY_TYPE, DEFAULT_DECAY_HALF_LIFE_MS, OBS_BM25, SESS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, OBS_FTS_COLUMNS } from './scoring-sql.mjs';
-export { cjkBigrams, extractCjkSynonymTokens, extractCjkKeywords, SYNONYM_MAP, expandToken, sanitizeFtsQuery, relaxFtsQueryToOr, FTS_STOP_WORDS, CJK_COMPOUNDS } from './nlp.mjs';
+export { cjkBigrams, extractCjkSynonymTokens, extractCjkKeywords, extractCjkLikePatterns, SYNONYM_MAP, expandToken, sanitizeFtsQuery, relaxFtsQueryToOr, FTS_STOP_WORDS, CJK_COMPOUNDS } from './nlp.mjs';
 export { resolveProject, _resetProjectCache } from './project-utils.mjs';
 export { scrubSecrets, SECRET_PATTERNS } from './secret-scrub.mjs';
 export { truncate, typeIcon, fmtDate, fmtTime, isoWeekKey } from './format-utils.mjs';

package/commands/recall.md

@@ -1,9 +0,0 @@
----
-description: "Recall past observations for a file before editing. Use when: about to edit a file, investigating a file with past issues, or before refactoring to check for past lessons"
-argument-hint: <file_path>
----
-
-## File Memory
-!`claude-mem-lite recall $ARGUMENTS 2>/dev/null || echo "No history found"`
-
-Consider these past observations before making changes.

package/commands/recent.md

@@ -1,7 +0,0 @@
----
-description: "Show recent memory observations. Use when: checking what happened recently, reviewing session progress, or verifying recent changes were captured"
-argument-hint: [count]
----
-
-## Recent Observations
-!`claude-mem-lite recent $ARGUMENTS 2>/dev/null || echo "No observations"`

package/commands/search.md

@@ -1,9 +0,0 @@
----
-description: "Search memory for past bugfixes, decisions, discoveries. Use when: encountering a familiar error, investigating a module before changes, or looking for prior solutions to a similar problem"
-argument-hint: <query>
----
-
-## Memory Search
-!`claude-mem-lite search $ARGUMENTS 2>/dev/null || echo "No results found"`
-
-Use `claude-mem-lite get <id>` via Bash for full details on any result.

package/commands/timeline.md

@@ -1,7 +0,0 @@
----
-description: "Browse memory timeline around an observation. Use when: exploring what happened before/after a specific event, understanding the sequence of changes that led to a bug, or reviewing chronological context"
-argument-hint: <observation_id>
----
-
-## Timeline
-!`claude-mem-lite timeline --anchor $ARGUMENTS 2>/dev/null || echo "Not found"`