claude-mem-lite 2.0.4 → 2.0.12

package/.mcp.json

@@ -1,9 +1,3 @@
 {
-  "mcpServers": {
-    "mem": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["./server.mjs"]
-    }
-  }
-}
+  "mcpServers": {}
+}

package/dispatch-feedback.mjs

@@ -162,6 +162,9 @@ export async function collectFeedback(db, sessionId, sessionEvents = []) {
     const outcome = detectOutcome(sessionEvents);
 
     for (const inv of invocations) {
+      // Skip if already collected (prevents double-collection from stop + session-start)
+      if (inv.outcome) continue;
+
       const adopted = detectAdoption(inv, sessionEvents);
       const score = adopted ? (outcome === 'success' ? 1.0 : outcome === 'partial' ? 0.5 : 0.2) : 0;
 

package/dispatch-inject.mjs

@@ -33,9 +33,21 @@ function isNativeSkill(name) {
 
 // ─── Injection Templates ─────────────────────────────────────────────────────
 
+/**
+ * Invocable skill template -- tells Claude to invoke via Skill tool.
+ * Used when the resource has an invocation_name (registered as a Claude Code skill/plugin).
+ * @param {object} resource Resource object from DB
+ * @returns {string} Injection text instructing Skill tool invocation
+ */
+function injectSkillInvocable(resource) {
+  return `[Auto-suggestion] A relevant skill is available for this task. ` +
+    `Invoke it now: use the Skill tool with skill="${resource.invocation_name}". ` +
+    `Capability: ${truncate(resource.capability_summary, 100)}`;
+}
+
 /**
  * Native skill template -- tells Claude to use the skill command.
- * Used when skill exists in ~/.claude/skills/.
+ * Used when skill exists in ~/.claude/skills/ but has no invocation_name.
  * @param {object} resource Resource object from DB
  * @returns {string} Injection text referencing the native skill command
  */
@@ -129,7 +141,11 @@ export function renderInjection(resource) {
   let injection;
 
   if (resource.type === 'skill') {
-    if (isNativeSkill(resource.name)) {
+    // Priority: if invocation_name is set, the skill is a registered Claude Code skill/plugin
+    // → instruct Claude to invoke via Skill tool (enables adoption tracking)
+    if (resource.invocation_name) {
+      injection = injectSkillInvocable(resource);
+    } else if (isNativeSkill(resource.name)) {
       injection = injectSkillNative(resource);
     } else {
       injection = injectSkillManaged(resource);

package/dispatch.mjs

@@ -25,7 +25,8 @@ const READ_ONLY_TOOLS = new Set([
   'AskUserQuestion', 'EnterPlanMode', 'ExitPlanMode',
 ]);
 
-export const COOLDOWN_MINUTES = 5;
+export const COOLDOWN_MINUTES = 60;
+export const SESSION_RECOMMEND_CAP = 3;
 
 // ─── Haiku Circuit Breaker ──────────────────────────────────────────────────
 // Prevents cascading latency when Haiku API is down or slow.
@@ -116,6 +117,16 @@ export function detectProjectDomains() {
     ['pubspec.yaml', ['dart', 'flutter']],
     ['Podfile', ['ios', 'swift']],
     ['CMakeLists.txt', ['cpp']],
+    // Web/browser context — enables domain filtering for browser-specific resources
+    ['next.config.js', ['web', 'browser', 'react']],
+    ['next.config.mjs', ['web', 'browser', 'react']],
+    ['next.config.ts', ['web', 'browser', 'react']],
+    ['nuxt.config.ts', ['web', 'browser', 'vue']],
+    ['angular.json', ['web', 'browser', 'angular']],
+    ['.browserslistrc', ['web', 'browser']],
+    ['vite.config.ts', ['web', 'browser', 'frontend']],
+    ['vite.config.js', ['web', 'browser', 'frontend']],
+    ['webpack.config.js', ['web', 'browser', 'frontend']],
   ];
   for (const [file, tags] of checks) {
     if (existsSync(join(dir, file))) tags.forEach(t => techs.add(t));
@@ -187,6 +198,7 @@ export function extractContextSignals(event, sessionCtx = {}) {
   const signals = {
     intent: '',          // comma-separated intent tags, primary first
     primaryIntent: '',   // first/strongest intent (for column-targeted queries)
+    suppressedIntents: [], // intents detected but actively suppressed (e.g. test-run)
     techStack: '',
     action: '',
     errorDomain: '',
@@ -194,7 +206,9 @@ export function extractContextSignals(event, sessionCtx = {}) {
 
   // Extract weighted intent from user prompt (primary intent is first element)
   if (sessionCtx.userPrompt) {
-    signals.intent = extractIntent(sessionCtx.userPrompt);
+    const { intent, suppressed } = extractIntent(sessionCtx.userPrompt);
+    signals.intent = intent;
+    signals.suppressedIntents = suppressed;
     signals.primaryIntent = signals.intent.split(',')[0] || '';
   }
 
@@ -234,6 +248,12 @@ export function extractContextSignals(event, sessionCtx = {}) {
 const NEGATION_EN = /\b(?:don'?t|do\s+not|no\s+need\s+to|skip|without|avoid|not|never|stop|cancel|ignore|hold\s+off)\s+/i;
 const NEGATION_CJK = /(?:不要|别|不用|先别|暂时不|不需要|跳过|停止|取消|算了|不做|不搞)/;
 
+// Test-run vs test-write disambiguation (module-scoped for performance)
+const _RUN_TEST = /\b(run\w*\s+(?:the\s+)?tests?|npm\s+test|npx\s+(?:vitest|jest|mocha|pytest)|yarn\s+test|pnpm\s+test|make\s+test|cargo\s+test|go\s+test|check\s+(?:if\s+)?tests?\s+pass|execute\s+(?:the\s+)?tests?)\b/i;
+const _RUN_TEST_CJK = /(?:运行测试|跑测试|跑一下测试|跑单测|执行测试|测试跑|看测试)/;
+const _WRITE_TEST = /\b(write\s+tests?|add\s+tests?|create\s+tests?|need\s+tests?|missing\s+tests?|tdd|test.?driven|red.?green|increase\s+coverage|improve\s+coverage)\b/i;
+const _WRITE_TEST_CJK = /(?:写测试|加测试|补测试|补单测|缺测试|测试覆盖)/;
+
 /**
  * Extract weighted intent keywords from user prompt.
  * Returns primary (first match, strongest signal) and secondary intents.
@@ -247,41 +267,48 @@ function extractIntent(prompt) {
   // English patterns — use trailing-optional boundaries for verb conjugations:
   //   \b prefix ensures word start, but many suffixed forms (debugging, refactoring, deployed)
   //   fail with trailing \b. Use \b...\w* for words that commonly have suffixes.
+  // Pattern ordering determines PRIMARY intent (first match).
+  // Priority: action verbs → domain-specific → quality/style → generic/overloaded.
+  // This ensures "review code before push" → review (not commit),
+  // "design database schema" → db (not design), "I have a spec" → plan (not test).
   const intentPatterns = [
-    [/\b(tests?|testing|tested|tdd|spec|coverage|jest|vitest|pytest|mocha|cypress)\b/i, 'test'],
+    // ── Action verbs (what the user wants to DO) ──
+    [/\b(tests?|testing|tested|tdd|coverage|jest|vitest|pytest|mocha|cypress)\b/i, 'test'],
     [/\b(debug\w*|fix\w*|bugs?|errors?|troubleshoot\w*|broken|crash\w*|issue|problem|fail\w*|not working|doesn'?t work)\b/i, 'fix'],
+    [/\b(reviews?|reviewing|reviewed|reviewer|code review|audit\w*|inspect\w*|look over|check over)\b/i, 'review'],
     [/\b(commits?|committing|committed|push\w*|pr|pull request|merg\w*|rebas\w*|cherry.?pick|stash|tag)\b/i, 'commit'],
     [/\b(deploy\w*|release\w*|publish\w*|ship\w*|rollout|staging|production)\b/i, 'deploy'],
-    [/\b(reviews?|reviewing|reviewed|reviewer|code review|audit\w*|inspect\w*|look over|check over)\b/i, 'review'],
+    [/\b(plan\w*|architect\w*|rfc|proposal|roadmap|blueprint|spec)\b/i, 'plan'],
     [/\b(refactor\w*|clean\w*|simplif\w*|tidy|organiz\w*|restructur\w*|rewrit\w*|messy|ugly|smell|technical.?debt)\b/i, 'clean'],
-    [/\b(perf|performance|optimiz\w*|fast\w*|slow\w*|speed\w*|latency|bottleneck|laggy)\b/i, 'fast'],
-    [/\b(secur\w*|vulnerabilit\w*|xss|csrf|injection|encrypt\w*|ssl|tls|cors|oauth|jwt|cve|insecure|unsafe)\b/i, 'secure'],
-    [/\b(lint\w*|format\w*|style|prettier|eslint|biome|stylelint)\b/i, 'lint'],
-    [/\b(design\w*|ui|ux|frontend|css|tailwind|responsive|layout|theme|component)\b/i, 'design'],
-    [/\b(build\w*|compil\w*|bundl\w*|transpil\w*|esbuild|vite|rollup|webpack|parcel|babel|swc)\b/i, 'build'],
     [/\b(docs?|documentation|readme|changelog|wiki|guide|tutorial|jsdoc|typedoc)\b/i, 'doc'],
-    [/\b(infra\w*|docker\w*|k8s|kubernetes|terraform|ansible|helm|aws|gcp|azure|cloud|nginx|ci\b|cd\b|pipeline)\b/i, 'infra'],
+    // ── Domain-specific (what area the work is in) ──
     [/\b(db|database|sql|migrat\w*|schema|orm|prisma|redis|mongo\w*|postgres\w*|mysql|sqlite)\b/i, 'db'],
     [/\b(api|endpoints?|routes?|rest|graphql|grpc|websocket|middleware|swagger|openapi)\b/i, 'api'],
-    [/\b(plan\w*|architect\w*|rfc|proposal|roadmap|blueprint|spec\b)\b/i, 'plan'],
-    // Chinese patterns — \b doesn't work with CJK characters, so match without boundaries.
-    // Use 2+ char compounds to avoid false positives from polysemous single chars.
+    [/\b(secur\w*|vulnerabilit\w*|xss|csrf|injection|encrypt\w*|ssl|tls|cors|oauth|jwt|cve|insecure|unsafe)\b/i, 'secure'],
+    [/\b(infra\w*|docker\w*|k8s|kubernetes|terraform|ansible|helm|aws|gcp|azure|cloud|nginx|ci\b|cd\b|pipeline)\b/i, 'infra'],
+    [/\b(build\w*|compil\w*|bundl\w*|transpil\w*|esbuild|vite|rollup|webpack|parcel|babel|swc)\b/i, 'build'],
+    // ── Quality / style ──
+    [/\b(perf|performance|optimiz\w*|fast\w*|slow\w*|speed\w*|latency|bottleneck|laggy)\b/i, 'fast'],
+    [/\b(lint\w*|format\w*|style|prettier|eslint|biome|stylelint)\b/i, 'lint'],
+    // ── Generic / overloaded (easily confused with domain terms) ──
+    [/\b(ui|ux|frontend|css|tailwind|responsive|layout|theme|component)\b/i, 'design'],
+    // ── Chinese patterns ──
     [/(测试|写测试|单测|单元测试|用例|覆盖率)/, 'test'],
     [/(修复|修bug|改bug|找bug|有bug|调试|排错|报错|出错|有问题|不工作|跑不起来|不能用|挂了|崩溃)/, 'fix'],
+    [/(审查|审核|代码审查|评审|代码审核|看看代码|review)/, 'review'],
     [/(提交|推送|上传)/, 'commit'],
     [/(部署|上线|发布|回滚)/, 'deploy'],
-    [/(审查|审核|代码审查|评审|代码审核|看看代码|review)/, 'review'],
+    [/(规划|架构|方案|设计方案)/, 'plan'],
     [/(重构|清理|整理|简化|太烂|乱七八糟|看不懂)/, 'clean'],
-    [/(优化|性能|卡顿|耗时|太慢|慢死了|好慢|缓存)/, 'fast'],
-    [/(安全|漏洞|鉴权|认证|授权|权限|泄露|暴露|不安全)/, 'secure'],
-    [/(格式化|代码风格|代码规范|类型检查)/, 'lint'],
-    [/(界面|前端|样式|页面|组件|布局)/, 'design'],
-    [/(构建|编译|打包|依赖)/, 'build'],
     [/(写文档|文档化|文档|注释)/, 'doc'],
-    [/(容器|服务器|运维|集群|监控|配置|日志)/, 'infra'],
     [/(数据库|建表|索引|迁移|查询慢)/, 'db'],
     [/(接口|路由)/, 'api'],
-    [/(规划|架构|方案|设计方案)/, 'plan'],
+    [/(安全|漏洞|鉴权|认证|授权|权限|泄露|暴露|不安全)/, 'secure'],
+    [/(容器|服务器|运维|集群|监控|配置|日志)/, 'infra'],
+    [/(构建|编译|打包|依赖)/, 'build'],
+    [/(优化|性能|卡顿|耗时|太慢|慢死了|好慢|缓存)/, 'fast'],
+    [/(格式化|代码风格|代码规范|类型检查)/, 'lint'],
+    [/(界面|前端|样式|页面|组件|布局)/, 'design'],
   ];
 
   // Build per-tag negation/affirmation tracking.
@@ -319,7 +346,20 @@ function extractIntent(prompt) {
       found.push(tag);
     }
   }
-  return found.join(',');
+
+  // Distinguish test-running from test-writing: "run tests" / "npm test" / "运行测试" should NOT
+  // trigger TDD recommendations. Only keep 'test' intent when the prompt implies *writing* tests.
+  const suppressed = [];
+  if (found.includes('test')) {
+    const isRunning = _RUN_TEST.test(prompt) || _RUN_TEST_CJK.test(prompt);
+    const isWriting = _WRITE_TEST.test(prompt) || _WRITE_TEST_CJK.test(prompt);
+    if (isRunning && !isWriting) {
+      found.splice(found.indexOf('test'), 1);
+      suppressed.push('test');
+    }
+  }
+
+  return { intent: found.join(','), suppressed };
 }
 
 /** Exported for testing. */
@@ -538,13 +578,21 @@ JSON: {"query":"search keywords for finding the right skill or agent","type":"sk
 // ─── Cooldown & Dedup (DB-persisted, survives process restarts) ─────────────
 
 export function isRecentlyRecommended(db, resourceId, sessionId) {
-  // Check 1: Already recommended in this session (session dedup)
+  // Check 1: Per-session recommendation cap (avoid overwhelming user with suggestions)
+  if (sessionId) {
+    const sessionCount = db.prepare(
+      'SELECT COUNT(*) as cnt FROM invocations WHERE session_id = ? AND recommended = 1'
+    ).get(sessionId);
+    if (sessionCount.cnt >= SESSION_RECOMMEND_CAP) return true;
+  }
+
+  // Check 2: Already recommended in this session (session dedup)
   const sessionHit = db.prepare(
     'SELECT 1 FROM invocations WHERE resource_id = ? AND session_id = ? LIMIT 1'
   ).get(resourceId, sessionId);
   if (sessionHit) return true;
 
-  // Check 2: Recommended within cooldown window (cross-session cooldown)
+  // Check 3: Recommended within cooldown window (cross-session cooldown)
   const cooldownHit = db.prepare(
     `SELECT 1 FROM invocations WHERE resource_id = ? AND created_at > datetime('now', ?) LIMIT 1`
   ).get(resourceId, `-${COOLDOWN_MINUTES} minutes`);
@@ -577,6 +625,13 @@ export async function dispatchOnSessionStart(db, userPrompt, sessionId) {
       const textQuery = buildQueryFromText(userPrompt);
       if (!textQuery) return null;
       results = retrieveResources(db, textQuery, { limit: 3, projectDomains });
+      // Filter out resources matching suppressed intents (e.g. TDD for test-running prompts)
+      if (signals.suppressedIntents.length > 0) {
+        results = results.filter(r => {
+          const tags = (r.intent_tags || '').toLowerCase().split(/[\s,]+/);
+          return !signals.suppressedIntents.some(s => tags.includes(s));
+        });
+      }
     }
 
     let tier = 2;
@@ -651,6 +706,12 @@ export async function dispatchOnUserPrompt(db, userPrompt, sessionId) {
       const textQuery = buildQueryFromText(userPrompt);
       if (!textQuery) return null;
       results = retrieveResources(db, textQuery, { limit: 3, projectDomains });
+      if (signals.suppressedIntents.length > 0) {
+        results = results.filter(r => {
+          const tags = (r.intent_tags || '').toLowerCase().split(/[\s,]+/);
+          return !signals.suppressedIntents.some(s => tags.includes(s));
+        });
+      }
     }
 
     if (results.length === 0) return null;

package/hook-llm.mjs

@@ -156,6 +156,27 @@ function linkRelatedObservations(db, savedId, obs, episode) {
   }
 }
 
+// ─── Degraded Title Builder ──────────────────────────────────────────────────
+// When LLM is unavailable, build a readable title from episode metadata
+// instead of using raw makeEntryDesc output (which contains JSON stdout).
+
+function buildDegradedTitle(episode) {
+  const files = (episode.files || []).filter(Boolean);
+  const hasError = episode.entries.some(e => e.isError);
+  const hasEdit = episode.entries.some(e => ['Edit', 'Write', 'NotebookEdit'].includes(e.tool));
+
+  if (files.length > 0) {
+    const names = files.map(f => basename(f)).slice(0, 3).join(', ');
+    const suffix = files.length > 3 ? ` +${files.length - 3} more` : '';
+    if (hasError) return `Error while working on ${names}${suffix}`;
+    if (hasEdit) return `Modified ${names}${suffix}`;
+    return `Worked on ${names}${suffix}`;
+  }
+  // No files: strip raw JSON output from Bash descriptions
+  const desc = episode.entries[0]?.desc || '(no description)';
+  return desc.replace(/ → (?:ERROR: )?\{.*$/, hasError ? ' (error)' : '');
+}
+
 // ─── Background: LLM Episode Extraction (Tier 2 F) ──────────────────────────
 
 export async function handleLLMEpisode() {
@@ -252,10 +273,9 @@ importance: 1=routine, 2=notable (error fix, arch decision, config change), 3=cr
     const hasError = episode.entries.some(e => e.isError);
     const hasEdit = episode.entries.some(e => ['Edit', 'Write', 'NotebookEdit'].includes(e.tool));
     const inferredType = hasError ? 'bugfix' : hasEdit ? 'change' : 'discovery';
-    const firstDesc = episode.entries[0]?.desc || '(no description)';
     obs = {
       type: inferredType,
-      title: truncate(firstDesc, 120),
+      title: truncate(buildDegradedTitle(episode), 120),
       subtitle: fileList,
       narrative: episode.entries.map(e => e.desc).join('; '),
       concepts: [],

package/hook.mjs

@@ -582,6 +582,35 @@ async function handleSessionStart() {
       summaryLines.push('');
     }
 
+    // Key context: top high-importance observations for CLAUDE.md persistence
+    const keyObs = db.prepare(`
+      SELECT id, type, title FROM observations
+      WHERE project = ? AND COALESCE(compressed_into, 0) = 0
+        AND COALESCE(importance, 1) >= 2
+      ORDER BY created_at_epoch DESC LIMIT 5
+    `).all(project);
+    if (keyObs.length > 0) {
+      summaryLines.push('### Key Context');
+      for (const o of keyObs) {
+        // Strip raw JSON output from degraded Bash-style titles
+        const clean = (o.title || '(untitled)')
+          .replace(/ → (?:ERROR: )?\{".*$/, '')
+          .replace(/ → (?:ERROR: )?\{[^}]*\.{3}$/, '');
+        summaryLines.push(`- [${o.type || 'discovery'}] ${truncate(clean, 80)} (#${o.id})`);
+      }
+      summaryLines.push('');
+    } else if (!latestSummary) {
+      // Fallback: no summary AND no key observations — show recent activity
+      const recentObs = (observations.length >= 3 ? observations : fallbackObs).slice(0, 3);
+      if (recentObs.length > 0) {
+        summaryLines.push('### Recent Activity');
+        for (const o of recentObs) {
+          summaryLines.push(`- ${truncate(o.title || '(untitled)', 80)}`);
+        }
+        summaryLines.push('');
+      }
+    }
+
     // Build observations table (stdout only — not persisted to CLAUDE.md)
     const obsLines = [];
     const obsToShow = observations.length >= 3 ? observations : fallbackObs;

package/install.mjs

@@ -511,8 +511,8 @@ const RESOURCE_METADATA = {
     trigger_patterns: 'when user needs XML sitemap generation optimization or crawl management',
   },
   'skill:seo-technical': {
-    intent_tags: 'seo,technical,performance,core-web-vitals,speed,crawl,indexing',
-    domain_tags: 'seo,technical,performance',
+    intent_tags: 'seo,technical,core-web-vitals,crawl,indexing',
+    domain_tags: 'seo,technical',
     capability_summary: 'Technical SEO audit covering core web vitals site speed crawlability and indexing',
     trigger_patterns: 'when user needs technical SEO improvements core web vitals or site speed optimization',
   },
@@ -997,8 +997,8 @@ const RESOURCE_METADATA = {
     trigger_patterns: 'when user needs SEO-optimized content creation keyword articles or blog writing',
   },
   'agent:seo-technical-optimization': {
-    intent_tags: 'seo,technical,optimization,speed,crawl,indexing,performance',
-    domain_tags: 'seo,technical,optimization',
+    intent_tags: 'seo,technical,optimization,crawl,indexing',
+    domain_tags: 'seo,technical',
     capability_summary: 'Technical SEO optimization agent for site speed crawl efficiency and indexing',
     trigger_patterns: 'when user needs technical SEO optimization site speed or crawl improvements',
   },
@@ -1290,6 +1290,8 @@ async function install() {
     // Remove existing first (ignore errors)
     try { execFileSync('claude', ['mcp', 'remove', '-s', 'user', 'mem'], { stdio: 'pipe' }); } catch {}
     execFileSync('claude', ['mcp', 'add', '-s', 'user', '-t', 'stdio', 'mem', '--', 'node', SERVER_PATH], { stdio: 'pipe' });
+    // Remove project-level registration that shadows global (from .mcp.json)
+    try { execFileSync('claude', ['mcp', 'remove', '-s', 'project', 'mem'], { stdio: 'pipe' }); } catch {}
     ok('MCP server registered: mem');
   } catch (e) {
     fail('MCP registration failed: ' + e.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.0.4",
+  "version": "2.0.12",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "engines": {

package/registry-retriever.mjs

@@ -260,6 +260,7 @@ const TECHNOLOGY_TAGS = new Set([
   'cpp', 'c', 'csharp', 'dotnet', 'aspnet',
   'elixir', 'erlang', 'lua', 'zig', 'solidity',
   'html', 'css', 'frontend', 'backend',
+  'browser', 'web', 'playwright',
 ]);
 
 /**

package/server.mjs

@@ -4,7 +4,7 @@
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { jaccardSimilarity, truncate, typeIcon, sanitizeFtsQuery, inferProject, computeMinHash, scrubSecrets, fmtDate, isoWeekKey, debugLog, debugCatch } from './utils.mjs';
+import { jaccardSimilarity, truncate, typeIcon, sanitizeFtsQuery, relaxFtsQueryToOr, inferProject, computeMinHash, scrubSecrets, fmtDate, isoWeekKey, debugLog, debugCatch } from './utils.mjs';
 import { ensureDb, DB_PATH } from './schema.mjs';
 import { reRankWithContext, markSuperseded, extractPRFTerms, expandQueryByConcepts } from './server-internals.mjs';
 import { memSearchSchema, memTimelineSchema, memGetSchema, memDeleteSchema, memSaveSchema, memStatsSchema, memCompressSchema } from './tool-schemas.mjs';
@@ -64,13 +64,21 @@ const server = new McpServer(
   { name: 'claude-mem-lite', version: '2.0.0' },
   {
     instructions: [
-      'Proactively use mem_search when:',
-      '- Errors occur: search for related past fixes (obs_type="bugfix")',
-      '- Before significant file changes: search for file history',
-      '- Architecture decisions: check past decisions (obs_type="decision")',
-      '- Stuck/blocked: search for similar past work',
+      'Proactively search memory to leverage past experience. This is your long-term memory across sessions.',
       '',
-      'Workflow: mem_search → mem_timeline(anchor=ID) → mem_get(ids=[...]) for full context.',
+      'WHEN TO SEARCH (mem_search):',
+      '- Error/bug encountered → mem_search(query="<error keyword>", obs_type="bugfix")',
+      '- Before modifying important files → mem_search(query="<filename>")',
+      '- Architecture/design decisions → mem_search(query="<topic>", obs_type="decision")',
+      '- Stuck or blocked → mem_search(query="<problem description>")',
+      '- Starting work on a feature → mem_search(query="<feature name>")',
+      '',
+      'WHEN TO SAVE (mem_save):',
+      '- Non-obvious debugging discovery → mem_save with type="bugfix"',
+      '- Key architecture decision → mem_save with type="decision"',
+      '- Important pattern or convention found → mem_save with type="discovery"',
+      '',
+      'WORKFLOW: mem_search → mem_timeline(anchor=ID) → mem_get(ids=[...]) for full context.',
     ].join('\n'),
   },
 );
@@ -129,6 +137,50 @@ function searchObservations(ctx) {
       results.push({ source: 'obs', id: r.id, type: r.type, title: r.title, subtitle: r.subtitle, project: r.project, date: r.created_at, score: r.score, files_modified: r.files_modified, importance: r.importance, snippet: r.match_snippet || '' });
     }
 
+    // OR fallback: when AND query returns 0 results, retry with OR semantics
+    if (rows.length === 0) {
+      const orQuery = relaxFtsQueryToOr(ftsQuery);
+      if (orQuery) {
+        try {
+          const orRows = db.prepare(`
+            SELECT o.id, o.type, o.title, o.subtitle, o.project, o.created_at, o.importance,
+                   o.files_modified,
+                   snippet(observations_fts, 2, '»', '«', '…', 10) as match_snippet,
+                   ${OBS_BM25}
+                     * (1.0 + EXP(-0.693 * (? - o.created_at_epoch) / ${RECENCY_HALF_LIFE_MS}.0))
+                     * (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)))
+                     * 0.8 as score
+            FROM observations_fts
+            JOIN observations o ON observations_fts.rowid = o.id
+            WHERE observations_fts MATCH ?
+              AND COALESCE(o.compressed_into, 0) = 0
+              AND (? IS NULL OR o.project = ?)
+              AND (? IS NULL OR o.type = ?)
+              AND (? IS NULL OR o.created_at_epoch >= ?)
+              AND (? IS NULL OR o.created_at_epoch <= ?)
+              AND (? IS NULL OR COALESCE(o.importance, 1) >= ?)
+            ORDER BY score
+            LIMIT ? OFFSET ?
+          `).all(
+            now,
+            projectBoost, projectBoost,
+            orQuery,
+            args.project ?? null, args.project ?? null,
+            args.obs_type ?? null, args.obs_type ?? null,
+            epochFrom, epochFrom,
+            epochTo, epochTo,
+            args.importance ?? null, args.importance ?? null,
+            perSourceLimit, perSourceOffset
+          );
+          for (const r of orRows) {
+            results.push({ source: 'obs', id: r.id, type: r.type, title: r.title, subtitle: r.subtitle, project: r.project, date: r.created_at, score: r.score, files_modified: r.files_modified, importance: r.importance, snippet: r.match_snippet || '' });
+          }
+        } catch (e) { debugCatch(e, 'searchObservations-or-fallback'); }
+      }
+    }
+
     // Two-phase query expansion for sparse results
     if (rows.length > 0 && results.length < limit) {
       const existingIds = new Set(results.map(r => r.id));

package/utils.mjs

@@ -238,6 +238,15 @@ const SYNONYM_PAIRS = [
   ['api', 'endpoint'],
   ['api', 'route'],
   ['cache', 'caching'],
+  ['cache', 'memoize'],
+  ['optimize', 'optimization'],
+  ['optimize', 'performance'],
+  ['speed', 'performance'],
+  ['fix', 'bugfix'],
+  ['fix', 'patch'],
+  ['debug', 'debugging'],
+  ['debug', 'troubleshoot'],
+  ['error', 'failure'],
   ['migrate', 'migration'],
 ];
 // Build bidirectional lookup (case-insensitive)
@@ -289,6 +298,26 @@ export function sanitizeFtsQuery(query) {
   return expanded.join(hasGroup ? ' AND ' : ' ');
 }
 
+/**
+ * Relax an AND-joined FTS5 query to OR-joined for fallback search.
+ * Only useful when the original query has multiple tokens (single-token queries
+ * are already as relaxed as possible).
+ * @param {string} ftsQuery Original AND-joined FTS5 query from sanitizeFtsQuery
+ * @returns {string|null} OR-joined query, or null if relaxation wouldn't help
+ */
+export function relaxFtsQueryToOr(ftsQuery) {
+  if (!ftsQuery) return null;
+  // Replace AND joins with OR — handles both explicit " AND " and implicit space joins
+  const orQuery = ftsQuery.replace(/ AND /g, ' OR ');
+  // If no AND was present, tokens are space-joined (implicit AND); convert to OR
+  if (orQuery === ftsQuery && !ftsQuery.includes(' OR ')) {
+    const parts = ftsQuery.split(/\s+/);
+    if (parts.length < 2) return null; // single token — OR won't help
+    return parts.join(' OR ');
+  }
+  return orQuery !== ftsQuery ? orQuery : null;
+}
+
 // ─── Importance ──────────────────────────────────────────────────────────────
 
 /**