neuro-vault-mcp 1.6.0 → 1.7.0

package/dist/cli.d.ts

@@ -6,6 +6,11 @@ interface RetrievalOutput {
     results: SearchResult[];
     blockResults?: BlockSearchResult[];
 }
+interface MultiRetrievalOutput {
+    results: MultiSearchResult[];
+    blockResults?: MultiBlockSearchResult[];
+    truncated: boolean;
+}
 
 interface SmartBlock {
     key: string;
@@ -58,7 +63,7 @@ interface SearchEngine {
 }
 type SearchMode = 'quick' | 'deep';
 interface SearchNotesInput {
-    query: string;
+    query: string | string[];
     mode?: SearchMode;
     limit?: number;
     threshold?: number;
@@ -79,6 +84,7 @@ interface ToolStats {
     embeddingDimension: number;
     modelKey: string;
 }
+type PathExistsCheck = (vaultRelativePath: string) => Promise<boolean>;
 interface ToolHandlerDependencies {
     loader: {
         sources: Map<string, SmartSource>;
@@ -86,13 +92,20 @@ interface ToolHandlerDependencies {
     embeddingProvider: EmbeddingProvider;
     searchEngine: SearchEngine;
     modelKey: string;
+    pathExists?: PathExistsCheck;
 }
 interface ToolHandlers {
-    searchNotes(input: SearchNotesInput): Promise<RetrievalOutput>;
+    searchNotes(input: SearchNotesInput): Promise<RetrievalOutput | MultiRetrievalOutput>;
     getSimilarNotes(input: GetSimilarNotesInput): Promise<SearchResult[]>;
     findDuplicates(input?: FindDuplicatesInput): Promise<DuplicatePair[]>;
     getStats(): Promise<ToolStats>;
 }
+interface MultiSearchResult extends SearchResult {
+    matched_queries: string[];
+}
+interface MultiBlockSearchResult extends BlockSearchResult {
+    matched_queries: string[];
+}
 
 interface SmartConnectionsCorpus {
     sources: Map<string, SmartSource>;
@@ -103,6 +116,7 @@ interface SemanticModuleDeps {
     embeddingServiceFactory?: (modelId: string) => EmbeddingProvider;
     searchEngine?: SearchEngine;
     toolHandlersFactory?: (deps: ToolHandlerDependencies) => ToolHandlers;
+    pathExists?: PathExistsCheck;
 }
 
 type NoteIdentifier = {

package/dist/cli.js

@@ -61,6 +61,10 @@ import { createRequire } from "module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
+// src/modules/semantic/index.ts
+import fs2 from "fs/promises";
+import path4 from "path";
+
 // src/modules/semantic/embedding-service.ts
 import { pipeline } from "@xenova/transformers";
 var DEFAULT_MODEL_KEY2 = "bge-micro-v2";
@@ -496,6 +500,7 @@ import path3 from "path";
 // src/modules/semantic/retrieval-policy.ts
 var FALLBACK_THRESHOLD = 0.3;
 var QUICK_BLOCK_LIMIT = 5;
+var HARD_MERGE_CAP = 50;
 var MODE_DEFAULTS = {
   quick: { limit: 3, threshold: 0.5, expansion: false, expansionLimit: 0 },
   deep: { limit: 8, threshold: 0.35, expansion: true, expansionLimit: 3 }
@@ -570,6 +575,97 @@ async function executeRetrieval(input) {
     ...blockResults !== void 0 ? { blockResults } : {}
   };
 }
+function mergeNoteResults(perQuery) {
+  const byPath = /* @__PURE__ */ new Map();
+  for (const { query, results } of perQuery) {
+    for (const result of results) {
+      const existing = byPath.get(result.path);
+      if (!existing) {
+        byPath.set(result.path, {
+          path: result.path,
+          similarity: result.similarity,
+          matched_queries: [query]
+        });
+        continue;
+      }
+      if (result.similarity > existing.similarity) {
+        existing.similarity = result.similarity;
+      }
+      if (!existing.matched_queries.includes(query)) {
+        existing.matched_queries.push(query);
+      }
+    }
+  }
+  return [...byPath.values()].sort(
+    (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 perQueryOutputs = await Promise.all(
+    queries.map(async (query) => {
+      const output = await executeRetrieval({
+        query,
+        mode,
+        threshold: input.threshold,
+        expansion: input.expansion,
+        expansionLimit: input.expansionLimit,
+        sources,
+        embeddingProvider,
+        searchEngine
+      });
+      return { query, output };
+    })
+  );
+  const mergedNotes = mergeNoteResults(
+    perQueryOutputs.map(({ query, output }) => ({ query, results: output.results }))
+  );
+  const anyBlocks = perQueryOutputs.some(({ output }) => output.blockResults !== void 0);
+  const mergedBlocks = anyBlocks ? mergeBlockResults(
+    perQueryOutputs.map(({ query, output }) => ({
+      query,
+      blocks: output.blockResults ?? []
+    }))
+  ) : void 0;
+  const perQueryLimit = input.limit ?? MODE_DEFAULTS[mode].limit;
+  const cap = Math.min(perQueryLimit * queries.length, HARD_MERGE_CAP);
+  const truncated = mergedNotes.length > cap || (mergedBlocks?.length ?? 0) > cap;
+  const cappedNotes = mergedNotes.slice(0, cap);
+  const cappedBlocks = mergedBlocks ? mergedBlocks.slice(0, cap) : void 0;
+  return {
+    results: cappedNotes,
+    ...cappedBlocks !== void 0 ? { blockResults: cappedBlocks } : {},
+    truncated
+  };
+}
 
 // src/lib/tool-response.ts
 var ToolHandlerError = class extends Error {
@@ -624,6 +720,7 @@ var DEFAULT_SEARCH_LIMIT = 10;
 var DEFAULT_SEARCH_THRESHOLD = 0.5;
 var DEFAULT_DUPLICATE_THRESHOLD = 0.9;
 var WINDOWS_ABSOLUTE_PATH_RE = /^[A-Za-z]:[\\/]/;
+var MAX_MULTI_QUERIES = 8;
 function normalizeNotePath(notePath) {
   const trimmed = notePath.trim();
   if (!trimmed) {
@@ -664,6 +761,40 @@ function normalizeQuery(query) {
   }
   return normalized;
 }
+function normalizeQueryArray(queries) {
+  if (queries.length === 0) {
+    throw new ToolHandlerError("INVALID_ARGUMENT", "query array must not be empty", {
+      details: { field: "query" }
+    });
+  }
+  if (queries.length > MAX_MULTI_QUERIES) {
+    throw new ToolHandlerError(
+      "INVALID_ARGUMENT",
+      `query array must contain at most ${MAX_MULTI_QUERIES} entries`,
+      { details: { field: "query", max: MAX_MULTI_QUERIES, received: queries.length } }
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const raw of queries) {
+    if (typeof raw !== "string") {
+      throw new ToolHandlerError("INVALID_ARGUMENT", "query array must contain strings", {
+        details: { field: "query" }
+      });
+    }
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+      throw new ToolHandlerError("INVALID_ARGUMENT", "query entries must not be empty", {
+        details: { field: "query" }
+      });
+    }
+    if (!seen.has(trimmed)) {
+      seen.add(trimmed);
+      out.push(trimmed);
+    }
+  }
+  return out;
+}
 function readPositiveInteger(value, defaultValue, field) {
   if (value === void 0) {
     return defaultValue;
@@ -732,20 +863,61 @@ function wrapDependencyError(error48, message, details) {
     cause: error48
   });
 }
+async function buildExistingPathSet(paths, pathExists) {
+  const unique = new Set(paths);
+  const checks = await Promise.all(
+    [...unique].map(async (notePath) => [notePath, await pathExists(notePath)])
+  );
+  return new Set(checks.filter(([, exists]) => exists).map(([notePath]) => notePath));
+}
 function createToolHandlers({
   loader,
   embeddingProvider,
   searchEngine,
-  modelKey
+  modelKey,
+  pathExists
 }) {
+  const existsCheck = pathExists ?? (async () => true);
   return {
     async searchNotes(input) {
-      const query = normalizeQuery(input.query);
       const mode = input.mode ?? "quick";
       const threshold = input.threshold !== void 0 ? readThreshold(input.threshold, input.threshold, "threshold") : void 0;
       const expansionLimit = input.expansion_limit !== void 0 ? readPositiveInteger(input.expansion_limit, 3, "expansion_limit") : void 0;
+      if (Array.isArray(input.query)) {
+        const queries = normalizeQueryArray(input.query);
+        const limit = input.limit !== void 0 ? readPositiveInteger(input.limit, input.limit, "limit") : void 0;
+        try {
+          const output = await executeMultiRetrieval({
+            queries,
+            mode,
+            threshold,
+            expansion: input.expansion,
+            expansionLimit,
+            limit,
+            sources: loader.sources,
+            embeddingProvider,
+            searchEngine
+          });
+          const candidatePaths = [
+            ...output.results.map((r) => r.path),
+            ...output.blockResults?.map((b) => b.path) ?? []
+          ];
+          const existing = await buildExistingPathSet(candidatePaths, existsCheck);
+          return {
+            results: output.results.filter((r) => existing.has(r.path)),
+            ...output.blockResults !== void 0 ? { blockResults: output.blockResults.filter((b) => existing.has(b.path)) } : {},
+            truncated: output.truncated
+          };
+        } catch (error48) {
+          throw wrapDependencyError(error48, "Failed to search notes", {
+            modelKey,
+            operation: "search_notes"
+          });
+        }
+      }
+      const query = normalizeQuery(input.query);
       try {
-        return await executeRetrieval({
+        const output = await executeRetrieval({
           query,
           mode,
           threshold,
@@ -755,6 +927,15 @@ function createToolHandlers({
           embeddingProvider,
           searchEngine
         });
+        const candidatePaths = [
+          ...output.results.map((r) => r.path),
+          ...output.blockResults?.map((b) => b.path) ?? []
+        ];
+        const existing = await buildExistingPathSet(candidatePaths, existsCheck);
+        return {
+          results: output.results.filter((r) => existing.has(r.path)),
+          ...output.blockResults !== void 0 ? { blockResults: output.blockResults.filter((b) => existing.has(b.path)) } : {}
+        };
       } catch (error48) {
         throw wrapDependencyError(error48, "Failed to search notes", {
           modelKey,
@@ -773,7 +954,7 @@ function createToolHandlers({
       const limit = readPositiveInteger(input.limit, DEFAULT_SEARCH_LIMIT, "limit");
       const threshold = readThreshold(input.threshold, DEFAULT_SEARCH_THRESHOLD, "threshold");
       try {
-        return toSearchResults2(
+        const results = toSearchResults2(
           searchEngine,
           source.embedding,
           loader.sources.values(),
@@ -781,6 +962,11 @@ function createToolHandlers({
           limit,
           notePath
         );
+        const existing = await buildExistingPathSet(
+          results.map((r) => r.path),
+          existsCheck
+        );
+        return results.filter((r) => existing.has(r.path));
       } catch (error48) {
         throw wrapDependencyError(error48, "Failed to find similar notes", {
           modelKey,
@@ -792,10 +978,15 @@ function createToolHandlers({
     async findDuplicates(input = {}) {
       const threshold = readThreshold(input.threshold, DEFAULT_DUPLICATE_THRESHOLD, "threshold");
       try {
-        return searchEngine.findDuplicates({
+        const pairs = searchEngine.findDuplicates({
           sources: loader.sources.values(),
           threshold
         });
+        const existing = await buildExistingPathSet(
+          pairs.flatMap((p) => [p.note_a, p.note_b]),
+          existsCheck
+        );
+        return pairs.filter((p) => existing.has(p.note_a) && existing.has(p.note_b));
       } catch (error48) {
         throw wrapDependencyError(error48, "Failed to find duplicate notes", {
           modelKey,
@@ -1585,10 +1776,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path4) {
-  if (!path4)
+function getElementAtPath(obj, path5) {
+  if (!path5)
     return obj;
-  return path4.reduce((acc, key) => acc?.[key], obj);
+  return path5.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -1971,11 +2162,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path4, issues) {
+function prefixIssues(path5, issues) {
   return issues.map((iss) => {
     var _a2;
     (_a2 = iss).path ?? (_a2.path = []);
-    iss.path.unshift(path4);
+    iss.path.unshift(path5);
     return iss;
   });
 }
@@ -2158,7 +2349,7 @@ function formatError(error48, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error48, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error49, path4 = []) => {
+  const processError = (error49, path5 = []) => {
     var _a2, _b;
     for (const issue2 of error49.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
@@ -2168,7 +2359,7 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
       } else if (issue2.code === "invalid_element") {
         processError({ issues: issue2.issues }, issue2.path);
       } else {
-        const fullpath = [...path4, ...issue2.path];
+        const fullpath = [...path5, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -2200,8 +2391,8 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path4 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path4) {
+  const path5 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path5) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -14178,13 +14369,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path4 = ref.slice(1).split("/").filter(Boolean);
-  if (path4.length === 0) {
+  const path5 = ref.slice(1).split("/").filter(Boolean);
+  if (path5.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path4[0] === defsKey) {
-    const key = path4[1];
+  if (path5[0] === defsKey) {
+    const key = path5[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -14588,7 +14779,7 @@ config(en_default());
 
 // src/modules/semantic/tools.ts
 var searchNotesSchema = external_exports.object({
-  query: external_exports.string(),
+  query: external_exports.union([external_exports.string(), external_exports.array(external_exports.string()).min(1).max(8)]),
   mode: external_exports.enum(["quick", "deep"]).optional(),
   limit: external_exports.number().int().positive().optional(),
   threshold: external_exports.number().min(0).max(1).optional(),
@@ -14609,7 +14800,7 @@ function buildSemanticTools(handlers) {
       name: "search_notes",
       spec: {
         title: "Search Notes",
-        description: 'Search notes by semantic similarity for fuzzy recall, topic lookup, or cross-language matching. Pass a short keyword query (1-4 words). Choose mode: "quick" for specific lookups (up to 3 notes), "deep" for broad topic overview with block-level search and expansion. Call multiple times with different queries for synonyms or multi-language searches.',
+        description: 'Search notes by semantic similarity for fuzzy recall, topic lookup, or cross-language matching. Pass a short keyword query (1-4 words). For synonyms, reformulations, or translations into the languages used in the vault, pass an array of 1-8 queries \u2014 they are batch-embedded server-side and returned as one merged ranked list with matched_queries on each result. Choose mode: "quick" for specific lookups (up to 3 notes), "deep" for broad topic overview with block-level search and expansion.',
         inputSchema: searchNotesSchema
       },
       handler: async (args) => invokeTool(() => handlers.searchNotes(searchNotesSchema.parse(args)))
@@ -14644,6 +14835,16 @@ function buildSemanticTools(handlers) {
 }
 
 // src/modules/semantic/index.ts
+function createDefaultPathExists(vaultPath) {
+  return async (vaultRelativePath) => {
+    try {
+      await fs2.access(path4.join(vaultPath, vaultRelativePath));
+      return true;
+    } catch {
+      return false;
+    }
+  };
+}
 async function createSemanticModule(config2, deps = {}) {
   const loadCorpus = deps.loadCorpus ?? loadSmartConnectionsCorpus;
   const embeddingServiceFactory = deps.embeddingServiceFactory ?? ((modelId) => new EmbeddingService({ modelKey: modelId }));
@@ -14654,11 +14855,13 @@ async function createSemanticModule(config2, deps = {}) {
     throw new Error("Loaded Smart Connections corpus is empty");
   }
   const embeddingService = embeddingServiceFactory(config2.modelId);
+  const pathExists = deps.pathExists ?? createDefaultPathExists(config2.vaultPath);
   const handlers = toolHandlersFactory({
     loader: corpus,
     embeddingProvider: embeddingService,
     searchEngine,
-    modelKey: config2.modelKey
+    modelKey: config2.modelKey,
+    pathExists
   });
   return {
     tools: buildSemanticTools(handlers),
@@ -15313,10 +15516,9 @@ Use \`search_notes\` when the user is recalling a topic fuzzily, asking a concep
 
 ### 1. Write the query
 1. Extract the core nouns and concepts from the user's message \u2014 strip filler words and verbs. From "remind me what I wanted to build with LLM agents" the key concepts are "LLM", "agents", "build".
-2. Search each concept separately and in small combinations: "LLM", "agents", "LLM agents", "AI projects".
-3. Try synonyms and reformulations \u2014 the note may use different wording than the query.
-4. The vault may contain notes in multiple languages. Search in the language of the user's message + English.
-5. If a search returns no results, lower the threshold to 0.3 before giving up.
+2. For synonyms, reformulations, or translations, pass \`query\` as an array of 1-8 strings in a SINGLE call \u2014 the server batch-embeds them and returns one merged ranked list with \`matched_queries\` showing which query hit which note. Do not make multiple sequential calls for synonyms.
+3. The vault may contain notes written in several languages. If you have evidence of which languages are in use (from prior reads, file names, or earlier results), include translations of the key concepts into each of those languages in the same \`query\` array.
+4. If a search returns no results, lower the threshold to 0.3 before giving up.
 
 ### 2. Choose mode
 - **quick** (default) \u2014 returns up to 3 notes, no expansion. Use for specific lookups.
@@ -15325,6 +15527,8 @@ Use \`search_notes\` when the user is recalling a topic fuzzily, asking a concep
 
 ### 3. Use the results
 - \`results\` \u2014 notes ranked by similarity; read the file by path
+- \`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 more candidates were merged than fit in the cap
 - \`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
 
@@ -15356,6 +15560,7 @@ async function startNeuroVaultServer(config2, deps = {}) {
   if (config2.semantic.enabled) {
     const semantic = await createSemanticModule(
       {
+        vaultPath: config2.vaultPath,
         smartEnvPath: config2.semantic.smartEnvPath,
         modelKey: config2.semantic.modelKey,
         modelId: config2.semantic.modelId