brain-cache 0.4.2 → 3.0.0

package/dist/mcp.js

@@ -1,5 +1,5 @@
 // src/mcp/index.ts
-import { resolve as resolve4 } from "path";
+import { resolve as resolve7 } from "path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z as z2 } from "zod";
@@ -48,15 +48,92 @@ function setLogLevel(level) {
 }
 
 // src/lib/format.ts
+import dedent from "dedent";
+function formatToolResponse(summary, body) {
+  return `${summary}
+
+${body}`;
+}
+function formatErrorEnvelope(message, suggestion) {
+  const lines = [`Error: ${message}`];
+  if (suggestion) lines.push(`Suggestion: ${suggestion}`);
+  return lines.join("\n");
+}
 function formatTokenSavings(input) {
-  const PAD = 27;
   const fileSuffix = input.filesInContext !== 1 ? "s" : "";
-  const lines = [
-    ["Tokens sent to Claude:", input.tokensSent.toLocaleString()],
-    ["Estimated without:", `~${input.estimatedWithout.toLocaleString()}  (${input.filesInContext} file${fileSuffix} + overhead)`],
-    ["Reduction:", `${input.reductionPct}%`]
-  ];
-  return lines.map(([label, value]) => `${label.padEnd(PAD)}${value}`).join("\n");
+  return [
+    `Tokens sent to Claude: ${input.tokensSent.toLocaleString()}`,
+    `Estimated without: ~${input.estimatedWithout.toLocaleString()}  (${input.filesInContext} file${fileSuffix} + overhead)`,
+    `Reduction: ${input.reductionPct}%`
+  ].join("\n");
+}
+function formatDoctorOutput(health) {
+  const lines = [];
+  let ollamaLine = `Ollama: ${health.ollamaStatus}`;
+  if (health.ollamaStatus === "running" && health.ollamaVersion) {
+    ollamaLine += ` (v${health.ollamaVersion})`;
+  }
+  lines.push(ollamaLine);
+  if (health.indexFreshness.indexed) {
+    const { fileCount, chunkCount, indexedAt } = health.indexFreshness;
+    let indexLine = "Index: indexed";
+    if (fileCount !== null && chunkCount !== null) {
+      indexLine += ` \u2014 ${fileCount} files, ${chunkCount} chunks`;
+    }
+    if (indexedAt) {
+      indexLine += ` (at ${indexedAt})`;
+    }
+    lines.push(indexLine);
+  } else {
+    lines.push("Index: not indexed");
+  }
+  lines.push(`Embedding model: ${health.embeddingModel ?? "none"}`);
+  if (health.vramTier === "none") {
+    lines.push("VRAM: no GPU detected");
+  } else {
+    const vramVal = health.vramAvailable !== null ? `${health.vramAvailable} GiB` : "unknown";
+    lines.push(`VRAM: ${health.vramTier} (${vramVal})`);
+  }
+  return lines.join("\n");
+}
+function formatIndexResult(result) {
+  if (result.fileCount !== null && result.chunkCount !== null) {
+    return `Indexed ${result.path} \u2014 ${result.fileCount} files, ${result.chunkCount} chunks.`;
+  }
+  return `Indexed ${result.path}.`;
+}
+function formatSearchResults(chunks) {
+  if (chunks.length === 0) {
+    return "No results found for the given query.";
+  }
+  return chunks.map((chunk, i) => {
+    const name = chunk.name ?? "(anonymous)";
+    return dedent`
+      ${i + 1}. ${name} (${chunk.chunkType})
+         ${chunk.filePath}:${chunk.startLine}
+         Score: ${chunk.similarity.toFixed(3)}
+    `.trim();
+  }).join("\n\n");
+}
+function formatTraceFlow(result) {
+  if (result.hops.length === 0) {
+    return "No call hops found. The entrypoint may not be indexed \u2014 run index_repo first.";
+  }
+  return result.hops.map((hop, i) => {
+    const name = hop.name ?? "(anonymous)";
+    const calls = hop.callsFound.length > 0 ? hop.callsFound.join(", ") : "(none)";
+    return dedent`
+      ${i + 1}. depth:${hop.hopDepth} ${name}
+         ${hop.filePath}:${hop.startLine}
+         Calls: ${calls}
+    `.trim();
+  }).join("\n\n");
+}
+function formatContext(result) {
+  return result.content;
+}
+function formatPipelineLabel(tasks) {
+  return tasks.join(" -> ");
 }
 
 // src/services/capability.ts
@@ -103,6 +180,7 @@ var GLOBAL_CONFIG_DIR = join(homedir(), ".brain-cache");
 var PROFILE_PATH = join(GLOBAL_CONFIG_DIR, "profile.json");
 var CONFIG_PATH = join(GLOBAL_CONFIG_DIR, "config.json");
 var PROJECT_DATA_DIR = ".brain-cache";
+var SESSION_STATS_FILENAME = "session-stats.json";
 var EMBEDDING_DIMENSIONS = {
   "nomic-embed-text": 768,
   "mxbai-embed-large": 1024
@@ -114,13 +192,12 @@ var VECTOR_INDEX_THRESHOLD = 256;
 var EMBED_TIMEOUT_MS = 3e4;
 var COLD_START_RETRY_DELAY_MS = 2e3;
 var EMBED_MAX_TOKENS = 8192;
-var DEFAULT_SEARCH_LIMIT = 10;
-var DEFAULT_DISTANCE_THRESHOLD = 0.4;
-var DIAGNOSTIC_DISTANCE_THRESHOLD = 0.45;
-var DIAGNOSTIC_SEARCH_LIMIT = 20;
 var DEFAULT_TOKEN_BUDGET = 4096;
 var FILE_HASHES_FILENAME = "file-hashes.json";
 var TOOL_CALL_OVERHEAD_TOKENS = 300;
+var COMPRESSION_TOKEN_THRESHOLD = 500;
+var HIGH_RELEVANCE_SIMILARITY_THRESHOLD = 0.85;
+var COMPRESSION_HARD_LIMIT = 800;
 
 // src/services/capability.ts
 var execFileAsync = promisify(execFile);
@@ -272,6 +349,12 @@ import { Schema, Field, Utf8, Int32, Float32, FixedSizeList } from "apache-arrow
 import { join as join2 } from "path";
 import { readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
 var log3 = childLogger("lancedb");
+var _writeMutex = Promise.resolve();
+function withWriteLock(fn) {
+  const next = _writeMutex.then(() => fn());
+  _writeMutex = next.then(() => void 0, () => void 0);
+  return next;
+}
 function chunkSchema(dim) {
   return new Schema([
     new Field("id", new Utf8(), false),
@@ -289,6 +372,16 @@ function chunkSchema(dim) {
     )
   ]);
 }
+function edgeSchema() {
+  return new Schema([
+    new Field("from_chunk_id", new Utf8(), false),
+    new Field("from_file", new Utf8(), false),
+    new Field("from_symbol", new Utf8(), true),
+    new Field("to_symbol", new Utf8(), false),
+    new Field("to_file", new Utf8(), true),
+    new Field("edge_type", new Utf8(), false)
+  ]);
+}
 async function openDatabase(projectRoot) {
   const dataDir = join2(projectRoot, PROJECT_DATA_DIR);
   await mkdir2(dataDir, { recursive: true });
@@ -306,6 +399,10 @@ async function openOrCreateChunkTable(db, projectRoot, model, dim) {
         "Embedding model or dimension changed \u2014 dropping and recreating chunks table"
       );
       await db.dropTable("chunks");
+      if (tableNames.includes("edges")) {
+        await db.dropTable("edges");
+        log3.warn("Also dropped edges table (stale chunk IDs)");
+      }
     } else {
       log3.info({ model, dim }, "Opened existing chunks table");
       return db.openTable("chunks");
@@ -321,8 +418,10 @@ async function insertChunks(table, rows) {
   if (rows.length === 0) {
     return;
   }
-  await table.add(rows);
-  log3.debug({ count: rows.length }, "Inserted chunk rows");
+  await withWriteLock(async () => {
+    await table.add(rows);
+    log3.debug({ count: rows.length }, "Inserted chunk rows");
+  });
 }
 async function createVectorIndexIfNeeded(table, embeddingModel) {
   const rowCount = await table.countRows();
@@ -389,12 +488,50 @@ async function writeFileHashes(projectRoot, hashes) {
 }
 async function deleteChunksByFilePath(table, filePath) {
   const escaped = filePath.replace(/'/g, "''");
-  await table.delete(`file_path = '${escaped}'`);
+  await withWriteLock(async () => {
+    await table.delete(`file_path = '${escaped}'`);
+  });
+}
+async function openOrCreateEdgesTable(db, opts) {
+  const tableNames = await db.tableNames();
+  if (tableNames.includes("edges")) {
+    if (opts?.shouldReset) {
+      log3.warn("Resetting edges table (chunks table was recreated)");
+      await db.dropTable("edges");
+    } else {
+      log3.info("Opened existing edges table");
+      return db.openTable("edges");
+    }
+  }
+  const schema = edgeSchema();
+  const emptyData = lancedb.makeArrowTable([], { schema });
+  const table = await db.createTable("edges", emptyData, { mode: "overwrite" });
+  log3.info("Created new edges table");
+  return table;
+}
+async function insertEdges(table, edges) {
+  if (edges.length === 0) return;
+  const rows = edges.map((e) => ({
+    from_chunk_id: e.fromChunkId,
+    from_file: e.fromFile,
+    from_symbol: e.fromSymbol,
+    to_symbol: e.toSymbol,
+    to_file: e.toFile,
+    edge_type: e.edgeType
+  }));
+  await withWriteLock(async () => {
+    await table.add(rows);
+    log3.debug({ count: rows.length }, "Inserted edge rows");
+  });
+}
+async function queryEdgesFrom(edgesTable, fromChunkId) {
+  const escaped = fromChunkId.replace(/'/g, "''");
+  return edgesTable.query().where(`from_chunk_id = '${escaped}'`).toArray();
 }
 
 // src/workflows/index.ts
-import { resolve } from "path";
-import { readFile as readFile4 } from "fs/promises";
+import { resolve as resolve2 } from "path";
+import { readFile as readFile5 } from "fs/promises";
 import { createHash } from "crypto";
 
 // src/services/crawler.ts
@@ -431,13 +568,16 @@ var ALWAYS_EXCLUDE_GLOBS = [
   "**/Cargo.lock",
   "**/*.min.js"
 ];
-async function crawlSourceFiles(rootDir) {
+async function crawlSourceFiles(rootDir, opts) {
   const ig = ignore();
   try {
     const gitignoreContent = await readFile3(`${rootDir}/.gitignore`, "utf-8");
     ig.add(gitignoreContent);
   } catch {
   }
+  if (opts?.extraIgnorePatterns?.length) {
+    ig.add(opts.extraIgnorePatterns);
+  }
   const files = await fg("**/*", {
     cwd: rootDir,
     absolute: true,
@@ -456,7 +596,7 @@ async function crawlSourceFiles(rootDir) {
 
 // src/services/chunker.ts
 import { createRequire } from "module";
-import { extname as extname2 } from "path";
+import { extname as extname2, resolve, dirname } from "path";
 var _require = createRequire(import.meta.url);
 var Parser = _require("tree-sitter");
 var { typescript: tsLang, tsx: tsxLang } = _require("tree-sitter-typescript");
@@ -561,7 +701,7 @@ function chunkFile(filePath, content) {
   const ext = extname2(filePath);
   const lang = LANGUAGE_MAP[ext];
   if (!lang) {
-    return [];
+    return { chunks: [], edges: [] };
   }
   const category = getLanguageCategory(ext);
   const nodeTypes = CHUNK_NODE_TYPES[category];
@@ -569,7 +709,50 @@ function chunkFile(filePath, content) {
   parser.setLanguage(lang);
   const tree = parser.parse(content);
   const chunks = [];
+  const edges = [];
+  let currentChunkId = null;
+  let currentSymbol = null;
   for (const node of walkNodes(tree.rootNode)) {
+    if (node.type === "call_expression") {
+      const funcNode = node.childForFieldName("function");
+      if (funcNode) {
+        let toSymbol = null;
+        if (funcNode.type === "identifier") {
+          toSymbol = funcNode.text;
+        } else if (funcNode.type === "member_expression" || funcNode.type === "optional_member_expression") {
+          toSymbol = funcNode.childForFieldName("property")?.text ?? null;
+        }
+        if (toSymbol) {
+          const chunkId = currentChunkId ?? `${filePath}:0`;
+          const symbol = currentSymbol;
+          edges.push({
+            fromChunkId: chunkId,
+            fromFile: filePath,
+            fromSymbol: symbol,
+            toSymbol,
+            toFile: null,
+            // Resolved at query time, not index time
+            edgeType: "call"
+          });
+        }
+      }
+    }
+    if (node.type === "import_statement") {
+      const source = node.childForFieldName("source");
+      if (source) {
+        const raw = source.text.replace(/['"]/g, "");
+        const isRelative = raw.startsWith("./") || raw.startsWith("../");
+        const toFile = isRelative ? resolve(dirname(filePath), raw) : null;
+        edges.push({
+          fromChunkId: `${filePath}:0`,
+          fromFile: filePath,
+          fromSymbol: null,
+          toSymbol: raw,
+          toFile,
+          edgeType: "import"
+        });
+      }
+    }
     if (!nodeTypes.has(node.type)) {
       continue;
     }
@@ -595,6 +778,8 @@ function chunkFile(filePath, content) {
       startLine: node.startPosition.row + 1,
       endLine: node.endPosition.row + 1
     });
+    currentChunkId = `${filePath}:${node.startPosition.row}`;
+    currentSymbol = extractName(node);
   }
   if (chunks.length === 0) {
     chunks.push({
@@ -608,8 +793,8 @@ function chunkFile(filePath, content) {
       endLine: content.split("\n").length
     });
   }
-  log5.debug({ filePath, chunkCount: chunks.length }, "File chunked");
-  return chunks;
+  log5.debug({ filePath, chunkCount: chunks.length, edgeCount: edges.length }, "File chunked");
+  return { chunks, edges };
 }
 
 // src/services/embedder.ts
@@ -677,6 +862,18 @@ async function embedBatchWithRetry(model, texts, dimension = DEFAULT_EMBEDDING_D
   }
 }
 
+// src/services/ignorePatterns.ts
+import { readFile as readFile4 } from "fs/promises";
+import { join as join3 } from "path";
+async function loadIgnorePatterns(rootDir) {
+  try {
+    const content = await readFile4(join3(rootDir, ".braincacheignore"), "utf-8");
+    return content.split("\n").filter((line) => line.trim() !== "" && !line.startsWith("#"));
+  } catch {
+    return [];
+  }
+}
+
 // src/services/tokenCounter.ts
 import { countTokens } from "@anthropic-ai/tokenizer";
 var log7 = childLogger("tokenCounter");
@@ -725,7 +922,12 @@ async function runIndex(targetPath, opts) {
     return originalStderrWrite(chunk, ...args);
   });
   try {
-    const rootDir = resolve(targetPath ?? ".");
+    const rootDir = resolve2(targetPath ?? ".");
+    const ignorePatterns = await loadIgnorePatterns(rootDir);
+    if (ignorePatterns.length > 0) {
+      process.stderr.write(`brain-cache: loaded ${ignorePatterns.length} patterns from .braincacheignore
+`);
+    }
     const profile = await readProfile();
     if (profile === null) {
       throw new Error("No profile found. Run 'brain-cache init' first.");
@@ -743,7 +945,10 @@ async function runIndex(targetPath, opts) {
     }
     const db = await openDatabase(rootDir);
     const table = await openOrCreateChunkTable(db, rootDir, profile.embeddingModel, dim);
-    const files = await crawlSourceFiles(rootDir);
+    const edgesTable = await openOrCreateEdgesTable(db);
+    const files = await crawlSourceFiles(rootDir, {
+      extraIgnorePatterns: ignorePatterns.length > 0 ? ignorePatterns : void 0
+    });
     process.stderr.write(`brain-cache: found ${files.length} source files
 `);
     if (files.length === 0) {
@@ -757,7 +962,7 @@ async function runIndex(targetPath, opts) {
       const group = files.slice(groupStart, groupStart + FILE_READ_CONCURRENCY);
       const results = await Promise.all(
         group.map(async (filePath) => {
-          const content = await readFile4(filePath, "utf-8");
+          const content = await readFile5(filePath, "utf-8");
           return { filePath, content, hash: hashContent(content) };
         })
       );
@@ -793,6 +998,10 @@ async function runIndex(targetPath, opts) {
     );
     for (const filePath of [...removedFiles, ...changedFiles]) {
       await deleteChunksByFilePath(table, filePath);
+      await withWriteLock(async () => {
+        const escaped = filePath.replace(/'/g, "''");
+        await edgesTable.delete(`from_file = '${escaped}'`);
+      });
     }
     const updatedHashes = { ...storedHashes };
     for (const filePath of removedFiles) {
@@ -840,11 +1049,13 @@ async function runIndex(targetPath, opts) {
     for (let groupStart = 0; groupStart < filesToProcess.length; groupStart += FILE_READ_CONCURRENCY) {
       const group = filesToProcess.slice(groupStart, groupStart + FILE_READ_CONCURRENCY);
       const groupChunks = [];
+      const groupEdges = [];
       for (const filePath of group) {
         const content = contentMap.get(filePath);
         totalRawTokens += countChunkTokens(content);
-        const chunks = chunkFile(filePath, content);
+        const { chunks, edges } = chunkFile(filePath, content);
         groupChunks.push(...chunks);
+        groupEdges.push(...edges);
       }
       processedFiles += group.length;
       totalChunks += groupChunks.length;
@@ -885,6 +1096,9 @@ async function runIndex(targetPath, opts) {
 `
         );
       }
+      if (groupEdges.length > 0) {
+        await insertEdges(edgesTable, groupEdges);
+      }
     }
     if (skippedChunks > 0) {
       process.stderr.write(`brain-cache: ${skippedChunks} chunks skipped (too large for model context)
@@ -894,6 +1108,14 @@ async function runIndex(targetPath, opts) {
       `brain-cache: ${totalChunks} chunks from ${filesToProcess.length} files
 `
     );
+    const edgeCount = await edgesTable.countRows();
+    if (edgeCount === 0) {
+      process.stderr.write(`brain-cache: no call edges extracted \u2014 check source files
+`);
+    } else {
+      process.stderr.write(`brain-cache: ${edgeCount} call/import edges stored
+`);
+    }
     await createVectorIndexIfNeeded(table, profile.embeddingModel);
     for (const filePath of filesToProcess) {
       updatedHashes[filePath] = currentHashes[filePath];
@@ -936,31 +1158,22 @@ ${savingsBlock}
 }
 
 // src/workflows/search.ts
-import { resolve as resolve2 } from "path";
+import { resolve as resolve3 } from "path";
 
 // src/services/retriever.ts
 var log8 = childLogger("retriever");
-var DIAGNOSTIC_KEYWORDS = [
-  "why",
-  "broken",
-  "error",
-  "bug",
-  "fail",
-  "crash",
-  "exception",
-  "undefined",
-  "null",
-  "wrong",
-  "issue",
-  "problem",
-  "causes",
-  "caused",
-  "debug",
-  "fix",
-  "incorrect",
-  "unexpected"
+var TRACE_KEYWORDS = [
+  "trace the",
+  "trace flow",
+  "call path",
+  "flow of",
+  "follows from",
+  "calls into",
+  "invokes",
+  "trace from"
 ];
-var DIAGNOSTIC_BIGRAMS = [
+var TRACE_REGEX = /how does\b.*\bflow\b/i;
+var LOOKUP_BIGRAMS = [
   "stack trace",
   "null pointer",
   "not defined",
@@ -972,7 +1185,16 @@ var DIAGNOSTIC_BIGRAMS = [
   "not working",
   "throws exception"
 ];
-var DIAGNOSTIC_EXCLUSIONS = [
+var LOOKUP_KEYWORDS = [
+  "where is",
+  "find the",
+  "definition of",
+  "signature of",
+  "show me the",
+  "what does",
+  "what is the type"
+];
+var EXPLORE_EXCLUSIONS = [
   "error handler",
   "error handling",
   "error boundary",
@@ -990,28 +1212,82 @@ var DIAGNOSTIC_EXCLUSIONS = [
   "fix the config",
   "fix the setup"
 ];
-function classifyQueryIntent(query) {
+function classifyRetrievalMode(query) {
   const lower = query.toLowerCase();
-  if (DIAGNOSTIC_BIGRAMS.some((bg) => lower.includes(bg))) {
-    return "diagnostic";
+  if (TRACE_KEYWORDS.some((kw) => lower.includes(kw)) || TRACE_REGEX.test(lower)) {
+    const broadTerms = ["architecture", "overview", "structure", "system", "design", "pipeline", "codebase"];
+    const isBroad = broadTerms.some((t) => lower.includes(t));
+    if (!isBroad) {
+      return "trace";
+    }
+  }
+  if (LOOKUP_BIGRAMS.some((bg) => lower.includes(bg))) {
+    return "lookup";
   }
-  const hasKeyword = DIAGNOSTIC_KEYWORDS.some((kw) => lower.includes(kw));
-  if (hasKeyword) {
-    const isExcluded = DIAGNOSTIC_EXCLUSIONS.some((ex) => lower.includes(ex));
+  const hasLookupKeyword = LOOKUP_KEYWORDS.some((kw) => lower.includes(kw));
+  if (hasLookupKeyword) {
+    const isExcluded = EXPLORE_EXCLUSIONS.some((ex) => lower.includes(ex));
     if (!isExcluded) {
-      return "diagnostic";
+      return "lookup";
     }
   }
-  return "knowledge";
+  return "explore";
 }
 var RETRIEVAL_STRATEGIES = {
-  diagnostic: { limit: DIAGNOSTIC_SEARCH_LIMIT, distanceThreshold: DIAGNOSTIC_DISTANCE_THRESHOLD },
-  knowledge: { limit: DEFAULT_SEARCH_LIMIT, distanceThreshold: DEFAULT_DISTANCE_THRESHOLD }
+  lookup: { limit: 5, distanceThreshold: 0.4, keywordBoostWeight: 0.4 },
+  trace: { limit: 3, distanceThreshold: 0.5, keywordBoostWeight: 0.2 },
+  explore: { limit: 20, distanceThreshold: 0.6, keywordBoostWeight: 0.1 }
 };
-async function searchChunks(table, queryVector, opts) {
+function extractQueryTokens(query) {
+  return query.toLowerCase().split(/[\s.,;:!?'"()\[\]{}/\\]+/).filter((t) => t.length >= 3);
+}
+function splitCamelCase(name) {
+  return name.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().split(/\s+/).filter((t) => t.length >= 2);
+}
+function computeKeywordBoost(chunk, queryTokens) {
+  if (queryTokens.length === 0) return 0;
+  const fileName = chunk.filePath.split("/").pop()?.toLowerCase() ?? "";
+  const fileNameStem = fileName.replace(/\.[^.]+$/, "");
+  const chunkName = (chunk.name ?? "").toLowerCase();
+  if (chunkName.length > 0 && queryTokens.some((t) => t === chunkName)) {
+    return 1;
+  }
+  const subTokens = chunkName.length > 0 ? splitCamelCase(chunkName) : [];
+  if (subTokens.length > 1 && subTokens.every((sub) => queryTokens.some((t) => t.includes(sub) || sub.includes(t)))) {
+    return 1;
+  }
+  if (fileNameStem.length > 0 && queryTokens.some((t) => t === fileNameStem)) {
+    return 0.6;
+  }
+  const target = `${fileName} ${chunkName}`;
+  const matchCount = queryTokens.filter((t) => target.includes(t)).length;
+  return matchCount / queryTokens.length;
+}
+var CONFIG_NOISE_PATTERNS = [
+  { pattern: /^vitest\.config\./, toolName: "vitest" },
+  { pattern: /^tsup\.config\./, toolName: "tsup" },
+  { pattern: /^tsconfig.*\.json$/, toolName: "tsconfig" },
+  { pattern: /^jest\.config\./, toolName: "jest" },
+  { pattern: /^eslint\.config\./, toolName: "eslint" },
+  { pattern: /^\.eslintrc/, toolName: "eslint" }
+];
+var CONFIG_FILE_NOISE_PENALTY = 0.15;
+function computeNoisePenalty(chunk, query) {
+  const fileName = chunk.filePath.split("/").pop() ?? "";
+  const lowerQuery = query.toLowerCase();
+  for (const { pattern, toolName } of CONFIG_NOISE_PATTERNS) {
+    if (pattern.test(fileName)) {
+      if (lowerQuery.includes(toolName)) return 0;
+      return CONFIG_FILE_NOISE_PENALTY;
+    }
+  }
+  return 0;
+}
+async function searchChunks(table, queryVector, opts, query) {
   log8.debug({ limit: opts.limit, distanceThreshold: opts.distanceThreshold }, "Searching chunks");
   const rows = await table.query().nearestTo(queryVector).distanceType("cosine").limit(opts.limit).toArray();
-  return rows.filter((r) => r._distance <= opts.distanceThreshold).map((r) => ({
+  const queryTokens = query ? extractQueryTokens(query) : [];
+  const chunks = rows.filter((r) => r._distance <= opts.distanceThreshold).map((r) => ({
     id: r.id,
     filePath: r.file_path,
     chunkType: r.chunk_type,
@@ -1021,7 +1297,18 @@ async function searchChunks(table, queryVector, opts) {
     startLine: r.start_line,
     endLine: r.end_line,
     similarity: 1 - r._distance
-  })).sort((a, b) => b.similarity - a.similarity);
+  }));
+  if (queryTokens.length > 0) {
+    const boostWeight = opts.keywordBoostWeight ?? 0.1;
+    const scored = chunks.map((chunk) => {
+      const boost = computeKeywordBoost(chunk, queryTokens);
+      const score = chunk.similarity * (1 - boostWeight) + boost * boostWeight - computeNoisePenalty(chunk, query);
+      const promotedSimilarity = boost > 0 ? Math.max(chunk.similarity, HIGH_RELEVANCE_SIMILARITY_THRESHOLD) : chunk.similarity;
+      return { chunk: { ...chunk, similarity: promotedSimilarity }, score };
+    });
+    return scored.sort((a, b) => b.score - a.score).map(({ chunk }) => chunk);
+  }
+  return chunks.sort((a, b) => b.similarity - a.similarity);
 }
 function deduplicateChunks(chunks) {
   const seen = /* @__PURE__ */ new Set();
@@ -1044,7 +1331,7 @@ async function runSearch(query, opts) {
       "Ollama is not running. Start it with 'ollama serve' or run 'brain-cache init'."
     );
   }
-  const rootDir = resolve2(opts?.path ?? ".");
+  const rootDir = resolve3(opts?.path ?? ".");
   const indexState = await readIndexState(rootDir);
   if (indexState === null) {
     throw new Error(
@@ -1063,18 +1350,19 @@ async function runSearch(query, opts) {
       `Index is empty at ${rootDir}. No source files were indexed.`
     );
   }
-  const intent = classifyQueryIntent(query);
+  const mode = classifyRetrievalMode(query);
   const strategy = {
-    limit: opts?.limit ?? RETRIEVAL_STRATEGIES[intent].limit,
-    distanceThreshold: RETRIEVAL_STRATEGIES[intent].distanceThreshold
+    limit: opts?.limit ?? RETRIEVAL_STRATEGIES[mode].limit,
+    distanceThreshold: RETRIEVAL_STRATEGIES[mode].distanceThreshold,
+    keywordBoostWeight: RETRIEVAL_STRATEGIES[mode].keywordBoostWeight
   };
   process.stderr.write(
-    `brain-cache: searching (intent=${intent}, limit=${strategy.limit})
+    `brain-cache: searching (mode=${mode}, limit=${strategy.limit})
 `
   );
   const { embeddings: vectors } = await embedBatchWithRetry(indexState.embeddingModel, [query]);
   const queryVector = vectors[0];
-  const results = await searchChunks(table, queryVector, strategy);
+  const results = await searchChunks(table, queryVector, strategy, query);
   const deduped = deduplicateChunks(results);
   process.stderr.write(
     `brain-cache: found ${deduped.length} chunks (${results.length} before dedup)
@@ -1090,8 +1378,798 @@ async function runSearch(query, opts) {
 }
 
 // src/workflows/buildContext.ts
-import { readFile as readFile5 } from "fs/promises";
-import { resolve as resolve3 } from "path";
+import { readFile as readFile9 } from "fs/promises";
+import { resolve as resolve6 } from "path";
+
+// src/services/cohesion.ts
+import { dirname as dirname2, relative as relative2, basename } from "path";
+var log9 = childLogger("cohesion");
+function groupChunksByFile(chunks) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const chunk of chunks) {
+    const group = groups.get(chunk.filePath);
+    if (group === void 0) {
+      groups.set(chunk.filePath, [chunk]);
+    } else {
+      group.push(chunk);
+    }
+  }
+  for (const [, group] of groups) {
+    group.sort((a, b) => a.startLine - b.startLine);
+  }
+  return groups;
+}
+async function enrichWithParentClass(chunks, chunksTable, opts) {
+  const existingIds = new Set(chunks.map((c) => c.id));
+  const result = [...chunks];
+  let { currentTokens } = opts;
+  const parentsToInsert = [];
+  for (const chunk of chunks) {
+    if (chunk.chunkType !== "method" || chunk.scope === null) {
+      continue;
+    }
+    const escapedScope = chunk.scope.replace(/'/g, "''");
+    const escapedFilePath = chunk.filePath.replace(/'/g, "''");
+    log9.debug({ scope: chunk.scope, filePath: chunk.filePath }, "Looking for parent class");
+    const rows = await chunksTable.query().where(`name = '${escapedScope}' AND file_path = '${escapedFilePath}' AND chunk_type = 'class'`).toArray();
+    if (rows.length === 0) {
+      continue;
+    }
+    const row = rows[0];
+    if (existingIds.has(row.id)) {
+      continue;
+    }
+    const parentChunk = {
+      id: row.id,
+      filePath: row.file_path,
+      chunkType: row.chunk_type,
+      scope: row.scope,
+      name: row.name,
+      content: row.content,
+      startLine: row.start_line,
+      endLine: row.end_line,
+      similarity: 1
+    };
+    const tokenCost = countChunkTokens(formatChunk(parentChunk));
+    if (currentTokens + tokenCost > opts.maxTokens) {
+      log9.debug({ parentId: row.id, tokenCost, currentTokens, maxTokens: opts.maxTokens }, "Skipping parent class \u2014 token budget exceeded");
+      continue;
+    }
+    existingIds.add(row.id);
+    currentTokens += tokenCost;
+    parentsToInsert.push({ parent: parentChunk, beforeId: chunk.id });
+  }
+  for (const { parent, beforeId } of parentsToInsert) {
+    const idx = result.findIndex((c) => c.id === beforeId);
+    if (idx !== -1) {
+      result.splice(idx, 0, parent);
+    }
+  }
+  return result;
+}
+function formatGroupedContext(groups) {
+  const sections = [];
+  for (const [filePath, chunks] of groups) {
+    const header = `// \u2500\u2500 ${filePath} \u2500\u2500`;
+    const body = chunks.map(formatChunk).join("\n\n");
+    sections.push(`${header}
+${body}`);
+  }
+  return sections.join("\n\n---\n\n");
+}
+function extractBehavioralSummary(content) {
+  const lines = content.split("\n");
+  const jsDocLines = [];
+  let inJsDoc = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("// [compressed]") || trimmed.startsWith("// Signature:") || trimmed.startsWith("// [body stripped]")) continue;
+    if (trimmed.startsWith("/**")) {
+      inJsDoc = true;
+      jsDocLines.push(line);
+      if (trimmed.endsWith("*/")) break;
+      continue;
+    }
+    if (inJsDoc) {
+      jsDocLines.push(line);
+      if (trimmed.endsWith("*/")) break;
+      continue;
+    }
+  }
+  if (jsDocLines.length === 0) return null;
+  const descLines = jsDocLines.map((l) => l.replace(/^\s*\/?\*+\s?/, "").replace(/\s*\*\/.*$/, "").trim()).filter((l) => l.length > 0 && !l.startsWith("@") && l !== "/");
+  return descLines[0] ?? null;
+}
+function groupChunksByModule(chunks, rootDir) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const chunk of chunks) {
+    const rel = relative2(rootDir, chunk.filePath);
+    const moduleKey = dirname2(rel) || ".";
+    const group = groups.get(moduleKey);
+    if (group === void 0) groups.set(moduleKey, [chunk]);
+    else group.push(chunk);
+  }
+  for (const [, group] of groups) {
+    group.sort((a, b) => a.startLine - b.startLine);
+  }
+  return groups;
+}
+function extractWiringAnnotations(chunks) {
+  const importPattern = /from\s+['"](\.[^'"]+)['"]/g;
+  const internalDeps = /* @__PURE__ */ new Set();
+  for (const chunk of chunks) {
+    for (const match of chunk.content.matchAll(importPattern)) {
+      const importPath = match[1];
+      const stem = importPath.replace(/\.js$/, "").split("/").pop();
+      if (stem && stem.length > 1) {
+        internalDeps.add(stem);
+      }
+    }
+  }
+  return [...internalDeps].sort();
+}
+function formatModuleNarratives(groups) {
+  const sections = [];
+  for (const [moduleKey, chunks] of groups) {
+    const lines = [`### module: ${moduleKey}`];
+    const byFile = /* @__PURE__ */ new Map();
+    for (const chunk of chunks) {
+      const file = chunk.filePath;
+      const group = byFile.get(file);
+      if (group === void 0) byFile.set(file, [chunk]);
+      else group.push(chunk);
+    }
+    for (const [filePath, fileChunks] of byFile) {
+      const fileName = basename(filePath);
+      const summary = extractBehavioralSummary(fileChunks[0].content);
+      if (summary) {
+        lines.push(`
+**${fileName}** -- ${summary}`);
+      } else {
+        lines.push(`
+**${fileName}**`);
+      }
+      const wiring = extractWiringAnnotations(fileChunks);
+      if (wiring.length > 0) {
+        lines.push(`  imports: ${wiring.join(", ")}`);
+      }
+    }
+    sections.push(lines.join("\n"));
+  }
+  return sections.join("\n\n");
+}
+
+// src/services/compression.ts
+function compressChunk(chunk) {
+  const tokens = countChunkTokens(chunk.content);
+  if (tokens <= COMPRESSION_TOKEN_THRESHOLD) return chunk;
+  const isHighRelevance = chunk.similarity >= HIGH_RELEVANCE_SIMILARITY_THRESHOLD;
+  if (tokens <= COMPRESSION_HARD_LIMIT && isHighRelevance) {
+    return chunk;
+  }
+  const lines = chunk.content.split("\n");
+  const jsDocLines = [];
+  let signatureLine = "";
+  let inJsDoc = false;
+  let jsDocDone = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!jsDocDone) {
+      if (trimmed.startsWith("/**")) {
+        inJsDoc = true;
+        jsDocLines.push(line);
+        if (trimmed.endsWith("*/")) {
+          inJsDoc = false;
+          jsDocDone = true;
+        }
+        continue;
+      }
+      if (inJsDoc) {
+        jsDocLines.push(line);
+        if (trimmed.endsWith("*/")) {
+          inJsDoc = false;
+          jsDocDone = true;
+        }
+        continue;
+      }
+    }
+    if (trimmed.length > 0 && signatureLine === "") {
+      signatureLine = line;
+      break;
+    }
+  }
+  if (signatureLine === "" && jsDocLines.length === 0) {
+    signatureLine = lines.find((l) => l.trim().length > 0) ?? "";
+  }
+  const manifestParts = [
+    `// [compressed] ${chunk.name ?? "unknown"} (lines ${chunk.startLine}-${chunk.endLine})`
+  ];
+  if (jsDocLines.length > 0) {
+    manifestParts.push(...jsDocLines);
+  }
+  manifestParts.push(`// Signature: ${signatureLine}`);
+  manifestParts.push("// [body stripped]");
+  return { ...chunk, content: manifestParts.join("\n") };
+}
+
+// src/services/configLoader.ts
+import { readFile as readFile6 } from "fs/promises";
+var log10 = childLogger("configLoader");
+async function loadUserConfig() {
+  try {
+    const raw = await readFile6(CONFIG_PATH, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    log10.debug({ configPath: CONFIG_PATH }, "Config file not found or invalid \u2014 using defaults");
+    return {};
+  }
+}
+function resolveStrategy(mode, userConfig, toolOverride) {
+  const base = RETRIEVAL_STRATEGIES[mode];
+  const userOverride = userConfig.retrieval?.[mode] ?? {};
+  return { ...base, ...userOverride, ...toolOverride };
+}
+
+// src/workflows/traceFlow.ts
+import { resolve as resolve4 } from "path";
+import { readFile as readFile7 } from "fs/promises";
+
+// src/services/flowTracer.ts
+var log11 = childLogger("flowTracer");
+async function resolveSymbolToChunkId(chunksTable, toSymbol, fromFile) {
+  const escaped = toSymbol.replace(/'/g, "''");
+  const rows = await chunksTable.query().where(`name = '${escaped}'`).toArray();
+  if (rows.length === 0) {
+    return null;
+  }
+  const sameFile = rows.find((r) => r.file_path === fromFile);
+  return (sameFile ?? rows[0]).id;
+}
+async function traceFlow(edgesTable, chunksTable, seedChunkId, opts) {
+  const maxHops = opts?.maxHops ?? 3;
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [{ chunkId: seedChunkId, depth: 0 }];
+  const hops = [];
+  log11.debug({ seedChunkId, maxHops }, "Starting BFS flow trace");
+  while (queue.length > 0) {
+    const { chunkId, depth } = queue.shift();
+    if (visited.has(chunkId)) {
+      continue;
+    }
+    visited.add(chunkId);
+    const escapedId = chunkId.replace(/'/g, "''");
+    const chunkRows = await chunksTable.query().where(`id = '${escapedId}'`).toArray();
+    if (chunkRows.length === 0) {
+      log11.debug({ chunkId }, "Chunk not found \u2014 skipping hop");
+      continue;
+    }
+    const row = chunkRows[0];
+    const edges = await queryEdgesFrom(edgesTable, chunkId);
+    const callEdges = edges.filter((e) => e.edge_type === "call");
+    hops.push({
+      chunkId,
+      filePath: row.file_path,
+      name: row.name,
+      startLine: row.start_line,
+      endLine: row.end_line,
+      content: row.content,
+      hopDepth: depth,
+      callsFound: [...new Set(callEdges.map((e) => e.to_symbol))]
+    });
+    if (depth >= maxHops) {
+      continue;
+    }
+    for (const edge of callEdges) {
+      const nextChunkId = await resolveSymbolToChunkId(chunksTable, edge.to_symbol, edge.from_file);
+      if (nextChunkId !== null && !visited.has(nextChunkId)) {
+        queue.push({ chunkId: nextChunkId, depth: depth + 1 });
+      }
+    }
+  }
+  log11.debug({ seedChunkId, hopsFound: hops.length, maxDepthReached: hops.length > 0 ? Math.max(...hops.map((h) => h.hopDepth)) : 0 }, "BFS flow trace complete");
+  return hops;
+}
+
+// src/workflows/traceFlow.ts
+var BODY_STRIPPED_MARKER = "// [body stripped]";
+var TEST_FILE_PATTERNS = [".test.", ".spec.", "/__tests__/", "/tests/"];
+function isTestFile(filePath) {
+  return TEST_FILE_PATTERNS.some((p) => filePath.includes(p));
+}
+var STDLIB_SYMBOLS = /* @__PURE__ */ new Set([
+  // Array
+  "map",
+  "filter",
+  "reduce",
+  "forEach",
+  "find",
+  "findIndex",
+  "some",
+  "every",
+  "includes",
+  "push",
+  "pop",
+  "shift",
+  "unshift",
+  "splice",
+  "slice",
+  "concat",
+  "join",
+  "sort",
+  "reverse",
+  "flat",
+  "flatMap",
+  "fill",
+  "indexOf",
+  "lastIndexOf",
+  // Set/Map
+  "keys",
+  "values",
+  "entries",
+  "has",
+  "get",
+  "set",
+  "delete",
+  "add",
+  "clear",
+  // Promise
+  "resolve",
+  "reject",
+  "then",
+  "catch",
+  "finally",
+  "all",
+  "race",
+  "allSettled",
+  // Object
+  "toString",
+  "valueOf",
+  "hasOwnProperty",
+  "assign",
+  "freeze",
+  "create",
+  // String
+  "split",
+  "replace",
+  "replaceAll",
+  "match",
+  "matchAll",
+  "trim",
+  "trimStart",
+  "trimEnd",
+  "startsWith",
+  "endsWith",
+  "padStart",
+  "padEnd",
+  "repeat",
+  "charAt",
+  "charCodeAt",
+  "substring",
+  "toLowerCase",
+  "toUpperCase",
+  // Property-like
+  "length"
+]);
+var LOW_CONFIDENCE_THRESHOLD = 0.5;
+function isCLIQuery(query) {
+  const lower = query.toLowerCase();
+  return lower.includes(" cli ") || lower.startsWith("cli ") || lower.includes("command");
+}
+function isCLIFile(filePath) {
+  return filePath.includes("/cli/");
+}
+async function computeHopSavings(hops) {
+  if (hops.length === 0) {
+    return { tokensSent: 0, estimatedWithoutBraincache: 0, reductionPct: 0, filesInContext: 0 };
+  }
+  const tokensSent = hops.reduce((sum, h) => sum + countChunkTokens(h.content), 0);
+  const uniqueFiles = [...new Set(hops.map((h) => h.filePath))];
+  const filesInContext = uniqueFiles.length;
+  const filesWithUncompressedContent = new Set(
+    hops.filter((h) => !h.content.includes(BODY_STRIPPED_MARKER)).map((h) => h.filePath)
+  );
+  let fileContentTokens = 0;
+  for (const filePath of uniqueFiles) {
+    if (!filesWithUncompressedContent.has(filePath)) continue;
+    try {
+      const fileContent = await readFile7(filePath, "utf-8");
+      fileContentTokens += countChunkTokens(fileContent);
+    } catch {
+    }
+  }
+  const toolCalls = 1 + filesInContext;
+  const toolCallOverhead = toolCalls * TOOL_CALL_OVERHEAD_TOKENS;
+  const estimatedWithoutBraincache = fileContentTokens + toolCallOverhead;
+  const reductionPct = estimatedWithoutBraincache > 0 ? Math.max(0, Math.round((1 - tokensSent / estimatedWithoutBraincache) * 100)) : 0;
+  return { tokensSent, estimatedWithoutBraincache, reductionPct, filesInContext };
+}
+function extractSymbolCandidate(query) {
+  const tokens = query.match(/\b[a-zA-Z_][a-zA-Z0-9_]{2,}\b/g);
+  if (!tokens) return null;
+  const stopWords = /* @__PURE__ */ new Set([
+    "how",
+    "does",
+    "work",
+    "the",
+    "what",
+    "where",
+    "trace",
+    "flow",
+    "call",
+    "path",
+    "find",
+    "show",
+    "into",
+    "from",
+    "this",
+    "that",
+    "with",
+    "when",
+    "which",
+    "about",
+    "explain",
+    "describe"
+  ]);
+  const camel = tokens.filter((t) => /[a-z][A-Z]/.test(t));
+  if (camel.length > 0) return camel[camel.length - 1];
+  const nonStop = tokens.filter((t) => !stopWords.has(t.toLowerCase()));
+  return nonStop.length > 0 ? nonStop[nonStop.length - 1] : null;
+}
+async function runTraceFlow(entrypoint, opts) {
+  const profile = await readProfile();
+  if (profile === null) {
+    throw new Error("No profile found. Run 'brain-cache init' first.");
+  }
+  const running = await isOllamaRunning();
+  if (!running) {
+    throw new Error("Ollama is not running.");
+  }
+  const rootDir = resolve4(opts?.path ?? ".");
+  const indexState = await readIndexState(rootDir);
+  if (indexState === null) {
+    throw new Error(`No index found at ${rootDir}. Run 'brain-cache index' first.`);
+  }
+  const db = await openDatabase(rootDir);
+  const tableNames = await db.tableNames();
+  if (!tableNames.includes("chunks")) {
+    throw new Error("No chunks table found. Run 'brain-cache index' first.");
+  }
+  const table = await db.openTable("chunks");
+  if (!tableNames.includes("edges")) {
+    throw new Error("No edges table found. Re-run 'brain-cache index' to build call edges.");
+  }
+  const edgesTable = await db.openTable("edges");
+  const userConfig = await loadUserConfig();
+  const toolOverride = {};
+  if (opts?.limit !== void 0) toolOverride.limit = opts.limit;
+  if (opts?.distanceThreshold !== void 0) toolOverride.distanceThreshold = opts.distanceThreshold;
+  const strategy = resolveStrategy("trace", userConfig, Object.keys(toolOverride).length > 0 ? toolOverride : void 0);
+  const candidate = extractSymbolCandidate(entrypoint);
+  let seedChunkId = null;
+  if (candidate !== null) {
+    seedChunkId = await resolveSymbolToChunkId(table, candidate, "");
+  }
+  if (seedChunkId !== null) {
+    const maxHops2 = opts?.maxHops ?? 3;
+    const flowHops2 = await traceFlow(edgesTable, table, seedChunkId, { maxHops: maxHops2 });
+    const productionHops2 = flowHops2.filter((hop) => !isTestFile(hop.filePath));
+    const hops2 = productionHops2.map((hop) => {
+      const asChunk = {
+        id: hop.chunkId,
+        filePath: hop.filePath,
+        chunkType: "function",
+        scope: null,
+        name: hop.name,
+        content: hop.content,
+        startLine: hop.startLine,
+        endLine: hop.endLine,
+        similarity: 1
+      };
+      const compressed = compressChunk(asChunk);
+      return {
+        filePath: hop.filePath,
+        name: hop.name,
+        startLine: hop.startLine,
+        content: compressed.content,
+        callsFound: hop.callsFound.filter((s) => !STDLIB_SYMBOLS.has(s)),
+        // TRACE-02
+        hopDepth: hop.hopDepth
+      };
+    });
+    const exactSavings = await computeHopSavings(hops2);
+    return {
+      hops: hops2,
+      metadata: {
+        seedChunkId,
+        totalHops: hops2.length,
+        localTasksPerformed: ["exact_name_lookup", "bfs_trace", "compress"],
+        ...exactSavings,
+        confidenceWarning: null
+      }
+    };
+  }
+  const { embeddings } = await embedBatchWithRetry(indexState.embeddingModel, [entrypoint]);
+  const seedResults = await searchChunks(table, embeddings[0], strategy, entrypoint);
+  const seeds = deduplicateChunks(seedResults);
+  if (seeds.length === 0) {
+    return {
+      hops: [],
+      metadata: {
+        seedChunkId: null,
+        totalHops: 0,
+        localTasksPerformed: ["embed_query", "seed_search"],
+        tokensSent: 0,
+        estimatedWithoutBraincache: 0,
+        reductionPct: 0,
+        filesInContext: 0
+      }
+    };
+  }
+  let selectedSeed = seeds[0];
+  if (isCLIQuery(entrypoint)) {
+    const cliSeed = seeds.find((s) => isCLIFile(s.filePath));
+    if (cliSeed) selectedSeed = cliSeed;
+  }
+  let confidenceWarning = null;
+  if (selectedSeed.similarity < LOW_CONFIDENCE_THRESHOLD) {
+    const seedName = selectedSeed.name ?? "unknown";
+    const seedFile = selectedSeed.filePath.split("/").pop() ?? selectedSeed.filePath;
+    confidenceWarning = `No confident match for "${entrypoint}" \u2014 tracing nearest match: ${seedName} (${seedFile}:${selectedSeed.startLine}, similarity: ${selectedSeed.similarity.toFixed(2)})`;
+  }
+  const maxHops = opts?.maxHops ?? 3;
+  const flowHops = await traceFlow(edgesTable, table, selectedSeed.id, { maxHops });
+  const productionHops = flowHops.filter((hop) => !isTestFile(hop.filePath));
+  const hops = productionHops.map((hop) => {
+    const asChunk = {
+      id: hop.chunkId,
+      filePath: hop.filePath,
+      chunkType: "function",
+      scope: null,
+      name: hop.name,
+      content: hop.content,
+      startLine: hop.startLine,
+      endLine: hop.endLine,
+      similarity: 1
+    };
+    const compressed = compressChunk(asChunk);
+    return {
+      filePath: hop.filePath,
+      name: hop.name,
+      startLine: hop.startLine,
+      content: compressed.content,
+      callsFound: hop.callsFound.filter((s) => !STDLIB_SYMBOLS.has(s)),
+      // TRACE-02
+      hopDepth: hop.hopDepth
+    };
+  });
+  const savings = await computeHopSavings(hops);
+  return {
+    hops,
+    metadata: {
+      seedChunkId: selectedSeed.id,
+      totalHops: hops.length,
+      localTasksPerformed: ["embed_query", "seed_search", "bfs_trace", "compress"],
+      ...savings,
+      confidenceWarning
+    }
+  };
+}
+
+// src/workflows/explainCodebase.ts
+import { readFile as readFile8 } from "fs/promises";
+import { resolve as resolve5, relative as relative3, dirname as dirname3 } from "path";
+function isExportedChunk(chunk) {
+  if (chunk.chunkType === "file") return true;
+  const lines = chunk.content.split("\n");
+  let inJsDoc = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("/**")) {
+      inJsDoc = true;
+      if (trimmed.endsWith("*/")) {
+        inJsDoc = false;
+      }
+      continue;
+    }
+    if (inJsDoc) {
+      if (trimmed.endsWith("*/")) inJsDoc = false;
+      continue;
+    }
+    if (trimmed.startsWith("// [compressed]") || trimmed.startsWith("// Signature:") || trimmed.startsWith("// [body stripped]")) continue;
+    if (trimmed.length === 0) continue;
+    return trimmed.startsWith("export ");
+  }
+  return false;
+}
+var FALLBACK_QUERY = "module structure and component responsibilities";
+var ARCHITECTURE_QUERIES = [
+  FALLBACK_QUERY,
+  "entry points, CLI commands, and main application flow",
+  "core services, business logic, and data processing",
+  "data models, types, schemas, and configuration"
+];
+function buildDirectoryTree(filePaths, rootDir) {
+  const relativePaths = [
+    ...new Set(filePaths.map((fp) => relative3(rootDir, fp)))
+  ].sort();
+  const byDir = /* @__PURE__ */ new Map();
+  for (const rel of relativePaths) {
+    const dir = dirname3(rel);
+    if (!byDir.has(dir)) byDir.set(dir, []);
+    byDir.get(dir).push(rel);
+  }
+  const lines = [];
+  const dirs = [...byDir.keys()].sort();
+  for (let di = 0; di < dirs.length; di++) {
+    const dir = dirs[di];
+    const files = byDir.get(dir);
+    const isLastDir = di === dirs.length - 1;
+    if (dir !== ".") {
+      lines.push(`${isLastDir ? "\u2514\u2500\u2500" : "\u251C\u2500\u2500"} ${dir}/`);
+    }
+    for (let fi = 0; fi < files.length; fi++) {
+      const isLastFile = fi === files.length - 1;
+      const fileName = files[fi].includes("/") ? files[fi].split("/").pop() : files[fi];
+      const indent = dir !== "." ? "    " : "";
+      const isLast = isLastFile && (isLastDir || dir === ".");
+      lines.push(`${indent}${isLast ? "\u2514\u2500\u2500" : "\u251C\u2500\u2500"} ${fileName}`);
+    }
+  }
+  return lines.join("\n");
+}
+async function runExplainCodebase(opts) {
+  const profile = await readProfile();
+  if (profile === null) {
+    throw new Error("No profile found. Run 'brain-cache init' first.");
+  }
+  const running = await isOllamaRunning();
+  if (!running) {
+    throw new Error("Ollama is not running.");
+  }
+  const rootDir = resolve5(opts?.path ?? ".");
+  const indexState = await readIndexState(rootDir);
+  if (indexState === null) {
+    throw new Error(
+      `No index found at ${rootDir}. Run 'brain-cache index' first.`
+    );
+  }
+  const db = await openDatabase(rootDir);
+  const tableNames = await db.tableNames();
+  if (!tableNames.includes("chunks")) {
+    throw new Error("No chunks table found. Run 'brain-cache index' first.");
+  }
+  const table = await db.openTable("chunks");
+  const userConfig = await loadUserConfig();
+  const toolOverride = {};
+  if (opts?.limit !== void 0) toolOverride.limit = opts.limit;
+  if (opts?.distanceThreshold !== void 0)
+    toolOverride.distanceThreshold = opts.distanceThreshold;
+  const strategy = resolveStrategy(
+    "explore",
+    userConfig,
+    Object.keys(toolOverride).length > 0 ? toolOverride : void 0
+  );
+  const maxTokens = opts?.maxTokens ?? DEFAULT_TOKEN_BUDGET * 2;
+  const customQuestion = opts?.question;
+  const queries = customQuestion ? [customQuestion] : ARCHITECTURE_QUERIES;
+  process.stderr.write(
+    `brain-cache: explaining codebase (budget=${maxTokens} tokens, queries=${queries.length})
+`
+  );
+  const { embeddings } = await embedBatchWithRetry(indexState.embeddingModel, queries);
+  const allResults = await Promise.all(
+    embeddings.map((vec) => searchChunks(table, vec, strategy))
+  );
+  const merged = allResults.flat();
+  const deduped = deduplicateChunks(merged);
+  let allFilePaths = [];
+  try {
+    const allRows = await table.query().toArray();
+    allFilePaths = [...new Set(allRows.map((r) => r.file_path))].sort();
+  } catch {
+    allFilePaths = [];
+  }
+  const sorted = [...deduped].sort((a, b) => {
+    const aIsTest = /\/(tests?|__tests__|spec)\//i.test(a.filePath) || /\.(test|spec)\./i.test(a.filePath);
+    const bIsTest = /\/(tests?|__tests__|spec)\//i.test(b.filePath) || /\.(test|spec)\./i.test(b.filePath);
+    if (aIsTest === bIsTest) return 0;
+    return aIsTest ? 1 : -1;
+  });
+  const exportedOnly = sorted.filter(isExportedChunk);
+  const assembled = assembleContext(exportedOnly, { maxTokens });
+  const enriched = await enrichWithParentClass(assembled.chunks, table, {
+    maxTokens,
+    currentTokens: assembled.tokenCount
+  });
+  const compressed = enriched.map((c) => {
+    const tokens = countChunkTokens(c.content);
+    return tokens > 500 ? compressChunk(c) : c;
+  });
+  const moduleGroups = groupChunksByModule(compressed, rootDir);
+  const codeContent = formatModuleNarratives(moduleGroups);
+  const treeFilePaths = allFilePaths.length > 0 ? allFilePaths : [...new Set(compressed.map((c) => c.filePath))];
+  const nonTestPaths = treeFilePaths.filter(
+    (fp) => !(/\/(tests?|__tests__|spec)\//i.test(fp) || /\.(test|spec)\./i.test(fp))
+  );
+  const directoryTree = buildDirectoryTree(nonTestPaths, rootDir);
+  const content = [
+    "## Directory Structure\n\n```\n" + directoryTree + "\n```",
+    codeContent
+  ].join("\n\n---\n\n");
+  const uniqueFiles = [...new Set(compressed.map((c) => c.filePath))];
+  let fileContentTokens = 0;
+  for (const filePath of uniqueFiles) {
+    try {
+      const fileContent = await readFile8(filePath, "utf-8");
+      fileContentTokens += countChunkTokens(fileContent);
+    } catch {
+    }
+  }
+  const toolCalls = 1 + uniqueFiles.length;
+  const estimatedWithoutBraincache = fileContentTokens + toolCalls * TOOL_CALL_OVERHEAD_TOKENS;
+  const tokensSent = assembled.tokenCount;
+  const reductionPct = estimatedWithoutBraincache > 0 ? Math.max(
+    0,
+    Math.round((1 - tokensSent / estimatedWithoutBraincache) * 100)
+  ) : 0;
+  return {
+    content,
+    chunks: compressed,
+    metadata: {
+      tokensSent,
+      estimatedWithoutBraincache,
+      reductionPct,
+      filesInContext: uniqueFiles.length,
+      localTasksPerformed: [
+        "embed_query",
+        "vector_search",
+        "dedup",
+        "parent_enrich",
+        "compress",
+        "cohesion_group",
+        "token_budget",
+        "directory_tree"
+      ],
+      cloudCallsMade: 0
+    }
+  };
+}
+
+// src/workflows/buildContext.ts
+function splitCamelCase2(name) {
+  return name.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().split(/\s+/).filter((t) => t.length >= 2);
+}
+function extractQueryTokens2(query) {
+  return query.toLowerCase().split(/[\s.,;:!?'"()\[\]{}/\\]+/).filter((t) => t.length >= 3);
+}
+function isPrimaryMatch(chunk, queryTokens) {
+  if (queryTokens.length === 0) return false;
+  const fileName = chunk.filePath.split("/").pop()?.toLowerCase() ?? "";
+  const fileNameStem = fileName.replace(/\.[^.]+$/, "");
+  const originalName = chunk.name ?? "";
+  const chunkName = originalName.toLowerCase();
+  if (chunkName.length > 0 && queryTokens.some((t) => t === chunkName)) return true;
+  const subTokens = originalName.length > 0 ? splitCamelCase2(originalName) : [];
+  if (subTokens.length > 1 && subTokens.every((sub) => queryTokens.some((t) => t.includes(sub) || sub.includes(t)))) return true;
+  if (fileNameStem.length > 0 && queryTokens.some((t) => t === fileNameStem)) return true;
+  return false;
+}
+var TEST_FILE_PATTERNS2 = [".test.", ".spec.", "/__tests__/", "/tests/"];
+function isTestFile2(filePath) {
+  return TEST_FILE_PATTERNS2.some((p) => filePath.includes(p));
+}
+var CONFIG_FILE_PATTERNS = [
+  /vitest\.config\./,
+  /tsup\.config\./,
+  /tsconfig.*\.json$/,
+  /jest\.config\./,
+  /eslint\.config\./,
+  /\.eslintrc/
+];
+function isConfigFile(filePath) {
+  const fileName = filePath.split("/").pop() ?? "";
+  return CONFIG_FILE_PATTERNS.some((p) => p.test(fileName));
+}
 async function runBuildContext(query, opts) {
   const profile = await readProfile();
   if (profile === null) {
@@ -1101,7 +2179,7 @@ async function runBuildContext(query, opts) {
   if (!running) {
     throw new Error("Ollama is not running. Start it with 'ollama serve' or run 'brain-cache init'.");
   }
-  const rootDir = resolve3(opts?.path ?? ".");
+  const rootDir = resolve6(opts?.path ?? ".");
   const indexState = await readIndexState(rootDir);
   if (indexState === null) {
     throw new Error(`No index found at ${rootDir}. Run 'brain-cache index' first.`);
@@ -1112,27 +2190,94 @@ async function runBuildContext(query, opts) {
     throw new Error("No chunks table found. Run 'brain-cache index' first.");
   }
   const table = await db.openTable("chunks");
-  const intent = classifyQueryIntent(query);
-  const strategy = {
-    limit: opts?.limit ?? RETRIEVAL_STRATEGIES[intent].limit,
-    distanceThreshold: RETRIEVAL_STRATEGIES[intent].distanceThreshold
-  };
+  const hasEdges = tableNames.includes("edges");
+  const mode = classifyRetrievalMode(query);
   const maxTokens = opts?.maxTokens ?? DEFAULT_TOKEN_BUDGET;
   process.stderr.write(
-    `brain-cache: building context (intent=${intent}, budget=${maxTokens} tokens)
+    `brain-cache: building context (intent=${mode}, budget=${maxTokens} tokens)
 `
   );
-  const { embeddings: vectors } = await embedBatchWithRetry(indexState.embeddingModel, [query]);
-  const queryVector = vectors[0];
-  const results = await searchChunks(table, queryVector, strategy);
-  const deduped = deduplicateChunks(results);
-  const assembled = assembleContext(deduped, { maxTokens });
-  const uniqueFiles = [...new Set(assembled.chunks.map((c) => c.filePath))];
+  const userConfig = await loadUserConfig();
+  const strategy = resolveStrategy(
+    mode,
+    userConfig,
+    opts?.limit !== void 0 ? { limit: opts.limit } : void 0
+  );
+  let finalChunks;
+  let finalContent;
+  let finalTokenCount;
+  let localTasksPerformed;
+  if (mode === "trace" && hasEdges) {
+    const traceResult = await runTraceFlow(query, {
+      maxHops: 3,
+      path: opts?.path,
+      limit: strategy.limit,
+      distanceThreshold: strategy.distanceThreshold
+    });
+    const traceChunks = traceResult.hops.map((hop, i) => ({
+      id: `trace-hop-${i}`,
+      filePath: hop.filePath,
+      chunkType: "function",
+      scope: null,
+      name: hop.name,
+      content: hop.content,
+      startLine: hop.startLine,
+      endLine: 0,
+      similarity: 1 - hop.hopDepth * 0.1
+    }));
+    const assembled = assembleContext(traceChunks, { maxTokens });
+    const groups = groupChunksByFile(assembled.chunks);
+    finalContent = formatGroupedContext(groups);
+    finalChunks = assembled.chunks;
+    finalTokenCount = assembled.tokenCount;
+    localTasksPerformed = traceResult.metadata.localTasksPerformed;
+  } else if (mode === "explore") {
+    const exploreResult = await runExplainCodebase({
+      question: query,
+      maxTokens,
+      path: opts?.path,
+      limit: strategy.limit,
+      distanceThreshold: strategy.distanceThreshold
+    });
+    finalContent = exploreResult.content;
+    finalChunks = exploreResult.chunks;
+    finalTokenCount = exploreResult.metadata.tokensSent;
+    localTasksPerformed = exploreResult.metadata.localTasksPerformed;
+  } else {
+    if (mode === "trace" && !hasEdges) {
+      process.stderr.write(`brain-cache: No edges table found, falling back to explore mode
+`);
+    }
+    const { embeddings: vectors } = await embedBatchWithRetry(indexState.embeddingModel, [query]);
+    const queryVector = vectors[0];
+    const results = await searchChunks(table, queryVector, strategy, query);
+    const deduped = deduplicateChunks(results);
+    const assembled = assembleContext(deduped, { maxTokens });
+    const enriched = await enrichWithParentClass(assembled.chunks, table, { maxTokens, currentTokens: assembled.tokenCount });
+    const withoutPeripheral = enriched.filter((chunk) => !isTestFile2(chunk.filePath) && !isConfigFile(chunk.filePath));
+    const queryTokens = extractQueryTokens2(query);
+    const compressed = withoutPeripheral.map(
+      (chunk) => isPrimaryMatch(chunk, queryTokens) ? chunk : compressChunk(chunk)
+    );
+    const groups = groupChunksByFile(compressed);
+    finalContent = formatGroupedContext(groups);
+    finalChunks = compressed;
+    finalTokenCount = assembled.tokenCount;
+    localTasksPerformed = ["embed_query", "vector_search", "dedup", "parent_enrich", "drop_peripheral", "compress", "cohesion_group", "token_budget"];
+  }
+  const BODY_STRIPPED_MARKER2 = "// [body stripped]";
+  const filesWithUncompressedContent = new Set(
+    finalChunks.filter((c) => !c.content.includes(BODY_STRIPPED_MARKER2)).map((c) => c.filePath)
+  );
+  const uniqueFiles = [...new Set(finalChunks.map((c) => c.filePath))];
   const numFiles = uniqueFiles.length;
   let fileContentTokens = 0;
   for (const filePath of uniqueFiles) {
+    if (!filesWithUncompressedContent.has(filePath)) {
+      continue;
+    }
     try {
-      const fileContent = await readFile5(filePath, "utf-8");
+      const fileContent = await readFile9(filePath, "utf-8");
       fileContentTokens += countChunkTokens(fileContent);
     } catch {
     }
@@ -1140,29 +2285,82 @@ async function runBuildContext(query, opts) {
   const toolCalls = 1 + numFiles;
   const toolCallOverhead = toolCalls * TOOL_CALL_OVERHEAD_TOKENS;
   const estimatedWithoutBraincache = fileContentTokens + toolCallOverhead;
-  const reductionPct = estimatedWithoutBraincache > 0 ? Math.max(0, Math.round((1 - assembled.tokenCount / estimatedWithoutBraincache) * 100)) : 0;
+  const reductionPct = estimatedWithoutBraincache > 0 ? Math.max(0, Math.round((1 - finalTokenCount / estimatedWithoutBraincache) * 100)) : 0;
   const result = {
-    content: assembled.content,
-    chunks: assembled.chunks,
+    content: finalContent,
+    chunks: finalChunks,
     metadata: {
-      tokensSent: assembled.tokenCount,
+      tokensSent: finalTokenCount,
       estimatedWithoutBraincache,
       reductionPct,
       filesInContext: numFiles,
-      localTasksPerformed: ["embed_query", "vector_search", "dedup", "token_budget"],
+      localTasksPerformed,
       cloudCallsMade: 0
     }
   };
   process.stderr.write(
-    `brain-cache: context assembled (${assembled.tokenCount} tokens, ${reductionPct}% reduction, ${assembled.chunks.length} chunks)
+    `brain-cache: context assembled (${finalTokenCount} tokens, ${reductionPct}% reduction, ${finalChunks.length} chunks)
 `
   );
   return result;
 }
 
+// src/services/sessionStats.ts
+import { readFile as readFile10, writeFile as writeFile3, rename, mkdir as mkdir3 } from "fs/promises";
+import { join as join4 } from "path";
+var log12 = childLogger("sessionStats");
+var SESSION_STATS_PATH = join4(GLOBAL_CONFIG_DIR, SESSION_STATS_FILENAME);
+var STATS_TTL_MS = 2 * 60 * 60 * 1e3;
+var _statsMutex = Promise.resolve();
+async function _readStats() {
+  try {
+    const raw = await readFile10(SESSION_STATS_PATH, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function _doAccumulate(delta, ttlMs) {
+  await mkdir3(GLOBAL_CONFIG_DIR, { recursive: true });
+  let effectiveTtlMs;
+  if (ttlMs !== void 0) {
+    effectiveTtlMs = ttlMs;
+  } else {
+    try {
+      const config = await loadUserConfig();
+      const ttlHours = config.stats?.ttlHours;
+      effectiveTtlMs = ttlHours !== void 0 ? ttlHours * 60 * 60 * 1e3 : STATS_TTL_MS;
+    } catch {
+      effectiveTtlMs = STATS_TTL_MS;
+    }
+  }
+  const existing = await _readStats();
+  const now = Date.now();
+  const isExpired = existing === null || now - Date.parse(existing.lastUpdatedAt) > effectiveTtlMs;
+  const base = isExpired ? { tokensSent: 0, estimatedWithoutBraincache: 0, callCount: 0 } : existing;
+  const updated = {
+    tokensSent: base.tokensSent + delta.tokensSent,
+    estimatedWithoutBraincache: base.estimatedWithoutBraincache + delta.estimatedWithoutBraincache,
+    callCount: base.callCount + 1,
+    lastUpdatedAt: new Date(now).toISOString()
+  };
+  const tmpPath = SESSION_STATS_PATH + ".tmp";
+  await writeFile3(tmpPath, JSON.stringify(updated, null, 2), "utf-8");
+  await rename(tmpPath, SESSION_STATS_PATH);
+}
+function accumulateStats(delta, ttlMs) {
+  const next = _statsMutex.then(
+    () => _doAccumulate(delta, ttlMs).catch((err) => {
+      log12.warn({ err }, "stats accumulation failed");
+    })
+  );
+  _statsMutex = next.then(() => void 0, () => void 0);
+  return next;
+}
+
 // src/mcp/index.ts
-var version = "0.4.2";
-var log9 = childLogger("mcp");
+var version = true ? "3.0.0" : "dev";
+var log13 = childLogger("mcp");
 var server = new McpServer({ name: "brain-cache", version });
 server.registerTool(
   "index_repo",
@@ -1183,7 +2381,7 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: "No capability profile found. Run 'brain-cache init' first."
+            text: formatErrorEnvelope("No capability profile found.", "Run 'brain-cache init' first.")
           }
         ]
       };
@@ -1195,14 +2393,14 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: "Ollama is not running. Start it with 'ollama serve'."
+            text: formatErrorEnvelope("Ollama is not running.", "Start it with 'ollama serve'.")
           }
         ]
       };
     }
     try {
       await runIndex(path, { force });
-      const resolvedPath = resolve4(path);
+      const resolvedPath = resolve7(path);
       const indexState = await readIndexState(resolvedPath);
       const result = {
         status: "ok",
@@ -1211,7 +2409,7 @@ server.registerTool(
         chunkCount: indexState?.chunkCount ?? null
       };
       return {
-        content: [{ type: "text", text: JSON.stringify(result) }]
+        content: [{ type: "text", text: formatIndexResult(result) }]
       };
     } catch (err) {
       return {
@@ -1219,17 +2417,48 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: `Indexing failed: ${err instanceof Error ? err.message : String(err)}`
+            text: formatErrorEnvelope(`Indexing failed: ${err instanceof Error ? err.message : String(err)}`)
           }
         ]
       };
     }
   }
 );
+function buildSearchResponse(chunks, query) {
+  const filesInContext = new Set(chunks.map((c) => c.filePath)).size;
+  const tokensSent = Math.round(chunks.reduce((sum, c) => sum + c.content.length, 0) / 4);
+  const estimatedWithout = tokensSent * 3;
+  const reductionPct = estimatedWithout > 0 ? Math.round((1 - tokensSent / estimatedWithout) * 100) : 0;
+  const savings = formatTokenSavings({ tokensSent, estimatedWithout, reductionPct, filesInContext });
+  const pipeline = formatPipelineLabel(["embed", "search", "dedup"]);
+  const footer = `---
+${savings}
+Pipeline: ${pipeline}`;
+  const summary = `Found ${chunks.length} result${chunks.length !== 1 ? "s" : ""} for "${query}".`;
+  return {
+    content: [{ type: "text", text: formatToolResponse(summary, `${formatSearchResults(chunks)}
+
+${footer}`) }]
+  };
+}
+function buildContextResponse(result, query) {
+  const { tokensSent, estimatedWithoutBraincache, reductionPct, filesInContext, localTasksPerformed } = result.metadata;
+  const savings = formatTokenSavings({ tokensSent, estimatedWithout: estimatedWithoutBraincache, reductionPct, filesInContext });
+  const pipeline = formatPipelineLabel(localTasksPerformed);
+  const footer = `---
+${savings}
+Pipeline: ${pipeline}`;
+  const summary = `Context assembled for "${query}".`;
+  return {
+    content: [{ type: "text", text: formatToolResponse(summary, `${formatContext(result)}
+
+${footer}`) }]
+  };
+}
 server.registerTool(
   "search_codebase",
   {
-    description: "Locate specific code \u2014 functions, symbols, definitions, implementations, and type declarations \u2014 using semantic search that finds code by meaning, not just keyword match. This is a locator tool \u2014 it finds WHERE code lives. For understanding HOW code works or answering questions that span multiple files, use build_context instead. Requires index_repo to have been run first.",
+    description: "Locate specific code \u2014 functions, symbols, definitions, implementations, and type declarations \u2014 using semantic search that finds code by meaning, not just keyword match. This is a locator tool \u2014 it finds WHERE code lives. For understanding HOW code works or answering questions that span multiple files, use build_context instead. Requires index_repo to have been run first. Do NOT use this tool to understand how code works or answer behavioral questions \u2014 use build_context once you have located the symbol.",
     inputSchema: {
       query: z2.string().describe("Natural language query string"),
       limit: z2.number().int().min(1).max(50).optional().describe("Max results (default 10)"),
@@ -1244,7 +2473,7 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: "No capability profile found. Run 'brain-cache init' first."
+            text: formatErrorEnvelope("No capability profile found.", "Run 'brain-cache init' first.")
           }
         ]
       };
@@ -1256,32 +2485,34 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: "Ollama is not running. Start it with 'ollama serve'."
+            text: formatErrorEnvelope("Ollama is not running.", "Start it with 'ollama serve'.")
           }
         ]
       };
     }
     try {
       const chunks = await runSearch(query, { limit, path });
-      return {
-        content: [{ type: "text", text: JSON.stringify(chunks) }]
-      };
+      const tokensSent = Math.round(chunks.reduce((sum, c) => sum + c.content.length, 0) / 4);
+      const estimatedWithoutBraincache = tokensSent * 3;
+      accumulateStats({ tokensSent, estimatedWithoutBraincache }).catch((err) => log13.warn({ err }, "stats accumulation failed"));
+      return buildSearchResponse(chunks, query);
     } catch (err) {
       if (err instanceof Error && err.message.includes("No index found")) {
-        const resolvedPath = resolve4(path ?? ".");
+        const resolvedPath = resolve7(path ?? ".");
         await runIndex(resolvedPath);
         try {
           const chunks = await runSearch(query, { limit, path });
-          return {
-            content: [{ type: "text", text: JSON.stringify(chunks) }]
-          };
+          const tokensSent = Math.round(chunks.reduce((sum, c) => sum + c.content.length, 0) / 4);
+          const estimatedWithoutBraincache = tokensSent * 3;
+          accumulateStats({ tokensSent, estimatedWithoutBraincache }).catch((err2) => log13.warn({ err: err2 }, "stats accumulation failed"));
+          return buildSearchResponse(chunks, query);
         } catch (retryErr) {
           return {
             isError: true,
             content: [
               {
                 type: "text",
-                text: `Search failed after auto-index: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`
+                text: formatErrorEnvelope(`Search failed after auto-index: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`)
               }
             ]
           };
@@ -1292,7 +2523,7 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: `Search failed: ${err instanceof Error ? err.message : String(err)}`
+            text: formatErrorEnvelope(`Search failed: ${err instanceof Error ? err.message : String(err)}`)
           }
         ]
       };
@@ -1302,7 +2533,7 @@ server.registerTool(
 server.registerTool(
   "build_context",
   {
-    description: "Prefer this tool when answering questions like 'how does X work', 'explain the architecture', 'what happens when Y', or any question requiring understanding across multiple files. Retrieves semantically relevant code across the entire repo, deduplicates, and assembles a token-budgeted context block \u2014 more accurate and efficient than reading files individually or relying on memory. Use this before answering to ensure your response is grounded in actual code rather than assumptions. Ideal for explaining how systems work, understanding workflows and data flow, answering architectural questions, multi-file reasoning, and debugging unfamiliar code paths. Requires index_repo to have been run first.",
+    description: "Use this tool when answering questions like 'how does X work', 'what does this function do', or any question requiring understanding of specific code behavior across multiple files. Retrieves semantically relevant code across the entire repo, deduplicates, and assembles a token-budgeted context block \u2014 more accurate and efficient than reading files individually or relying on memory. Use this before answering to ensure your response is grounded in actual code rather than assumptions. Ideal for explaining how systems work, understanding workflows and data flow, answering code behavior questions, multi-file reasoning, and debugging unfamiliar code paths. Do NOT use this tool when you need to trace a call path across files \u2014 use trace_flow instead. Do NOT use this tool for architecture overviews \u2014 use explain_codebase instead. Requires index_repo to have been run first.",
     inputSchema: {
       query: z2.string().describe("Natural language query or question"),
       maxTokens: z2.number().int().min(100).max(1e5).optional().describe("Token budget for assembled context (default 4096)"),
@@ -1317,7 +2548,7 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: "No capability profile found. Run 'brain-cache init' first."
+            text: formatErrorEnvelope("No capability profile found.", "Run 'brain-cache init' first.")
           }
         ]
       };
@@ -1329,38 +2560,36 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: "Ollama is not running. Start it with 'ollama serve'."
+            text: formatErrorEnvelope("Ollama is not running.", "Start it with 'ollama serve'.")
           }
         ]
       };
     }
     try {
       const result = await runBuildContext(query, { maxTokens, path });
-      const { tokensSent, estimatedWithoutBraincache, reductionPct, filesInContext } = result.metadata;
-      return {
-        content: [
-          { type: "text", text: JSON.stringify({ ...result, tokenSavings: formatTokenSavings({ tokensSent, estimatedWithout: estimatedWithoutBraincache, reductionPct, filesInContext }) }) }
-        ]
-      };
+      accumulateStats({
+        tokensSent: result.metadata.tokensSent,
+        estimatedWithoutBraincache: result.metadata.estimatedWithoutBraincache
+      }).catch((err) => log13.warn({ err }, "stats accumulation failed"));
+      return buildContextResponse(result, query);
     } catch (err) {
       if (err instanceof Error && err.message.includes("No index found")) {
-        const resolvedPath = resolve4(path ?? ".");
+        const resolvedPath = resolve7(path ?? ".");
         await runIndex(resolvedPath);
         try {
           const result = await runBuildContext(query, { maxTokens, path });
-          const { tokensSent, estimatedWithoutBraincache, reductionPct, filesInContext } = result.metadata;
-          return {
-            content: [
-              { type: "text", text: JSON.stringify({ ...result, tokenSavings: formatTokenSavings({ tokensSent, estimatedWithout: estimatedWithoutBraincache, reductionPct, filesInContext }) }) }
-            ]
-          };
+          accumulateStats({
+            tokensSent: result.metadata.tokensSent,
+            estimatedWithoutBraincache: result.metadata.estimatedWithoutBraincache
+          }).catch((err2) => log13.warn({ err: err2 }, "stats accumulation failed"));
+          return buildContextResponse(result, query);
         } catch (retryErr) {
           return {
             isError: true,
             content: [
               {
                 type: "text",
-                text: `Context build failed after auto-index: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`
+                text: formatErrorEnvelope(`Context build failed after auto-index: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`)
               }
             ]
           };
@@ -1371,7 +2600,7 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: `Context build failed: ${err instanceof Error ? err.message : String(err)}`
+            text: formatErrorEnvelope(`Context build failed: ${err instanceof Error ? err.message : String(err)}`)
           }
         ]
       };
@@ -1390,7 +2619,7 @@ server.registerTool(
   },
   async ({ path: projectPath }) => {
     try {
-      const rootDir = resolve4(projectPath ?? ".");
+      const rootDir = resolve7(projectPath ?? ".");
       const profile = await readProfile();
       const installed = await isOllamaInstalled();
       const running = installed ? await isOllamaRunning() : false;
@@ -1412,7 +2641,7 @@ server.registerTool(
         vramTier: live.vramTier
       };
       return {
-        content: [{ type: "text", text: JSON.stringify(health) }]
+        content: [{ type: "text", text: formatDoctorOutput(health) }]
       };
     } catch (err) {
       return {
@@ -1420,17 +2649,108 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: `Doctor failed: ${err instanceof Error ? err.message : String(err)}`
+            text: formatErrorEnvelope(`Doctor failed: ${err instanceof Error ? err.message : String(err)}`)
           }
         ]
       };
     }
   }
 );
+server.registerTool(
+  "trace_flow",
+  {
+    description: 'Trace call paths from an entrypoint symbol. Returns a structured hops[] array showing which functions are called in sequence, their file locations, and what they call next. Use this instead of build_context when asked to trace how a function call propagates through the codebase, e.g. "how does indexing flow from CLI to LanceDB". Requires index_repo to have been run first. Do NOT use this tool when the question is about how code works or what a function does \u2014 use build_context instead.',
+    inputSchema: {
+      entrypoint: z2.string().describe('Natural language description of the starting function or entry point to trace from, e.g. "runBuildContext workflow" or "how does indexing work"'),
+      maxHops: z2.number().int().min(1).max(10).optional().describe("Maximum call depth to follow (default 3)"),
+      path: z2.string().optional().describe("Project root directory (default: current directory)")
+    }
+  },
+  async ({ entrypoint, maxHops, path }) => {
+    const profile = await readProfile();
+    if (!profile) {
+      return { isError: true, content: [{ type: "text", text: formatErrorEnvelope("No capability profile found.", "Run 'brain-cache init' first.") }] };
+    }
+    const running = await isOllamaRunning();
+    if (!running) {
+      return { isError: true, content: [{ type: "text", text: formatErrorEnvelope("Ollama is not running.", "Start it with 'ollama serve'.") }] };
+    }
+    try {
+      const result = await runTraceFlow(entrypoint, { maxHops, path });
+      accumulateStats({
+        tokensSent: result.metadata.tokensSent,
+        estimatedWithoutBraincache: result.metadata.estimatedWithoutBraincache
+      }).catch((err) => log13.warn({ err }, "stats accumulation failed"));
+      const { tokensSent, estimatedWithoutBraincache, reductionPct, filesInContext } = result.metadata;
+      const savings = formatTokenSavings({
+        tokensSent,
+        estimatedWithout: estimatedWithoutBraincache,
+        reductionPct,
+        filesInContext
+      });
+      const pipeline = formatPipelineLabel(result.metadata.localTasksPerformed);
+      const footer = `---
+${savings}
+Pipeline: ${pipeline}`;
+      const summary = `Traced ${result.hops.length} hop${result.hops.length !== 1 ? "s" : ""} from "${entrypoint}".`;
+      const warningLine = result.metadata.confidenceWarning ? `Warning: ${result.metadata.confidenceWarning}
+
+` : "";
+      return {
+        content: [{ type: "text", text: formatToolResponse(summary, `${warningLine}${formatTraceFlow(result)}
+
+${footer}`) }]
+      };
+    } catch (err) {
+      return { isError: true, content: [{ type: "text", text: formatErrorEnvelope(`trace_flow failed: ${err instanceof Error ? err.message : String(err)}`) }] };
+    }
+  }
+);
+server.registerTool(
+  "explain_codebase",
+  {
+    description: "Get a high-level architecture overview of the indexed codebase. Returns module-grouped summaries describing what each part of the repo does. Use this instead of build_context when asked to explain the project architecture, understand the overall structure, or get oriented in a new codebase. No follow-up question required \u2014 works with just a project path. Requires index_repo to have been run first. Do NOT use this tool for questions about specific code behavior or how a particular function works \u2014 use build_context instead.",
+    inputSchema: {
+      question: z2.string().optional().describe('Optional focus question, e.g. "how is authentication structured". Defaults to a broad architecture overview.'),
+      maxTokens: z2.number().int().min(100).max(1e5).optional().describe("Token budget for assembled context (default 4096)"),
+      path: z2.string().optional().describe("Project root directory (default: current directory)")
+    }
+  },
+  async ({ question, maxTokens, path }) => {
+    const profile = await readProfile();
+    if (!profile) {
+      return { isError: true, content: [{ type: "text", text: formatErrorEnvelope("No capability profile found.", "Run 'brain-cache init' first.") }] };
+    }
+    const running = await isOllamaRunning();
+    if (!running) {
+      return { isError: true, content: [{ type: "text", text: formatErrorEnvelope("Ollama is not running.", "Start it with 'ollama serve'.") }] };
+    }
+    try {
+      const result = await runExplainCodebase({ question, maxTokens, path });
+      accumulateStats({
+        tokensSent: result.metadata.tokensSent,
+        estimatedWithoutBraincache: result.metadata.estimatedWithoutBraincache
+      }).catch((err) => log13.warn({ err }, "stats accumulation failed"));
+      const { tokensSent, estimatedWithoutBraincache, reductionPct, filesInContext, localTasksPerformed } = result.metadata;
+      const savings = formatTokenSavings({ tokensSent, estimatedWithout: estimatedWithoutBraincache, reductionPct, filesInContext });
+      const pipeline = formatPipelineLabel(localTasksPerformed);
+      const footer = `---
+${savings}
+Pipeline: ${pipeline}`;
+      const summary = `Architecture overview for ${path ?? "."}.`;
+      const text = formatToolResponse(summary, `${formatContext(result)}
+
+${footer}`);
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return { isError: true, content: [{ type: "text", text: formatErrorEnvelope(`explain_codebase failed: ${err instanceof Error ? err.message : String(err)}`) }] };
+    }
+  }
+);
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  log9.info("brain-cache MCP server running on stdio");
+  log13.info("brain-cache MCP server running on stdio");
 }
 main().catch((error) => {
   process.stderr.write(`Fatal: ${String(error)}