claude-mem-lite 3.1.0 → 3.1.2

package/mem-cli.mjs

@@ -10,6 +10,7 @@ import { TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
 import { _resetVocabCache } from './tfidf.mjs';
 import { autoBoostIfNeeded, reRankWithContext, markSuperseded } from './server-internals.mjs';
 import { searchObservationsHybrid, countSearchTotal } from './search-engine.mjs';
+import { deepSearch } from './deep-search.mjs';
 import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
@@ -47,11 +48,11 @@ import {
 
 // ─── Commands ────────────────────────────────────────────────────────────────
 
-function cmdSearch(db, args) {
+async function cmdSearch(db, args) {
   const { positional, flags } = parseArgs(args);
   const query = positional.join(' ');
   if (!query) {
-    fail('[mem] Usage: claude-mem-lite search <query> [--type TYPE] [--source SOURCE] [--limit N] [--project P] [--from DATE] [--to DATE] [--importance N] [--branch B] [--offset N] [--sort relevance|time|importance] [--include-noise]');
+    fail('[mem] Usage: claude-mem-lite search <query> [--type TYPE] [--source SOURCE] [--limit N] [--project P] [--from DATE] [--to DATE] [--importance N] [--branch B] [--offset N] [--sort relevance|time|importance] [--include-noise] [--deep]');
     return;
   }
 
@@ -99,6 +100,10 @@ function cmdSearch(db, args) {
   // when explicitly searching for a file/command that produced a degraded title.
   const includeNoise = flags['include-noise'] === true || flags['include-noise'] === 'true';
   const jsonOutput = flags.json === true || flags.json === 'true';
+  // --deep: opt-in LLM multi-query / HyDE deep search (deep-search.mjs). Costs one
+  // Haiku call + N hybrid searches; observations-only. NOT the passive path — this
+  // is the explicit "search harder" lever for vocabulary-mismatch recall misses.
+  const deep = flags.deep === true || flags.deep === 'true';
 
   if (source && !['observations', 'sessions', 'prompts'].includes(source)) {
     fail(`[mem] Invalid --source "${source}". Use: observations, sessions, prompts`);
@@ -106,10 +111,17 @@ function cmdSearch(db, args) {
   }
 
   const ftsQuery = buildSearchFtsQuery(query, { or: useOr });
-  if (!ftsQuery) {
+  // --deep proceeds even when the literal query sanitizes to nothing — its LLM
+  // rewrite may still produce searchable variants (F3, parity with server.mjs).
+  if (!ftsQuery && !deep) {
     fail(`[mem] No valid search terms in "${query}"`);
     return;
   }
+  // --deep ignores --or: each variant runs AND + the engine's built-in
+  // OR-fallback, so --or has no effect on the deep path — say so (F8).
+  if (deep && useOr) {
+    process.stderr.write('[mem] Note: --or has no effect with --deep (variants use AND + engine OR-fallback)\n');
+  }
 
   // Warn if obs-only filters used with non-observation source
   if (source && source !== 'observations' && (type || tier || minImportance || branch)) {
@@ -121,7 +133,14 @@ function cmdSearch(db, args) {
   // --branch was previously cross-source: sessions/prompts have no branch column, so a query like
   // `search "cache" --branch main` would include unrelated session/prompt rows, surprising users
   // who passed --branch expecting a branch-scoped result.
-  const effectiveSource = source || ((type || tier || minImportance || branch) ? 'observations' : null);
+  // --deep is observations-only (deepSearch fuses searchObservationsHybrid lists);
+  // it overrides --source and the obs-only filter inference.
+  if (deep && source && source !== 'observations') {
+    process.stderr.write(`[mem] Note: --deep searches observations only; ignoring --source ${source}\n`);
+  }
+  const effectiveSource = deep
+    ? 'observations'
+    : (source || ((type || tier || minImportance || branch) ? 'observations' : null));
 
   // Cross-source mode: each source needs more candidates than the final limit
   // so the post-merge sort has room to pick the best from each (shared sizing
@@ -136,27 +155,55 @@ function cmdSearch(db, args) {
   // ctx.orFallbackFired so the header can surface a "(relaxed AND→OR)" hint.
   let orFallbackFired = false;
 
+  let deepVariants = null;
   // Search observations — shared engine with server.mjs (#8198/#8212 paired-path fix)
   if (!effectiveSource || effectiveSource === 'observations') {
-    const obsCtx = {
-      ftsQuery,
-      args: {
+    let obsResults;
+    if (deep) {
+      // Opt-in deep search: rewrite the query into variants (keyword / concept /
+      // HyDE), run each through the hybrid engine, RRF-fuse. Collapses to the
+      // single query when the rewrite yields nothing — never worse than baseline
+      // (deep-search.mjs). Over-fetch perSourceLimit so the offset/slice below has room.
+      const ds = await deepSearch(db, {
+        query,
         project: project || null,
-        obs_type: type || null,
+        type: type || null,
         importance: minImportance || null,
         branch: branch || null,
-        include_noise: includeNoise,
-      },
-      epochFrom: dateFrom,
-      epochTo: dateTo,
-      perSourceLimit,
-      perSourceOffset,
-      currentProject: project ? null : inferProject(),
-      limit,
-      orFallbackFired: false,
-    };
-    const obsResults = searchObservationsHybrid(db, obsCtx);
-    if (obsCtx.orFallbackFired) orFallbackFired = true;
+        includeNoise,
+        epochFrom: dateFrom,
+        epochTo: dateTo,
+        limit: perSourceLimit,
+        currentProject: project ? null : inferProject(),
+      });
+      obsResults = ds.results;
+      deepVariants = ds.variants;
+      if (deepVariants.length > 1) {
+        process.stderr.write(`[mem] Deep search: rewrote into ${deepVariants.length} query variants, RRF-fused\n`);
+      } else {
+        process.stderr.write('[mem] Deep search: rewrite returned no usable variants; used original query only\n');
+      }
+    } else {
+      const obsCtx = {
+        ftsQuery,
+        args: {
+          project: project || null,
+          obs_type: type || null,
+          importance: minImportance || null,
+          branch: branch || null,
+          include_noise: includeNoise,
+        },
+        epochFrom: dateFrom,
+        epochTo: dateTo,
+        perSourceLimit,
+        perSourceOffset,
+        currentProject: project ? null : inferProject(),
+        limit,
+        orFallbackFired: false,
+      };
+      obsResults = searchObservationsHybrid(db, obsCtx);
+      if (obsCtx.orFallbackFired) orFallbackFired = true;
+    }
     for (const r of obsResults) results.push({ ...r, _source: 'obs', score: r.score ?? 0 });
 
     // Tier post-filter — applied to ALL obs results from the engine.
@@ -191,7 +238,7 @@ function cmdSearch(db, args) {
 
   if (results.length === 0) {
     if (jsonOutput) {
-      out(JSON.stringify({ query, total: 0, returned: 0, offset, limit, results: [] }));
+      out(JSON.stringify({ query, total: 0, returned: 0, offset, limit, deep, variants: deep ? deepVariants : undefined, results: [] }));
     } else {
       out(`[mem] No results for "${query}"`);
     }
@@ -228,22 +275,28 @@ function cmdSearch(db, args) {
   // pagination contract). countSearchTotal mirrors each source's MATCH+filters;
   // clamp to >= results.length so it never understates the rows actually shown
   // (vector/concept augmentation can add obs rows beyond the FTS count).
-  const trueTotal = countSearchTotal(db, {
-    effectiveSource,
-    ftsQuery,
-    obsFtsQuery: effectiveObsFtsQuery(ftsQuery, orFallbackFired),
-    args: { project: project || null, obs_type: type || null, importance: minImportance || null, branch: branch || null },
-    project: project || null,
-    epochFrom: dateFrom,
-    epochTo: dateTo,
-    includeNoise,
-  });
-  const total = Math.max(trueTotal, results.length);
+  // For --deep the population is the fused variant result set: deepSearch already
+  // returned all fused rows (capped at perSourceLimit) and they are the only rows
+  // in `results` (deep is obs-only). countSearchTotal would instead count the
+  // ORIGINAL query's FTS matches — wrong, and ~0 on the vocabulary-mismatch
+  // queries deep exists for, which falsely shrinks the "N of M" total (F1).
+  const total = deep
+    ? results.length
+    : Math.max(countSearchTotal(db, {
+      effectiveSource,
+      ftsQuery,
+      obsFtsQuery: effectiveObsFtsQuery(ftsQuery, orFallbackFired),
+      args: { project: project || null, obs_type: type || null, importance: minImportance || null, branch: branch || null },
+      project: project || null,
+      epochFrom: dateFrom,
+      epochTo: dateTo,
+      includeNoise,
+    }), results.length);
   const paged = results.slice(offset, offset + limit);
 
   if (paged.length === 0) {
     if (jsonOutput) {
-      out(JSON.stringify({ query, total, returned: 0, offset, limit, results: [] }));
+      out(JSON.stringify({ query, total, returned: 0, offset, limit, deep, variants: deep ? deepVariants : undefined, results: [] }));
     } else {
       out(`[mem] No results for "${query}" at offset ${offset}`);
     }
@@ -286,6 +339,8 @@ function cmdSearch(db, args) {
       returned: paged.length,
       offset,
       limit,
+      deep,
+      variants: deep ? deepVariants : undefined,
       relaxed_and_to_or: orFallbackFired && !useOr,
       mixed_sources: hasMixed,
       results: items,
@@ -2785,7 +2840,7 @@ export async function run(argv) {
 
   try {
     switch (cmd) {
-      case 'search':    cmdSearch(db, cmdArgs); break;
+      case 'search':    await cmdSearch(db, cmdArgs); break;
       case 'recent':    cmdRecent(db, cmdArgs); break;
       case 'recall':    cmdRecall(db, cmdArgs); break;
       case 'get':       cmdGet(db, cmdArgs); break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -25,10 +25,12 @@
   },
   "files": [
     "cli.mjs",
+    "cli-path.mjs",
     "mem-cli.mjs",
     "server.mjs",
     "server-internals.mjs",
     "search-engine.mjs",
+    "deep-search.mjs",
     "hook.mjs",
     "hook-shared.mjs",
     "hook-llm.mjs",

package/scripts/hook-launcher.mjs

@@ -24,7 +24,7 @@
 // would defeat the entire purpose — the launcher must survive a broken
 // install.
 
-import { existsSync, mkdirSync, writeFileSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, statSync, unlinkSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -37,8 +37,18 @@ const RUNTIME_DIR = process.env.CLAUDE_MEM_DIR
   : join(homedir(), '.claude-mem-lite', 'runtime');
 const HEAL_MARKER = join(RUNTIME_DIR, 'hook-launcher-lastheal');
 const HEAL_COOLDOWN_MS = 6 * 60 * 60 * 1000;
+// Observable breakage state: written when the launcher degrades a broken install
+// to exit 0, cleared once the install is confirmed healthy. `doctor` reads it so
+// the intentional silence (no stack trace per fire) stays detectable. (#4/#8)
+const BROKEN_MARKER = join(RUNTIME_DIR, 'hook-launcher-broken');
 
-// Last-resort recovery string for users whose `claude-mem-lite repair` path
+// Resolvable invocation of the bundled CLI's repair path. Absolute via
+// INSTALL_DIR (import.meta.url) so it works on a plugin-only install, where
+// bare `claude-mem-lite` is not on PATH and ~/.claude-mem-lite/ holds no source.
+// cli.mjs routes `repair` → install.mjs. (review #3)
+const CLI_REPAIR = `node ${join(INSTALL_DIR, 'cli.mjs')} repair`;
+
+// Last-resort recovery string for users whose `cli.mjs repair` path
 // itself failed (install.mjs missing / repair errored / retry still drifting).
 // Duplicated in install.mjs::repair() catch; both are reachable when local
 // scripts are broken, so neither can import a shared constant.
@@ -76,13 +86,51 @@ async function runEntry({ bustCache = false } = {}) {
 // Anchor on any path the error exposes — the missing URL and/or the importer
 // (present in both messages as "imported from <path>"). If it sits inside our
 // install, a self-heal could fix it.
+// package.json dependency set of THIS install — read lazily, best-effort. Lets
+// isLocalModuleErr tell a genuinely-ours missing bare dependency (better-sqlite3,
+// zod, …) apart from a foreign/mistyped package name that merely happens to be
+// imported from an install-dir file. The former is self-healable; the latter is
+// a real packaging bug that must surface a Node stack trace rather than be
+// swallowed by an exit-0 self-heal. (review #5/#7)
+function ownDependencies() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(INSTALL_DIR, 'package.json'), 'utf8'));
+    return new Set([
+      ...Object.keys(pkg.dependencies || {}),
+      ...Object.keys(pkg.optionalDependencies || {}),
+    ]);
+  } catch {
+    return null; // unreadable package.json → caller stays permissive
+  }
+}
+
 function isLocalModuleErr(e) {
   if (!e || e.code !== 'ERR_MODULE_NOT_FOUND') return false;
-  const importer = /imported from (.+?)\s*$/.exec(String(e.message || ''))?.[1];
-  const paths = [e.url, importer]
-    .filter(Boolean)
-    .map((p) => String(p).replace(/^file:\/\//, ''));
-  return paths.some((p) => p.startsWith(INSTALL_DIR) || p.includes('.claude-mem-lite'));
+  // Missing RELATIVE module: e.url is the missing file's URL. Ours iff it sits
+  // under our install dir (the `.claude-mem-lite` substring also covers the
+  // symlink-farm dev/direct-install case where INSTALL_DIR is the realpath).
+  if (e.url) {
+    const p = String(e.url).replace(/^file:\/\//, '');
+    return p.startsWith(INSTALL_DIR) || p.includes('.claude-mem-lite');
+  }
+  // Missing BARE dependency: e.url is UNDEFINED; message is
+  // `Cannot find package '<name>' imported from <importer>`. The (.+) capture
+  // needs no `m` flag (`.` stops at a newline) and so tolerates a multi-line
+  // message that appends a hint line after the importer path — the old
+  // `(.+?)\s*$` returned undefined there and misclassified the dep. (review #11/#15)
+  const msg = String(e.message || '');
+  const importer = /imported from (.+)/.exec(msg)?.[1]?.trim();
+  if (!importer) return false;
+  const importerPath = importer.replace(/^file:\/\//, '');
+  if (!(importerPath.startsWith(INSTALL_DIR) || importerPath.includes('.claude-mem-lite'))) return false;
+  // Importer is ours — but only self-heal if the missing package is one we
+  // actually declare. A foreign/typo'd name re-throws so the bug is visible.
+  const pkgName = /Cannot find package '([^']+)'/.exec(msg)?.[1];
+  const deps = ownDependencies();
+  if (!deps || !pkgName) return true; // best-effort: can't verify → stay permissive
+  // Normalize sub-path / scoped imports to the package root (better-sqlite3/x → better-sqlite3).
+  const root = pkgName.startsWith('@') ? pkgName.split('/').slice(0, 2).join('/') : pkgName.split('/')[0];
+  return deps.has(root);
 }
 
 // Human-readable label for the "Detected broken install (<reason>)" line:
@@ -107,11 +155,29 @@ function recordHealAttempt() {
   } catch { /* best-effort */ }
 }
 
+// Drop the 6h cooldown once a heal fully resolves. The marker is written BEFORE
+// spawn (rate-limits concurrent fires), but a SUCCESSFUL heal must not keep
+// blocking an unrelated later breakage that happens within the window. (#6/#9)
+function clearHealMarker() {
+  try { unlinkSync(HEAL_MARKER); } catch { /* already gone — fine */ }
+}
+
+function recordBreakage(reason) {
+  try {
+    mkdirSync(RUNTIME_DIR, { recursive: true });
+    writeFileSync(BROKEN_MARKER, JSON.stringify({ reason, ts: Date.now() }));
+  } catch { /* best-effort */ }
+}
+
+function clearBreakage() {
+  try { if (existsSync(BROKEN_MARKER)) unlinkSync(BROKEN_MARKER); } catch { /* best-effort */ }
+}
+
 async function attemptHeal(reason) {
   if (recentHealAttempt()) {
     process.stderr.write(
       `[claude-mem-lite] Self-heal skipped (last attempt < 6h ago).\n` +
-      `[claude-mem-lite] Manual recovery: claude-mem-lite repair\n` +
+      `[claude-mem-lite] Manual recovery: ${CLI_REPAIR}\n` +
       `[claude-mem-lite] If that fails, run: ${TARBALL_FALLBACK}\n`,
     );
     return false;
@@ -160,19 +226,30 @@ if (rest.includes('session-start')) {
 
 try {
   await runEntry();
+  // A clean session-start fire confirms the install is healthy → clear any stale
+  // breakage marker. Gated to session-start so the per-tool hot path pays nothing.
+  if (rest.includes('session-start')) clearBreakage();
 } catch (e) {
   if (!isLocalModuleErr(e)) throw e;
-  const healed = await attemptHeal(describeFailure(e));
+  const reason = describeFailure(e);
+  const healed = await attemptHeal(reason);
   if (!healed) {
     // Broken/missing dependency we can't repair right now (repair failed, or
     // was skipped within the 6h cooldown). attemptHeal already wrote actionable
     // guidance — degrade quietly instead of re-throwing the original import
-    // error, which would spew a Node stack trace on every hook fire.
+    // error, which would spew a Node stack trace on every hook fire. Record the
+    // breakage so the exit-0 silence stays observable to `doctor`. (#4/#8)
+    recordBreakage(reason);
     process.exit(0);
   }
   try {
     await runEntry({ bustCache: true });
+    // Fully healed: drop the cooldown so an UNRELATED later break can heal
+    // immediately (#6/#9), and clear the breakage marker.
+    clearHealMarker();
+    clearBreakage();
   } catch (retryErr) {
+    recordBreakage(`retry-failed: ${retryErr.message}`);
     process.stderr.write(
       `[claude-mem-lite] Hook still failing after self-heal: ${retryErr.message}\n` +
       `[claude-mem-lite] Manual recovery: ${TARBALL_FALLBACK}\n`,

package/server-internals.mjs

@@ -4,6 +4,7 @@
 import { debugCatch, COMPRESSED_AUTO, COMPRESSED_PENDING_PURGE, OBS_BM25 } from './utils.mjs';
 import { BASE_STOP_WORDS } from './stop-words.mjs';
 import { porterStem } from './tfidf.mjs';
+import { CLI_INVOKE } from './cli-path.mjs';
 
 // ─── MCP Server Instructions Builder ───────────────────────────────────────
 // Phase A (v2.31.3+): when quiet=true, drops WHEN-TO-USE proactive-trigger and
@@ -14,13 +15,13 @@ import { porterStem } from './tfidf.mjs';
 const INSTRUCTIONS_BASE = [
   'Long-term memory across sessions. Hooks auto-inject context; CLI preferred for explicit queries.',
   '',
-  'CLI (via Bash) — invoke as `node ~/.claude-mem-lite/cli.mjs <cmd>` (shipped with the plugin), or bare `claude-mem-lite <cmd>` only if you ran the optional global `npm i -g claude-mem-lite`:',
-  '  claude-mem-lite search "query"              — FTS5 full-text search',
-  '  claude-mem-lite search "err" --type bugfix  — filter by type',
-  '  claude-mem-lite recall "file.mjs"           — file-related memories',
-  '  claude-mem-lite recent 5                    — latest observations',
-  '  claude-mem-lite get 42,43                   — full details by ID',
-  '  claude-mem-lite timeline --anchor 42        — chronological context',
+  `CLI (via Bash) — invoke as \`${CLI_INVOKE} <cmd>\` (resolves on any install shape; the bare \`claude-mem-lite\` shorthand works only after an optional global \`npm i -g claude-mem-lite\`):`,
+  `  ${CLI_INVOKE} search "query"  — FTS5 full-text search`,
+  `  ${CLI_INVOKE} search "err" --type bugfix  — filter by type`,
+  `  ${CLI_INVOKE} recall "file.mjs"  — file-related memories`,
+  `  ${CLI_INVOKE} recent 5  — latest observations`,
+  `  ${CLI_INVOKE} get 42,43  — full details by ID`,
+  `  ${CLI_INVOKE} timeline --anchor 42  — chronological context`,
   '',
   'MCP tools: mem_search, mem_recent, mem_save, mem_get, mem_recall, mem_timeline for programmatic access (always available — no PATH/CLI install needed).',
   'mem_save: Save non-obvious insights (bugfix lessons, architecture decisions).',

package/server.mjs

@@ -10,6 +10,7 @@ import { resolveProject as _resolveProjectShared } from './project-utils.mjs';
 import { ensureDb, DB_PATH, DB_DIR, REGISTRY_DB_PATH } from './schema.mjs';
 import { reRankWithContext, markSuperseded, autoBoostIfNeeded, runIdleCleanup, buildServerInstructions } from './server-internals.mjs';
 import { searchObservationsHybrid, countSearchTotal } from './search-engine.mjs';
+import { deepSearch } from './deep-search.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
 import { resolveAnchorToken, formatAnchorError, resolveQueryAnchor, fetchRecentTimeline, fetchTimelineWindow } from './lib/timeline-core.mjs';
 import { buildSearchFtsQuery, parseDateBounds, computePerSourceWindow, effectiveObsFtsQuery, searchSessionsFts, searchPromptsFts, normalizeCrossSourceScores, applyUserSort, applyTierFilter } from './lib/search-core.mjs';
@@ -249,7 +250,13 @@ function searchPrompts(ctx) {
 function formatSearchOutput(paginatedResults, args, ftsQuery, totalCount, orFallbackFired = false) {
   if (paginatedResults.length === 0) {
     const hint = [];
-    if (args.query && !ftsQuery) {
+    if (args.deep) {
+      // Deep search runs even when the literal query sanitizes to empty, so the
+      // "query was filtered" hint below would be misleading — the LLM rewrite ran
+      // N variants and simply found nothing (F9).
+      hint.push('No results — deep search rewrote the query into variants and still found nothing.');
+      hint.push('This is a recall miss (the rewrite ran), not a query-syntax issue; the memory likely has no related observations.');
+    } else if (args.query && !ftsQuery) {
       hint.push(`Query "${args.query}" was filtered (FTS5 keywords/special chars only).`);
       hint.push('Tip: use content words instead of operators (AND, OR, NOT, NEAR).');
     } else {
@@ -331,18 +338,44 @@ server.registerTool(
     if (!bounds.ok) throw new Error(`Invalid date_${bounds.bad}: "${bounds.value}" (use ISO 8601 or YYYY-MM-DD)`);
     const { epochFrom, epochTo } = bounds;
 
-    // Early return when query was provided but sanitized to nothing (all FTS5 keywords/special chars)
-    if (args.query && !ftsQuery && !epochFrom && !epochTo && !args.obs_type && !args.importance) {
+    // Early return when query was provided but sanitized to nothing (all FTS5
+    // keywords/special chars). Skipped for deep search — its LLM rewrite may
+    // still produce searchable variants from a query the FTS sanitizer rejects.
+    if (args.query && !ftsQuery && !epochFrom && !epochTo && !args.obs_type && !args.importance && !args.deep) {
       return formatSearchOutput([], args, ftsQuery, 0);
     }
 
-    // When obs_type is specified, implicitly restrict to observations only
-    const effectiveType = searchType || (args.obs_type ? 'observations' : undefined);
+    // When obs_type is specified, implicitly restrict to observations only.
+    // --deep is observations-only too (deepSearch fuses hybrid-obs lists).
+    const effectiveType = args.deep ? 'observations' : (searchType || (args.obs_type ? 'observations' : undefined));
     const isCrossSource = !effectiveType;
     const ctx = { ftsQuery, searchType: effectiveType, args, epochFrom, epochTo, perSourceLimit, perSourceOffset, currentProject, limit };
     const results = [];
-
-    if (!effectiveType || effectiveType === 'observations') results.push(...searchObservations(ctx));
+    let deepVariants = null;
+
+    if (!effectiveType || effectiveType === 'observations') {
+      if (args.deep) {
+        // Opt-in LLM multi-query/HyDE deep search: rewrite → per-variant hybrid
+        // search → RRF fusion, collapsing to the single query (== baseline) when
+        // the rewrite yields nothing (deep-search.mjs). Over-fetch perSourceLimit
+        // so the pagination slice below has room.
+        const { results: deepRows, variants } = await deepSearch(db, {
+          query: args.query,
+          project: args.project || null,
+          type: args.obs_type || null,
+          importance: args.importance || null,
+          branch: args.branch || null,
+          includeNoise: args.include_noise === true,
+          epochFrom, epochTo,
+          limit: perSourceLimit,
+          currentProject,
+        });
+        results.push(...deepRows);
+        deepVariants = variants;
+      } else {
+        results.push(...searchObservations(ctx));
+      }
+    }
     if (!effectiveType || effectiveType === 'sessions')     results.push(...searchSessions(ctx));
     if (!effectiveType || effectiveType === 'prompts')       results.push(...searchPrompts(ctx));
 
@@ -382,12 +415,17 @@ server.registerTool(
       }
     }
 
-    // Re-rank observations by file context overlap and mark superseded
-    if (ftsQuery && results.some(r => r.source === 'obs')) {
+    // Re-rank observations by file context overlap and mark superseded.
+    // markSuperseded is pure correctness (stale-tag) and must run for deep results
+    // too, including the case where the ORIGINAL query sanitized to an empty
+    // ftsQuery but the rewrite still returned rows (F2). reRankWithContext + the
+    // re-sort are FTS-rank operations; deep rows are already RRF-ranked, so on the
+    // empty-ftsQuery deep path we tag-but-don't-reorder (keep RRF order).
+    if ((ftsQuery || args.deep) && results.some(r => r.source === 'obs')) {
       const obsResults = results.filter(r => r.source === 'obs');
-      reRankWithContext(db, obsResults, currentProject);
+      if (ftsQuery) reRankWithContext(db, obsResults, currentProject);
       markSuperseded(obsResults);
-      results.sort((a, b) => (a.score ?? 0) - (b.score ?? 0));
+      if (ftsQuery) results.sort((a, b) => (a.score ?? 0) - (b.score ?? 0));
     }
 
     // Tier post-filter: batch-lookup full rows and classify (shared with CLI).
@@ -407,20 +445,34 @@ server.registerTool(
     // results.length is NOT the population — count the real MATCH set instead. Clamp
     // to >= results.length so vector/concept-augmented obs rows are never undercounted.
     // (paired-path with mem-cli.mjs via shared countSearchTotal — #8217)
-    const trueTotal = countSearchTotal(db, {
-      effectiveSource: effectiveType || null,
-      ftsQuery,
-      obsFtsQuery: effectiveObsFtsQuery(ftsQuery, ctx.orFallbackFired === true),
-      args: { project: args.project || null, obs_type: args.obs_type || null, importance: args.importance || null, branch: args.branch || null },
-      project: args.project || null,
-      epochFrom, epochTo,
-      includeNoise: args.include_noise === true,
-    });
-    const totalBeforePagination = Math.max(trueTotal, results.length);
+    // For --deep the population is the fused variant set already in `results`
+    // (deep is obs-only, returned by deepSearch capped at perSourceLimit).
+    // countSearchTotal would count the ORIGINAL query's FTS matches instead —
+    // wrong, and ~0 on the vocabulary-mismatch queries deep exists for (F1).
+    const totalBeforePagination = args.deep
+      ? results.length
+      : Math.max(countSearchTotal(db, {
+        effectiveSource: effectiveType || null,
+        ftsQuery,
+        obsFtsQuery: effectiveObsFtsQuery(ftsQuery, ctx.orFallbackFired === true),
+        args: { project: args.project || null, obs_type: args.obs_type || null, importance: args.importance || null, branch: args.branch || null },
+        project: args.project || null,
+        epochFrom, epochTo,
+        includeNoise: args.include_noise === true,
+      }), results.length);
     // Always apply pagination — single-source results can exceed SQL LIMIT due to expansion (concept co-occurrence, PRF, vector search)
     const paginatedResults = (offset > 0 || results.length > limit) ? results.slice(offset, offset + limit) : results;
 
-    return formatSearchOutput(paginatedResults, args, ftsQuery, totalBeforePagination, ctx.orFallbackFired === true);
+    const output = formatSearchOutput(paginatedResults, args, ftsQuery, totalBeforePagination, ctx.orFallbackFired === true);
+    // Surface the rewrite to the calling agent (CLI prints this to stderr + JSON;
+    // MCP had no signal at all — F13). Tells the agent whether deep actually
+    // reformulated the query or collapsed to the single-query baseline.
+    if (args.deep && deepVariants && output.content?.[0]?.type === 'text') {
+      output.content[0].text += deepVariants.length > 1
+        ? `\n\n[deep search: rewrote into ${deepVariants.length} variants — ${deepVariants.slice(1).map(v => JSON.stringify(v)).join(', ')}]`
+        : '\n\n[deep search: rewrite produced no usable variants; searched the original query only (== baseline)]';
+    }
+    return output;
   })
 );
 

package/source-files.mjs

@@ -6,7 +6,7 @@
 
 export const SOURCE_FILES = [
   // Entry points and top-level modules
-  'cli.mjs', 'server.mjs', 'server-internals.mjs', 'search-engine.mjs', 'tool-schemas.mjs',
+  'cli.mjs', 'cli-path.mjs', 'server.mjs', 'server-internals.mjs', 'search-engine.mjs', 'deep-search.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-optimize.mjs', 'hook-precompact.mjs',