@hiveai/mcp 0.9.15 → 0.9.17

package/README.md

@@ -2,7 +2,7 @@
 
 > **hAIve MCP server** — policy-aware briefing and memory tools for MCP-compatible AI coding agents.
 
-The MCP server is how agents load team policy before changing code. By default it exposes a small enforcement-oriented tool surface: briefing, relevant memories, failed-attempt capture, anchor verification, code-map lookup, and pre-commit checks. The larger maintenance surface is still available with `HAIVE_TOOL_PROFILE=full`.
+The MCP server is how agents load team policy before changing code. By default it exposes a small enforcement-oriented tool surface: briefing, relevant memories, failed-attempt capture, anchor verification, code-map lookup, and pre-commit checks. Larger maintenance and experimental surfaces are opt-in via `HAIVE_TOOL_PROFILE`.
 
 hAIve is not just a memory database. The MCP layer participates in enforcement: state-changing hAIve tools require `get_briefing` or `mem_relevant_to` first, so agents cannot silently skip team context while using hAIve.
 
@@ -117,17 +117,26 @@ Default tools:
 - `mem_tried`
 - `mem_search`
 - `mem_get`
-- `mem_update`
 - `mem_verify`
 - `code_map`
 - `pre_commit_check`
+- `mem_session_end`
 
 Default prompts:
 
 - `bootstrap_project`
 - `post_task`
 
-Set `HAIVE_TOOL_PROFILE=full` to expose advanced lifecycle, import, timeline, conflict, runtime-journal, and diagnostic tools.
+### Tool Profiles
+
+`HAIVE_TOOL_PROFILE` controls how much hAIve surface an agent sees:
+
+- `enforcement` (default): compact repo-native context harness for coding agents.
+- `maintenance`: adds corpus review, lifecycle, distillation, code-search, and project-context maintenance tools.
+- `experimental`: adds exploratory diagnostics such as runtime journal, pattern detection, why-this-file, why-this-decision, and conflict analysis.
+- `full`: legacy alias for `experimental`.
+
+Use `maintenance` for human/team stewardship sessions and `experimental` only when you are intentionally working on hAIve's broader research tooling.
 
 ### `get_briefing` ⭐ Start every task with this
 

package/dist/index.js

@@ -224,7 +224,6 @@ async function memSave(input, ctx) {
       const { similarityWarning: simW, body_similar: bs } = bodySimilarWarnings(/* @__PURE__ */ new Set([fm.id]));
       const newFrontmatter = {
         ...fm,
-        body: input.body,
         tags: input.tags.length ? input.tags : fm.tags,
         revision_count: (fm.revision_count ?? 0) + 1,
         anchor: {
@@ -240,6 +239,7 @@ async function memSave(input, ctx) {
       );
       const mergedTw = [
         invalidPaths.length > 0 ? `Anchor path(s) not found in project: ${invalidPaths.join(", ")}. They will be marked stale by haive sync.` : null,
+        criticalAnchorWarning(input.type, fm.status, newFrontmatter.anchor.paths, newFrontmatter.anchor.symbols),
         simW ?? null
       ].filter(Boolean).join(" \u2014 ") || void 0;
       return {
@@ -295,6 +295,7 @@ async function memSave(input, ctx) {
   const { similarityWarning: simWarnNew, body_similar: bsNew } = bodySimilarWarnings();
   const finalWarning = [
     invalidPaths.length > 0 ? `Anchor path(s) not found in project: ${invalidPaths.join(", ")}. They will be marked stale by \`haive sync\`.` : null,
+    criticalAnchorWarning(frontmatter.type, frontmatter.status, frontmatter.anchor.paths, frontmatter.anchor.symbols),
     warning ?? null,
     simWarnNew ?? null
   ].filter(Boolean).join(" \u2014 ") || void 0;
@@ -309,6 +310,12 @@ async function memSave(input, ctx) {
     ...invalidPaths.length > 0 ? { invalid_paths: invalidPaths } : {}
   };
 }
+function criticalAnchorWarning(type, status, paths, symbols) {
+  if (!["decision", "gotcha", "architecture"].includes(type)) return null;
+  if (status !== "validated") return null;
+  if (paths.length > 0 || symbols.length > 0) return null;
+  return `${type} is validated without paths or symbols; add anchors so hAIve can detect drift.`;
+}
 
 // src/tools/mem-search.ts
 import { existsSync as existsSync5 } from "fs";
@@ -1385,6 +1392,7 @@ import {
   extractActionsBriefBody,
   getUsage as getUsage5,
   inferModulesFromPaths as inferModulesFromPaths2,
+  isGlobPath,
   isAutoPromoteEligible,
   isDecaying,
   literalMatchesAllTokens as literalMatchesAllTokens2,
@@ -1506,6 +1514,7 @@ async function getBriefing(input, ctx) {
         reasons: [reason],
         match_quality: matchQuality ?? "partial",
         ...score !== void 0 ? { semantic_score: score } : {},
+        priority: "background",
         body: loaded.memory.body,
         file_path: loaded.filePath
       });
@@ -1521,6 +1530,13 @@ async function getBriefing(input, ctx) {
         if (fm.tags.some((t) => inferred.includes(t))) addOrUpdate(loaded, "module", void 0, "partial");
       }
     }
+    if (input.symbols.length > 0) {
+      const wanted = new Set(input.symbols.map((s) => s.toLowerCase()));
+      for (const loaded of allMemories) {
+        const symbols = loaded.memory.frontmatter.anchor.symbols.map((s) => s.toLowerCase());
+        if (symbols.some((s) => wanted.has(s))) addOrUpdate(loaded, "symbol", void 0, "exact");
+      }
+    }
     if (input.task) {
       const tokens = tokenizeQuery2(input.task);
       const andHits = allMemories.filter((m) => literalMatchesAllTokens2(m.memory, tokens));
@@ -1546,11 +1562,12 @@ async function getBriefing(input, ctx) {
       }
     }
     const ranked = [...seen.values()].sort((a, b) => {
+      const priorityScore = (m) => priorityRank(classifyMemoryPriority(m, byId.get(m.id), input.files, input.symbols));
       const reasonScore = (m) => (m.type === "attempt" ? 3 : 0) + // attempt = negative knowledge, surface first to prevent repeating mistakes
-      (m.reasons.includes("anchor") ? 4 : 0) + (m.reasons.includes("module") ? 2 : 0) + (m.reasons.includes("semantic") ? 2 : 0) + (m.reasons.includes("domain") ? 1 : 0);
+      (m.reasons.includes("anchor") ? 4 : 0) + (m.reasons.includes("symbol") ? 4 : 0) + (m.reasons.includes("module") ? 2 : 0) + (m.reasons.includes("semantic") ? 2 : 0) + (m.reasons.includes("domain") ? 1 : 0);
       const confidenceScore = (m) => m.confidence === "authoritative" ? 4 : m.confidence === "trusted" ? 3 : m.confidence === "low" ? 1 : m.confidence === "stale" ? -2 : 0;
-      const sa = reasonScore(a) + confidenceScore(a) + (a.semantic_score ?? 0);
-      const sb = reasonScore(b) + confidenceScore(b) + (b.semantic_score ?? 0);
+      const sa = priorityScore(a) * 100 + reasonScore(a) + confidenceScore(a) + (a.semantic_score ?? 0);
+      const sb = priorityScore(b) * 100 + reasonScore(b) + confidenceScore(b) + (b.semantic_score ?? 0);
       return sb - sa;
     });
     for (const mem of ranked.slice(0, briefingMaxMemories)) {
@@ -1709,8 +1726,15 @@ ${m.content}`).join("\n\n---\n\n"),
   })) : trimmedMemories;
   const outputMemories = formattedMemories.map((m) => ({
     ...m,
+    priority: classifyMemoryPriority(m, byId.get(m.id), input.files, input.symbols),
     why: explainWhySurfaced(m, byId.get(m.id), input.files, inferred)
   }));
+  const briefingQuality = classifyBriefingQuality(outputMemories, {
+    isTemplateContext,
+    autoContextGenerated,
+    hasLastSession: Boolean(lastSession),
+    searchMode
+  });
   let symbolLocations;
   const symbolsToLookup = new Set(input.symbols);
   for (const m of outputMemories) {
@@ -1851,6 +1875,7 @@ When done, call \`mem_session_end\` to acknowledge \u2014 this clears the pendin
     } : null,
     module_contexts: trimmedModules,
     memories: outputMemories,
+    briefing_quality: briefingQuality,
     ...symbolLocations ? { symbol_locations: symbolLocations } : {},
     action_required: actionRequired,
     decay_warnings: decayWarnings,
@@ -1876,6 +1901,53 @@ function compactSummary(body) {
   }
   return body.slice(0, 120);
 }
+function classifyMemoryPriority(memory, loaded, inputFiles, inputSymbols) {
+  const fm = loaded?.memory.frontmatter;
+  const directAnchor = Boolean(
+    fm && inputFiles.length > 0 && fm.anchor.paths.some((p) => inputFiles.some((file) => pathsOverlap(p, file)))
+  );
+  const directSymbol = Boolean(
+    fm && inputSymbols.length > 0 && fm.anchor.symbols.some(
+      (sym) => inputSymbols.some((wanted) => wanted.toLowerCase() === sym.toLowerCase())
+    )
+  );
+  const strongSemantic = (memory.semantic_score ?? 0) >= 0.65;
+  const usefulSemantic = (memory.semantic_score ?? 0) >= 0.35;
+  if (fm?.requires_human_approval || directAnchor || directSymbol || memory.type === "attempt" && (memory.match_quality === "exact" || strongSemantic)) {
+    return "must_read";
+  }
+  if (memory.reasons.includes("module") || memory.reasons.includes("domain") || memory.match_quality === "exact" || usefulSemantic) {
+    return "useful";
+  }
+  return "background";
+}
+function priorityRank(priority) {
+  return priority === "must_read" ? 3 : priority === "useful" ? 2 : 1;
+}
+function classifyBriefingQuality(memories, context) {
+  const mustRead = memories.filter((m) => m.priority === "must_read").length;
+  const useful = memories.filter((m) => m.priority === "useful").length;
+  const background = memories.filter((m) => m.priority === "background").length;
+  const weakSemantic = memories.filter(
+    (m) => m.reasons.length === 1 && m.reasons.includes("semantic") && (m.semantic_score ?? 0) > 0 && (m.semantic_score ?? 0) < 0.35
+  ).length;
+  const reasons = [];
+  if (memories.length === 0) reasons.push("no memories matched the task or files");
+  if (context.isTemplateContext && !context.autoContextGenerated) reasons.push("project context is still a template");
+  if (!context.hasLastSession) reasons.push("no previous session recap");
+  if (mustRead > 0) reasons.push(`${mustRead} must_read memor${mustRead === 1 ? "y" : "ies"} matched directly`);
+  if (useful > 0) reasons.push(`${useful} useful memor${useful === 1 ? "y" : "ies"} matched`);
+  if (background > useful + mustRead && background > 2) reasons.push(`${background} background memories dominate the result`);
+  if (weakSemantic > 0) reasons.push(`${weakSemantic} weak semantic-only match${weakSemantic === 1 ? "" : "es"}`);
+  if (context.searchMode === "literal_fallback") reasons.push("semantic index unavailable or empty; literal fallback used");
+  if (memories.length === 0 || mustRead === 0 && useful === 0) {
+    return { level: "thin", reasons };
+  }
+  if (background > useful + mustRead && background > 2) {
+    return { level: "noisy", reasons };
+  }
+  return { level: "strong", reasons };
+}
 function explainWhySurfaced(memory, loaded, inputFiles, inferredModules) {
   const why = [];
   const fm = loaded?.memory.frontmatter;
@@ -1884,7 +1956,19 @@ function explainWhySurfaced(memory, loaded, inputFiles, inferredModules) {
       (p) => inputFiles.length === 0 || inputFiles.some((file) => pathsOverlap(p, file))
     );
     if (matching.length > 0) {
-      why.push(`Anchored to touched path${matching.length === 1 ? "" : "s"}: ${matching.slice(0, 4).join(", ")}`);
+      const exact = matching.filter(
+        (p) => !isGlobPath(p) && inputFiles.some((file) => p === file || pathsOverlap(p, file))
+      );
+      const glob = matching.filter((p) => isGlobPath(p));
+      if (exact.length > 0) {
+        why.push(`Exact/file anchor match: ${exact.slice(0, 4).join(", ")}`);
+      }
+      if (glob.length > 0) {
+        why.push(`Glob anchor match: ${glob.slice(0, 4).join(", ")}`);
+      }
+      if (exact.length === 0 && glob.length === 0) {
+        why.push(`Anchored to touched path${matching.length === 1 ? "" : "s"}: ${matching.slice(0, 4).join(", ")}`);
+      }
     } else if (fm.anchor.paths.length > 0) {
       why.push(`Pulled by related anchor: ${fm.anchor.paths.slice(0, 4).join(", ")}`);
     }
@@ -1892,6 +1976,9 @@ function explainWhySurfaced(memory, loaded, inputFiles, inferredModules) {
       why.push(`Anchor symbol${fm.anchor.symbols.length === 1 ? "" : "s"}: ${fm.anchor.symbols.slice(0, 4).join(", ")}`);
     }
   }
+  if (memory.reasons.includes("symbol") && fm) {
+    why.push(`Explicit symbol match: ${fm.anchor.symbols.slice(0, 4).join(", ")}`);
+  }
   if (memory.reasons.includes("module")) {
     const moduleHints = [
       ...memory.module ? [memory.module] : [],
@@ -2133,7 +2220,8 @@ async function memRelevantTo(input, ctx) {
   const out = {
     task: input.task,
     search_mode: briefing.search_mode,
-    memories: briefing.memories
+    memories: briefing.memories,
+    briefing_quality: briefing.briefing_quality
   };
   if (briefing.hints && briefing.hints.length > 0) out.hints = briefing.hints;
   if (briefing.memories.length === 0) out.empty = true;
@@ -2880,7 +2968,7 @@ async function preCommitCheck(input, ctx) {
   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;
-  const classifiedWarnings = apResult.warnings.map(classifyWarning);
+  const classifiedWarnings = apResult.warnings.map((warning) => classifyWarning(warning, input.paths));
   const blockingWarnings = classifiedWarnings.filter((w) => w.level === "blocking");
   const reviewWarnings = classifiedWarnings.filter((w) => w.level === "review");
   const infoWarnings = classifiedWarnings.filter((w) => w.level === "info");
@@ -2915,12 +3003,26 @@ async function preCommitCheck(input, ctx) {
     }))
   };
 }
-function classifyWarning(warning) {
+function classifyWarning(warning, paths) {
+  const affectedFiles = paths.filter((p) => !p.startsWith(".ai/.usage/"));
+  const repairCommand = repairCommandForWarning(warning, affectedFiles);
+  const fileDowngrade = fileTypeDowngradeReason(warning, affectedFiles);
+  if (fileDowngrade) {
+    return {
+      ...warning,
+      level: "info",
+      rationale: fileDowngrade,
+      affected_files: affectedFiles,
+      repair_command: repairCommand
+    };
+  }
   if (isBlockingWarning(warning)) {
     return {
       ...warning,
       level: "blocking",
-      rationale: "authoritative/trusted memory plus strong semantic match to the diff (score >= 0.65)"
+      rationale: "authoritative/trusted memory plus strong semantic match to the diff (score >= 0.65)",
+      affected_files: affectedFiles,
+      repair_command: repairCommand
     };
   }
   const hasSemantic = warning.reasons.includes("semantic");
@@ -2930,13 +3032,17 @@ function classifyWarning(warning) {
     return {
       ...warning,
       level: "review",
-      rationale: hasSemantic ? "semantic match is plausible but below blocking threshold" : "anchored high-confidence memory also matched diff tokens, but no strong semantic proof"
+      rationale: hasSemantic ? "semantic match is plausible but below blocking threshold" : "anchored high-confidence memory also matched diff tokens, but no strong semantic proof",
+      affected_files: affectedFiles,
+      repair_command: repairCommand
     };
   }
   return {
     ...warning,
     level: "info",
-    rationale: "weak signal only (literal/anchor/low semantic evidence); surfaced for audit, hidden in concise CLI output"
+    rationale: "weak signal only (literal/anchor/low semantic evidence); surfaced for audit, hidden in concise CLI output",
+    affected_files: affectedFiles,
+    repair_command: repairCommand
   };
 }
 function isBlockingWarning(warning) {
@@ -2944,6 +3050,40 @@ function isBlockingWarning(warning) {
   if (!highConfidence) return false;
   return warning.reasons.includes("semantic") && (warning.semantic_score ?? 0) >= 0.65;
 }
+function fileTypeDowngradeReason(warning, paths) {
+  if (paths.length === 0) return null;
+  if (paths.every((p) => p.startsWith(".ai/.usage/") || p === ".ai/.usage/tool-usage.jsonl")) {
+    return ".ai usage logs are local telemetry and never block commits.";
+  }
+  const docsOnly = paths.every(isDocLikePath);
+  if (docsOnly && !hasStrongSemantic(warning)) {
+    return "docs/changelog-only change; anti-pattern is downgraded unless semantic evidence is strong.";
+  }
+  const configOnly = paths.every(isPackageOrConfigPath);
+  if (configOnly && looksRuntimeSpecific(warning) && !warning.reasons.includes("anchor") && !hasStrongSemantic(warning)) {
+    return "package/config-only change; runtime-specific gotcha is not anchored or semantically strong.";
+  }
+  return null;
+}
+function hasStrongSemantic(warning) {
+  return warning.reasons.includes("semantic") && (warning.semantic_score ?? 0) >= 0.65;
+}
+function isDocLikePath(file) {
+  const lower = file.toLowerCase();
+  return lower.endsWith(".md") || lower.includes("changelog") || lower.startsWith("docs/") || lower.startsWith(".github/") && lower.endsWith(".md");
+}
+function isPackageOrConfigPath(file) {
+  const lower = file.toLowerCase();
+  return lower.endsWith("package.json") || lower.endsWith("package-lock.json") || lower.endsWith("pnpm-lock.yaml") || lower.endsWith("yarn.lock") || lower.endsWith("bun.lockb") || lower.endsWith(".config.ts") || lower.endsWith(".config.js") || lower.endsWith(".json") || lower.endsWith(".yml") || lower.endsWith(".yaml") || lower.startsWith(".github/workflows/");
+}
+function looksRuntimeSpecific(warning) {
+  const text = `${warning.body_preview} ${warning.id}`.toLowerCase();
+  return /\b(runtime|controller|request|response|database|transaction|auth|cache|production|service|api|endpoint)\b/.test(text);
+}
+function repairCommandForWarning(warning, paths) {
+  const firstPath = paths[0];
+  return firstPath ? `haive briefing --files "${firstPath}" --task "review ${warning.id}"` : `haive memory show ${warning.id}`;
+}
 
 // src/tools/pattern-detect.ts
 import { mkdir as mkdir7, writeFile as writeFile12 } from "fs/promises";
@@ -3530,7 +3670,7 @@ When done, respond with: "Imported N memories: [list of IDs]" or "Nothing action
 // src/server.ts
 import { loadConfigSync } from "@hiveai/core";
 var SERVER_NAME = "haive";
-var SERVER_VERSION = "0.9.15";
+var SERVER_VERSION = "0.9.17";
 function jsonResult(data) {
   return {
     content: [
@@ -3541,7 +3681,7 @@ function jsonResult(data) {
     ]
   };
 }
-var ENFORCEMENT_PROFILE_TOOLS = /* @__PURE__ */ new Set([
+var ENFORCEMENT_PROFILE_TOOLS = [
   "get_briefing",
   "mem_save",
   "mem_tried",
@@ -3552,7 +3692,47 @@ var ENFORCEMENT_PROFILE_TOOLS = /* @__PURE__ */ new Set([
   "code_map",
   "pre_commit_check",
   "mem_session_end"
-]);
+];
+var MAINTENANCE_PROFILE_TOOLS = [
+  ...ENFORCEMENT_PROFILE_TOOLS,
+  "mem_suggest_topic",
+  "mem_for_files",
+  "mem_list",
+  "get_project_context",
+  "bootstrap_project_save",
+  "mem_resolve_project",
+  "mem_update",
+  "mem_approve",
+  "mem_reject",
+  "mem_pending",
+  "mem_delete",
+  "mem_diff",
+  "get_recap",
+  "code_search",
+  "anti_patterns_check",
+  "mem_distill",
+  "mem_timeline",
+  "mem_conflict_candidates"
+];
+var EXPERIMENTAL_PROFILE_TOOLS = [
+  ...MAINTENANCE_PROFILE_TOOLS,
+  "mem_observe",
+  "why_this_file",
+  "why_this_decision",
+  "mem_conflicts_with",
+  "pattern_detect",
+  "runtime_journal_append",
+  "runtime_journal_tail"
+];
+var TOOL_PROFILES = {
+  enforcement: new Set(ENFORCEMENT_PROFILE_TOOLS),
+  maintenance: new Set(MAINTENANCE_PROFILE_TOOLS),
+  experimental: new Set(EXPERIMENTAL_PROFILE_TOOLS)
+};
+function getAllowedToolsForProfile(profile) {
+  if (profile === "full") return TOOL_PROFILES.experimental;
+  return TOOL_PROFILES[profile] ?? TOOL_PROFILES.enforcement;
+}
 var BRIEFING_TOOLS = /* @__PURE__ */ new Set(["get_briefing", "mem_relevant_to"]);
 var MUTATING_TOOLS = /* @__PURE__ */ new Set([
   "mem_save",
@@ -3579,7 +3759,8 @@ function createHaiveServer(options = {}) {
     { name: SERVER_NAME, version: SERVER_VERSION },
     { capabilities: { tools: {}, prompts: {} } }
   );
-  const shouldRegisterTool = (name) => toolProfile === "full" || ENFORCEMENT_PROFILE_TOOLS.has(name);
+  const allowedTools = getAllowedToolsForProfile(toolProfile);
+  const shouldRegisterTool = (name) => allowedTools.has(name);
   const registerTool = (name, description, schema, handler) => {
     if (!shouldRegisterTool(name)) return;
     const tool = server.tool.bind(server);
@@ -3603,7 +3784,11 @@ function createHaiveServer(options = {}) {
       }
     );
   };
-  const shouldRegisterPrompt = (name) => toolProfile === "full" || name === "bootstrap_project" || name === "post_task";
+  const shouldRegisterPrompt = (name) => {
+    if (name === "bootstrap_project" || name === "post_task") return true;
+    if (name === "import_docs") return toolProfile !== "enforcement";
+    return toolProfile === "experimental" || toolProfile === "full";
+  };
   registerTool(
     "mem_save",
     [