@hiveai/mcp 0.3.0 → 0.3.3

package/dist/index.js

@@ -130,6 +130,7 @@ import { existsSync as existsSync4 } from "fs";
 import path3 from "path";
 import {
   buildFrontmatter,
+  loadConfig,
   loadMemoriesFromDir as loadMemoriesFromDir2,
   memoryFilePath,
   serializeMemory
@@ -207,10 +208,12 @@ async function memSave(input, ctx) {
       };
     }
   }
+  const haiveConfig = await loadConfig(ctx.paths);
+  const resolvedScope = input.scope !== "personal" ? input.scope : haiveConfig.defaultScope ?? "personal";
   const frontmatter = buildFrontmatter({
     type: input.type,
     slug: input.slug,
-    scope: input.scope,
+    scope: resolvedScope,
     module: input.module,
     tags: input.tags,
     domain: input.domain,
@@ -218,7 +221,8 @@ async function memSave(input, ctx) {
     paths: input.paths,
     symbols: input.symbols,
     commit: input.commit,
-    topic: input.topic
+    topic: input.topic,
+    status: haiveConfig.defaultStatus === "validated" ? "validated" : void 0
   });
   const file = memoryFilePath(
     ctx.paths,
@@ -1165,6 +1169,7 @@ import {
   literalMatchesAllTokens as literalMatchesAllTokens2,
   literalMatchesAnyToken as literalMatchesAnyToken2,
   loadCodeMap,
+  loadConfig as loadConfig2,
   loadMemoriesFromDir as loadMemoriesFromDir13,
   loadUsageIndex as loadUsageIndex7,
   memoryMatchesAnchorPaths as memoryMatchesAnchorPaths2,
@@ -1322,17 +1327,55 @@ async function getBriefing(input, ctx) {
   }
   const projectContextRaw = input.include_project_context && existsSync17(ctx.paths.projectContext) ? await readFile3(ctx.paths.projectContext, "utf8") : "";
   const isTemplateContext = projectContextRaw.includes("TODO \u2014 high-level overview") || projectContextRaw.includes("Generated by `haive init`");
-  const projectContext = isTemplateContext ? "" : projectContextRaw;
   const setupWarnings = [];
-  if (isTemplateContext) {
-    setupWarnings.push(
-      "project-context.md still contains the default template. Invoke the bootstrap_project MCP prompt to auto-fill it from your codebase. Until then, get_briefing returns no project context."
-    );
-  }
-  if (!existsSync17(ctx.paths.projectContext)) {
-    setupWarnings.push(
-      "No project-context.md found. Run `haive init` then invoke the bootstrap_project MCP prompt."
-    );
+  let autoContextGenerated = false;
+  let projectContext = isTemplateContext ? "" : projectContextRaw;
+  if ((isTemplateContext || !existsSync17(ctx.paths.projectContext)) && input.include_project_context) {
+    const haiveConfig = await loadConfig2(ctx.paths);
+    if (haiveConfig.autoContext) {
+      const codeMap = await loadCodeMap(ctx.paths);
+      if (codeMap) {
+        const totalFiles = Object.keys(codeMap.files).length;
+        const extensions = /* @__PURE__ */ new Map();
+        for (const filePath of Object.keys(codeMap.files)) {
+          const ext = filePath.slice(filePath.lastIndexOf(".") + 1).toLowerCase();
+          extensions.set(ext, (extensions.get(ext) ?? 0) + 1);
+        }
+        const topExts = [...extensions.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([e, n]) => `${e} (${n})`).join(", ");
+        const topSymbols = Object.entries(codeMap.files).flatMap(
+          ([fp, entry]) => entry.exports.slice(0, 3).map((e) => `${e.name} (${fp.split("/").slice(-2).join("/")})`)
+        ).slice(0, 15).join(", ");
+        projectContext = `# Project context (auto-generated by hAIve)
+
+> \u26A0 This is a minimal auto-generated context based on the code-map. Invoke the \`bootstrap_project\` MCP prompt to replace it with a full analysis.
+
+## Codebase overview
+- **${totalFiles} files** indexed in code-map
+- **Main file types:** ${topExts}
+- **Generated at:** ${codeMap.generated_at}
+
+## Key exports (sample)
+` + topSymbols + "\n";
+        autoContextGenerated = true;
+        setupWarnings.push(
+          "project-context.md is still the default template. A minimal auto-generated context has been injected from the code-map. Invoke bootstrap_project to replace it with a full AI-analyzed context."
+        );
+      } else {
+        setupWarnings.push(
+          "project-context.md is still the default template and no code-map found. Run `haive index code` then invoke bootstrap_project for a full context."
+        );
+      }
+    } else {
+      if (isTemplateContext) {
+        setupWarnings.push(
+          "project-context.md still contains the default template. Invoke the bootstrap_project MCP prompt to auto-fill it from your codebase. Until then, get_briefing returns no project context."
+        );
+      } else {
+        setupWarnings.push(
+          "No project-context.md found. Run `haive init` then invoke the bootstrap_project MCP prompt."
+        );
+      }
+    }
   }
   const moduleContents = input.include_module_contexts ? await loadModuleContexts2(ctx, inferred) : [];
   const memoriesText = memories.map((m) => {
@@ -1431,10 +1474,11 @@ ${m.content}`).join("\n\n---\n\n"),
     search_mode: searchMode,
     inferred_modules: inferred,
     ...lastSession ? { last_session: lastSession } : {},
-    project_context: projectContextRaw ? {
+    project_context: projectContextRaw || autoContextGenerated ? {
       content: projectSlice.text,
       truncated: projectSlice.truncated,
-      ...isTemplateContext ? { is_template: true } : {}
+      ...isTemplateContext && !autoContextGenerated ? { is_template: true } : {},
+      ...autoContextGenerated ? { auto_generated: true } : {}
     } : null,
     module_contexts: trimmedModules,
     memories: outputMemories,
@@ -1804,9 +1848,78 @@ When done, respond with: "Imported N memories: [list of IDs]" or "Nothing action
   };
 }
 
+// src/session-tracker.ts
+import { loadConfig as loadConfig3 } from "@hiveai/core";
+var SessionTracker = class {
+  events = [];
+  startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  config = null;
+  ctx;
+  shutdownRegistered = false;
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  async init() {
+    this.config = await loadConfig3(this.ctx.paths);
+    if (this.config.autoSessionEnd) {
+      this.registerShutdownHandler();
+    }
+  }
+  record(tool, summary) {
+    this.events.push({ tool, at: (/* @__PURE__ */ new Date()).toISOString(), summary });
+  }
+  registerShutdownHandler() {
+    if (this.shutdownRegistered) return;
+    this.shutdownRegistered = true;
+    const save = async () => {
+      const writingTools = this.events.filter(
+        (e) => ["mem_save", "mem_tried", "mem_observe", "mem_update", "bootstrap_project_save"].includes(e.tool)
+      );
+      const totalCalls = this.events.length;
+      if (totalCalls === 0) return;
+      const toolSummary = summarizeTools(this.events);
+      const filesSet = /* @__PURE__ */ new Set();
+      for (const e of this.events) {
+        if (e.summary) {
+          const matches = e.summary.match(/[^\s"',]+\.[a-zA-Z]{1,6}/g) ?? [];
+          for (const m of matches) filesSet.add(m);
+        }
+      }
+      try {
+        await memSessionEnd(
+          {
+            goal: `Auto-captured session (${totalCalls} tool call${totalCalls === 1 ? "" : "s"})`,
+            accomplished: toolSummary,
+            discoveries: writingTools.length > 0 ? `${writingTools.length} memor${writingTools.length === 1 ? "y" : "ies"} saved during this session.` : "No new memories saved this session.",
+            files_touched: [...filesSet].slice(0, 10),
+            next_steps: "",
+            scope: this.config?.defaultScope ?? "personal",
+            module: void 0
+          },
+          this.ctx
+        );
+      } catch {
+      }
+    };
+    process.once("SIGTERM", () => {
+      void save().finally(() => process.exit(0));
+    });
+    process.once("SIGINT", () => {
+      void save().finally(() => process.exit(0));
+    });
+  }
+};
+function summarizeTools(events) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const e of events) {
+    counts.set(e.tool, (counts.get(e.tool) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([t, n]) => `${t} \xD7${n}`).join(", ");
+}
+
 // src/server.ts
 var SERVER_NAME = "haive";
-var SERVER_VERSION = "0.3.0";
+var SERVER_VERSION = "0.3.3";
 function jsonResult(data) {
   return {
     content: [
@@ -1819,143 +1932,474 @@ function jsonResult(data) {
 }
 function createHaiveServer(options = {}) {
   const context = createContext(options);
+  const tracker = new SessionTracker(context);
+  void tracker.init();
   const server = new McpServer(
     { name: SERVER_NAME, version: SERVER_VERSION },
     { capabilities: { tools: {}, prompts: {} } }
   );
   server.tool(
     "mem_save",
-    "Save a new memory (convention, decision, gotcha, architecture, glossary). For failed approaches use mem_tried instead \u2014 it enforces a structured format that is more useful to future agents. Use scope=team to share with the whole team.",
+    [
+      "Save a piece of knowledge as a persistent memory that survives across AI sessions.",
+      "",
+      "USE THIS WHEN you discover something worth remembering for future sessions:",
+      "  - A project convention (how things are done here)",
+      "  - An architectural decision and its rationale",
+      "  - A gotcha or non-obvious behavior that surprised you",
+      "  - A domain term and what it means in this codebase",
+      "",
+      "DO NOT USE for failed approaches \u2192 use mem_tried instead (better structure).",
+      "DO NOT USE for code discoveries during exploration \u2192 use mem_observe instead.",
+      "",
+      "PARAMETERS:",
+      "  type     \u2014 convention | decision | gotcha | architecture | glossary | attempt",
+      "  slug     \u2014 short kebab-case id (e.g. 'flyway-no-modify-existing')",
+      "  body     \u2014 Markdown content with the full knowledge",
+      "  scope    \u2014 team (shared with all devs) | personal (private) | module (component-scoped)",
+      "  paths    \u2014 anchor to source files for staleness detection (STRONGLY recommended)",
+      "  topic    \u2014 stable key for upsert: if a memory with same topic+scope exists, update it in-place",
+      "",
+      "RETURNS: { id, scope, file_path, action: 'created'|'updated', warning?, invalid_paths? }",
+      "WARNING: if paths point to non-existent files, they will be immediately stale after haive sync.",
+      "DEDUP: identical body content within the same scope is rejected \u2014 use mem_update to modify."
+    ].join("\n"),
     MemSaveInputSchema,
-    async (input) => jsonResult(await memSave(input, context))
+    async (input) => {
+      tracker.record("mem_save", input.slug);
+      return jsonResult(await memSave(input, context));
+    }
+  );
+  server.tool(
+    "mem_tried",
+    [
+      "Record a FAILED approach so future agents don't repeat the same mistake.",
+      "",
+      "USE THIS IMMEDIATELY when you try something and it doesn't work. This is the",
+      "most valuable type of negative knowledge \u2014 it saves hours of debugging for",
+      "future agents working on the same codebase.",
+      "",
+      "Auto-validated (no approval cycle). Surfaced FIRST in future get_briefing calls",
+      "so it's impossible to miss.",
+      "",
+      "PARAMETERS:",
+      "  what       \u2014 short title of what you tried (e.g. 'importing X with ESM dynamic import')",
+      "  why_failed \u2014 the exact error or reason it failed",
+      "  instead    \u2014 what to do instead (the correct approach)",
+      "  scope      \u2014 team (default) | personal",
+      "  paths      \u2014 source files where the issue lives",
+      "",
+      "RETURNS: { id, file_path, action: 'created' }"
+    ].join("\n"),
+    MemTriedInputSchema,
+    async (input) => {
+      tracker.record("mem_tried", input.what.slice(0, 80));
+      return jsonResult(await memTried(input, context));
+    }
+  );
+  server.tool(
+    "mem_observe",
+    [
+      "Capture a code-level discovery made WHILE READING existing code.",
+      "",
+      "USE THIS when you read a file and spot something the team may not know about:",
+      "  - A bug or race condition hiding in the code",
+      "  - A security gap or missing validation",
+      "  - An inconsistency between two files",
+      "  - A missing configuration or environment variable",
+      "  - Anything that could silently break in production",
+      "",
+      "DIFFERENCE from mem_save: mem_observe is for REACTIVE discoveries during code",
+      "reading. mem_save is for deliberate knowledge capture (conventions, decisions).",
+      "",
+      "Auto-validated, anchored to file paths for staleness detection.",
+      "",
+      "PARAMETERS:",
+      "  what   \u2014 one-line title (e.g. 'MobilePaymentController: duplicate @RequestBody')",
+      "  where  \u2014 file path(s) where the issue lives",
+      "  impact \u2014 what breaks or could break because of this",
+      "  fix    \u2014 suggested fix (optional)",
+      "  scope  \u2014 team (default, since discoveries benefit everyone)",
+      "",
+      "RETURNS: { id, file_path }"
+    ].join("\n"),
+    MemObserveInputSchema,
+    async (input) => {
+      tracker.record("mem_observe", input.where);
+      return jsonResult(await memObserve(input, context));
+    }
+  );
+  server.tool(
+    "mem_session_end",
+    [
+      "Save an end-of-session recap so the NEXT session starts with fresh context.",
+      "",
+      "CALL THIS before closing any significant working session. In autopilot mode,",
+      "the MCP server saves a minimal recap automatically on exit \u2014 but calling this",
+      "manually produces a richer, more useful recap.",
+      "",
+      "HOW IT WORKS: uses topic-upsert \u2014 one recap per scope is kept and updated",
+      "in-place (revision_count increments). get_briefing surfaces the latest recap",
+      "at the very top of the next session's briefing, before project context.",
+      "",
+      "PARAMETERS:",
+      "  goal         \u2014 what you were trying to accomplish (1\u20132 sentences)",
+      "  accomplished \u2014 what was actually done (bullet list recommended)",
+      "  discoveries  \u2014 bugs, surprises, missing knowledge found during this session",
+      "  files_touched \u2014 key files read or modified (used as anchor for staleness)",
+      "  next_steps   \u2014 what should happen in the next session or for a teammate",
+      "  scope        \u2014 personal (default) | team",
+      "",
+      "RETURNS: { id, scope, action: 'created'|'updated', revision_count }"
+    ].join("\n"),
+    MemSessionEndInputSchema,
+    async (input) => {
+      tracker.record("mem_session_end", input.goal.slice(0, 80));
+      return jsonResult(await memSessionEnd(input, context));
+    }
+  );
+  server.tool(
+    "get_briefing",
+    [
+      "\u2B50 CALL THIS FIRST at the start of every task. One-shot onboarding that returns",
+      "everything relevant in a single call under a token budget.",
+      "",
+      "RETURNS (in order of priority):",
+      "  1. last_session   \u2014 recap of the previous session (goal, what was done, next steps)",
+      "  2. project_context \u2014 .ai/project-context.md (auto-generated from code-map if template)",
+      "  3. module_contexts \u2014 relevant .ai/modules/<name>/context.md based on files being edited",
+      "  4. memories        \u2014 ranked team memories relevant to your task",
+      "  5. symbol_locations \u2014 file:line:kind for any requested symbols (no grep needed)",
+      "  6. setup_warnings  \u2014 actionable warnings if setup is incomplete",
+      "  7. decay_warnings  \u2014 memories not read in >90 days (consider reviewing)",
+      "",
+      "KEY PARAMETERS:",
+      "  task    \u2014 what you are about to do (1\u20132 sentences) \u2014 ALWAYS provide this",
+      "  files   \u2014 files you are about to edit \u2014 surfaces anchored memories",
+      "  symbols \u2014 symbol names to look up in the code-map (e.g. ['PaymentService'])",
+      "  format  \u2014 'full' (default) | 'compact' (1-line summaries, use when token budget is tight)",
+      "",
+      "EXAMPLE USAGE:",
+      "  get_briefing({ task: 'add a Stripe payment integration', files: ['src/payments/'], symbols: ['PaymentService'] })",
+      "",
+      "CONFIDENCE LEVELS in memories:",
+      "  authoritative \u2014 validated + read 10+ times (highest trust)",
+      "  trusted       \u2014 validated or proposed + read 3+ times",
+      "  low           \u2014 proposed, few reads (take with caution)",
+      "  unverified    \u2014 draft (unverified: true flag set)",
+      "",
+      "Replaces 4\u20135 separate tool calls. Always call this before any other tool."
+    ].join("\n"),
+    GetBriefingInputSchema,
+    async (input) => {
+      tracker.record("get_briefing", input.task ?? "");
+      return jsonResult(await getBriefing(input, context));
+    }
   );
   server.tool(
     "mem_search",
-    "Search memories by substring across id, tags, and body. Optional filters by scope/type/module.",
+    [
+      "Search memories by keyword or semantic similarity.",
+      "",
+      "USE WHEN you need to find a specific memory and don't know its id.",
+      "For session onboarding, use get_briefing instead (richer, ranked, budgeted).",
+      "",
+      "SEARCH MODES:",
+      "  Literal (default): AND search across id, tags, and body \u2014 all tokens must match.",
+      "  Falls back to OR automatically if no AND results (partial match).",
+      "  Semantic (semantic: true): embedding-based similarity \u2014 finds related memories",
+      "  even with different wording. Requires haive embeddings index to be built.",
+      "",
+      "PARAMETERS:",
+      "  query    \u2014 search terms or natural language question",
+      "  scope    \u2014 filter by personal | team | module",
+      "  type     \u2014 filter by convention | decision | gotcha | architecture | glossary",
+      "  semantic \u2014 true for embedding-based search (requires @hiveai/embeddings)",
+      "  limit    \u2014 max results (default 10)",
+      "",
+      "RETURNS: array of { id, type, scope, status, confidence, body, match_quality }"
+    ].join("\n"),
     MemSearchInputSchema,
     async (input) => jsonResult(await memSearch(input, context))
   );
+  server.tool(
+    "mem_for_files",
+    [
+      "Surface memories relevant to the files you are currently editing.",
+      "",
+      "USE WHEN starting work on specific files and you want to know:",
+      "  - What conventions apply to these files",
+      "  - What gotchas are anchored to these paths",
+      "  - What decisions were made about this module",
+      "",
+      "Matching strategy (in priority order):",
+      "  1. Anchor overlap \u2014 memories whose paths overlap with your files",
+      "  2. Module context \u2014 .ai/modules/<name>/context.md if module is inferred",
+      "  3. Domain/tag match \u2014 memories whose tags include path segments",
+      "",
+      "PARAMETERS:",
+      "  files \u2014 list of project-relative file paths you are editing",
+      "  scope \u2014 filter by scope (default: all)",
+      "",
+      "RETURNS: { memories: [...], module_contexts: [...] }"
+    ].join("\n"),
+    MemForFilesInputSchema,
+    async (input) => jsonResult(await memForFiles(input, context))
+  );
+  server.tool(
+    "mem_get",
+    [
+      "Fetch a single memory by its full id with all details.",
+      "",
+      "USE WHEN get_briefing returned a memory in 'compact' format and you need",
+      "the full body, or when you know the exact id of a memory.",
+      "",
+      "PARAMETERS:",
+      "  id \u2014 full memory id (e.g. '2026-04-28-gotcha-flyway-strict-no-ddl')",
+      "",
+      "RETURNS: { id, type, scope, status, confidence, body, anchor, tags, usage }"
+    ].join("\n"),
+    MemGetInputSchema,
+    async (input) => jsonResult(await memGet(input, context))
+  );
   server.tool(
     "mem_list",
-    "List memories with optional filters by scope/type/module/tag.",
+    [
+      "List memories with optional filters. Use for browsing, not for task onboarding.",
+      "",
+      "For task onboarding use get_briefing (ranked + budgeted).",
+      "For keyword search use mem_search.",
+      "",
+      "PARAMETERS:",
+      "  scope  \u2014 personal | team | module",
+      "  type   \u2014 convention | decision | gotcha | architecture | glossary",
+      "  status \u2014 draft | proposed | validated | stale | rejected",
+      "  tags   \u2014 filter by tags (AND match)",
+      "  module \u2014 filter by module name",
+      "",
+      "RETURNS: array of { id, type, scope, status, confidence, tags, created_at }"
+    ].join("\n"),
     MemListInputSchema,
     async (input) => jsonResult(await memList(input, context))
   );
   server.tool(
     "get_project_context",
-    "Read the shared .ai/project-context.md (and optionally a module context).",
+    [
+      "Read .ai/project-context.md (and optionally a module context) directly.",
+      "",
+      "USE WHEN you need the full project context without the memory ranking and",
+      "token budgeting of get_briefing \u2014 e.g. for a reference architecture review.",
+      "",
+      "For normal task onboarding, use get_briefing instead (more efficient).",
+      "",
+      "PARAMETERS:",
+      "  module \u2014 also load .ai/modules/<module>/context.md if provided",
+      "",
+      "RETURNS: { content: string, module_context?: string }"
+    ].join("\n"),
     GetProjectContextInputSchema,
     async (input) => jsonResult(await getProjectContext(input, context))
   );
   server.tool(
-    "get_briefing",
-    "One-shot onboarding: returns project context + module contexts + ranked relevant memories under a token budget. Replaces 4\u20135 separate calls when an agent starts a task.",
-    GetBriefingInputSchema,
-    async (input) => jsonResult(await getBriefing(input, context))
+    "bootstrap_project_save",
+    [
+      "Persist the project context document (.ai/project-context.md) or a module",
+      "context (.ai/modules/<name>/context.md) analyzed by the AI.",
+      "",
+      "USE AFTER the bootstrap_project MCP prompt: the prompt tells you how to",
+      "analyze the codebase; this tool saves the result.",
+      "",
+      "PARAMETERS:",
+      "  content \u2014 full Markdown content of the context document",
+      "  module  \u2014 if provided, saves as a module context (not root project context)",
+      "",
+      "RETURNS: { file_path, module? }"
+    ].join("\n"),
+    BootstrapProjectSaveInputSchema,
+    async (input) => jsonResult(await bootstrapProjectSave(input, context))
   );
   server.tool(
     "code_map",
-    "Browse the project's pre-computed code map (file \u2192 exports + 1-line description) instead of grepping. Requires `haive index code`.",
+    [
+      "Look up where symbols (classes, functions, interfaces) are defined in the codebase.",
+      "",
+      "USE INSTEAD OF grepping when you need to find where something lives.",
+      "Requires haive index code to have been run (done automatically in autopilot mode).",
+      "",
+      "TIP: include symbols in get_briefing directly for auto-lookup at session start.",
+      "",
+      "PARAMETERS:",
+      "  symbol   \u2014 name or partial name to search (e.g. 'PaymentService')",
+      "  file     \u2014 filter by file path substring",
+      "  max_files \u2014 cap on results (default 40)",
+      "",
+      "RETURNS: { available: bool, files: [{ path, exports: [{ name, kind, line, description }] }] }",
+      "If available: false \u2192 run haive index code first."
+    ].join("\n"),
     CodeMapInputSchema,
     async (input) => jsonResult(await codeMapTool(input, context))
   );
   server.tool(
-    "bootstrap_project_save",
-    "Persist a project (or module) context document analyzed by the AI client.",
-    BootstrapProjectSaveInputSchema,
-    async (input) => jsonResult(await bootstrapProjectSave(input, context))
+    "mem_update",
+    [
+      "Update the body, tags, or anchor of an existing memory in-place.",
+      "",
+      "USE WHEN a memory exists but its content has become outdated or incomplete.",
+      "This preserves the memory's id, usage history, and read_count.",
+      "",
+      "For evolving memories that you will update repeatedly, use mem_save with a",
+      "topic key instead (topic-upsert pattern).",
+      "",
+      "PARAMETERS:",
+      "  id      \u2014 full memory id to update",
+      "  body    \u2014 new Markdown content (replaces existing body)",
+      "  tags    \u2014 new tag list (replaces existing tags)",
+      "  paths   \u2014 new anchor paths (replaces existing paths)",
+      "  symbols \u2014 new anchor symbols (replaces existing symbols)",
+      "",
+      "RETURNS: { id, file_path, updated_fields: string[] }"
+    ].join("\n"),
+    MemUpdateInputSchema,
+    async (input) => jsonResult(await memUpdate(input, context))
   );
   server.tool(
     "mem_verify",
-    "Check anchor freshness for one or every memory; optionally write status updates back to disk.",
+    [
+      "Check whether memory anchor paths and symbols still exist in the current code.",
+      "",
+      "USE WHEN you want to know if a specific memory is still valid after a refactor,",
+      "or to check all memories for staleness (haive sync does this automatically).",
+      "",
+      "PARAMETERS:",
+      "  id     \u2014 check a single memory (omit to check all)",
+      "  update \u2014 write 'stale' or 'validated' status back to disk",
+      "",
+      "RETURNS: { results: [{ id, status: 'fresh'|'stale'|'anchorless', reason? }] }",
+      "Stale means the anchored file/symbol no longer exists at that path.",
+      "Anchorless means the memory has no paths/symbols \u2014 staleness is undetectable."
+    ].join("\n"),
     MemVerifyInputSchema,
     async (input) => jsonResult(await memVerify(input, context))
   );
+  server.tool(
+    "mem_approve",
+    [
+      "Mark a memory as validated (trusted, approved by a human or the team).",
+      "",
+      "In autopilot mode, memories are validated automatically \u2014 you rarely need this.",
+      "In manual mode, call this after reviewing a proposed memory to activate it.",
+      "",
+      "PARAMETERS:",
+      "  id \u2014 full memory id to approve",
+      "",
+      "RETURNS: { id, previous_status, new_status: 'validated' }"
+    ].join("\n"),
+    MemApproveInputSchema,
+    async (input) => jsonResult(await memApprove(input, context))
+  );
   server.tool(
     "mem_reject",
-    "Record a rejection for a memory (blocks auto-promotion and lowers its trust signal).",
+    [
+      "Mark a memory as rejected and record a reason.",
+      "",
+      "USE WHEN a memory is factually wrong, outdated, or not useful.",
+      "Rejection blocks auto-promotion and lowers the memory's trust signal.",
+      "Rejected memories are excluded from get_briefing by default.",
+      "",
+      "PARAMETERS:",
+      "  id     \u2014 full memory id to reject",
+      "  reason \u2014 why this memory is being rejected (stored in frontmatter)",
+      "",
+      "RETURNS: { id, previous_status, new_status: 'rejected' }"
+    ].join("\n"),
     MemRejectInputSchema,
     async (input) => jsonResult(await memReject(input, context))
   );
-  server.tool(
-    "mem_for_files",
-    "Given the file paths the agent is currently working on, return relevant memories grouped by reason (anchor overlap, module, domain) plus any matching .ai/modules/<name>/context.md contents.",
-    MemForFilesInputSchema,
-    async (input) => jsonResult(await memForFiles(input, context))
-  );
-  server.tool(
-    "mem_get",
-    "Fetch a single memory by id, including its body, anchor, usage, and confidence.",
-    MemGetInputSchema,
-    async (input) => jsonResult(await memGet(input, context))
-  );
-  server.tool(
-    "mem_delete",
-    "Delete a memory by id (and its usage entry by default).",
-    MemDeleteInputSchema,
-    async (input) => jsonResult(await memDelete(input, context))
-  );
-  server.tool(
-    "mem_update",
-    "Update the body, tags, or anchor of an existing memory without changing its id or losing usage history.",
-    MemUpdateInputSchema,
-    async (input) => jsonResult(await memUpdate(input, context))
-  );
   server.tool(
     "mem_pending",
-    "List 'proposed' memories awaiting review, sorted by reads (most-read first).",
+    [
+      "List memories in 'proposed' status awaiting review, sorted by read count.",
+      "",
+      "USE IN MANUAL MODE to see what memories are waiting for human review.",
+      "In autopilot mode, proposed memories auto-approve after 72h.",
+      "",
+      "High read_count on a proposed memory = many agents found it useful without",
+      "rejecting it = strong signal to approve.",
+      "",
+      "RETURNS: array of { id, type, scope, read_count, created_at, body_preview }"
+    ].join("\n"),
     MemPendingInputSchema,
     async (input) => jsonResult(await memPending(input, context))
   );
   server.tool(
-    "mem_approve",
-    "Mark a memory as validated immediately (explicit team review).",
-    MemApproveInputSchema,
-    async (input) => jsonResult(await memApprove(input, context))
-  );
-  server.tool(
-    "mem_tried",
-    "Preferred way to record a failed approach. Enforces a structured what/why_failed/instead format that is immediately actionable for future agents. Auto-validated (no approval cycle). Use whenever you tried an approach and it failed \u2014 prevents the same mistake from happening in the next session.",
-    MemTriedInputSchema,
-    async (input) => jsonResult(await memTried(input, context))
+    "mem_delete",
+    [
+      "Permanently delete a memory by id.",
+      "",
+      "USE WITH CAUTION \u2014 prefer mem_reject for outdated memories (preserves history).",
+      "Use delete only for accidentally created memories or duplicates.",
+      "",
+      "PARAMETERS:",
+      "  id            \u2014 full memory id to delete",
+      "  delete_usage  \u2014 also delete usage stats (default: true)",
+      "",
+      "RETURNS: { deleted: true, id }"
+    ].join("\n"),
+    MemDeleteInputSchema,
+    async (input) => jsonResult(await memDelete(input, context))
   );
   server.tool(
     "mem_diff",
-    "Compare two memories side-by-side: shows frontmatter fields that differ and lines unique to each body. Useful before merging or deduplicating memories.",
+    [
+      "Compare two memories side-by-side to decide if they should be merged.",
+      "",
+      "USE BEFORE merging or deduplicating similar memories.",
+      "Shows: frontmatter fields that differ + lines unique to each body.",
+      "",
+      "PARAMETERS:",
+      "  id_a \u2014 first memory id",
+      "  id_b \u2014 second memory id",
+      "",
+      "RETURNS: { frontmatter_diff: {...}, body_only_in_a: [...], body_only_in_b: [...] }"
+    ].join("\n"),
     MemDiffInputSchema,
     async (input) => jsonResult(await memDiff(input, context))
   );
-  server.tool(
-    "mem_observe",
-    "Capture a code-level discovery made during exploration: a bug, inconsistency, missing config, or security gap found by reading existing code that was NOT in the briefing. Use this whenever you read code and spot something that could silently break in production. Auto-validated, anchored to file paths for staleness detection. Prefer this over mem_save for reactive discoveries during code reading.",
-    MemObserveInputSchema,
-    async (input) => jsonResult(await memObserve(input, context))
-  );
-  server.tool(
-    "mem_session_end",
-    "Save a structured end-of-session recap (goal / accomplished / discoveries / next steps). Uses topic-upsert: one recap per scope is kept and updated in-place so the next session always has fresh context. Call this before closing every significant session. get_briefing automatically surfaces the latest recap at the top of the next session's briefing.",
-    MemSessionEndInputSchema,
-    async (input) => jsonResult(await memSessionEnd(input, context))
-  );
   server.prompt(
     "bootstrap_project",
-    "Instructions for the AI client to analyze the project and save the context.",
+    [
+      "Analyze the project codebase and write .ai/project-context.md \u2014 run once after haive init.",
+      "The AI explores the directory structure, reads key files (package.json, README, config),",
+      "identifies the tech stack, architectural patterns, key modules, and conventions,",
+      "then persists everything via bootstrap_project_save.",
+      "For multi-component projects, run with module param to create .ai/modules/<name>/context.md."
+    ].join(" "),
     BootstrapProjectArgsSchema,
     (args) => bootstrapProjectPrompt(args, context)
   );
   server.prompt(
     "post_task",
-    "Post-task checklist: run this after completing a task to capture failed approaches, new conventions, decisions, and gotchas before closing the session.",
+    [
+      "\u2B50 Post-task reflection \u2014 run at the end of every session to capture what you learned:",
+      "failed approaches (mem_tried), new conventions/decisions/gotchas (mem_save),",
+      "code discoveries (mem_observe), and an end-of-session recap (mem_session_end).",
+      "In autopilot mode a minimal recap saves automatically; calling this produces a richer one."
+    ].join(" "),
     PostTaskArgsSchema,
     (args) => postTaskPrompt(args, context)
   );
   server.prompt(
     "import_docs",
-    "Analyze documentation (README, ADR, wiki page, etc.) and save the actionable knowledge as hAIve memories. Pass the content and an optional source/scope.",
+    [
+      "Import knowledge from a document (README, ADR, wiki, API spec) as hAIve memories.",
+      "Pass the full document content; the AI extracts up to 10 actionable memories",
+      "(conventions, decisions, gotchas, architecture) and saves them via mem_save.",
+      "Good candidates: ADRs, onboarding docs, runbooks, team wikis."
+    ].join(" "),
     ImportDocsArgsSchema,
     (args) => importDocsPrompt(args, context)
   );
-  return { server, context };
+  return { server, context, tracker };
 }
 
 // src/index.ts