seekstone 0.18.0 → 0.19.0

package/README.md

@@ -24,7 +24,7 @@ If you use Claude Code, Cursor, or another coding agent, paste this prompt and t
 
 ### Option 1 — One-click (Claude Desktop, no terminal needed)
 
-Download `seekstone.mcpb` from [GitHub Releases](https://github.com/shaqmughal/seekstone/releases/latest), double-click it in Claude Desktop, and pick your Obsidian vault folder when prompted. No JSON editing, no terminal, no Node.js setup required.
+Download [`seekstone.mcpb`](https://github.com/shaqmughal/seekstone/releases/latest/download/seekstone.mcpb), double-click it in Claude Desktop, and pick your Obsidian vault folder when prompted. No JSON editing, no terminal, no Node.js setup required. Want semantic search out of the box? Grab [`seekstone-semantic.mcpb`](https://github.com/shaqmughal/seekstone/releases/latest/download/seekstone-semantic.mcpb) instead — the local embedding model ships inside the bundle, and nothing is downloaded at runtime.
 
 ### Option 2 — Guided setup (recommended for CLI users)
 
@@ -112,7 +112,7 @@ Other MCP clients (Windsurf, Cline, …) take the Option 3 JSON block in their o
 |---|---|
 | `search` | Full-text search. Returns ranked excerpts (default ~120 chars, tunable via `excerptLength`), not full notes. Fuzzy and prefix matching; with `SEEKSTONE_SEMANTIC=1`, `mode: "semantic"`/`"hybrid"` searches by meaning via a local embedding model (nothing leaves your machine). |
 | `query_notes` | Structured metadata query. Filter by frontmatter key/value predicates (`eq`, `ne`, `contains`, `exists`, `missing`, `gt`/`gte`/`lt`/`lte`), tag, folder, modified time, and size; sort and select the fields you need. Returns compact rows, not note content. |
-| `context_pack` | Answer-ready context for a natural-language question in one call, hard-capped at a byte budget (default 2 KB): ranked excerpts, linked neighbor notes with one-line summaries, and follow-up source paths — replaces a search → read → get_backlinks round-trip loop. |
+| `context_pack` | Answer-ready context for a natural-language question in one call, hard-capped at a byte budget (default 2 KB): ranked excerpts, linked neighbor notes with one-line summaries, and follow-up source paths — replaces a search → read → get_backlinks round-trip loop. Scopable by `folder`/`tag` and takes the same `mode` as `search`. |
 | `read_note` | Read the full content of a note by vault-relative path. Supports returning a single section, block, or line range. |
 | `list_notes` | List notes, optionally filtered by folder prefix or tag. |
 | `list_tags` | List all tags in the vault sorted by usage count (or alphabetically). |
@@ -158,7 +158,7 @@ Every write tool (`append_note`, `patch_note`, `patch_frontmatter`, `replace_in_
 | `SEEKSTONE_HISTORY_MAX_ENTRIES` | no | Cap on journal entries (default `1000`); the oldest are dropped past it. |
 | `SEEKSTONE_AUDIT_FILE` | no | Absolute path; off unless set. Appends one JSON-line audit record per write-tool call — ok or refused — with the tool, paths, sha-256 before/after, outcome, and op metadata. Never note content. |
 | `SEEKSTONE_AUDIT_MAX_SIZE` | no | Rotate the audit file to `<file>.1` past this size (e.g. `10mb`; default 10 MB). |
-| `SEEKSTONE_SEMANTIC` | no | Set to `1` to enable semantic search (`search` gains `mode: "semantic"` and `"hybrid"`). Download the local model once with `npx -y seekstone fetch-model`; the running server never touches the network. The `seekstone-semantic.mcpb` bundle sets this automatically and ships the model inside. |
+| `SEEKSTONE_SEMANTIC` | no | Set to `1` to enable semantic search (`search` and `context_pack` gain `mode: "semantic"` and `"hybrid"`). Download the local model once with `npx -y seekstone fetch-model`; the running server never touches the network. The `seekstone-semantic.mcpb` bundle sets this automatically and ships the model inside. |
 | `SEEKSTONE_SEMANTIC_MODEL` | no | `potion-base-8M` (default, ~30 MB) or `potion-retrieval-32M` (~129 MB, more accurate, ~2× query latency). Fetch it first: `npx -y seekstone fetch-model --model potion-retrieval-32M`. |
 | `SEEKSTONE_MODEL_PATH` | no | Directory holding the Model2Vec embedding model (default: where `fetch-model` puts the selected model). |
 | `SEEKSTONE_CACHE_DIR` | no | Cache root for the model and per-vault embedding caches (default `~/.cache/seekstone`). |

package/dist/index.js

@@ -1081,22 +1081,25 @@ function basenameNoExt(path2) {
   const dot = base.lastIndexOf(".");
   return dot > 0 ? base.slice(0, dot) : base;
 }
-function search(ctx2, input) {
+function retrieve(ctx2, input) {
   const mode = input.mode ?? "lexical";
   if (mode === "lexical") return lexicalSearch(ctx2, input);
   const semantic = requireSemantic(ctx2);
   if (mode === "semantic") return semanticSearch(ctx2, semantic, input);
   const words = queryWords(input.query);
   if (words.length > 0 && words.length <= MAX_ROUTE_WORDS) {
-    const lexHits = lexicalSearch(ctx2, input);
+    const lex = lexicalSearch(ctx2, input);
     if (routeToLexical(
       input.query,
-      lexHits.map((h) => h.path)
+      lex.hits.map((h) => h.path)
     ))
-      return lexHits;
+      return lex;
   }
   return semanticSearch(ctx2, semantic, input);
 }
+function search(ctx2, input) {
+  return retrieve(ctx2, input).hits;
+}
 function requireSemantic(ctx2) {
   if (!ctx2.semantic) {
     throw new Error(
@@ -1143,7 +1146,7 @@ function lexicalSearch(ctx2, input) {
     hits.push(hit);
     if (hits.length >= input.limit) break;
   }
-  return hits;
+  return { hits, totalCandidates: results.length };
 }
 function semanticSearch(ctx2, semantic, input) {
   const queryVec = semantic.embedQuery(input.query);
@@ -1166,7 +1169,7 @@ function semanticSearch(ctx2, semantic, input) {
     hits.push(hit);
     if (hits.length >= input.limit) break;
   }
-  return hits;
+  return { hits, totalCandidates: candidates.length };
 }
 function filterNote(ctx2, input, path2) {
   if (input.folder && !path2.startsWith(input.folder)) return void 0;
@@ -1189,7 +1192,12 @@ function decorate(hit, title, tags) {
 // src/tools/context_pack.ts
 var ContextPackInput = z3.object({
   query: z3.string().min(1).describe("Natural-language question or topic to assemble context for."),
-  budgetBytes: z3.number().int().min(256).max(16384).default(2048).describe("Hard cap on the response JSON size in bytes. The pack never exceeds it.")
+  budgetBytes: z3.number().int().min(256).max(16384).default(2048).describe("Hard cap on the response JSON size in bytes. The pack never exceeds it."),
+  mode: z3.enum(["lexical", "semantic", "hybrid"]).optional().describe(
+    "lexical = keyword search (default). semantic = meaning-based search over local embeddings (requires SEEKSTONE_SEMANTIC=1 and a fetched model). hybrid = exact-title lookups go lexical, everything else semantic. A question asked in words the note does not use needs semantic or hybrid."
+  ),
+  folder: z3.string().optional().describe("Restrict results to notes under this vault-relative folder prefix."),
+  tag: z3.string().optional().describe("Restrict results to notes containing this tag.")
 });
 var MAX_CANDIDATES = 10;
 var NEIGHBOR_HITS = 3;
@@ -1220,18 +1228,22 @@ function clamp(n, lo, hi) {
   return Math.min(hi, Math.max(lo, n));
 }
 function contextPack(ctx2, input) {
-  const results = ctx2.index.search(input.query, {
-    boost: { title: 3, tags: 2, body: 1 },
-    fuzzy: 0.2,
-    prefix: true
+  const excerptLen = clamp(Math.floor(input.budgetBytes / 10), 80, 400);
+  const { hits: results, totalCandidates } = retrieve(ctx2, {
+    query: input.query,
+    mode: input.mode,
+    folder: input.folder,
+    tag: input.tag,
+    limit: MAX_CANDIDATES,
+    excerptLength: excerptLen
   });
-  const totalMatches = results.length;
-  if (totalMatches === 0) {
-    return { excerpts: [], neighborhood: [], sources: [], totalMatches: 0, confidence: "none" };
+  const totalMatches = totalCandidates;
+  if (results.length === 0) {
+    return { excerpts: [], neighborhood: [], sources: [], totalMatches, confidence: "none" };
   }
   const terms = input.query.toLowerCase().split(/\s+/).filter((t) => t.length > 1);
   const scoreByPath = /* @__PURE__ */ new Map();
-  for (const r of results) scoreByPath.set(r.id, r.score);
+  for (const r of results) scoreByPath.set(r.path, r.score);
   const budget = input.budgetBytes;
   let used = Buffer.byteLength(
     JSON.stringify({
@@ -1244,24 +1256,20 @@ function contextPack(ctx2, input) {
     }),
     "utf8"
   );
-  const excerptLen = clamp(Math.floor(budget / 10), 80, 400);
   const reserve = Math.min(Math.floor(budget / 4), 600);
   const candidates = results.slice(0, MAX_CANDIDATES);
   const excerpts = [];
   const overflowHits = [];
   let droppedForBudget = false;
-  const buildEntry = (r, len) => {
-    const note = ctx2.notes.get(r.id);
-    const body = note?.body ?? "";
-    const noteTags = note?.tags ? note.tags.split(" ").filter(Boolean) : [];
+  const buildEntry = (h, len) => {
+    const note = ctx2.notes.get(h.path);
     const entry = {
-      path: r.id,
-      score: Math.round(r.score * 100) / 100,
-      excerpt: extractExcerpt(body, terms, len)
+      path: h.path,
+      score: h.score,
+      excerpt: h.excerpt.length > len ? extractExcerpt(h.excerpt, terms, len) : h.excerpt
     };
-    const title = r.title;
-    if (title && title !== basenameNoExt(r.id)) entry.title = title;
-    if (noteTags.length > 0) entry.tags = noteTags;
+    if (h.title) entry.title = h.title;
+    if (h.tags && h.tags.length > 0) entry.tags = h.tags;
     const fm = pickFm(note?.fm ?? null);
     if (fm) entry.fm = fm;
     return entry;
@@ -1270,7 +1278,7 @@ function contextPack(ctx2, input) {
   let phaseOpen = true;
   for (const r of candidates) {
     if (!phaseOpen) {
-      overflowHits.push({ path: r.id });
+      overflowHits.push({ path: r.path });
       continue;
     }
     let placed = false;
@@ -1295,7 +1303,7 @@ function contextPack(ctx2, input) {
     if (!placed) {
       phaseOpen = false;
       droppedForBudget = true;
-      overflowHits.push({ path: r.id });
+      overflowHits.push({ path: r.path });
     }
   }
   const includedPaths = new Set(excerpts.map((e) => e.path));
@@ -4927,7 +4935,7 @@ var ALL_TOOLS = [
   {
     name: "context_pack",
     annotations: READ_ONLY_ANNOTATIONS,
-    description: 'Assemble everything needed to ANSWER a natural-language question in one call, under a strict byte budget (default 2048): ranked excerpts, linked neighbor notes (backlinks/outlinks) with one-line summaries, and follow-up source paths. Use search to locate notes and query_notes for metadata filters; use context_pack when you want answer-ready context without multiple round-trips. Empty excerpts with confidence "none" or "low" means the vault lacks coverage \u2014 do not infer content.',
+    description: 'Assemble everything needed to ANSWER a natural-language question in one call, under a strict byte budget (default 2048): ranked excerpts, linked neighbor notes (backlinks/outlinks) with one-line summaries, and follow-up source paths. Retrieval is lexical by default: for a question phrased in words the note itself may not use, pass mode "hybrid" or "semantic", and scope with folder/tag exactly as in search. Use search to locate notes and query_notes for metadata filters; use context_pack when you want answer-ready context without multiple round-trips. Empty excerpts with confidence "none" or "low" means the vault lacks coverage \u2014 do not infer content; with folder or tag set, "none" can also mean the filter excluded every match, which totalMatches distinguishes.',
     inputSchema: {
       type: "object",
       properties: {
@@ -4935,7 +4943,14 @@ var ALL_TOOLS = [
         budgetBytes: {
           type: "number",
           description: "Hard cap on response JSON bytes (256\u201316384, default 2048)."
-        }
+        },
+        mode: {
+          type: "string",
+          enum: ["lexical", "semantic", "hybrid"],
+          description: "lexical = keyword search (default). semantic = meaning-based over local embeddings (needs SEEKSTONE_SEMANTIC=1 and a fetched model). hybrid = exact-title lookups go lexical, everything else semantic."
+        },
+        folder: { type: "string", description: "Restrict to a vault-relative folder prefix." },
+        tag: { type: "string", description: "Restrict to notes with this tag." }
       },
       required: ["query"]
     }
@@ -5465,7 +5480,7 @@ function startWatcher(ctx2, log2, opts) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.18.0" : "0.0.0-dev";
+var VERSION = true ? "0.19.0" : "0.0.0-dev";
 var intent = parseCliIntent(process.argv.slice(2));
 if (intent === "version") {
   process.stdout.write(`${VERSION}