neuro-vault-mcp 5.0.0 → 5.1.0

package/README.md

@@ -62,6 +62,18 @@ One question, one answer. Your assistant stops being a file browser and starts b
 
 ---
 
+### 🔍 Hybrid search: scope semantic with structural filters
+
+`search_notes` accepts an optional `filter` to narrow the candidate set **before** semantic ranking — combining the precision of `query_notes` with the recall of vector search. Useful when domain-relevant notes are crowded out by larger narrative clusters.
+
+```json
+{ "query": "trading lessons", "filter": { "tags": ["trading"] } }
+```
+
+`filter` accepts `path_prefix`, `tags` (ANY-of), and a `frontmatter` sift filter. Composition is `filter` AND `threshold` AND semantic. See the [Semantic Search guide](./docs/guide/semantic-search.md#pre-filter-filter-parameter) for full details.
+
+---
+
 ## 🏗 How it works
 
 ```mermaid

package/dist/cli.d.ts

@@ -75,6 +75,13 @@ declare class WikilinkGraphIndex {
     private rebuild;
 }
 
+interface NoteFilter {
+    path_prefix?: string;
+    tags?: string[];
+    frontmatter?: Record<string, unknown>;
+}
+type ListMatchingPaths = (filter: NoteFilter) => Promise<Set<string>>;
+
 interface BlockSearchResult {
     path: string;
     heading: string;
@@ -126,6 +133,7 @@ interface SemanticModuleDeps {
     vaultReaderFactory?: (opts: {
         vaultRoot: string;
     }) => VaultReader;
+    listMatchingPaths?: ListMatchingPaths;
 }
 
 type NoteIdentifier = {

package/dist/cli.js

@@ -1022,6 +1022,21 @@ function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+// src/lib/obsidian/query/path-prefix.ts
+var WINDOWS_ABSOLUTE_PATH_RE2 = /^[A-Za-z]:[\\/]/;
+function normalizeVaultPathPrefix(raw, invalid) {
+  const trimmed = raw.trim();
+  if (trimmed === "" || trimmed === "." || trimmed === "./") return void 0;
+  if (trimmed.startsWith("/") || WINDOWS_ABSOLUTE_PATH_RE2.test(trimmed)) {
+    throw invalid("path_prefix must be vault-relative");
+  }
+  const slashed = trimmed.replace(/\\/g, "/").replace(/^\.\//, "");
+  if (slashed.split("/").some((segment) => segment === "..")) {
+    throw invalid("path_prefix must be vault-relative");
+  }
+  return slashed.replace(/\/+$/, "");
+}
+
 // src/lib/obsidian/query/whitelist.ts
 var ALLOWED_OPERATORS = /* @__PURE__ */ new Set([
   "$eq",
@@ -1071,38 +1086,32 @@ function invalidFilter(message) {
 var sift = typeof siftModule === "function" ? siftModule : siftModule.default;
 var DEFAULT_LIMIT = 100;
 var HARD_LIMIT_CAP = 1e3;
-var WINDOWS_ABSOLUTE_PATH_RE2 = /^[A-Za-z]:[\\/]/;
 var READ_BATCH_SIZE2 = 32;
-async function runQueryNotes(input, reader, graph) {
-  const validated = validateInput(input);
-  validateFilter(validated.filter);
-  const effectiveFilter = applyDefaultRegexOptions(validated.filter);
-  if (graph) {
-    await graph.ensureFresh();
-  }
+async function collectMatchingPaths(input, deps) {
+  const { filter, pathPrefix, includeContent, earlyExitAfter } = input;
+  const { reader, graph } = deps;
   let paths;
   try {
-    paths = await reader.scan({ pathPrefix: validated.pathPrefix });
+    paths = await reader.scan({ pathPrefix });
   } catch (err) {
     if (err instanceof ScanPathNotFoundError) {
       throw new ToolHandlerError("PATH_NOT_FOUND", err.message, {
-        details: { path_prefix: validated.pathPrefix }
+        details: { path_prefix: pathPrefix }
       });
     }
     throw err;
   }
   if (paths.length === 0) {
-    return { results: [], count: 0, truncated: false };
+    return [];
   }
   let matcher;
   try {
-    matcher = sift(effectiveFilter);
+    matcher = sift(filter);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     throw new ToolHandlerError("INVALID_FILTER", `filter rejected by sift: ${message}`);
   }
-  const fields = validated.includeContent ? ["frontmatter", "content"] : ["frontmatter"];
-  const earlyExitAllowed = !validated.sort || validated.sort.field === "path" && validated.sort.order === "asc";
+  const fields = includeContent ? ["frontmatter", "content"] : ["frontmatter"];
   const matched = [];
   for (let i = 0; i < paths.length; i += READ_BATCH_SIZE2) {
     const slice = paths.slice(i, i + READ_BATCH_SIZE2);
@@ -1125,10 +1134,29 @@ async function runQueryNotes(input, reader, graph) {
         throw new ToolHandlerError("INVALID_FILTER", `filter execution failed: ${message}`);
       }
       if (!isMatch) continue;
-      matched.push(validated.includeContent ? { record: record2, content: item.content } : { record: record2 });
+      matched.push(includeContent ? { record: record2, content: item.content } : { record: record2 });
     }
-    if (earlyExitAllowed && matched.length > validated.limit) break;
+    if (earlyExitAfter !== void 0 && matched.length > earlyExitAfter) break;
+  }
+  return matched;
+}
+async function runQueryNotes(input, reader, graph) {
+  const validated = validateInput(input);
+  validateFilter(validated.filter);
+  const effectiveFilter = applyDefaultRegexOptions(validated.filter);
+  if (graph) {
+    await graph.ensureFresh();
   }
+  const earlyExitAllowed = !validated.sort || validated.sort.field === "path" && validated.sort.order === "asc";
+  const matched = await collectMatchingPaths(
+    {
+      filter: effectiveFilter,
+      pathPrefix: validated.pathPrefix,
+      includeContent: validated.includeContent,
+      earlyExitAfter: earlyExitAllowed ? validated.limit : void 0
+    },
+    { reader, graph }
+  );
   if (validated.sort) {
     sortInPlace(matched, validated.sort);
   }
@@ -1192,16 +1220,7 @@ function validateInput(input) {
   };
 }
 function normalizeScanPrefixInput(raw) {
-  const trimmed = raw.trim();
-  if (trimmed === "" || trimmed === "." || trimmed === "./") return void 0;
-  if (trimmed.startsWith("/") || WINDOWS_ABSOLUTE_PATH_RE2.test(trimmed)) {
-    throw invalidParams("path_prefix must be vault-relative", "path_prefix");
-  }
-  const slashed = trimmed.replace(/\\/g, "/").replace(/^\.\//, "");
-  if (slashed.split("/").some((segment) => segment === "..")) {
-    throw invalidParams("path_prefix must be vault-relative", "path_prefix");
-  }
-  return slashed.replace(/\/+$/, "");
+  return normalizeVaultPathPrefix(raw, (message) => invalidParams(message, "path_prefix"));
 }
 function validateSort(raw) {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
@@ -1261,6 +1280,66 @@ function invalidParams(message, field) {
   return new ToolHandlerError("INVALID_PARAMS", message, { details: { field } });
 }
 
+// src/lib/obsidian/query/list-matching-paths.ts
+function createListMatchingPaths(deps) {
+  return async (filter) => {
+    const { path_prefix, tags, frontmatter } = filter;
+    const hasPathPrefix = path_prefix !== void 0 && path_prefix !== "";
+    const hasTags = Array.isArray(tags) && tags.length > 0;
+    const hasFrontmatter = frontmatter !== void 0 && Object.keys(frontmatter).length > 0;
+    if (!hasPathPrefix && !hasTags && !hasFrontmatter) {
+      throw new ToolHandlerError(
+        "INVALID_FILTER",
+        "filter must specify at least one of: path_prefix, tags, frontmatter"
+      );
+    }
+    const normalizedPrefix = hasPathPrefix ? normalizeVaultPathPrefix(
+      path_prefix,
+      (message) => new ToolHandlerError("INVALID_FILTER", message)
+    ) : void 0;
+    if (hasPathPrefix && !hasTags && !hasFrontmatter) {
+      try {
+        const paths = await deps.reader.scan({ pathPrefix: normalizedPrefix });
+        return new Set(paths);
+      } catch (err) {
+        if (err instanceof ScanPathNotFoundError) {
+          throw new ToolHandlerError("PATH_NOT_FOUND", err.message, {
+            details: { path_prefix: normalizedPrefix }
+          });
+        }
+        throw err;
+      }
+    }
+    if (hasFrontmatter) {
+      validateFilter(frontmatter);
+    }
+    const internalFilter = compileFilter({ tags, frontmatter });
+    const effectiveFilter = applyDefaultRegexOptions(internalFilter);
+    const rows = await collectMatchingPaths(
+      {
+        filter: effectiveFilter,
+        pathPrefix: normalizedPrefix,
+        includeContent: false
+      },
+      deps
+    );
+    return new Set(rows.map((row) => row.record.path));
+  };
+}
+function compileFilter(parts) {
+  const clauses = [];
+  if (parts.tags && parts.tags.length > 0) {
+    clauses.push({ tags: { $in: parts.tags } });
+  }
+  if (parts.frontmatter && Object.keys(parts.frontmatter).length > 0) {
+    for (const [key, value] of Object.entries(parts.frontmatter)) {
+      clauses.push({ [`frontmatter.${key}`]: value });
+    }
+  }
+  if (clauses.length === 1) return clauses[0];
+  return { $and: clauses };
+}
+
 // node_modules/zod/v4/classic/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -15752,13 +15831,29 @@ var SEARCH_NOTES_DESCRIPTION = [
   '- "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 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.',
+  "",
+  "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?, tags?, frontmatter? }. At least one field required.",
+  '  - path_prefix: scope to a folder (e.g. "Resources/").',
+  '  - 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: filter AND threshold AND 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.',
+  '- 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/"}, mode: "deep"}).'
 ].join("\n");
+var filterSchema = external_exports.object({
+  path_prefix: external_exports.string().optional(),
+  tags: external_exports.array(external_exports.string()).optional(),
+  frontmatter: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+});
 var inputSchema4 = external_exports.object({
   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()
+  threshold: external_exports.number().min(0).max(1).optional(),
+  filter: filterSchema.optional()
 });
 async function buildExistingPathSet2(paths, pathExists) {
   const unique = new Set(paths);
@@ -15773,8 +15868,30 @@ function wrapDependencyError2(error48, message, details) {
   }
   return new ToolHandlerError("DEPENDENCY_ERROR", message, { details, cause: error48 });
 }
+function isFilterEmpty(filter) {
+  const hasPath = filter.path_prefix !== void 0 && filter.path_prefix !== "";
+  const hasTags = Array.isArray(filter.tags) && filter.tags.length > 0;
+  const hasFm = filter.frontmatter !== void 0 && Object.keys(filter.frontmatter).length > 0;
+  return !hasPath && !hasTags && !hasFm;
+}
+function narrowSources(sources, allowed) {
+  const out = /* @__PURE__ */ new Map();
+  for (const path7 of allowed) {
+    const src = sources.get(path7);
+    if (src) out.set(path7, src);
+  }
+  return out;
+}
 function buildSearchNotesTool(deps) {
-  const { sources, embeddingProvider, searchEngine, modelKey, pathExists, graph } = deps;
+  const {
+    sources,
+    embeddingProvider,
+    searchEngine,
+    modelKey,
+    pathExists,
+    graph,
+    listMatchingPaths
+  } = deps;
   return {
     name: "search_notes",
     title: "Search Notes",
@@ -15784,6 +15901,39 @@ function buildSearchNotesTool(deps) {
       const mode = input.mode ?? "quick";
       const threshold = input.threshold !== void 0 ? readThreshold(input.threshold, input.threshold, "threshold") : void 0;
       const limit = input.limit !== void 0 ? readPositiveInteger(input.limit, input.limit, "limit") : void 0;
+      let effectiveSources = sources;
+      if (input.filter !== void 0) {
+        if (isFilterEmpty(input.filter)) {
+          throw new ToolHandlerError(
+            "INVALID_ARGUMENT",
+            "filter must specify at least one of: path_prefix, tags, frontmatter"
+          );
+        }
+        let allowed;
+        try {
+          allowed = await listMatchingPaths(input.filter);
+        } catch (error48) {
+          if (error48 instanceof ToolHandlerError && error48.code === "INVALID_FILTER") {
+            throw new ToolHandlerError("INVALID_ARGUMENT", error48.message, {
+              details: error48.details
+            });
+          }
+          throw wrapDependencyError2(error48, "Failed to compute filter set", {
+            modelKey,
+            operation: "search_notes"
+          });
+        }
+        if (allowed.size === 0) {
+          const isMulti = Array.isArray(input.query);
+          const isDeep = mode === "deep";
+          return {
+            results: [],
+            ...isDeep ? { blockResults: [] } : {},
+            ...isMulti ? { truncated: false } : {}
+          };
+        }
+        effectiveSources = narrowSources(sources, allowed);
+      }
       if (Array.isArray(input.query)) {
         const queries = normalizeQueryArray(input.query);
         try {
@@ -15792,7 +15942,7 @@ function buildSearchNotesTool(deps) {
             mode,
             threshold,
             limit,
-            sources,
+            sources: effectiveSources,
             embeddingProvider,
             searchEngine
           });
@@ -15823,7 +15973,7 @@ function buildSearchNotesTool(deps) {
           mode,
           limit,
           threshold,
-          sources,
+          sources: effectiveSources,
           embeddingProvider,
           searchEngine
         });
@@ -15886,10 +16036,12 @@ async function createSemanticModule(config2, deps = {}) {
   const readNoteContent = deps.readNoteContent ?? createDefaultReadNoteContent(config2.vaultPath);
   const basenameIndex = buildBasenameIndex(corpus.sources.keys());
   let graph = deps.graph;
-  if (!graph) {
+  let listMatchingPaths = deps.listMatchingPaths;
+  if (!graph || !listMatchingPaths) {
     const readerFactory = deps.vaultReaderFactory ?? ((opts) => new FsVaultReader({ vaultRoot: opts.vaultRoot }));
     const reader = readerFactory({ vaultRoot: config2.vaultPath });
-    graph = new WikilinkGraphIndex({ reader });
+    if (!graph) graph = new WikilinkGraphIndex({ reader });
+    if (!listMatchingPaths) listMatchingPaths = createListMatchingPaths({ reader, graph });
   }
   const semanticDeps = {
     sources: corpus.sources,
@@ -15899,7 +16051,8 @@ async function createSemanticModule(config2, deps = {}) {
     pathExists,
     basenameIndex,
     readNoteContent,
-    graph
+    graph,
+    listMatchingPaths
   };
   return {
     tools: buildSemanticTools(semanticDeps),
@@ -16311,7 +16464,7 @@ async function resolveToPath(input, reader) {
   if (matches.length > 1) {
     throw new ToolHandlerError(
       "AMBIGUOUS_MATCH",
-      `Multiple notes match name '${name}'; pass an explicit path`,
+      `Multiple notes match name '${name}': ${matches.join(", ")}; pass an explicit path`,
       { details: { name, matches } }
     );
   }
@@ -16595,7 +16748,7 @@ var FsVaultWriter = class {
       }
       throw new ToolHandlerError(
         "AMBIGUOUS_MATCH",
-        `Find text matched ${result.lines.length} times in ${input.path}; use a more specific anchor or omit the replace field to rewrite the whole body`,
+        `Find text matched ${result.lines.length} times in ${input.path} at lines ${result.lines.join(", ")}; make 'replace' more specific (extend the anchor with surrounding text) or omit it to rewrite the whole body`,
         { details: { path: input.path, matches: result.lines } }
       );
     }
@@ -16703,6 +16856,10 @@ Use \`search_notes\` when the user is recalling a topic fuzzily, asking a concep
 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.
 
+### 1a. Narrow scope when domain is known
+
+If the query is about a known folder, tag, or frontmatter dimension, pass \`filter\` to scope semantic search to that subset BEFORE ranking. This dramatically improves precision when the vault has many narrative notes that crowd top-K. Shape: \`{ path_prefix?, tags?, frontmatter? }\` (at least one). Tags match ANY-of (OR). \`frontmatter\` accepts the same sift operators as \`query_notes\`. Examples: \`filter: { tags: ['trading'] }\`, \`filter: { path_prefix: 'Resources/', frontmatter: { type: 'reflection' } }\`.
+
 ### 2. Choose mode
 - **quick** (default) \u2014 returns up to 3 notes plus block-level matches scoped to those notes. Use for specific lookups.
 - **deep** \u2014 returns up to 8 notes plus block-level matches across the whole vault. After the merged top-\`limit\` seeds are selected, expansion runs once on those seeds to pull in related notes. Use for broad topics.
@@ -16740,6 +16897,10 @@ async function startNeuroVaultServer(config2, deps = {}) {
   const server = serverFactory();
   const sharedReader = new FsVaultReader({ vaultRoot: config2.vaultPath });
   const sharedGraph = new WikilinkGraphIndex({ reader: sharedReader });
+  const sharedListMatchingPaths = createListMatchingPaths({
+    reader: sharedReader,
+    graph: sharedGraph
+  });
   const registrations = [];
   let warmup = async () => {
   };
@@ -16751,7 +16912,11 @@ async function startNeuroVaultServer(config2, deps = {}) {
         modelKey: config2.semantic.modelKey,
         modelId: config2.semantic.modelId
       },
-      { graph: sharedGraph, ...deps.semantic }
+      {
+        graph: sharedGraph,
+        listMatchingPaths: sharedListMatchingPaths,
+        ...deps.semantic
+      }
     );
     registrations.push(...semantic.tools);
     warmup = semantic.warmup;