neuro-vault-mcp 8.2.0 → 9.0.0

package/dist/cli.d.ts

@@ -88,7 +88,6 @@ interface BlockSearchResult {
 interface SearchResult {
     path: string;
     similarity: number;
-    via_expansion?: true;
 }
 interface DuplicatePair {
     note_a: string;

package/dist/cli.js

@@ -15896,28 +15896,26 @@ var MODE_DEFAULTS = {
   quick: { limit: 3, threshold: 0.5, expansion: false, expansionLimit: 0 },
   deep: { limit: 8, threshold: 0.35, expansion: true, expansionLimit: 3 }
 };
-function computeExpansion(args) {
-  const { seeds, sources, searchEngine, threshold, perSeedLimit, totalLimit } = args;
-  const seedPaths = new Set(seeds.map((s) => s.path));
-  const bestByPath = /* @__PURE__ */ new Map();
-  for (const seed of seeds) {
-    const source = sources.get(seed.path);
-    if (!source || source.embedding.length === 0) continue;
-    const neighbors = searchEngine.findNeighbors({
+function computeRelatedPerSeed(args) {
+  const { seedPaths, sources, searchEngine, threshold, perSeedLimit } = args;
+  const seedSet = new Set(seedPaths);
+  const out = /* @__PURE__ */ new Map();
+  for (const seedPath of seedPaths) {
+    const source = sources.get(seedPath);
+    if (!source || source.embedding.length === 0) {
+      out.set(seedPath, []);
+      continue;
+    }
+    const neighbours = searchEngine.findNeighbors({
       queryVector: source.embedding,
       sources: sources.values(),
       threshold,
-      limit: perSeedLimit
+      limit: perSeedLimit + seedSet.size
     });
-    for (const n of neighbors) {
-      if (seedPaths.has(n.path)) continue;
-      const cur = bestByPath.get(n.path);
-      if (cur === void 0 || n.similarity > cur) {
-        bestByPath.set(n.path, n.similarity);
-      }
-    }
+    const related = neighbours.filter((n) => !seedSet.has(n.path)).sort((a, b) => b.similarity - a.similarity || a.path.localeCompare(b.path)).slice(0, perSeedLimit).map((n) => ({ path: n.path, expansion_similarity: n.similarity }));
+    out.set(seedPath, related);
   }
-  return [...bestByPath.entries()].map(([path10, similarity]) => ({ path: path10, similarity, via_expansion: true })).sort((a, b) => b.similarity - a.similarity || a.path.localeCompare(b.path)).slice(0, totalLimit);
+  return out;
 }
 async function executeRetrieval(input) {
   const { query, mode, sources, embeddingProvider, searchEngine } = input;
@@ -15941,40 +15939,50 @@ async function executeRetrieval(input) {
       limit
     });
   }
-  let blockResults;
-  if (mode === "deep") {
-    blockResults = searchEngine.findBlockNeighbors({
+  const seeds = vectorResults.slice(0, limit);
+  const seedPaths = seeds.map((s) => s.path);
+  const seedPathSet = new Set(seedPaths);
+  const blocksByPath = /* @__PURE__ */ new Map();
+  if (seeds.length > 0) {
+    const seedSources = [...sources.values()].filter((s) => seedPathSet.has(s.path));
+    const rawBlocks = mode === "deep" ? searchEngine.findBlockNeighbors({
       queryVector,
-      sources: sources.values(),
+      sources: seedSources,
       threshold,
       limit
-    });
-  } else if (vectorResults.length > 0) {
-    const matchedPaths = new Set(vectorResults.map((r) => r.path));
-    const matchedSources = [...sources.values()].filter((s) => matchedPaths.has(s.path));
-    blockResults = searchEngine.findBlockNeighbors({
+    }) : searchEngine.findBlockNeighbors({
       queryVector,
-      sources: matchedSources,
+      sources: seedSources,
       threshold: 0,
       limit: QUICK_BLOCK_LIMIT
     });
+    for (const block of rawBlocks) {
+      if (!seedPathSet.has(block.path)) continue;
+      const bucket = blocksByPath.get(block.path) ?? [];
+      bucket.push({ heading: block.heading, lines: block.lines, similarity: block.similarity });
+      blocksByPath.set(block.path, bucket);
+    }
+    for (const bucket of blocksByPath.values()) {
+      bucket.sort((a, b) => b.similarity - a.similarity || a.lines[0] - b.lines[0]);
+    }
   }
-  const cappedSeeds = vectorResults.slice(0, limit);
-  let expansionResults = [];
-  if (expansion && expansionLimit > 0 && cappedSeeds.length > 0) {
-    expansionResults = computeExpansion({
-      seeds: cappedSeeds,
+  let relatedByPath = /* @__PURE__ */ new Map();
+  if (expansion && expansionLimit > 0 && seeds.length > 0) {
+    relatedByPath = computeRelatedPerSeed({
+      seedPaths,
       sources,
       searchEngine,
       threshold,
-      perSeedLimit: limit,
-      totalLimit: expansionLimit
+      perSeedLimit: expansionLimit
     });
   }
-  return {
-    results: [...cappedSeeds, ...expansionResults],
-    ...blockResults !== void 0 ? { blockResults } : {}
-  };
+  const results = seeds.map((seed) => ({
+    path: seed.path,
+    similarity: seed.similarity,
+    blocks: blocksByPath.get(seed.path) ?? [],
+    related: relatedByPath.get(seed.path) ?? []
+  }));
+  return { results };
 }
 function mergeNoteResults(perQuery) {
   const byPath = /* @__PURE__ */ new Map();
@@ -15992,7 +16000,6 @@ function mergeNoteResults(perQuery) {
       if (result.similarity > existing.similarity) {
         existing.similarity = result.similarity;
       }
-      existing.matched_queries ??= [];
       if (!existing.matched_queries.includes(query)) {
         existing.matched_queries.push(query);
       }
@@ -16002,34 +16009,6 @@ function mergeNoteResults(perQuery) {
     (a, b) => b.similarity - a.similarity || a.path.localeCompare(b.path)
   );
 }
-function mergeBlockResults(perQuery) {
-  const byKey = /* @__PURE__ */ new Map();
-  for (const { query, blocks } of perQuery) {
-    for (const block of blocks) {
-      const key = `${block.path}\0${block.heading}\0${block.lines[0]}-${block.lines[1]}`;
-      const existing = byKey.get(key);
-      if (!existing) {
-        byKey.set(key, {
-          path: block.path,
-          heading: block.heading,
-          lines: block.lines,
-          similarity: block.similarity,
-          matched_queries: [query]
-        });
-        continue;
-      }
-      if (block.similarity > existing.similarity) {
-        existing.similarity = block.similarity;
-      }
-      if (!existing.matched_queries.includes(query)) {
-        existing.matched_queries.push(query);
-      }
-    }
-  }
-  return [...byKey.values()].sort(
-    (a, b) => b.similarity - a.similarity || a.path.localeCompare(b.path)
-  );
-}
 async function executeMultiRetrieval(input) {
   const { queries, mode, sources, embeddingProvider, searchEngine } = input;
   const modeConfig = MODE_DEFAULTS[mode];
@@ -16054,57 +16033,77 @@ async function executeMultiRetrieval(input) {
           limit
         });
       }
-      let blocks = [];
-      if (mode === "deep") {
-        blocks = searchEngine.findBlockNeighbors({
-          queryVector,
-          sources: sources.values(),
-          threshold,
-          limit
-        });
-      } else if (neighbors.length > 0) {
-        const matched = new Set(neighbors.map((r) => r.path));
-        const matchedSources = [...sources.values()].filter((s) => matched.has(s.path));
-        blocks = searchEngine.findBlockNeighbors({
-          queryVector,
-          sources: matchedSources,
-          threshold: 0,
-          limit: QUICK_BLOCK_LIMIT
-        });
-      }
-      return { query, neighbors, blocks };
+      return { query, queryVector, neighbors };
     })
   );
-  const mergedNotes = mergeNoteResults(
+  const merged = mergeNoteResults(
     perQueryOutputs.map(({ query, neighbors }) => ({ query, results: neighbors }))
   );
-  const anyBlocks = perQueryOutputs.some(({ blocks }) => blocks.length > 0);
-  const mergedBlocks = anyBlocks ? mergeBlockResults(perQueryOutputs.map(({ query, blocks }) => ({ query, blocks }))) : void 0;
-  const truncated = mergedNotes.length > limit || (mergedBlocks?.length ?? 0) > limit;
-  const cappedNotes = mergedNotes.slice(0, limit);
-  const cappedBlocks = mergedBlocks ? mergedBlocks.slice(0, limit) : void 0;
-  let expansionResults = [];
-  if (expansion && expansionLimit > 0 && cappedNotes.length > 0) {
-    const seeds = cappedNotes.map((n) => ({ path: n.path, similarity: n.similarity }));
-    const raw = computeExpansion({
-      seeds,
+  const truncated = merged.length > limit;
+  const seeds = merged.slice(0, limit);
+  const seedPaths = seeds.map((s) => s.path);
+  const seedPathSet = new Set(seedPaths);
+  const blocksByPath = /* @__PURE__ */ new Map();
+  if (seeds.length > 0) {
+    const seedSources = [...sources.values()].filter((s) => seedPathSet.has(s.path));
+    const rawByKey = /* @__PURE__ */ new Map();
+    for (const { queryVector } of perQueryOutputs) {
+      const raw = mode === "deep" ? searchEngine.findBlockNeighbors({
+        queryVector,
+        sources: seedSources,
+        threshold,
+        limit
+      }) : searchEngine.findBlockNeighbors({
+        queryVector,
+        sources: seedSources,
+        threshold: 0,
+        limit: QUICK_BLOCK_LIMIT
+      });
+      for (const block of raw) {
+        if (!seedPathSet.has(block.path)) continue;
+        const key = `${block.path}\0${block.heading}\0${block.lines[0]}-${block.lines[1]}`;
+        const existing = rawByKey.get(key);
+        if (!existing || block.similarity > existing.similarity) {
+          rawByKey.set(key, {
+            path: block.path,
+            heading: block.heading,
+            lines: block.lines,
+            similarity: block.similarity
+          });
+        }
+      }
+    }
+    for (const block of rawByKey.values()) {
+      const bucket = blocksByPath.get(block.path) ?? [];
+      bucket.push({
+        heading: block.heading,
+        lines: block.lines,
+        similarity: block.similarity
+      });
+      blocksByPath.set(block.path, bucket);
+    }
+    for (const bucket of blocksByPath.values()) {
+      bucket.sort((a, b) => b.similarity - a.similarity || a.lines[0] - b.lines[0]);
+    }
+  }
+  let relatedByPath = /* @__PURE__ */ new Map();
+  if (expansion && expansionLimit > 0 && seeds.length > 0) {
+    relatedByPath = computeRelatedPerSeed({
+      seedPaths,
       sources,
       searchEngine,
       threshold,
-      perSeedLimit: limit,
-      totalLimit: expansionLimit
+      perSeedLimit: expansionLimit
     });
-    expansionResults = raw.map((r) => ({
-      path: r.path,
-      similarity: r.similarity,
-      via_expansion: true
-    }));
   }
-  return {
-    results: [...cappedNotes, ...expansionResults],
-    ...cappedBlocks !== void 0 ? { blockResults: cappedBlocks } : {},
-    truncated
-  };
+  const results = seeds.map((seed) => ({
+    path: seed.path,
+    similarity: seed.similarity,
+    matched_queries: seed.matched_queries,
+    blocks: blocksByPath.get(seed.path) ?? [],
+    related: relatedByPath.get(seed.path) ?? []
+  }));
+  return { results, truncated };
 }
 
 // src/modules/semantic/tools/search-notes.ts
@@ -16185,12 +16184,7 @@ async function runSearchForEntry(entry, input, deps) {
     }
     if (allowed.size === 0) {
       const isMulti = Array.isArray(input.query);
-      const isDeep = mode === "deep";
-      return {
-        results: [],
-        ...isDeep ? { blockResults: [] } : {},
-        ...isMulti ? { truncated: false } : {}
-      };
+      return isMulti ? { results: [], truncated: false } : { results: [] };
     }
     effectiveSources = narrowSources(sources, allowed);
   }
@@ -16208,23 +16202,19 @@ async function runSearchForEntry(entry, input, deps) {
       });
       const candidatePaths = [
         ...output.results.map((r) => r.path),
-        ...output.blockResults?.map((b) => b.path) ?? []
+        ...output.results.flatMap((r) => r.related.map((rel) => rel.path))
       ];
       const [existing] = await Promise.all([
         buildExistingPathSet2(entry, candidatePaths),
         graph.ensureFresh()
       ]);
-      return {
-        results: output.results.filter((r) => existing.has(r.path)).map((r) => ({
-          ...r,
-          backlink_count: graph.getBacklinkCount(r.path),
-          vault: entry.name
-        })),
-        ...output.blockResults !== void 0 ? {
-          blockResults: output.blockResults.filter((b) => existing.has(b.path)).map((b) => ({ ...b, vault: entry.name }))
-        } : {},
-        truncated: output.truncated
-      };
+      const enriched = output.results.filter((r) => existing.has(r.path)).map((r) => ({
+        ...r,
+        related: r.related.filter((rel) => existing.has(rel.path)),
+        backlink_count: graph.getBacklinkCount(r.path),
+        vault: entry.name
+      }));
+      return { results: enriched, truncated: output.truncated };
     } catch (error48) {
       throw wrapDependencyError2(error48, "Failed to search notes", {
         modelKey,
@@ -16245,22 +16235,19 @@ async function runSearchForEntry(entry, input, deps) {
     });
     const candidatePaths = [
       ...output.results.map((r) => r.path),
-      ...output.blockResults?.map((b) => b.path) ?? []
+      ...output.results.flatMap((r) => r.related.map((rel) => rel.path))
     ];
     const [existing] = await Promise.all([
       buildExistingPathSet2(entry, candidatePaths),
       graph.ensureFresh()
     ]);
-    return {
-      results: output.results.filter((r) => existing.has(r.path)).map((r) => ({
-        ...r,
-        backlink_count: graph.getBacklinkCount(r.path),
-        vault: entry.name
-      })),
-      ...output.blockResults !== void 0 ? {
-        blockResults: output.blockResults.filter((b) => existing.has(b.path)).map((b) => ({ ...b, vault: entry.name }))
-      } : {}
-    };
+    const enriched = output.results.filter((r) => existing.has(r.path)).map((r) => ({
+      ...r,
+      related: r.related.filter((rel) => existing.has(rel.path)),
+      backlink_count: graph.getBacklinkCount(r.path),
+      vault: entry.name
+    }));
+    return { results: enriched };
   } catch (error48) {
     throw wrapDependencyError2(error48, "Failed to search notes", {
       modelKey,
@@ -16283,36 +16270,45 @@ function buildSearchNotesTool(deps) {
     "Search notes by semantic similarity. Best for fuzzy recall, topic exploration, or cross-language matches. Pass short keyword queries (1-4 words), not sentences.",
     "",
     "MODES (pick based on intent):",
-    '- "quick" (default) \u2014 specific lookup. Returns up to 3 top notes plus block-level matches scoped to those notes. Use when you want one or two specific notes.',
-    '- "deep" \u2014 topic exploration. Returns up to 8 notes plus block-level matches across the whole vault. After the merged top-`limit` results are selected, expansion runs once to pull in semantically related notes; expansion-derived results carry `via_expansion: true`. Use for "tell me about X" or building an overview.',
+    '- "quick" (default) \u2014 specific lookup. Returns up to 3 notes; each note carries `blocks[]` scoped to itself and `related: []`. Use when you want one or two specific notes.',
+    '- "deep" \u2014 topic exploration. Returns up to 8 notes; each note carries `blocks[]` (scoped to itself) and `related[]` (semantically neighbouring notes). Use for "tell me about X" or building an overview.',
     "",
     "PARAMETERS:",
-    "- query (required): string, or array of 1-8 strings. Pass an array for synonyms / reformulations / translations \u2014 embedded in batch, merged into one ranked list. Each result carries `matched_queries` (which of your queries hit it). `limit` is the FINAL result count regardless of how many queries are passed \u2014 passing more queries widens coverage but does not increase the result count.",
+    "- query (required): string, or array of 1-8 strings. Pass an array for synonyms / reformulations / translations \u2014 embedded in batch, merged into one ranked list. Each result carries `matched_queries` (which of your queries hit it). `limit` is the FINAL result count regardless of how many queries are passed.",
     '- mode: "quick" | "deep" (default "quick").',
-    "- limit: max notes in `results`. Default 3 (quick) / 8 (deep). Override to widen or narrow the result set. Does not affect `blockResults` (quick: capped at 5; deep: capped at mode limit).",
+    "- limit: max notes in `results`. Default 3 (quick) / 8 (deep). Does not affect leaves (`blocks` / `related`).",
     "- threshold: min similarity, 0-1. Default 0.5 (quick) / 0.35 (deep). Raise to 0.6+ to cut weak matches; lower (e.g. 0.3) when nothing comes back.",
     ...registry2.isMulti() ? ["- vault: target a specific vault by name when multiple are registered."] : [],
     "",
-    "OUTPUT FIELDS (multi-query):",
-    "- matched_queries: which of your queries surfaced this result \u2014 tells you which synonym was load-bearing.",
-    "- truncated: true when more unique candidates were merged than fit in `limit`.",
-    "- via_expansion: true on results pulled in by post-merge expansion in deep mode (mutually exclusive with matched_queries).",
+    "RESPONSE SHAPE (tree, depth = 2):",
+    "- `results[]` \u2014 top-level direct note matches, ranked by query similarity.",
+    "  - `path`, `similarity` (query-similarity), `backlink_count`, `vault`",
+    "  - `matched_queries` (only when `query` is an array) \u2014 which of your queries hit this note",
+    "  - `blocks[]` \u2014 section-level matches WITHIN this note. Each block has `heading`, `lines: [start, end]`, `similarity` (query-similarity at block level).",
+    "  - `related[]` \u2014 expansion neighbours OF this note (deep mode only; empty otherwise). Each item has `path` and `expansion_similarity` (note-to-note, DIFFERENT SCALE from `similarity` \u2014 do not compare them numerically).",
+    "- `truncated` \u2014 top-level, only when `query` is an array; true when merged candidates exceeded `limit`.",
+    "",
+    "INVARIANTS:",
+    "- A `related` item NEVER has a `similarity` field \u2014 only `expansion_similarity`. A direct result NEVER has `expansion_similarity`. Don't conflate them.",
+    "- The same neighbour can appear in `related[]` of multiple direct results (with different `expansion_similarity` values per parent) \u2014 that's by design.",
+    "- `blocks[]` and `related[]` are always present on direct results (possibly empty).",
+    "- After finding a relevant note, call `get_similar_notes` on it for a deeper neighbour profile \u2014 do not infer relationships from `related[]` alone.",
     "",
     "EXAMPLES:",
     '- "where did I write about X?" \u2192 search_notes({query: "X"}) \u2014 quick.',
     '- "what do I know about Y?" \u2192 search_notes({query: "Y", mode: "deep"}).',
-    '- multilingual pair: search_notes({query: ["embeddings", "\u0432\u0435\u043A\u0442\u043E\u0440\u043D\u0438\u0439 \u043F\u043E\u0448\u0443\u043A"]}) \u2014 returns one merged list; notes matched by both queries appear with both in matched_queries.',
-    '- multilingual deep: search_notes({query: ["optimization", "\u043E\u043F\u0442\u0438\u043C\u0456\u0437\u0430\u0446\u0456\u044F"], mode: "deep"}) \u2014 merged top-`limit` seeds, then expansion once on the merged set.',
+    '- multilingual pair: search_notes({query: ["embeddings", "\u0432\u0435\u043A\u0442\u043E\u0440\u043D\u0438\u0439 \u043F\u043E\u0448\u0443\u043A"]}).',
+    '- multilingual deep: search_notes({query: ["optimization", "\u043E\u043F\u0442\u0438\u043C\u0456\u0437\u0430\u0446\u0456\u044F"], mode: "deep"}).',
     "",
     "PRE-FILTER (filter parameter):",
     "- filter: optional structural narrowing applied BEFORE semantic ranking. Best when vault has many narrative notes that crowd top-K on a niche query.",
     "  Shape: { path_prefix?, exclude_path_prefix?, tags?, frontmatter? }. At least one field required.",
     '  - path_prefix: scope to a folder, or array of folders for OR-semantics (e.g. ["Tasks/", "Reflections/"]).',
-    '  - exclude_path_prefix: drop notes whose path starts with any of the listed prefixes (e.g. ["Resources/", "Archive/"]). Valid as the sole filter field \u2014 "search the whole vault except these subtrees".',
+    '  - exclude_path_prefix: drop notes whose path starts with any of the listed prefixes (e.g. ["Resources/", "Archive/"]). Valid as the sole filter field.',
     '  - tags: notes that have ANY of these tags (OR within the array; no leading "#").',
     '  - frontmatter: sift filter on frontmatter keys (e.g. { type: "reflection", status: "active" }). Same operator allow-list as query_notes.',
-    "  Composition: include \u2192 exclude \u2192 tags \u2192 frontmatter \u2192 threshold \u2192 semantic. Use this instead of querying twice and intersecting on the client.",
-    '- scoped recall: search_notes({query: "trading lessons", filter: {tags: ["trading"]}}) \u2014 semantic only inside notes tagged trading.',
+    "  Composition: include \u2192 exclude \u2192 tags \u2192 frontmatter \u2192 threshold \u2192 semantic.",
+    '- scoped recall: search_notes({query: "trading lessons", filter: {tags: ["trading"]}}).',
     '- carve out noise: search_notes({query: "active thinking", filter: {exclude_path_prefix: ["Resources/", "Archive/"]}, mode: "deep"}).',
     '- scoped multi-query: search_notes({query: ["embeddings","\u0432\u0435\u043A\u0442\u043E\u0440\u043D\u0438\u0439 \u043F\u043E\u0448\u0443\u043A"], filter: {path_prefix: ["Resources/", "Inbox/"]}, mode: "deep"}).',
     ...registry2.isMulti() ? [
@@ -17613,12 +17609,12 @@ If the query is about a known folder, tag, or frontmatter dimension, pass \`filt
 - Use \`limit\` to override the default note count in either mode. Widening \`limit\` widens recall.
 
 ### 3. Use the results
-- \`results\` \u2014 notes ranked by similarity; read the file by path. Each result also carries \`backlink_count\` (vault-wide inbound wikilinks + embeds) \u2014 useful as a tiebreaker when several results share a similar similarity score.
-- \`matched_queries\` (only when \`query\` is an array) \u2014 which of your queries hit this note; lets you spot which synonym was load-bearing
-- \`truncated\` (only when \`query\` is an array) \u2014 true when unique merged candidates exceeded \`limit\`; widen \`limit\` to see more
-- \`via_expansion: true\` (deep mode only) \u2014 marks results pulled in by post-merge expansion; these have no \`matched_queries\`
-- \`blockResults\` \u2014 sections ranked by relevance; use heading + line range to jump to the relevant part
-- After finding a relevant note, call get_similar_notes to discover related content
+- \`results\` \u2014 top-level notes ranked by similarity. Each result carries \`backlink_count\` (vault-wide inbound wikilinks + embeds) \u2014 useful as a tiebreaker when scores are close.
+- \`results[].blocks\` \u2014 section-level matches inside this note; use heading + line range to jump to the relevant part. Always present (possibly empty).
+- \`results[].related\` \u2014 expansion neighbours of this note (deep mode only). Each item has \`path\` and \`expansion_similarity\` \u2014 a DIFFERENT scale from \`similarity\`; do not compare them numerically. Always present (possibly empty). The same neighbour may appear under multiple parents.
+- \`matched_queries\` (only when \`query\` is an array) \u2014 which of your queries hit this note; lets you spot which synonym was load-bearing.
+- \`truncated\` (only when \`query\` is an array) \u2014 true when unique merged candidates exceeded \`limit\`; widen \`limit\` to see more.
+- After finding a relevant note, call \`get_similar_notes\` for a deeper neighbour profile.
 
 ## Routing between operations and semantic