@hiveai/mcp 0.9.3 → 0.9.6

package/dist/index.js

@@ -321,6 +321,7 @@ import {
   loadMemoriesFromDir as loadMemoriesFromDir3,
   loadUsageIndex,
   pickSnippetNeedle,
+  rankMemoriesLexical,
   tokenizeQuery,
   trackReads
 } from "@hiveai/core";
@@ -337,6 +338,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)")
 };
@@ -362,6 +366,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);
   }
@@ -459,6 +484,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";
@@ -1099,7 +1127,11 @@ import {
 import { z as z16 } from "zod";
 
 // src/session-tracker.ts
-import { appendUsageEvent, loadConfig as loadConfig2 } from "@hiveai/core";
+import {
+  appendUsageEvent,
+  appendRuntimeJournalEntry,
+  loadConfig as loadConfig2
+} from "@hiveai/core";
 import { mkdir as mkdir5, writeFile as writeFile9, rm } from "fs/promises";
 import { existsSync as existsSync16 } from "fs";
 import path7 from "path";
@@ -1172,6 +1204,14 @@ var SessionTracker = class {
         recapId = result.id;
       } catch {
       }
+      void appendRuntimeJournalEntry(this.ctx.paths, {
+        kind: "session_end",
+        message: recapId ? `auto session close | ${toolSummary} | recap:${recapId}` : `auto session close | ${toolSummary}`,
+        meta: {
+          recap_id: recapId ?? null,
+          total_tool_calls: totalCalls
+        }
+      });
       const ranPostTask = this.events.some(
         (e) => e.tool === "mem_session_end" && !e.summary?.startsWith("Auto-captured")
       );
@@ -3040,13 +3080,139 @@ function gitFileDiff(root, file, sinceDays) {
   }
 }
 
-// src/prompts/bootstrap-project.ts
+// src/tools/mem-conflict-candidates.ts
+import { existsSync as existsSync27 } from "fs";
+import {
+  findLexicalConflictPairs,
+  findTopicStatusConflictPairs,
+  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."),
+  max_topic_pairs: z30.number().int().positive().max(100).default(20).describe(
+    "Cap for extra signal: memories sharing the same topic with validated vs rejected status."
+  )
+};
+async function memConflictCandidates(input, ctx) {
+  if (!existsSync27(ctx.paths.memoriesDir)) {
+    return {
+      pairs: [],
+      topic_status_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 topicStatusPairs = findTopicStatusConflictPairs(all, input.max_topic_pairs);
+  const notice = pairs.length === 0 && topicStatusPairs.length === 0 ? "No lexical or topic-status candidates \u2014 widen since_days/types or lower min_jaccard." : void 0;
+  return { pairs, topic_status_pairs: topicStatusPairs, 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/tools/runtime-journal-append.ts
+import { appendRuntimeJournalEntry as appendRuntimeJournalEntry2 } from "@hiveai/core";
+import { z as z34 } from "zod";
+var RuntimeJournalAppendInputSchema = {
+  message: z34.string().min(1).describe("Short line to append to the runtime session journal"),
+  kind: z34.enum(["note", "session_end", "mcp"]).default("note"),
+  tool: z34.string().optional().describe("When kind=mcp, which tool name (optional)")
+};
+async function runtimeJournalAppend(input, ctx) {
+  await appendRuntimeJournalEntry2(ctx.paths, {
+    kind: input.kind,
+    message: input.message,
+    ...input.tool ? { tool: input.tool } : {}
+  });
+  return {
+    ok: true,
+    path_hint: `${ctx.paths.runtimeDir}/session-journal.ndjson`
+  };
+}
+
+// src/tools/runtime-journal-tail.ts
+import { readRuntimeJournalTail } from "@hiveai/core";
+import { z as z35 } from "zod";
+var RuntimeJournalTailInputSchema = {
+  limit: z35.number().int().positive().max(500).default(30).describe("Last N journal entries to return")
+};
+async function runtimeJournalTail(input, ctx) {
+  const entries = await readRuntimeJournalTail(ctx.paths, input.limit);
+  if (entries.length === 0) {
+    return { entries: [], empty: true };
+  }
+  return { entries };
+}
+
+// src/prompts/bootstrap-project.ts
+import { z as z36 } from "zod";
 var BootstrapProjectArgsSchema = {
-  module: z30.string().optional().describe(
+  module: z36.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: z36.string().optional().describe("Optional area to emphasize (e.g. 'data layer', 'API surface')")
 };
 var ROOT_TEMPLATE = `# Project context
 
@@ -3128,10 +3294,10 @@ ${template}\`\`\`
 }
 
 // src/prompts/post-task.ts
-import { z as z31 } from "zod";
+import { z as z37 } 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: z37.string().optional().describe("One sentence describing what you just did"),
+  files_touched: z37.array(z37.string()).optional().describe("Files you created or modified during the task")
 };
 function postTaskPrompt(args, ctx) {
   const taskLine = args.task_summary ? `
@@ -3215,12 +3381,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 z38 } 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: z38.string().describe("The documentation content to analyze and import as memories (Markdown, README, ADR, etc.)"),
+  source: z38.string().optional().describe("Origin of the content (file path, URL, or document title) \u2014 used to anchor memories"),
+  scope: z38.enum(["personal", "team"]).default("team").describe("Scope to assign to created memories"),
+  dry_run: z38.boolean().default(false).describe("If true, describe what would be saved without actually calling mem_save")
 };
 function importDocsPrompt(args, ctx) {
   const sourceLine = args.source ? `
@@ -3285,7 +3451,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.6";
 function jsonResult(data) {
   return {
     content: [
@@ -3336,6 +3502,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",
     [
@@ -3427,8 +3610,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)",
@@ -3463,7 +3650,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) => {
@@ -3482,6 +3669,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.",
       "",
@@ -3490,6 +3679,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 }"
@@ -3500,6 +3690,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",
     [
@@ -3529,7 +3735,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:",
@@ -3617,6 +3823,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",
     [
@@ -3750,6 +3972,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.",
       "",
@@ -3907,6 +4131,53 @@ function createHaiveServer(options = {}) {
       return jsonResult(await memConflicts(input, context));
     }
   );
+  server.tool(
+    "mem_conflict_candidates",
+    [
+      "Bulk scan for conflict CANDIDATES (not proof):",
+      "",
+      "  1. Lexical similarity (Jaccard) on decision/architecture-like pairs",
+      "  2. Same frontmatter.topic with validated vs rejected \u2014 quick human-review signal",
+      "",
+      "Advisory only \u2014 follow with mem_conflicts_with on specific ids.",
+      "",
+      "PARAMETERS:",
+      "  since_days, types, min_jaccard, max_pairs, max_scan, max_topic_pairs",
+      "",
+      "RETURNS: { pairs, topic_status_pairs, 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(
+    "runtime_journal_append",
+    [
+      "Append one line to `.ai/.runtime/session-journal.ndjson` \u2014 machine-local session continuity.",
+      "",
+      "Does NOT replace team memories; complements mem_session_end recaps for local traces.",
+      "",
+      "PARAMETERS: message, kind (note|session_end|mcp), optional tool",
+      "",
+      "RETURNS: { ok, path_hint }"
+    ].join("\n"),
+    RuntimeJournalAppendInputSchema,
+    async (input) => jsonResult(await runtimeJournalAppend(input, context))
+  );
+  server.tool(
+    "runtime_journal_tail",
+    [
+      "Read the last N entries from the runtime session journal (parsed JSON lines).",
+      "",
+      "PARAMETERS: limit (default 30, max 500)",
+      "",
+      "RETURNS: { entries: [...], empty?: true }"
+    ].join("\n"),
+    RuntimeJournalTailInputSchema,
+    async (input) => jsonResult(await runtimeJournalTail(input, context))
+  );
   server.tool(
     "pre_commit_check",
     [