claude-mem-lite 2.28.2 → 2.30.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.28.2",
+      "version": "2.30.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.30.0",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const CLI_COMMANDS = new Set(['search', 'recent', 'recall', 'get', 'timeline', 'save', 'stats', 'context', 'browse', 'delete', 'update', 'export', 'compress', 'maintain', 'fts-check', 'registry', 'import', 'enrich', 'help']);
+const CLI_COMMANDS = new Set(['search', 'recent', 'recall', 'get', 'timeline', 'save', 'stats', 'context', 'browse', 'delete', 'update', 'export', 'compress', 'maintain', 'optimize', 'fts-check', 'registry', 'import', 'enrich', 'help']);
 const INSTALL_COMMANDS = new Set(['install', 'uninstall', 'status', 'doctor', 'cleanup', 'cleanup-hooks', 'self-update', 'release']);
 
 const cmd = process.argv[2];

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-context.mjs

@@ -1,9 +1,15 @@
 // claude-mem-lite CLAUDE.md context injection and token budgeting
-// Handles adaptive time windows, token-budgeted selection, and CLAUDE.md persistence
+// Handles adaptive time windows, token-budgeted selection, and legacy CLAUDE.md cleanup.
 
-import { join } from 'path';
+import { basename, join } from 'path';
 import { readFileSync, writeFileSync, renameSync, unlinkSync } from 'fs';
-import { estimateTokens, truncate, debugLog, debugCatch, DECAY_HALF_LIFE_BY_TYPE, DEFAULT_DECAY_HALF_LIFE_MS } from './utils.mjs';
+import {
+  estimateTokens, truncate, typeIcon, fmtTime,
+  debugLog, debugCatch,
+  DECAY_HALF_LIFE_BY_TYPE, DEFAULT_DECAY_HALF_LIFE_MS, notLowSignalTitleClause,
+} from './utils.mjs';
+import { STALE_SESSION_MS, FALLBACK_OBS_WINDOW_MS } from './hook-shared.mjs';
+import { extractUnfinishedSummary } from './hook-handoff.mjs';
 
 /**
  * Infer the project directory from environment variables or cwd.
@@ -56,11 +62,15 @@ export function selectWithTokenBudget(db, project, budget = 2000) {
   const tier2Ago = now_ms - windows.tier2;
   const tier3Ago = now_ms - windows.tier3;
 
-  // Candidate pool: tiered time windows by importance (adaptive)
+  // Candidate pool: tiered time windows by importance (adaptive).
+  // R1/R3: exclude LOW_SIGNAL degraded titles ("Modified X", "Worked on X",
+  // "Reviewed N files:", raw error logs) from the Key Context table at
+  // session start — they pollute the visible "Recent" table with noise.
   const obsPool = db.prepare(`
     SELECT id, type, title, narrative, importance, created_at_epoch, files_modified, lesson_learned
     FROM observations
     WHERE project = ? AND COALESCE(compressed_into, 0) = 0
+      AND ${notLowSignalTitleClause('')}
       AND (
         (created_at_epoch > ? AND importance >= 1)
         OR (created_at_epoch > ? AND importance >= 2)
@@ -82,9 +92,11 @@ export function selectWithTokenBudget(db, project, budget = 2000) {
   const selectedSess = [];
   let totalTokens = 0;
 
-  // Type quality multipliers — aligned with scoring-sql.mjs TYPE_QUALITY_CASE
-  // Demotes bugfix (noisy error logs) and promotes high-signal types
-  const TYPE_QUALITY = { decision: 1.5, discovery: 1.3, feature: 1.2, refactor: 1.0, change: 0.8, bugfix: 0.35 };
+  // Type quality multipliers — aligned with scoring-sql.mjs TYPE_QUALITY_CASE (R2).
+  // Weights calibrated from empirical avg access_count per type:
+  //   decision 6.05, discovery 3.32, bugfix 2.24, feature 2.04, change 0.93, refactor 0.54.
+  // Pre-R2 had bugfix=0.35 (inverted vs reality — bugfixes are 2.4× more used than changes).
+  const TYPE_QUALITY = { decision: 1.5, discovery: 1.3, bugfix: 1.1, feature: 1.0, refactor: 0.6, change: 0.5 };
 
   // Score each candidate: value = recency * type_quality * importance, cost = tokens
   // Recency uses exponential half-life (consistent with server.mjs BM25 scoring)
@@ -154,48 +166,217 @@ export function selectWithTokenBudget(db, project, budget = 2000) {
 }
 
 /**
- * Update the project's CLAUDE.md file with a context block.
- * Replaces existing <claude-mem-context> section or appends a new one.
- * Uses atomic tmp+rename write to prevent partial writes.
- * @param {string} contextBlock Markdown content to inject
+ * One-time cleanup of the legacy <claude-mem-context> block from the project's
+ * CLAUDE.md file. Pre-v2.30 the hook wrote a slim context snapshot here on every
+ * session start, causing constant git noise and stale, one-session-behind content.
+ * Context is now delivered exclusively via SessionStart hook stdout.
+ *
+ * Idempotent: if no legacy block (or no CLAUDE.md) exists, it is a no-op. Also
+ * removes the paired hint comment if present, and normalizes residual whitespace
+ * at the seam. Uses atomic tmp+rename write.
  */
-export function updateClaudeMd(contextBlock) {
+export function cleanupClaudeMdLegacyBlock() {
   const claudeMdPath = join(inferProjectDir(), 'CLAUDE.md');
-  let content = '';
-  try { content = readFileSync(claudeMdPath, 'utf8'); } catch {}
+  let content;
+  try { content = readFileSync(claudeMdPath, 'utf8'); } catch { return; }
 
   const startTag = '<claude-mem-context>';
   const endTag = '</claude-mem-context>';
-  const hintComment = '<!-- claude-mem-lite: auto-updated context. To avoid git noise, add CLAUDE.md to .gitignore -->';
-  const newSection = `${startTag}\n${contextBlock}\n${endTag}`;
 
-  // Use lastIndexOf for both tags — prevents matching documentation references
-  // to <claude-mem-context> that appear in code/markdown before the actual context block
+  // Use lastIndexOf so documentation references to the tag earlier in the file
+  // (e.g. inside a code block in architecture notes) are not accidentally swept.
   const startIdx = content.lastIndexOf(startTag);
   const endIdx = content.lastIndexOf(endTag);
+  if (startIdx === -1 || endIdx === -1 || startIdx >= endIdx) return;
 
-  if (startIdx !== -1 && endIdx !== -1 && startIdx < endIdx) {
-    // Skip write if content is unchanged — reduces git noise
-    const existingSection = content.slice(startIdx, endIdx + endTag.length);
-    if (existingSection === newSection) return;
-    // Replace from first start to last end — collapses any duplicate sections into one
-    content = content.slice(0, startIdx) + newSection + content.slice(endIdx + endTag.length);
-  } else if (content.length > 0) {
-    // Append to end — never disturb existing CLAUDE.md structure
-    const hint = content.includes(hintComment) ? '' : hintComment + '\n';
-    content = content.trimEnd() + '\n\n' + hint + newSection + '\n';
-  } else {
-    content = hintComment + '\n' + newSection + '\n';
+  // Extend forward to swallow a trailing newline so we don't leave a stranded blank line.
+  let removeEnd = endIdx + endTag.length;
+  if (content[removeEnd] === '\n') removeEnd += 1;
+
+  // Extend backward if the paired hint comment sits on the line immediately before
+  // the start tag. The hint is the exact string the old updateClaudeMd emitted.
+  let removeStart = startIdx;
+  const hintPattern = '<!-- claude-mem-lite: auto-updated context';
+  const leadingSlice = content.slice(0, startIdx);
+  const hintIdx = leadingSlice.lastIndexOf(hintPattern);
+  if (hintIdx !== -1) {
+    const between = content.slice(hintIdx, startIdx);
+    if (/^<!-- claude-mem-lite: [^\n]*-->\s*$/.test(between)) {
+      removeStart = hintIdx;
+    }
   }
 
+  // Swallow a single preceding newline to avoid leaving a blank-line gap behind.
+  if (removeStart > 0 && content[removeStart - 1] === '\n') removeStart -= 1;
+
+  const cleaned = content.slice(0, removeStart) + content.slice(removeEnd);
+  // Collapse any ≥3 consecutive newlines to two, then ensure exactly one trailing newline.
+  const normalized = cleaned.replace(/\n{3,}/g, '\n\n').replace(/\s*$/, '\n');
+
+  if (normalized === content) return;
+
   const tmp = claudeMdPath + '.mem-tmp';
   try {
-    writeFileSync(tmp, content);
+    writeFileSync(tmp, normalized);
     renameSync(tmp, claudeMdPath);
   } catch (e) {
     try { unlinkSync(tmp); } catch {}
-    debugLog('ERROR', 'updateClaudeMd', `CLAUDE.md write failed: ${e.message}`);
+    debugLog('ERROR', 'cleanupClaudeMdLegacyBlock', `CLAUDE.md write failed: ${e.message}`);
+  }
+}
+
+/**
+ * Assemble the full markdown body that goes inside the <claude-mem-context>
+ * block emitted at session start. Same shape as the inline builder hook.mjs
+ * used to compose directly; extracted so both the SessionStart hook AND the
+ * `claude-mem-lite context` CLI can read live context from the DB.
+ *
+ * Sections (in order):
+ *   1. Last Session (from session_summaries.latest)
+ *   2. File Lessons / Key Context (top importance≥2 observations)
+ *   3. Recent Activity fallback (when no summary and no key obs)
+ *   4. Working State (from latest clear handoff)
+ *   5. Recent (N) table (observations via selectWithTokenBudget + fallback)
+ *
+ * @param {import('better-sqlite3').Database} db Opened main DB
+ * @param {string} project Canonical project name (from inferProject())
+ * @param {Date} [now=new Date()] Clock reference for time windows and table header
+ * @returns {string} Joined markdown lines (without <claude-mem-context> wrappers)
+ */
+export function buildSessionContextLines(db, project, now = new Date()) {
+  // 1. Token-budgeted observation selection
+  const selected = selectWithTokenBudget(db, project, 2000);
+  const observations = selected.observations;
+
+  // 2. Fallback: recent across all projects with tiered windows (when local pool is thin)
+  let fallbackObs = [];
+  if (observations.length < 3) {
+    const fbOneDayAgo = now.getTime() - STALE_SESSION_MS;
+    const fbSevenDaysAgo = now.getTime() - FALLBACK_OBS_WINDOW_MS;
+    fallbackObs = db.prepare(`
+      SELECT id, type, title, project, created_at
+      FROM observations
+      WHERE COALESCE(compressed_into, 0) = 0
+        AND (
+          (created_at_epoch > ? AND importance >= 1)
+          OR (created_at_epoch > ? AND importance >= 2)
+        )
+      ORDER BY created_at_epoch DESC
+      LIMIT 5
+    `).all(fbOneDayAgo, fbSevenDaysAgo);
+  }
+
+  // 3. Latest session summary → base summaryLines
+  const latestSummary = db.prepare(`
+    SELECT request, completed, next_steps, remaining_items, lessons, key_decisions, created_at
+    FROM session_summaries
+    WHERE project = ?
+    ORDER BY created_at_epoch DESC
+    LIMIT 1
+  `).get(project);
+
+  const summaryLines = buildSummaryLines(latestSummary);
+
+  // 4. Key context: top high-importance observations split into File Lessons (actionable)
+  //    and Key Context (informational). Pushed into summaryLines.
+  const keyObs = db.prepare(`
+    SELECT o.id, o.type, o.title, o.lesson_learned, o.files_modified FROM observations o
+    WHERE o.project = ? AND COALESCE(o.compressed_into, 0) = 0
+      AND o.superseded_at IS NULL
+      AND COALESCE(o.importance, 1) >= 2
+    ORDER BY o.created_at_epoch DESC LIMIT 10
+  `).all(project);
+
+  if (keyObs.length > 0) {
+    const fileLessons = [];
+    const keyContext = [];
+
+    for (const o of keyObs) {
+      const clean = (o.title || '(untitled)')
+        .replace(/ → (?:ERROR: )?\{".*$/, '')
+        .replace(/ → (?:ERROR: )?\{[^}]*\.{3}$/, '');
+      const hasLesson = o.lesson_learned && o.lesson_learned.trim();
+      const hasFiles = o.files_modified && o.files_modified !== '[]';
+
+      if (hasLesson && hasFiles) {
+        try {
+          const files = JSON.parse(o.files_modified);
+          const fname = basename(Array.isArray(files) && files.length > 0 ? files[0] : '');
+          if (fname) {
+            fileLessons.push(`- ${fname}: ${truncate(o.lesson_learned, 100)} (#${o.id})`);
+            continue;
+          }
+        } catch { /* fall through to keyContext */ }
+      }
+      const lesson = hasLesson ? ` — ${truncate(o.lesson_learned, 60)}` : '';
+      keyContext.push(`- [${o.type || 'discovery'}] ${truncate(clean, 80)} (#${o.id})${lesson}`);
+    }
+
+    if (fileLessons.length > 0) {
+      summaryLines.push('### File Lessons');
+      summaryLines.push(...fileLessons.slice(0, 5));
+      summaryLines.push('');
+    }
+    if (keyContext.length > 0) {
+      summaryLines.push('### Key Context');
+      summaryLines.push(...keyContext.slice(0, 5));
+      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('');
+    }
   }
+
+  // 5. Working state from latest /clear handoff
+  const prevClearHandoff = db.prepare(`
+    SELECT working_on, unfinished, key_files
+    FROM session_handoffs
+    WHERE project = ? AND type = 'clear'
+    ORDER BY created_at_epoch DESC LIMIT 1
+  `).get(project);
+
+  const handoffLines = [];
+  if (prevClearHandoff) {
+    handoffLines.push('### Working State (from /clear)');
+    if (prevClearHandoff.working_on) {
+      handoffLines.push(`- Working on: ${truncate(prevClearHandoff.working_on, 200)}`);
+    }
+    if (prevClearHandoff.unfinished) {
+      const pendingSummary = extractUnfinishedSummary(prevClearHandoff.unfinished);
+      if (pendingSummary) handoffLines.push(`- Unfinished: ${truncate(pendingSummary, 200)}`);
+    }
+    if (prevClearHandoff.key_files) {
+      try {
+        const files = JSON.parse(prevClearHandoff.key_files);
+        if (files.length > 0) handoffLines.push(`- Key files: ${files.map(f => basename(f)).join(', ')}`);
+      } catch { /* malformed JSON — skip */ }
+    }
+    handoffLines.push('');
+  }
+
+  // 6. Recent observations table
+  const obsLines = [];
+  const obsToShow = observations.length >= 3 ? observations : fallbackObs;
+  if (obsToShow.length > 0) {
+    const today = now.toISOString().slice(0, 10);
+    obsLines.push(`### Recent (${today})`);
+    obsLines.push('');
+    obsLines.push('| ID | Time | T | Title |');
+    obsLines.push('|----|------|---|-------|');
+    for (const o of obsToShow) {
+      const proj = o.project && o.project !== project ? ` (${o.project})` : '';
+      obsLines.push(`| #${o.id} | ${fmtTime(o.created_at)} | ${typeIcon(o.type)} | ${truncate(o.title || '(untitled)', 60)}${proj} |`);
+    }
+  }
+
+  return [...summaryLines, ...handoffLines, ...obsLines].join('\n');
 }
 
 /**

package/hook-memory.mjs

@@ -1,13 +1,20 @@
 // claude-mem-lite — Semantic Memory Injection
 // Search past observations for relevant memories to inject as context at user-prompt time.
 
-import { sanitizeFtsQuery, relaxFtsQueryToOr, debugCatch, OBS_BM25 } from './utils.mjs';
+import { sanitizeFtsQuery, relaxFtsQueryToOr, debugCatch, OBS_BM25, notLowSignalTitleClause } from './utils.mjs';
 
 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 };
+// Aligned with TYPE_QUALITY_CASE in scoring-sql.mjs (R2 rebalance).
+// Weights calibrated to empirical avg access_count:
+//   decision 6.05, discovery 3.32, bugfix 2.24, feature 2.04, change 0.93, refactor 0.54.
+// lesson_learned boost (1.5×) stacks for entries with a real takeaway.
+const MEMORY_TYPE_BOOST = { decision: 1.5, discovery: 1.3, bugfix: 1.1, feature: 1.0, refactor: 0.6, change: 0.5 };
+// 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;
@@ -32,6 +39,9 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     const excludeSet = new Set(excludeIds);
 
     // Phase 1: Same-project search (highest priority)
+    // R1: notLowSignalTitleClause() excludes hook-llm fallback titles
+    // ("Modified X", "Worked on X", "Reviewed N files:", raw error logs, etc.)
+    // that almost never get referenced (3.3% access rate) but compete for BM25 rank.
     const selectStmt = db.prepare(`
       SELECT o.id, o.type, o.title, o.importance, o.lesson_learned, o.project,
              ${OBS_BM25} as relevance
@@ -43,22 +53,30 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
         AND o.created_at_epoch > ?
         AND COALESCE(o.compressed_into, 0) = 0
         AND o.superseded_at IS NULL
+        AND ${notLowSignalTitleClause('o')}
       ORDER BY ${OBS_BM25}
       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,
@@ -72,46 +90,51 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
           AND o.created_at_epoch > ?
           AND COALESCE(o.compressed_into, 0) = 0
           AND o.superseded_at IS NULL
+          AND ${notLowSignalTitleClause('o')}
         ORDER BY ${OBS_BM25}
         LIMIT 5
       `);
       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) {