@hiveai/mcp 0.9.3 → 0.9.5

package/dist/server.d.ts

@@ -1,5 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { HaivePaths, ConfidenceLevel } from '@hiveai/core';
+import * as _hiveai_core from '@hiveai/core';
+import { HaivePaths, ConfidenceLevel, resolveProjectInfo } from '@hiveai/core';
 import { z } from 'zod';
 
 interface HaiveContext {
@@ -565,6 +566,62 @@ interface PatternDetectOutput {
 }
 declare function patternDetect(input: PatternDetectInput, ctx: HaiveContext): Promise<PatternDetectOutput>;
 
+/** Input is intentionally minimal — callers may pass cwd for multi-root clients. */
+declare const MemResolveProjectInputSchema: {
+    cwd: z.ZodOptional<z.ZodString>;
+};
+type MemResolveProjectInput = {
+    [K in keyof typeof MemResolveProjectInputSchema]: z.infer<(typeof MemResolveProjectInputSchema)[K]>;
+};
+declare function memResolveProject(input: MemResolveProjectInput, _ctx: HaiveContext): Promise<{
+    info: ReturnType<typeof resolveProjectInfo>;
+    ok: true;
+}>;
+
+declare const MemSuggestTopicInputSchema: {
+    type: z.ZodEnum<["convention", "decision", "gotcha", "architecture", "glossary", "attempt", "session_recap"]>;
+    title: z.ZodString;
+};
+type MemSuggestTopicInput = {
+    [K in keyof typeof MemSuggestTopicInputSchema]: z.infer<(typeof MemSuggestTopicInputSchema)[K]>;
+};
+declare function memSuggestTopic(input: MemSuggestTopicInput, _ctx: HaiveContext): Promise<{
+    topic_key: string;
+    family: string;
+    type: string;
+}>;
+
+declare const MemTimelineInputSchema: {
+    memory_id: z.ZodOptional<z.ZodString>;
+    topic: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+};
+type MemTimelineInput = {
+    [K in keyof typeof MemTimelineInputSchema]: z.infer<(typeof MemTimelineInputSchema)[K]>;
+};
+declare function memTimeline(input: MemTimelineInput, ctx: HaiveContext): Promise<{
+    entries: _hiveai_core.TimelineEntry[];
+    total: number;
+    notice: string | undefined;
+}>;
+
+declare const MemConflictCandidatesInputSchema: {
+    since_days: z.ZodDefault<z.ZodNumber>;
+    types: z.ZodDefault<z.ZodArray<z.ZodEnum<["decision", "architecture", "convention", "gotcha"]>, "many">>;
+    min_jaccard: z.ZodDefault<z.ZodNumber>;
+    max_pairs: z.ZodDefault<z.ZodNumber>;
+    max_scan: z.ZodDefault<z.ZodNumber>;
+};
+type MemConflictCandidatesInput = {
+    [K in keyof typeof MemConflictCandidatesInputSchema]: z.infer<(typeof MemConflictCandidatesInputSchema)[K]>;
+};
+declare function memConflictCandidates(input: MemConflictCandidatesInput, ctx: HaiveContext): Promise<{
+    pairs: _hiveai_core.ConflictCandidatePair[];
+    scanned: number;
+    truncated: boolean;
+    notice: string | undefined;
+}>;
+
 declare const SERVER_NAME = "haive";
 declare const SERVER_VERSION: string;
 declare function createHaiveServer(options?: CreateContextOptions): {
@@ -587,4 +644,4 @@ declare function runHaiveMcpStdio(options: {
     root?: string;
 }): Promise<void>;
 
-export { type AntiPatternsCheckInput, type AntiPatternsCheckOutput, type BriefingOutput, type CodeMapInput, type CodeMapToolOutput, type CodeSearchInput, type CodeSearchOutput, type GetBriefingInput, type GetRecapInput, type GetRecapOutput, type MemConflictsInput, type MemConflictsOutput, type MemDistillInput, type MemDistillOutput, type MemRelevantToInput, type MemRelevantToOutput, type PatternDetectInput, type PatternDetectOutput, type PreCommitCheckInput, type PreCommitCheckOutput, SERVER_NAME, SERVER_VERSION, type WhyThisDecisionInput, type WhyThisDecisionOutput, type WhyThisFileInput, type WhyThisFileOutput, antiPatternsCheck, codeMapTool, codeSearch, createHaiveServer, getBriefing, getRecap, memConflicts, memDistill, memRelevantTo, parseMcpCliArgs, patternDetect, preCommitCheck, printHaiveMcpVersion, runHaiveMcpStdio, whyThisDecision, whyThisFile };
+export { type AntiPatternsCheckInput, type AntiPatternsCheckOutput, type BriefingOutput, type CodeMapInput, type CodeMapToolOutput, type CodeSearchInput, type CodeSearchOutput, type GetBriefingInput, type GetRecapInput, type GetRecapOutput, type MemConflictCandidatesInput, type MemConflictsInput, type MemConflictsOutput, type MemDistillInput, type MemDistillOutput, type MemRelevantToInput, type MemRelevantToOutput, type MemResolveProjectInput, type MemSuggestTopicInput, type MemTimelineInput, type PatternDetectInput, type PatternDetectOutput, type PreCommitCheckInput, type PreCommitCheckOutput, SERVER_NAME, SERVER_VERSION, type WhyThisDecisionInput, type WhyThisDecisionOutput, type WhyThisFileInput, type WhyThisFileOutput, antiPatternsCheck, codeMapTool, codeSearch, createHaiveServer, getBriefing, getRecap, memConflictCandidates, memConflicts, memDistill, memRelevantTo, memResolveProject, memSuggestTopic, memTimeline, parseMcpCliArgs, patternDetect, preCommitCheck, printHaiveMcpVersion, runHaiveMcpStdio, whyThisDecision, whyThisFile };

package/dist/server.js

@@ -319,6 +319,7 @@ import {
   loadMemoriesFromDir as loadMemoriesFromDir3,
   loadUsageIndex,
   pickSnippetNeedle,
+  rankMemoriesLexical,
   tokenizeQuery,
   trackReads
 } from "@hiveai/core";
@@ -335,6 +336,9 @@ var MemSearchInputSchema = {
   semantic: z5.boolean().default(false).describe(
     "Use semantic similarity from the embeddings index (requires `haive embeddings index`)."
   ),
+  lexical_rank: z5.boolean().default(false).describe(
+    "When true (and semantic is false), rank the filtered corpus with Okapi-BM25-style lexical scoring instead of literal AND/OR. Helps phrase-like queries without embeddings."
+  ),
   min_score: z5.number().min(0).max(1).default(0).describe("Minimum cosine similarity (semantic mode only)"),
   track: z5.boolean().default(true).describe("Increment read_count on returned memories (used for passive validation)")
 };
@@ -360,6 +364,27 @@ async function memSearch(input, ctx) {
         notice: "Semantic search unavailable (embeddings index missing or @hiveai/embeddings not installed). Falling back to literal search."
       };
     }
+  } else if (input.lexical_rank && input.query.trim()) {
+    const { ranked, scores } = rankMemoriesLexical(
+      filtered,
+      input.query,
+      input.limit
+    );
+    if (ranked.length > 0) {
+      const snippetNeedle = pickSnippetNeedle(input.query);
+      result = {
+        matches: ranked.map(
+          (loaded, i) => lexicalHit(loaded, snippetNeedle, usage, scores[i])
+        ),
+        total: ranked.length,
+        mode: "lexical_ranked"
+      };
+    } else {
+      result = {
+        ...buildLiteralResult(input, filtered, usage),
+        notice: "Lexical ranking found no BM25-positive hits \u2014 showing literal matches instead."
+      };
+    }
   } else {
     result = buildLiteralResult(input, filtered, usage);
   }
@@ -457,6 +482,9 @@ function toHit(loaded, needle, usage) {
     file_path: loaded.filePath
   };
 }
+function lexicalHit(loaded, needle, usage, lexicalScore) {
+  return { ...toHit(loaded, needle, usage), score: lexicalScore };
+}
 
 // src/tools/mem-verify.ts
 import { writeFile as writeFile3 } from "fs/promises";
@@ -3038,13 +3066,96 @@ function gitFileDiff(root, file, sinceDays) {
   }
 }
 
-// src/prompts/bootstrap-project.ts
+// src/tools/mem-conflict-candidates.ts
+import { existsSync as existsSync27 } from "fs";
+import { findLexicalConflictPairs, loadMemoriesFromDir as loadMemoriesFromDir21 } from "@hiveai/core";
 import { z as z30 } from "zod";
+var MemConflictCandidatesInputSchema = {
+  since_days: z30.number().int().positive().max(3650).default(365).describe("Only memories created since N days ago"),
+  types: z30.array(z30.enum(["decision", "architecture", "convention", "gotcha"])).default(["decision", "architecture"]).describe("Memory types scanned for pairwise lexical overlap"),
+  min_jaccard: z30.number().min(0).max(1).default(0.45).describe("Minimum Jaccard token similarity to surface as a candidate pair"),
+  max_pairs: z30.number().int().positive().max(100).default(20).describe("Cap pairs returned"),
+  max_scan: z30.number().int().positive().max(2e3).default(500).describe("Maximum memories sampled for O(n\xB2) scan \u2014 excess dropped after chronological sort.")
+};
+async function memConflictCandidates(input, ctx) {
+  if (!existsSync27(ctx.paths.memoriesDir)) {
+    return {
+      pairs: [],
+      scanned: 0,
+      truncated: false,
+      notice: "No .ai/memories directory."
+    };
+  }
+  const all = await loadMemoriesFromDir21(ctx.paths.memoriesDir);
+  const { pairs, scanned, truncated } = findLexicalConflictPairs(all, {
+    sinceDays: input.since_days,
+    types: input.types,
+    minJaccard: input.min_jaccard,
+    maxPairs: input.max_pairs,
+    maxScan: input.max_scan
+  });
+  const notice = pairs.length === 0 ? "No lexical candidate pairs \u2265 threshold \u2014 try lowering min_jaccard or widen since_days/types." : void 0;
+  return { pairs, scanned, truncated, notice };
+}
+
+// src/tools/mem-resolve-project.ts
+import { resolveProjectInfo } from "@hiveai/core";
+import { z as z31 } from "zod";
+var MemResolveProjectInputSchema = {
+  cwd: z31.string().optional().describe("Directory used for root discovery when HAIVE_PROJECT_ROOT is unset.")
+};
+async function memResolveProject(input, _ctx) {
+  void _ctx;
+  return {
+    ok: true,
+    info: resolveProjectInfo({
+      cwd: input.cwd
+    })
+  };
+}
+
+// src/tools/mem-suggest-topic.ts
+import { MemoryTypeSchema, suggestTopicKey } from "@hiveai/core";
+import { z as z32 } from "zod";
+var MemSuggestTopicInputSchema = {
+  type: MemoryTypeSchema.describe("Memory kind \u2014 drives the suggested topic family."),
+  title: z32.string().min(1).describe("Short title or phrase (headers, headings) \u2014 turned into slug")
+};
+async function memSuggestTopic(input, _ctx) {
+  void _ctx;
+  const suggestion = suggestTopicKey(input.type, input.title);
+  return { topic_key: suggestion.topic_key, family: suggestion.family, type: input.type };
+}
+
+// src/tools/mem-timeline.ts
+import { existsSync as existsSync28 } from "fs";
+import { collectTimelineEntries, loadMemoriesFromDir as loadMemoriesFromDir22 } from "@hiveai/core";
+import { z as z33 } from "zod";
+var MemTimelineInputSchema = {
+  memory_id: z33.string().optional().describe("Seed id \u2014 expands via related_ids, topic, anchors"),
+  topic: z33.string().optional().describe("Frontmatter.topic value \u2014 chronological list when memory_id omitted"),
+  limit: z33.number().int().positive().max(100).default(30).describe("Max timeline entries returned")
+};
+async function memTimeline(input, ctx) {
+  if (!existsSync28(ctx.paths.memoriesDir)) {
+    return { entries: [], total: 0, notice: "No .ai/memories directory." };
+  }
+  const all = await loadMemoriesFromDir22(ctx.paths.memoriesDir);
+  const { entries, notice } = collectTimelineEntries(all, {
+    memoryId: input.memory_id,
+    topic: input.topic,
+    limit: input.limit
+  });
+  return { entries, total: entries.length, notice };
+}
+
+// src/prompts/bootstrap-project.ts
+import { z as z34 } from "zod";
 var BootstrapProjectArgsSchema = {
-  module: z30.string().optional().describe(
+  module: z34.string().optional().describe(
     "Optional module name to scope the analysis to (writes to .ai/modules/<module>/context.md)"
   ),
-  focus: z30.string().optional().describe("Optional area to emphasize (e.g. 'data layer', 'API surface')")
+  focus: z34.string().optional().describe("Optional area to emphasize (e.g. 'data layer', 'API surface')")
 };
 var ROOT_TEMPLATE = `# Project context
 
@@ -3126,10 +3237,10 @@ ${template}\`\`\`
 }
 
 // src/prompts/post-task.ts
-import { z as z31 } from "zod";
+import { z as z35 } from "zod";
 var PostTaskArgsSchema = {
-  task_summary: z31.string().optional().describe("One sentence describing what you just did"),
-  files_touched: z31.array(z31.string()).optional().describe("Files you created or modified during the task")
+  task_summary: z35.string().optional().describe("One sentence describing what you just did"),
+  files_touched: z35.array(z35.string()).optional().describe("Files you created or modified during the task")
 };
 function postTaskPrompt(args, ctx) {
   const taskLine = args.task_summary ? `
@@ -3213,12 +3324,12 @@ When done, respond with a brief summary: "Saved N memories: [list of IDs]. Sessi
 }
 
 // src/prompts/import-docs.ts
-import { z as z32 } from "zod";
+import { z as z36 } from "zod";
 var ImportDocsArgsSchema = {
-  content: z32.string().describe("The documentation content to analyze and import as memories (Markdown, README, ADR, etc.)"),
-  source: z32.string().optional().describe("Origin of the content (file path, URL, or document title) \u2014 used to anchor memories"),
-  scope: z32.enum(["personal", "team"]).default("team").describe("Scope to assign to created memories"),
-  dry_run: z32.boolean().default(false).describe("If true, describe what would be saved without actually calling mem_save")
+  content: z36.string().describe("The documentation content to analyze and import as memories (Markdown, README, ADR, etc.)"),
+  source: z36.string().optional().describe("Origin of the content (file path, URL, or document title) \u2014 used to anchor memories"),
+  scope: z36.enum(["personal", "team"]).default("team").describe("Scope to assign to created memories"),
+  dry_run: z36.boolean().default(false).describe("If true, describe what would be saved without actually calling mem_save")
 };
 function importDocsPrompt(args, ctx) {
   const sourceLine = args.source ? `
@@ -3283,7 +3394,7 @@ When done, respond with: "Imported N memories: [list of IDs]" or "Nothing action
 
 // src/server.ts
 var SERVER_NAME = "haive";
-var SERVER_VERSION = "0.9.3";
+var SERVER_VERSION = "0.9.5";
 function jsonResult(data) {
   return {
     content: [
@@ -3334,6 +3445,23 @@ function createHaiveServer(options = {}) {
       return jsonResult(await memSave(input, context));
     }
   );
+  server.tool(
+    "mem_suggest_topic",
+    [
+      "Propose a stable `topic` key (topic-upsert) from type + short title.",
+      "",
+      "USE BEFORE mem_save when you want deterministic updates to the same memory over time;",
+      "families mimic Engram-style grouping (architecture/*, bug/*, decision/*, \u2026).",
+      "",
+      "PARAMETERS:",
+      "  type  \u2014 convention | decision | gotcha | architecture | glossary | attempt | session_recap",
+      "  title \u2014 phrase to slugify under the suggested family prefix",
+      "",
+      "RETURNS: { topic_key, family, type }"
+    ].join("\n"),
+    MemSuggestTopicInputSchema,
+    async (input) => jsonResult(await memSuggestTopic(input, context))
+  );
   server.tool(
     "mem_tried",
     [
@@ -3425,8 +3553,12 @@ function createHaiveServer(options = {}) {
   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.",
+      "\u2B50 DEFAULT-FIRST for coding agents on any repo where `haive init` ran: call this BEFORE",
+      "changing source or project config for the current goal (unless the developer explicitly opts out).",
+      "One-shot onboarding: everything relevant in a single call under a token budget.",
+      "",
+      "PROGRESSIVE DISCLOSURE \u2014 after this, drill down only if needed:",
+      "  mem_relevant_to / mem_search (compact lists) \u2192 mem_get (full body + anchors).",
       "",
       "RETURNS (in order of priority):",
       "  0. action_required \u2014 \u26A0\uFE0F HANDLE THIS FIRST if non-empty (see protocol below)",
@@ -3461,7 +3593,7 @@ function createHaiveServer(options = {}) {
       "  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."
+      "Replaces 4\u20135 separate tool calls. Prefer this first; use mem_search / mem_get only for follow-up."
     ].join("\n"),
     GetBriefingInputSchema,
     async (input) => {
@@ -3480,6 +3612,8 @@ function createHaiveServer(options = {}) {
       "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).",
+      "  Lexical rank (lexical_rank: true, semantic: false): Okapi-BM25-style scoring on the",
+      "  filtered corpus \u2014 good for phrase-like queries without embeddings.",
       "  Semantic (semantic: true): embedding-based similarity \u2014 finds related memories",
       "  even with different wording. Requires haive embeddings index to be built.",
       "",
@@ -3488,6 +3622,7 @@ function createHaiveServer(options = {}) {
       "  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)",
+      "  lexical_rank \u2014 BM25-style ranking (ignored when semantic is true)",
       "  limit    \u2014 max results (default 10)",
       "",
       "RETURNS: array of { id, type, scope, status, confidence, body, match_quality }"
@@ -3498,6 +3633,22 @@ function createHaiveServer(options = {}) {
       return jsonResult(await memSearch(input, context));
     }
   );
+  server.tool(
+    "mem_timeline",
+    [
+      "Chronological view of related memories: by shared frontmatter.topic OR expanded from a seed id",
+      "(related_ids, same topic, overlapping anchor paths \u2014 one extra hop on related_ids).",
+      "",
+      "PARAMETERS:",
+      "  memory_id \u2014 optional seed memory id",
+      "  topic     \u2014 optional topic key (required if memory_id omitted)",
+      "  limit     \u2014 max entries (default 30)",
+      "",
+      "RETURNS: { entries: [{ id, type, scope, created_at, one_line, topic? }], total, notice? }"
+    ].join("\n"),
+    MemTimelineInputSchema,
+    async (input) => jsonResult(await memTimeline(input, context))
+  );
   server.tool(
     "mem_for_files",
     [
@@ -3527,7 +3678,7 @@ function createHaiveServer(options = {}) {
     [
       "Fetch a single memory by its full id with all details.",
       "",
-      "USE WHEN get_briefing returned a memory in 'compact' format and you need",
+      "USE WHEN get_briefing / mem_relevant_to / mem_search returned a compact hit and you need",
       "the full body, or when you know the exact id of a memory.",
       "",
       "PARAMETERS:",
@@ -3615,6 +3766,22 @@ function createHaiveServer(options = {}) {
     CodeMapInputSchema,
     async (input) => jsonResult(await codeMapTool(input, context))
   );
+  server.tool(
+    "mem_resolve_project",
+    [
+      "Diagnostics: resolve which project root hAIve is using (never throws).",
+      "",
+      "USE IN multi-root workspaces or when the agent CWD may not be the repo root \u2014",
+      "mirrors HAIVE_PROJECT_ROOT, findProjectRoot markers, and presence of .ai/memories.",
+      "",
+      "PARAMETERS:",
+      "  cwd \u2014 optional directory used for discovery when HAIVE_PROJECT_ROOT is unset",
+      "",
+      "RETURNS: { ok: true, info: { cwd, resolved_root, haive_project_root_env, \u2026 } }"
+    ].join("\n"),
+    MemResolveProjectInputSchema,
+    async (input) => jsonResult(await memResolveProject(input, context))
+  );
   server.tool(
     "mem_update",
     [
@@ -3748,6 +3915,8 @@ function createHaiveServer(options = {}) {
       "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.",
       "",
+      "Second step in progressive disclosure (after get_briefing): narrow here, then mem_get for full text.",
+      "",
       "Reuses the same ranking pipeline (anchor / module / literal / semantic) but",
       "skips project_context, modules, action_required, etc.",
       "",
@@ -3905,6 +4074,24 @@ function createHaiveServer(options = {}) {
       return jsonResult(await memConflicts(input, context));
     }
   );
+  server.tool(
+    "mem_conflict_candidates",
+    [
+      "Bulk lexical scan for decision/architecture-like pairs that look similar (Jaccard on tokens).",
+      "",
+      "Advisory only \u2014 follow with mem_conflicts_with on specific ids for real contradiction checks.",
+      "",
+      "PARAMETERS:",
+      "  since_days, types, min_jaccard, max_pairs, max_scan",
+      "",
+      "RETURNS: { pairs: [{ id_a, id_b, jaccard }], scanned, truncated, notice? }"
+    ].join("\n"),
+    MemConflictCandidatesInputSchema,
+    async (input) => {
+      tracker.record("mem_conflict_candidates", `${input.since_days}d`);
+      return jsonResult(await memConflictCandidates(input, context));
+    }
+  );
   server.tool(
     "pre_commit_check",
     [
@@ -4051,9 +4238,13 @@ export {
   createHaiveServer,
   getBriefing,
   getRecap,
+  memConflictCandidates,
   memConflicts,
   memDistill,
   memRelevantTo,
+  memResolveProject,
+  memSuggestTopic,
+  memTimeline,
   parseMcpCliArgs,
   patternDetect,
   preCommitCheck,