@hiveai/mcp 0.4.5 → 0.6.0

package/dist/index.js

@@ -1200,6 +1200,9 @@ var GetBriefingInputSchema = {
   ),
   symbols: z17.array(z17.string()).default([]).describe(
     "Symbol names to look up in the code-map (e.g. ['PaymentService', 'TenantFilter']). Returns the file(s) exporting each symbol so agents don't need to grep. Requires `haive index code` to have been run."
+  ),
+  min_semantic_score: z17.number().min(0).max(1).default(0).describe(
+    "Drop semantic-only memory hits whose cosine score is below this threshold. Useful to avoid weakly-related noise when the task is short or the corpus is broad. Has no effect on memories matched via anchor/module/literal \u2014 those are always kept. Try 0.25\u20130.4 for stricter matching."
   )
 };
 async function getBriefing(input, ctx) {
@@ -1232,6 +1235,7 @@ async function getBriefing(input, ctx) {
       return true;
     });
     usage = await loadUsageIndex7(ctx.paths);
+    byId = new Map(allMemories.map((m) => [m.memory.frontmatter.id, m]));
     const semanticHits = input.task && input.semantic ? await trySemanticHits(ctx, input.task, allMemories.length * 2) : null;
     if (input.task && input.semantic) {
       searchMode = semanticHits ? "semantic" : "literal_fallback";
@@ -1296,6 +1300,10 @@ async function getBriefing(input, ctx) {
       }
       if (semanticHits) {
         for (const hit of semanticHits) {
+          if (hit.score < input.min_semantic_score) {
+            const existing = seen.get(hit.id);
+            if (!existing) continue;
+          }
           const loaded = byId.get(hit.id);
           if (loaded) addOrUpdate(loaded, "semantic", hit.score, "semantic");
         }
@@ -1309,7 +1317,6 @@ async function getBriefing(input, ctx) {
       const sb = reasonScore(b) + confidenceScore(b) + (b.semantic_score ?? 0);
       return sb - sa;
     });
-    byId = new Map(allMemories.map((m) => [m.memory.frontmatter.id, m]));
     for (const mem of ranked.slice(0, input.max_memories)) {
       if (seen.size >= input.max_memories * 2) break;
       const loaded = byId.get(mem.id);
@@ -1501,6 +1508,36 @@ ${m.content}`).join("\n\n---\n\n"),
       });
     }
   }
+  const memoriesEmpty = outputMemories.length === 0;
+  const hasMemoriesDir = existsSync17(ctx.paths.memoriesDir);
+  const isColdStart = isTemplateContext && memoriesEmpty && !lastSession && !autoContextGenerated;
+  const hints = [];
+  if (isColdStart) {
+    hints.push(
+      "haive is uninitialized for this project (project-context.md is template, 0 memories, no past session). Skip future get_briefing calls until memories exist \u2014 use Read/Grep directly. Run `haive init` and the bootstrap_project prompt to fix."
+    );
+  } else {
+    if (outputMemories.some((m) => m.type === "attempt")) {
+      hints.push(
+        "\u26A0\uFE0F One or more 'attempt' memories matched \u2014 these document failed approaches. Read them BEFORE writing code to avoid repeating the mistake."
+      );
+    }
+    if (outputMemories.some((m) => m.type === "gotcha")) {
+      hints.push(
+        "Gotcha memories matched \u2014 non-obvious traps. Verify the 'how to apply' line still holds before assuming behavior."
+      );
+    }
+    if (memoriesEmpty && hasMemoriesDir && input.task) {
+      hints.push(
+        "No memories matched this task. Try mem_search with broader/different terms, or call mem_for_files with the files you intend to edit."
+      );
+    }
+    if (input.task && outputMemories.length > 0 && actionRequired.length === 0) {
+      hints.push(
+        "After completing the task: capture new gotchas with mem_observe, failed approaches with mem_tried, validated patterns with mem_save."
+      );
+    }
+  }
   return {
     ...input.task ? { task: input.task } : {},
     search_mode: searchMode,
@@ -1518,6 +1555,8 @@ ${m.content}`).join("\n\n---\n\n"),
     action_required: actionRequired,
     decay_warnings: decayWarnings,
     setup_warnings: setupWarnings,
+    ...isColdStart ? { low_value: true } : {},
+    ...hints.length > 0 ? { hints } : {},
     estimated_tokens: totalTokens,
     budget: {
       max_tokens: input.max_tokens,
@@ -1565,12 +1604,18 @@ async function loadModuleContexts2(ctx, modules) {
 }
 
 // src/tools/code-map.ts
-import { loadCodeMap as loadCodeMap2, queryCodeMap as queryCodeMap2 } from "@hiveai/core";
+import { estimateTokens as estimateTokens2, loadCodeMap as loadCodeMap2, queryCodeMap as queryCodeMap2 } from "@hiveai/core";
 import { z as z18 } from "zod";
 var CodeMapInputSchema = {
   file: z18.string().optional().describe("Filter to files whose path contains this substring"),
   symbol: z18.string().optional().describe("Filter to files exporting a symbol whose name contains this substring"),
-  max_files: z18.number().int().positive().default(40).describe("Cap on returned files")
+  paths: z18.array(z18.string()).default([]).describe(
+    "Filter to files under any of these path prefixes (e.g. ['packages/mcp/src/tools/', 'src/auth/']). OR-joined with `file` substring; useful to get a focused view of one module."
+  ),
+  max_files: z18.number().int().positive().default(40).describe("Cap on returned files (hard limit, applied after token budget)"),
+  max_tokens: z18.number().int().positive().optional().describe(
+    "Approximate token budget for the response. When the matching set exceeds it, files are ranked by export density (exports per LOC) and the highest-signal ones are kept first. Omit to disable budgeting (legacy behavior)."
+  )
 };
 async function codeMapTool(input, ctx) {
   const map = await loadCodeMap2(ctx.paths);
@@ -1581,19 +1626,63 @@ async function codeMapTool(input, ctx) {
       notice: "No code map found. Run `haive index code` to generate `.ai/code-map.json`."
     };
   }
-  const { files } = queryCodeMap2(map, { file: input.file, symbol: input.symbol });
+  const { files: matched } = queryCodeMap2(map, { file: input.file, symbol: input.symbol });
+  const pathsFiltered = input.paths.length === 0 ? matched : matched.filter((f) => input.paths.some((p) => f.path.startsWith(stripLeadingSlash(p))));
+  const alphabetical = [...pathsFiltered].sort((a, b) => a.path.localeCompare(b.path));
+  let kept = alphabetical;
+  let budgetClipped = false;
+  if (input.max_tokens !== void 0) {
+    const byDensity = [...alphabetical].sort((a, b) => {
+      const da = density(a.entry.exports.length, a.entry.loc);
+      const db = density(b.entry.exports.length, b.entry.loc);
+      if (da !== db) return db - da;
+      return a.path.localeCompare(b.path);
+    });
+    const keepSet = /* @__PURE__ */ new Set();
+    let spent = 0;
+    for (const f of byDensity) {
+      const cost = estimateFileEntryTokens(f);
+      if (spent + cost > input.max_tokens && keepSet.size > 0) {
+        budgetClipped = true;
+        break;
+      }
+      keepSet.add(f.path);
+      spent += cost;
+    }
+    if (budgetClipped) {
+      kept = alphabetical.filter((f) => keepSet.has(f.path));
+    }
+  }
+  const finalFiles = kept.slice(0, input.max_files);
+  const totalDropped = pathsFiltered.length - finalFiles.length;
   return {
     available: true,
     generated_at: map.generated_at,
     total_files: Object.keys(map.files).length,
-    files: files.slice(0, input.max_files).map((f) => ({
+    files: finalFiles.map((f) => ({
       path: f.path,
       ...f.entry.summary ? { summary: f.entry.summary } : {},
       loc: f.entry.loc,
       exports: f.entry.exports
-    }))
+    })),
+    ...totalDropped > 0 ? { truncated: totalDropped } : {},
+    ...budgetClipped ? { budget_clipped: true } : {}
   };
 }
+function density(exports, loc) {
+  if (loc <= 0) return 0;
+  return exports / Math.max(loc, 1);
+}
+function stripLeadingSlash(p) {
+  return p.startsWith("/") ? p.slice(1) : p;
+}
+function estimateFileEntryTokens(f) {
+  const exportsCost = f.entry.exports.reduce(
+    (acc, e) => acc + 6 + estimateTokens2(e.description ?? ""),
+    0
+  );
+  return estimateTokens2(f.path) + estimateTokens2(f.entry.summary ?? "") + exportsCost + 4;
+}
 
 // src/tools/mem-diff.ts
 import { existsSync as existsSync18 } from "fs";
@@ -1640,13 +1729,856 @@ async function memDiff(input, ctx) {
   };
 }
 
-// src/prompts/bootstrap-project.ts
+// src/tools/get-recap.ts
+import { existsSync as existsSync19 } from "fs";
+import { loadMemoriesFromDir as loadMemoriesFromDir15 } from "@hiveai/core";
 import { z as z20 } from "zod";
+var GetRecapInputSchema = {
+  scope: z20.enum(["personal", "team", "any"]).default("any").describe(
+    "Limit to a specific scope's recap. Default 'any' returns the most recent recap across both personal and team scopes."
+  )
+};
+async function getRecap(input, ctx) {
+  if (!existsSync19(ctx.paths.memoriesDir)) {
+    return { recap: null, notice: "No .ai/memories directory \u2014 haive not initialized here." };
+  }
+  const all = await loadMemoriesFromDir15(ctx.paths.memoriesDir);
+  const recaps = all.filter(({ memory }) => memory.frontmatter.type === "session_recap").filter(({ memory }) => input.scope === "any" || memory.frontmatter.scope === input.scope).sort(
+    (a, b) => new Date(b.memory.frontmatter.created_at).getTime() - new Date(a.memory.frontmatter.created_at).getTime()
+  );
+  if (recaps.length === 0) {
+    return {
+      recap: null,
+      notice: input.scope === "any" ? "No session recap saved yet. Run mem_session_end (or post_task prompt) to capture one." : `No session recap found in scope '${input.scope}'.`
+    };
+  }
+  const r = recaps[0];
+  const fm = r.memory.frontmatter;
+  return {
+    recap: {
+      id: fm.id,
+      scope: fm.scope,
+      revision_count: fm.revision_count ?? 0,
+      created_at: fm.created_at,
+      body: r.memory.body
+    }
+  };
+}
+
+// src/tools/mem-relevant-to.ts
+import { z as z21 } from "zod";
+var MemRelevantToInputSchema = {
+  task: z21.string().min(1).describe("What you are about to do, in 1\u20132 sentences. Used to rank relevant memories."),
+  files: z21.array(z21.string()).default([]).describe("Optional: files you are about to edit \u2014 surfaces anchored memories."),
+  limit: z21.number().int().positive().max(30).default(8).describe("Cap on returned memories."),
+  min_semantic_score: z21.number().min(0).max(1).default(0.25).describe("Drop weakly-related semantic hits below this cosine threshold."),
+  format: z21.enum(["full", "compact"]).default("full").describe("'compact' = id + 1-line summary; 'full' = complete bodies.")
+};
+async function memRelevantTo(input, ctx) {
+  const briefingInput = {
+    task: input.task,
+    files: input.files,
+    max_tokens: 16e3,
+    max_memories: input.limit,
+    include_project_context: false,
+    include_module_contexts: false,
+    semantic: true,
+    include_stale: false,
+    track: true,
+    format: input.format,
+    symbols: [],
+    min_semantic_score: input.min_semantic_score
+  };
+  const briefing = await getBriefing(briefingInput, ctx);
+  const out = {
+    task: input.task,
+    search_mode: briefing.search_mode,
+    memories: briefing.memories
+  };
+  if (briefing.hints && briefing.hints.length > 0) out.hints = briefing.hints;
+  if (briefing.memories.length === 0) out.empty = true;
+  return out;
+}
+
+// src/tools/code-search.ts
+import { z as z22 } from "zod";
+var CodeSearchInputSchema = {
+  query: z22.string().min(1).describe(
+    "Natural-language description of what you are looking for in the codebase (e.g. 'function that hashes passwords', 'JWT signing logic', 'route registration')."
+  ),
+  k: z22.number().int().positive().max(50).default(5).describe("Number of top hits to return."),
+  min_score: z22.number().min(0).max(1).default(0.2).describe(
+    "Minimum cosine similarity. Hits below this threshold are dropped to avoid noise. Try 0.3+ for stricter matching."
+  )
+};
+async function codeSearch(input, ctx) {
+  let mod;
+  try {
+    mod = await import("@hiveai/embeddings");
+  } catch {
+    return {
+      available: false,
+      hits: [],
+      notice: "@hiveai/embeddings is not installed. Install it (`pnpm add @hiveai/embeddings`) and run `haive index code-search` to enable semantic code search."
+    };
+  }
+  const result = await mod.codeSemanticSearch(ctx.paths, input.query, {
+    limit: input.k,
+    minScore: input.min_score
+  });
+  if (!result) {
+    return {
+      available: false,
+      hits: [],
+      notice: "Code semantic-search index not built. Run `haive index code-search` to generate it (builds embeddings for every exported symbol in the code-map)."
+    };
+  }
+  return { available: true, hits: result.hits };
+}
+
+// src/tools/why-this-file.ts
+import { existsSync as existsSync20 } from "fs";
+import { spawn } from "child_process";
+import path9 from "path";
+import {
+  deriveConfidence as deriveConfidence5,
+  getUsage as getUsage6,
+  loadCodeMap as loadCodeMap3,
+  loadMemoriesFromDir as loadMemoriesFromDir16,
+  loadUsageIndex as loadUsageIndex8,
+  memoryMatchesAnchorPaths as memoryMatchesAnchorPaths3
+} from "@hiveai/core";
+import { z as z23 } from "zod";
+var WhyThisFileInputSchema = {
+  path: z23.string().min(1).describe(
+    "Project-relative path to the file you want context on (e.g. 'packages/mcp/src/tools/mem-save.ts')."
+  ),
+  git_log_limit: z23.number().int().positive().max(20).default(5).describe("How many recent commits touching this file to include."),
+  memory_limit: z23.number().int().positive().max(20).default(5).describe("Cap on memories anchored to this path.")
+};
+async function whyThisFile(input, ctx) {
+  const fileExists = existsSync20(path9.join(ctx.paths.root, input.path));
+  const [commits, memories, codeMap] = await Promise.all([
+    runGitLog(ctx.paths.root, input.path, input.git_log_limit).catch(() => []),
+    collectAnchoredMemories(ctx, input.path, input.memory_limit),
+    loadCodeMap3(ctx.paths)
+  ]);
+  const codeMapEntry = codeMap?.files[input.path];
+  const hints = [];
+  if (!fileExists) {
+    hints.push(`File '${input.path}' does not exist on disk \u2014 path may be wrong or file removed.`);
+  }
+  if (commits.length === 0 && fileExists) {
+    hints.push("No git history found \u2014 file may be untracked or git not initialized.");
+  }
+  if (memories.length === 0 && fileExists) {
+    hints.push(
+      "No memories anchored here. If you discover something non-obvious while editing, use mem_observe (with where=" + input.path + ") to capture it."
+    );
+  }
+  if (memories.some((m) => m.type === "attempt" || m.type === "gotcha")) {
+    hints.push("\u26A0\uFE0F attempt/gotcha memories anchored to this file \u2014 read them BEFORE editing.");
+  }
+  return {
+    file: input.path,
+    exists: fileExists,
+    recent_commits: commits,
+    memories,
+    code_map_entry: codeMapEntry ? {
+      ...codeMapEntry.summary ? { summary: codeMapEntry.summary } : {},
+      loc: codeMapEntry.loc,
+      exports: codeMapEntry.exports.map((e) => ({
+        name: e.name,
+        kind: e.kind,
+        line: e.line,
+        ...e.description ? { description: e.description } : {}
+      }))
+    } : null,
+    ...hints.length > 0 ? { hints } : {}
+  };
+}
+async function collectAnchoredMemories(ctx, filePath, limit) {
+  if (!existsSync20(ctx.paths.memoriesDir)) return [];
+  const all = await loadMemoriesFromDir16(ctx.paths.memoriesDir);
+  const usage = await loadUsageIndex8(ctx.paths);
+  const out = [];
+  for (const { memory } of all) {
+    const fm = memory.frontmatter;
+    if (fm.status === "rejected" || fm.status === "deprecated") continue;
+    if (fm.type === "session_recap") continue;
+    if (!memoryMatchesAnchorPaths3(memory, [filePath])) continue;
+    const u = getUsage6(usage, fm.id);
+    out.push({
+      id: fm.id,
+      type: fm.type,
+      scope: fm.scope,
+      confidence: deriveConfidence5(fm, u),
+      body_preview: memory.body.split("\n").slice(0, 6).join("\n")
+    });
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+async function runGitLog(cwd, filePath, limit) {
+  const sep = "<<HV>>";
+  const fmt = `%h${sep}%an${sep}%ar${sep}%s`;
+  const output = await runCommand(
+    "git",
+    ["log", `-n`, String(limit), `--pretty=format:${fmt}`, "--", filePath],
+    cwd
+  );
+  if (!output.trim()) return [];
+  return output.split("\n").map((line) => {
+    const [sha = "", author = "", relative_date = "", subject = ""] = line.split(sep);
+    return { sha, author, relative_date, subject };
+  }).filter((c) => c.sha);
+}
+function runCommand(cmd, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    proc.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    proc.on("error", reject);
+    proc.on("close", (code) => {
+      if (code === 0) resolve(stdout);
+      else reject(new Error(stderr || `${cmd} exited with code ${code}`));
+    });
+  });
+}
+
+// src/tools/anti-patterns-check.ts
+import { existsSync as existsSync21 } from "fs";
+import {
+  deriveConfidence as deriveConfidence6,
+  getUsage as getUsage7,
+  loadMemoriesFromDir as loadMemoriesFromDir17,
+  loadUsageIndex as loadUsageIndex9,
+  literalMatchesAnyToken as literalMatchesAnyToken3,
+  memoryMatchesAnchorPaths as memoryMatchesAnchorPaths4,
+  tokenizeQuery as tokenizeQuery3
+} from "@hiveai/core";
+import { z as z24 } from "zod";
+var AntiPatternsCheckInputSchema = {
+  diff: z24.string().optional().describe(
+    "Raw unified diff text (or any code/text snippet) to scan for previously documented anti-patterns. Tokens from the diff are used to match memory bodies and the embeddings index."
+  ),
+  paths: z24.array(z24.string()).default([]).describe(
+    "File paths affected by the change. Memories anchored to any of these paths are surfaced regardless of the diff content."
+  ),
+  limit: z24.number().int().positive().max(20).default(8).describe("Cap on returned warnings."),
+  semantic: z24.boolean().default(true).describe(
+    "When true, also use semantic search (requires @hiveai/embeddings + memory index) to find related anti-patterns."
+  )
+};
+async function antiPatternsCheck(input, ctx) {
+  if (!input.diff && input.paths.length === 0) {
+    return {
+      scanned: 0,
+      warnings: [],
+      notice: "Nothing to check \u2014 provide either `diff` text or `paths`."
+    };
+  }
+  if (!existsSync21(ctx.paths.memoriesDir)) {
+    return { scanned: 0, warnings: [], notice: "No .ai/memories directory \u2014 nothing to check against." };
+  }
+  const all = await loadMemoriesFromDir17(ctx.paths.memoriesDir);
+  const negative = all.filter(({ memory }) => {
+    const t = memory.frontmatter.type;
+    if (t !== "attempt" && t !== "gotcha") return false;
+    const s = memory.frontmatter.status;
+    return s !== "rejected" && s !== "deprecated" && s !== "stale";
+  });
+  if (negative.length === 0) {
+    return { scanned: 0, warnings: [], notice: "No attempt/gotcha memories found yet." };
+  }
+  const usage = await loadUsageIndex9(ctx.paths);
+  const seen = /* @__PURE__ */ new Map();
+  const upsert = (fm, body, reason, score) => {
+    const existing = seen.get(fm.id);
+    if (existing) {
+      if (!existing.reasons.includes(reason)) existing.reasons.push(reason);
+      if (score !== void 0 && (existing.semantic_score ?? 0) < score) {
+        existing.semantic_score = score;
+      }
+      return;
+    }
+    const u = getUsage7(usage, fm.id);
+    seen.set(fm.id, {
+      id: fm.id,
+      type: fm.type,
+      scope: fm.scope,
+      confidence: deriveConfidence6(fm, u),
+      body_preview: body.split("\n").slice(0, 5).join("\n").slice(0, 400),
+      reasons: [reason],
+      ...score !== void 0 ? { semantic_score: score } : {}
+    });
+  };
+  if (input.paths.length > 0) {
+    for (const { memory } of negative) {
+      if (memoryMatchesAnchorPaths4(memory, input.paths)) {
+        upsert(memory.frontmatter, memory.body, "anchor");
+      }
+    }
+  }
+  if (input.diff) {
+    const tokens = tokenizeQuery3(input.diff);
+    if (tokens.length > 0) {
+      for (const { memory } of negative) {
+        if (literalMatchesAnyToken3(memory, tokens)) {
+          upsert(memory.frontmatter, memory.body, "literal");
+        }
+      }
+    }
+  }
+  if (input.semantic && input.diff) {
+    try {
+      const mod = await import("@hiveai/embeddings");
+      const result = await mod.semanticSearch(ctx.paths, input.diff, { limit: input.limit * 2 });
+      if (result) {
+        const negativeIds = new Set(negative.map(({ memory }) => memory.frontmatter.id));
+        for (const hit of result.hits) {
+          if (!negativeIds.has(hit.id)) continue;
+          const found = negative.find(({ memory }) => memory.frontmatter.id === hit.id);
+          if (found) upsert(found.memory.frontmatter, found.memory.body, "semantic", hit.score);
+        }
+      }
+    } catch {
+    }
+  }
+  const warnings = [...seen.values()].sort((a, b) => {
+    const score = (w) => {
+      const reasonW = (w.reasons.includes("anchor") ? 4 : 0) + (w.reasons.includes("literal") ? 2 : 0) + (w.reasons.includes("semantic") ? 1 : 0);
+      const confW = w.confidence === "authoritative" ? 3 : w.confidence === "trusted" ? 2 : w.confidence === "low" ? 1 : 0;
+      return reasonW + confW + (w.semantic_score ?? 0);
+    };
+    return score(b) - score(a);
+  }).slice(0, input.limit);
+  return {
+    scanned: negative.length,
+    warnings
+  };
+}
+
+// src/tools/mem-distill.ts
+import { existsSync as existsSync22 } from "fs";
+import {
+  loadMemoriesFromDir as loadMemoriesFromDir18,
+  tokenizeQuery as tokenizeQuery4
+} from "@hiveai/core";
+import { z as z25 } from "zod";
+var MemDistillInputSchema = {
+  since_days: z25.number().int().positive().default(30).describe("Only consider memories created in the last N days."),
+  min_cluster: z25.number().int().min(2).default(3).describe("Minimum cluster size to surface."),
+  type_filter: z25.enum(["gotcha", "attempt", "all"]).default("gotcha").describe(
+    "Memory type to scan. 'gotcha' targets observe-style discoveries that recur, 'attempt' surfaces failed approaches that repeat, 'all' considers both."
+  ),
+  scope: z25.enum(["personal", "team", "module", "any"]).default("any").describe("Restrict to a specific scope.")
+};
+var MS_PER_DAY = 24 * 60 * 60 * 1e3;
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "that",
+  "this",
+  "from",
+  "into",
+  "when",
+  "then",
+  "also",
+  "must",
+  "have",
+  "does",
+  "not",
+  "but",
+  "you",
+  "your",
+  "its",
+  "because",
+  "why",
+  "how",
+  "what",
+  "use",
+  "using",
+  "used",
+  "add",
+  "added",
+  "make",
+  "made",
+  "fix",
+  "fixed",
+  "bug",
+  "error"
+]);
+async function memDistill(input, ctx) {
+  if (!existsSync22(ctx.paths.memoriesDir)) {
+    return { scanned: 0, singletons: 0, clusters: [], notice: "No .ai/memories directory." };
+  }
+  const cutoff = Date.now() - input.since_days * MS_PER_DAY;
+  const all = await loadMemoriesFromDir18(ctx.paths.memoriesDir);
+  const candidates = all.filter(({ memory }) => {
+    const fm = memory.frontmatter;
+    if (fm.status === "rejected" || fm.status === "deprecated" || fm.status === "stale") return false;
+    if (input.scope !== "any" && fm.scope !== input.scope) return false;
+    if (input.type_filter === "gotcha" && fm.type !== "gotcha") return false;
+    if (input.type_filter === "attempt" && fm.type !== "attempt") return false;
+    if (input.type_filter === "all" && fm.type !== "gotcha" && fm.type !== "attempt") return false;
+    if (Date.parse(fm.created_at) < cutoff) return false;
+    return true;
+  });
+  if (candidates.length < input.min_cluster) {
+    return {
+      scanned: candidates.length,
+      singletons: candidates.length,
+      clusters: [],
+      notice: candidates.length === 0 ? `No matching memories in the last ${input.since_days} days.` : `Only ${candidates.length} candidate${candidates.length === 1 ? "" : "s"} \u2014 below min_cluster=${input.min_cluster}.`
+    };
+  }
+  const features = candidates.map((loaded) => ({
+    loaded,
+    keywords: keywordSet(loaded),
+    paths: new Set(loaded.memory.frontmatter.anchor.paths)
+  }));
+  const parent = features.map((_, i) => i);
+  const find = (i) => parent[i] === i ? i : parent[i] = find(parent[i] ?? 0);
+  const union = (a, b) => {
+    const ra = find(a), rb = find(b);
+    if (ra !== rb) parent[ra] = rb;
+  };
+  for (let i = 0; i < features.length; i++) {
+    for (let j = i + 1; j < features.length; j++) {
+      const fi = features[i], fj = features[j];
+      const pathSim = jaccard(fi.paths, fj.paths);
+      const kwSim = jaccard(fi.keywords, fj.keywords);
+      if (pathSim >= 0.5 || kwSim >= 0.4) union(i, j);
+    }
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (let i = 0; i < features.length; i++) {
+    const root = find(i);
+    const arr = groups.get(root) ?? [];
+    arr.push(i);
+    groups.set(root, arr);
+  }
+  const clusters = [];
+  let singletons = 0;
+  for (const indices of groups.values()) {
+    if (indices.length < input.min_cluster) {
+      singletons += indices.length;
+      continue;
+    }
+    const members = indices.map((i) => features[i]);
+    const allPaths = /* @__PURE__ */ new Set();
+    const allKeywords = /* @__PURE__ */ new Map();
+    let latest = 0;
+    for (const m of members) {
+      for (const p of m.paths) allPaths.add(p);
+      for (const k of m.keywords) allKeywords.set(k, (allKeywords.get(k) ?? 0) + 1);
+      const t = Date.parse(m.loaded.memory.frontmatter.created_at);
+      if (t > latest) latest = t;
+    }
+    const commonKeywords = [...allKeywords.entries()].filter(([, n]) => n >= Math.max(2, Math.floor(members.length / 2))).sort((a, b) => b[1] - a[1]).slice(0, 5).map(([k]) => k);
+    const titles = members.map((m) => firstHeading(m.loaded.memory.body) ?? m.loaded.memory.frontmatter.id).slice(0, 5);
+    const suggestedType = members.every((m) => m.loaded.memory.frontmatter.type === "attempt") ? "gotcha" : "convention";
+    clusters.push({
+      suggested_topic: commonKeywords.slice(0, 3).join("-") || "merged-observations",
+      suggested_type: suggestedType,
+      member_ids: members.map((m) => m.loaded.memory.frontmatter.id),
+      overlapping_paths: [...allPaths].slice(0, 10),
+      common_keywords: commonKeywords,
+      sample_titles: titles,
+      latest_at: new Date(latest).toISOString()
+    });
+  }
+  clusters.sort((a, b) => b.member_ids.length - a.member_ids.length);
+  return {
+    scanned: candidates.length,
+    singletons,
+    clusters
+  };
+}
+function keywordSet(loaded) {
+  const text = (loaded.memory.body + " " + loaded.memory.frontmatter.tags.join(" ")).slice(0, 800);
+  const tokens = tokenizeQuery4(text).filter((t) => t.length >= 4 && !STOP_WORDS.has(t));
+  return new Set(tokens);
+}
+function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0) return 0;
+  let intersect = 0;
+  for (const x of a) if (b.has(x)) intersect++;
+  const union = a.size + b.size - intersect;
+  return union === 0 ? 0 : intersect / union;
+}
+function firstHeading(body) {
+  for (const line of body.split("\n")) {
+    const t = line.trim();
+    if (t.startsWith("#")) return t.replace(/^#+\s*/, "").slice(0, 80);
+    if (t.length > 0) return t.slice(0, 80);
+  }
+  return void 0;
+}
+
+// src/tools/why-this-decision.ts
+import { existsSync as existsSync23 } from "fs";
+import { spawn as spawn2 } from "child_process";
+import {
+  deriveConfidence as deriveConfidence7,
+  getUsage as getUsage8,
+  loadMemoriesFromDir as loadMemoriesFromDir19,
+  loadUsageIndex as loadUsageIndex10,
+  pathsOverlap as singlePathsOverlap
+} from "@hiveai/core";
+import { z as z26 } from "zod";
+var WhyThisDecisionInputSchema = {
+  id: z26.string().min(1).describe("Memory id to inspect (e.g. '2026-04-25-decision-esm-only')."),
+  git_log_limit: z26.number().int().positive().max(20).default(5).describe("How many recent commits per anchor path to surface.")
+};
+async function whyThisDecision(input, ctx) {
+  if (!existsSync23(ctx.paths.memoriesDir)) {
+    return {
+      found: false,
+      related: [],
+      path_neighbors: [],
+      recent_commits: [],
+      notice: "No .ai/memories directory."
+    };
+  }
+  const all = await loadMemoriesFromDir19(ctx.paths.memoriesDir);
+  const usage = await loadUsageIndex10(ctx.paths);
+  const target = all.find(({ memory }) => memory.frontmatter.id === input.id);
+  if (!target) {
+    return {
+      found: false,
+      related: [],
+      path_neighbors: [],
+      recent_commits: [],
+      notice: `Memory '${input.id}' not found.`
+    };
+  }
+  const fm = target.memory.frontmatter;
+  const targetUsage = getUsage8(usage, fm.id);
+  const decision = {
+    id: fm.id,
+    type: fm.type,
+    scope: fm.scope,
+    status: fm.status,
+    confidence: deriveConfidence7(fm, targetUsage),
+    body: target.memory.body,
+    created_at: fm.created_at
+  };
+  const relatedSet = new Set(fm.related_ids ?? []);
+  const related = [];
+  for (const { memory } of all) {
+    if (memory.frontmatter.id === fm.id) continue;
+    const isExplicit = relatedSet.has(memory.frontmatter.id);
+    const isBackLink = (memory.frontmatter.related_ids ?? []).includes(fm.id);
+    if (!isExplicit && !isBackLink) continue;
+    const u = getUsage8(usage, memory.frontmatter.id);
+    related.push({
+      id: memory.frontmatter.id,
+      type: memory.frontmatter.type,
+      scope: memory.frontmatter.scope,
+      confidence: deriveConfidence7(memory.frontmatter, u),
+      body_preview: memory.body.split("\n").slice(0, 4).join("\n").slice(0, 300),
+      relation: isExplicit ? "explicit" : "back-link"
+    });
+  }
+  const targetPaths = fm.anchor.paths;
+  const path_neighbors = [];
+  if (targetPaths.length > 0) {
+    for (const { memory } of all) {
+      if (memory.frontmatter.id === fm.id) continue;
+      if (relatedSet.has(memory.frontmatter.id)) continue;
+      const overlappingPaths = memory.frontmatter.anchor.paths.filter(
+        (p) => targetPaths.some((tp) => singlePathsOverlap(p, tp))
+      );
+      if (overlappingPaths.length === 0) continue;
+      const u = getUsage8(usage, memory.frontmatter.id);
+      path_neighbors.push({
+        id: memory.frontmatter.id,
+        type: memory.frontmatter.type,
+        scope: memory.frontmatter.scope,
+        confidence: deriveConfidence7(memory.frontmatter, u),
+        overlap: overlappingPaths,
+        body_preview: memory.body.split("\n").slice(0, 3).join("\n").slice(0, 200)
+      });
+      if (path_neighbors.length >= 10) break;
+    }
+  }
+  const recent_commits = [];
+  for (const p of targetPaths.slice(0, 5)) {
+    try {
+      const commits = await runGitLog2(ctx.paths.root, p, input.git_log_limit);
+      for (const c of commits) recent_commits.push({ path: p, ...c });
+    } catch {
+    }
+  }
+  const hints = [];
+  if (decision.confidence === "low" || decision.confidence === "stale") {
+    hints.push(`\u26A0\uFE0F Confidence is ${decision.confidence}. Verify this decision still applies before quoting it.`);
+  }
+  if (related.length === 0 && path_neighbors.length === 0 && targetPaths.length === 0) {
+    hints.push("No related memories and no anchored paths \u2014 this decision is isolated; consider adding related_ids or paths.");
+  }
+  if (fm.type !== "decision" && fm.type !== "architecture") {
+    hints.push(`Memory type is '${fm.type}', not 'decision'/'architecture' \u2014 output may be less informative.`);
+  }
+  return {
+    found: true,
+    decision,
+    related,
+    path_neighbors,
+    recent_commits,
+    ...hints.length > 0 ? { hints } : {}
+  };
+}
+async function runGitLog2(cwd, filePath, limit) {
+  const sep = "<<HV>>";
+  const fmt = `%h${sep}%an${sep}%ar${sep}%s`;
+  const output = await runCommand2(
+    "git",
+    ["log", "-n", String(limit), `--pretty=format:${fmt}`, "--", filePath],
+    cwd
+  );
+  if (!output.trim()) return [];
+  return output.split("\n").map((line) => {
+    const [sha = "", author = "", relative_date = "", subject = ""] = line.split(sep);
+    return { sha, author, relative_date, subject };
+  }).filter((c) => c.sha);
+}
+function runCommand2(cmd, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn2(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    proc.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    proc.on("error", reject);
+    proc.on("close", (code) => {
+      if (code === 0) resolve(stdout);
+      else reject(new Error(stderr || `${cmd} exited with code ${code}`));
+    });
+  });
+}
+
+// src/tools/mem-conflicts.ts
+import { existsSync as existsSync24 } from "fs";
+import {
+  deriveConfidence as deriveConfidence8,
+  getUsage as getUsage9,
+  loadMemoriesFromDir as loadMemoriesFromDir20,
+  loadUsageIndex as loadUsageIndex11,
+  pathsOverlap,
+  tokenizeQuery as tokenizeQuery5
+} from "@hiveai/core";
+import { z as z27 } from "zod";
+var MemConflictsInputSchema = {
+  id: z27.string().min(1).describe("Memory id to check for conflicts."),
+  min_score: z27.number().min(0).max(1).default(0.5).describe("Minimum cosine similarity to consider a memory as a potential conflict (semantic mode)."),
+  semantic: z27.boolean().default(true).describe("Use embeddings for similarity. Falls back to keyword overlap when embeddings are not installed.")
+};
+var POSITIVE_PATTERNS = /\b(use|prefer|always|should use|do this|recommended|ok to)\b/i;
+var NEGATIVE_PATTERNS = /\b(do not use|don'?t use|never|avoid|forbidden|deprecated|stop using|do NOT|❌)\b/i;
+async function memConflicts(input, ctx) {
+  if (!existsSync24(ctx.paths.memoriesDir)) {
+    return { found: false, scanned: 0, conflicts: [], notice: "No .ai/memories directory." };
+  }
+  const all = await loadMemoriesFromDir20(ctx.paths.memoriesDir);
+  const target = all.find(({ memory }) => memory.frontmatter.id === input.id);
+  if (!target) {
+    return { found: false, scanned: 0, conflicts: [], notice: `Memory '${input.id}' not found.` };
+  }
+  const usage = await loadUsageIndex11(ctx.paths);
+  const others = all.filter(
+    ({ memory }) => memory.frontmatter.id !== input.id && memory.frontmatter.type !== "session_recap"
+  );
+  const simScores = input.semantic ? await trySemanticSimilarities(ctx, target, others) : null;
+  const targetText = (target.memory.body + " " + target.memory.frontmatter.tags.join(" ")).toLowerCase();
+  const targetTokens = new Set(tokenizeQuery5(targetText));
+  const targetPolarity = polarity(targetText);
+  const targetPaths = target.memory.frontmatter.anchor.paths;
+  const explicitContradicts = extractContradictsTags(target.memory.body);
+  const conflicts = [];
+  for (const other of others) {
+    const fm = other.memory.frontmatter;
+    const otherText = (other.memory.body + " " + fm.tags.join(" ")).toLowerCase();
+    const reasons = [];
+    const sim = simScores?.get(fm.id) ?? null;
+    const hasPathOverlap = fm.anchor.paths.some((p) => targetPaths.some((tp) => pathsOverlap(p, tp)));
+    const otherTokens = new Set(tokenizeQuery5(otherText));
+    const tokenOverlap = countIntersection(targetTokens, otherTokens);
+    const isSemanticNeighbor = sim !== null && sim >= input.min_score;
+    if (!hasPathOverlap && tokenOverlap < 4 && !isSemanticNeighbor) continue;
+    const otherContradicts = extractContradictsTags(other.memory.body);
+    if (explicitContradicts.has(fm.id) || otherContradicts.has(input.id)) {
+      reasons.push("explicit-contradiction-tag");
+    }
+    if (target.memory.frontmatter.status === "validated" && fm.status === "rejected" || target.memory.frontmatter.status === "rejected" && fm.status === "validated") {
+      if (tokenOverlap >= 4 || isSemanticNeighbor) reasons.push("opposite-status");
+    }
+    if (hasPathOverlap) {
+      const tType = target.memory.frontmatter.type;
+      const oType = fm.type;
+      const isAttemptVsRule = tType === "attempt" && (oType === "convention" || oType === "decision") || oType === "attempt" && (tType === "convention" || tType === "decision");
+      if (isAttemptVsRule) reasons.push("attempt-vs-convention-same-paths");
+    }
+    if (isSemanticNeighbor) {
+      const otherPolarity = polarity(otherText);
+      if (targetPolarity === "positive" && otherPolarity === "negative" || targetPolarity === "negative" && otherPolarity === "positive") {
+        reasons.push("polarity-keywords");
+      }
+    }
+    if (reasons.length === 0) continue;
+    const u = getUsage9(usage, fm.id);
+    conflicts.push({
+      id: fm.id,
+      type: fm.type,
+      scope: fm.scope,
+      status: fm.status,
+      confidence: deriveConfidence8(fm, u),
+      body_preview: other.memory.body.split("\n").slice(0, 4).join("\n").slice(0, 300),
+      similarity: sim,
+      reasons,
+      shared_paths: fm.anchor.paths.filter((p) => targetPaths.some((tp) => pathsOverlap(p, tp)))
+    });
+  }
+  conflicts.sort((a, b) => {
+    const score = (c) => (c.reasons.includes("explicit-contradiction-tag") ? 100 : 0) + (c.reasons.includes("opposite-status") ? 50 : 0) + (c.reasons.includes("attempt-vs-convention-same-paths") ? 25 : 0) + (c.reasons.includes("polarity-keywords") ? 10 : 0) + (c.similarity ?? 0) * 5;
+    return score(b) - score(a);
+  });
+  return {
+    found: true,
+    target: {
+      id: target.memory.frontmatter.id,
+      type: target.memory.frontmatter.type,
+      status: target.memory.frontmatter.status
+    },
+    scanned: others.length,
+    conflicts: conflicts.slice(0, 10)
+  };
+}
+function polarity(text) {
+  const neg = NEGATIVE_PATTERNS.test(text);
+  const pos = POSITIVE_PATTERNS.test(text);
+  if (neg && !pos) return "negative";
+  if (pos && !neg) return "positive";
+  return "neutral";
+}
+function extractContradictsTags(body) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of body.matchAll(/#contradicts:([\w-]+)/g)) {
+    if (m[1]) out.add(m[1]);
+  }
+  return out;
+}
+function countIntersection(a, b) {
+  let n = 0;
+  for (const x of a) if (b.has(x)) n++;
+  return n;
+}
+async function trySemanticSimilarities(ctx, target, others) {
+  let mod;
+  try {
+    mod = await import("@hiveai/embeddings");
+  } catch {
+    return null;
+  }
+  const result = await mod.semanticSearch(
+    ctx.paths,
+    target.memory.body,
+    { limit: others.length }
+  );
+  if (!result) return null;
+  const map = /* @__PURE__ */ new Map();
+  for (const hit of result.hits) map.set(hit.id, hit.score);
+  return map;
+}
+
+// src/tools/precommit-check.ts
+import { z as z28 } from "zod";
+var PreCommitCheckInputSchema = {
+  diff: z28.string().optional().describe(
+    "Raw unified diff text to scan. If omitted, only `paths` is used. When called from a pre-commit hook, pipe the output of `git diff --cached`."
+  ),
+  paths: z28.array(z28.string()).default([]).describe("Project-relative paths affected by the change. At least one of `diff` or `paths` should be provided."),
+  block_on: z28.enum(["any", "high-confidence", "never"]).default("high-confidence").describe(
+    "When to set should_block=true: 'any' = any warning blocks; 'high-confidence' = only warnings from authoritative/trusted memories block; 'never' = report only, never block."
+  ),
+  semantic: z28.boolean().default(true).describe("Enable semantic search in anti_patterns_check (requires embeddings index).")
+};
+async function preCommitCheck(input, ctx) {
+  if (!input.diff && input.paths.length === 0) {
+    return {
+      should_block: false,
+      summary: { anti_patterns: 0, relevant_memories: 0, stale_anchors: 0 },
+      warnings: [],
+      relevant_memories: [],
+      stale_anchors: [],
+      notice: "Nothing to check \u2014 provide either `diff` or `paths`."
+    };
+  }
+  const apResult = await antiPatternsCheck({
+    diff: input.diff,
+    paths: input.paths,
+    limit: 20,
+    semantic: input.semantic
+  }, ctx);
+  const relevant = input.paths.length > 0 ? await memForFiles({ files: input.paths, include_module_contexts: false, track: false }, ctx) : { by_anchor: [], by_module: [], by_domain: [], module_contexts: [], inferred_modules: [] };
+  const relevantMatches = [...relevant.by_anchor, ...relevant.by_module];
+  const verifyResult = input.paths.length > 0 ? await memVerify({ update: false, id: void 0 }, ctx) : { results: [], summary: { checked: 0, fresh: 0, stale: 0, anchorless_skipped: 0, updated: 0 } };
+  const filesTouching = new Set(relevantMatches.map((m) => m.id));
+  const staleHits = verifyResult.results.filter((r) => r.stale && filesTouching.has(r.id));
+  const blockOn = input.block_on;
+  let should_block = false;
+  if (blockOn !== "never") {
+    const high = apResult.warnings.filter(
+      (w) => w.confidence === "authoritative" || w.confidence === "trusted"
+    );
+    if (blockOn === "any" && (apResult.warnings.length > 0 || staleHits.length > 0)) should_block = true;
+    if (blockOn === "high-confidence" && (high.length > 0 || staleHits.length > 0)) should_block = true;
+  }
+  const relevant_memories = relevantMatches.slice(0, 8).map((m) => ({
+    id: m.id,
+    type: m.type,
+    confidence: String(m.confidence),
+    body_preview: (m.body ?? "").split("\n").slice(0, 4).join("\n").slice(0, 250)
+  }));
+  return {
+    should_block,
+    summary: {
+      anti_patterns: apResult.warnings.length,
+      relevant_memories: relevant_memories.length,
+      stale_anchors: staleHits.length
+    },
+    warnings: apResult.warnings,
+    relevant_memories,
+    stale_anchors: staleHits.map((r) => ({
+      id: r.id,
+      // The matching `relevantMatches` entry tells us which paths overlap.
+      paths: relevantMatches.find((m) => m.id === r.id) ? input.paths.filter((p) => relevantMatches.some((m) => m.id === r.id)) : [],
+      body_preview: r.reason ?? "anchored code drifted; verify before relying on this memory"
+    }))
+  };
+}
+
+// src/prompts/bootstrap-project.ts
+import { z as z29 } from "zod";
 var BootstrapProjectArgsSchema = {
-  module: z20.string().optional().describe(
+  module: z29.string().optional().describe(
     "Optional module name to scope the analysis to (writes to .ai/modules/<module>/context.md)"
   ),
-  focus: z20.string().optional().describe("Optional area to emphasize (e.g. 'data layer', 'API surface')")
+  focus: z29.string().optional().describe("Optional area to emphasize (e.g. 'data layer', 'API surface')")
 };
 var ROOT_TEMPLATE = `# Project context
 
@@ -1728,10 +2660,10 @@ ${template}\`\`\`
 }
 
 // src/prompts/post-task.ts
-import { z as z21 } from "zod";
+import { z as z30 } from "zod";
 var PostTaskArgsSchema = {
-  task_summary: z21.string().optional().describe("One sentence describing what you just did"),
-  files_touched: z21.array(z21.string()).optional().describe("Files you created or modified during the task")
+  task_summary: z30.string().optional().describe("One sentence describing what you just did"),
+  files_touched: z30.array(z30.string()).optional().describe("Files you created or modified during the task")
 };
 function postTaskPrompt(args, ctx) {
   const taskLine = args.task_summary ? `
@@ -1813,12 +2745,12 @@ When done, respond with a brief summary: "Saved N memories: [list of IDs]. Sessi
 }
 
 // src/prompts/import-docs.ts
-import { z as z22 } from "zod";
+import { z as z31 } from "zod";
 var ImportDocsArgsSchema = {
-  content: z22.string().describe("The documentation content to analyze and import as memories (Markdown, README, ADR, etc.)"),
-  source: z22.string().optional().describe("Origin of the content (file path, URL, or document title) \u2014 used to anchor memories"),
-  scope: z22.enum(["personal", "team"]).default("team").describe("Scope to assign to created memories"),
-  dry_run: z22.boolean().default(false).describe("If true, describe what would be saved without actually calling mem_save")
+  content: z31.string().describe("The documentation content to analyze and import as memories (Markdown, README, ADR, etc.)"),
+  source: z31.string().optional().describe("Origin of the content (file path, URL, or document title) \u2014 used to anchor memories"),
+  scope: z31.enum(["personal", "team"]).default("team").describe("Scope to assign to created memories"),
+  dry_run: z31.boolean().default(false).describe("If true, describe what would be saved without actually calling mem_save")
 };
 function importDocsPrompt(args, ctx) {
   const sourceLine = args.source ? `
@@ -1882,7 +2814,7 @@ When done, respond with: "Imported N memories: [list of IDs]" or "Nothing action
 }
 
 // src/session-tracker.ts
-import { loadConfig as loadConfig3 } from "@hiveai/core";
+import { appendUsageEvent, loadConfig as loadConfig3 } from "@hiveai/core";
 var SessionTracker = class {
   events = [];
   startedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -1899,7 +2831,9 @@ var SessionTracker = class {
     }
   }
   record(tool, summary) {
-    this.events.push({ tool, at: (/* @__PURE__ */ new Date()).toISOString(), summary });
+    const event = { tool, at: (/* @__PURE__ */ new Date()).toISOString(), summary };
+    this.events.push(event);
+    void appendUsageEvent(this.ctx.paths, event);
   }
   registerShutdownHandler() {
     if (this.shutdownRegistered) return;
@@ -1952,7 +2886,7 @@ function summarizeTools(events) {
 
 // src/server.ts
 var SERVER_NAME = "haive";
-var SERVER_VERSION = "0.4.5";
+var SERVER_VERSION = "0.6.0";
 function jsonResult(data) {
   return {
     content: [
@@ -2161,7 +3095,10 @@ function createHaiveServer(options = {}) {
       "RETURNS: array of { id, type, scope, status, confidence, body, match_quality }"
     ].join("\n"),
     MemSearchInputSchema,
-    async (input) => jsonResult(await memSearch(input, context))
+    async (input) => {
+      tracker.record("mem_search", input.query.slice(0, 80));
+      return jsonResult(await memSearch(input, context));
+    }
   );
   server.tool(
     "mem_for_files",
@@ -2389,6 +3326,211 @@ function createHaiveServer(options = {}) {
     MemDeleteInputSchema,
     async (input) => jsonResult(await memDelete(input, context))
   );
+  server.tool(
+    "get_recap",
+    [
+      "Return ONLY the most recent session_recap. Cheaper than get_briefing when",
+      "you just want to know 'what was I doing last time?' and don't need project",
+      "context, modules, or memory ranking.",
+      "",
+      "PARAMETERS:",
+      "  scope \u2014 'personal' | 'team' | 'any' (default 'any', returns the most recent across both)",
+      "",
+      "RETURNS: { recap: { id, scope, revision_count, created_at, body } | null, notice? }"
+    ].join("\n"),
+    GetRecapInputSchema,
+    async (input) => {
+      tracker.record("get_recap", input.scope);
+      return jsonResult(await getRecap(input, context));
+    }
+  );
+  server.tool(
+    "mem_relevant_to",
+    [
+      "One-shot ranked memories for a task \u2014 use instead of get_briefing when",
+      "project context is already loaded and you only want the relevant memory layer.",
+      "",
+      "Reuses the same ranking pipeline (anchor / module / literal / semantic) but",
+      "skips project_context, modules, action_required, etc.",
+      "",
+      "PARAMETERS:",
+      "  task    \u2014 1\u20132 sentences describing what you are about to do (required)",
+      "  files   \u2014 files you'll edit (surfaces anchored memories)",
+      "  limit   \u2014 cap on returned memories (default 8)",
+      "  min_semantic_score \u2014 drop weak semantic hits below this cosine (default 0.25)",
+      "",
+      "RETURNS: { task, search_mode, memories: [...], hints?: [...], empty?: true }"
+    ].join("\n"),
+    MemRelevantToInputSchema,
+    async (input) => {
+      tracker.record("mem_relevant_to", input.task.slice(0, 80));
+      return jsonResult(await memRelevantTo(input, context));
+    }
+  );
+  server.tool(
+    "code_search",
+    [
+      "Semantic search over the codebase \u2014 finds exported symbols (functions, classes,",
+      "interfaces) related to a natural-language query. Replaces blind grep when you",
+      "don't know the exact symbol name.",
+      "",
+      "Requires `haive index code-search` to have been run (builds embeddings for every",
+      "exported symbol from the code-map). Falls back to a notice when index is missing.",
+      "",
+      "PARAMETERS:",
+      "  query     \u2014 natural language (e.g. 'function that hashes passwords', 'JWT signing')",
+      "  k         \u2014 number of top hits (default 5)",
+      "  min_score \u2014 minimum cosine similarity (default 0.2; try 0.3+ for stricter)",
+      "",
+      "RETURNS: { available: bool, hits: [{ file, name, kind, line, description?, score }] }"
+    ].join("\n"),
+    CodeSearchInputSchema,
+    async (input) => {
+      tracker.record("code_search", input.query.slice(0, 80));
+      return jsonResult(await codeSearch(input, context));
+    }
+  );
+  server.tool(
+    "why_this_file",
+    [
+      "One-shot file-context lookup: combines recent git history, memories anchored",
+      "to the path, and the code-map entry. Answers 'why is this file the way it is?'",
+      "in a single call instead of 3-4 manual ones.",
+      "",
+      "PARAMETERS:",
+      "  path           \u2014 project-relative path (required)",
+      "  git_log_limit  \u2014 recent commits to include (default 5)",
+      "  memory_limit   \u2014 anchored memories cap (default 5)",
+      "",
+      "RETURNS: { file, exists, recent_commits: [...], memories: [...], code_map_entry, hints? }"
+    ].join("\n"),
+    WhyThisFileInputSchema,
+    async (input) => {
+      tracker.record("why_this_file", input.path);
+      return jsonResult(await whyThisFile(input, context));
+    }
+  );
+  server.tool(
+    "anti_patterns_check",
+    [
+      "Scan a diff (or set of paths) against documented attempt/gotcha memories.",
+      "Surfaces 'you are about to repeat a known mistake' warnings BEFORE you commit.",
+      "",
+      "USE BEFORE finalizing a non-trivial change. Cheap and high-signal: the only",
+      "memories scanned are 'attempt' and 'gotcha' types.",
+      "",
+      "PARAMETERS:",
+      "  diff     \u2014 raw unified diff text (or any code snippet) \u2014 optional if `paths` provided",
+      "  paths    \u2014 affected file paths (optional if `diff` provided)",
+      "  limit    \u2014 cap on returned warnings (default 8)",
+      "  semantic \u2014 also use semantic search (default true; requires embeddings index)",
+      "",
+      "RETURNS: { scanned, warnings: [{ id, type, scope, confidence, body_preview, reasons, semantic_score? }] }"
+    ].join("\n"),
+    AntiPatternsCheckInputSchema,
+    async (input) => {
+      tracker.record("anti_patterns_check", input.paths.join(",").slice(0, 80));
+      return jsonResult(await antiPatternsCheck(input, context));
+    }
+  );
+  server.tool(
+    "mem_distill",
+    [
+      "Cluster recurring observations / failed attempts so a human can collapse",
+      "N similar memories into one richer convention/gotcha. Cheap heuristic",
+      "(anchor path overlap + body keyword overlap) \u2014 no embeddings required.",
+      "",
+      "USE periodically (e.g. monthly) to prevent memory pollution from agents",
+      "saving the same observation many times.",
+      "",
+      "PARAMETERS:",
+      "  since_days   \u2014 only consider memories from the last N days (default 30)",
+      "  min_cluster  \u2014 minimum cluster size to surface (default 3)",
+      "  type_filter  \u2014 'gotcha' | 'attempt' | 'all' (default 'gotcha')",
+      "  scope        \u2014 'personal' | 'team' | 'module' | 'any' (default 'any')",
+      "",
+      "RETURNS: { scanned, singletons, clusters: [{ suggested_topic, member_ids, ... }] }",
+      "Output is advisory \u2014 nothing is written to disk."
+    ].join("\n"),
+    MemDistillInputSchema,
+    async (input) => {
+      tracker.record("mem_distill", `${input.type_filter}/since=${input.since_days}d`);
+      return jsonResult(await memDistill(input, context));
+    }
+  );
+  server.tool(
+    "why_this_decision",
+    [
+      "Trace the genealogy of a memory (especially decision/architecture):",
+      "the memory itself + memories explicitly linked via related_ids + memories",
+      "anchored to overlapping paths + recent commits touching those paths.",
+      "",
+      "USE WHEN you find a memory and need to understand WHY it was made and",
+      "what surrounds it. One call instead of 4-5 manual lookups.",
+      "",
+      "PARAMETERS:",
+      "  id            \u2014 memory id (required)",
+      "  git_log_limit \u2014 how many recent commits per anchor path (default 5)",
+      "",
+      "RETURNS: { decision, related: [...], path_neighbors: [...], recent_commits: [...] }"
+    ].join("\n"),
+    WhyThisDecisionInputSchema,
+    async (input) => {
+      tracker.record("why_this_decision", input.id);
+      return jsonResult(await whyThisDecision(input, context));
+    }
+  );
+  server.tool(
+    "mem_conflicts_with",
+    [
+      "Detect memories that potentially CONTRADICT a given memory.",
+      "",
+      "USE BEFORE relying on a memory's advice \u2014 surfaces 'another memory says",
+      "the opposite'. Detection uses several heuristics layered together:",
+      "",
+      "  1. Opposite status \u2014 validated vs rejected on overlapping topic",
+      "  2. attempt-vs-convention on overlapping anchor paths",
+      "  3. Polarity keywords \u2014 'use X' vs 'do not use X' among semantic neighbors",
+      "  4. Explicit #contradicts:<id> tags in either body",
+      "",
+      "PARAMETERS:",
+      "  id        \u2014 memory id to check (required)",
+      "  min_score \u2014 minimum cosine similarity for semantic neighbors (default 0.5)",
+      "  semantic  \u2014 use embeddings (default true)",
+      "",
+      "RETURNS: { found, target, scanned, conflicts: [{ id, reasons, similarity, ... }] }"
+    ].join("\n"),
+    MemConflictsInputSchema,
+    async (input) => {
+      tracker.record("mem_conflicts_with", input.id);
+      return jsonResult(await memConflicts(input, context));
+    }
+  );
+  server.tool(
+    "pre_commit_check",
+    [
+      "One-shot 'should I block this commit?' check. Combines three signals:",
+      "",
+      "  1. anti_patterns_check \u2014 known gotchas/attempts that match the diff",
+      "  2. mem_for_files       \u2014 conventions/decisions anchored to touched files",
+      "  3. mem_verify          \u2014 memories whose anchors are stale (knowledge may be wrong)",
+      "",
+      "USE FROM A GIT HOOK or before finalizing a non-trivial change.",
+      "",
+      "PARAMETERS:",
+      "  diff       \u2014 raw unified diff text (e.g. `git diff --cached`)",
+      "  paths      \u2014 affected file paths (project-relative)",
+      "  block_on   \u2014 'any' | 'high-confidence' (default) | 'never'",
+      "  semantic   \u2014 use embeddings in anti_patterns_check (default true)",
+      "",
+      "RETURNS: { should_block, summary, warnings, relevant_memories, stale_anchors }"
+    ].join("\n"),
+    PreCommitCheckInputSchema,
+    async (input) => {
+      tracker.record("pre_commit_check", `${input.paths.length}p`);
+      return jsonResult(await preCommitCheck(input, context));
+    }
+  );
   server.tool(
     "mem_diff",
     [