seekstone 0.18.0 → 0.20.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,11 +158,12 @@ 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`). |
 | `SEEKSTONE_BUNDLED_MODEL_DIR` | no | Set by the `seekstone-semantic.mcpb` bundle's manifest — sharded model files shipped inside the extension, reassembled into the model directory at boot (disk-only, hash-verified). Not usually set by hand. |
+| `SEEKSTONE_INSTRUCTIONS` | no | Path to a file whose contents become the MCP server's `instructions` string (surfaced to clients alongside the tool list). A relative path resolves against the vault root. Read once at boot, trimmed, capped at 16 KB (truncated with a warning past that). Missing, unreadable, or empty after trim means no instructions — never a boot failure. |
 
 ---
 

package/dist/index.js

@@ -192,7 +192,7 @@ var init_fetch_model = __esm({
 
 // src/index.ts
 import { homedir } from "os";
-import { resolve as resolve2 } from "path";
+import { resolve as resolve3 } from "path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -439,6 +439,8 @@ Optional environment:
   SEEKSTONE_SEMANTIC_MODEL  potion-base-8M (default) | potion-retrieval-32M (bigger, more accurate)
   SEEKSTONE_MODEL_PATH Override the embedding-model directory
   SEEKSTONE_CACHE_DIR  Override the cache root (default ~/.cache/seekstone)
+  SEEKSTONE_INSTRUCTIONS  Path to a file whose contents become the MCP
+                       "instructions" (relative paths resolve against the vault)
 
 Add to Claude Code:
   claude mcp add seekstone --env SEEKSTONE_VAULT=/path/to/vault -- npx -y seekstone
@@ -1081,22 +1083,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 +1148,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 +1171,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 +1194,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 +1230,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 +1258,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 +1280,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 +1305,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));
@@ -3782,6 +3792,47 @@ async function runInit(opts, deps) {
   return { ok: true, exitCode: 0, output: out, wrotePath: configPath, backupPath };
 }
 
+// src/instructions.ts
+import { readFileSync } from "fs";
+import { isAbsolute, resolve as resolve2 } from "path";
+var MAX_BYTES = 16 * 1024;
+function truncateUtf8(text, maxBytes) {
+  let bytes = 0;
+  let out = "";
+  for (const ch of text) {
+    const chBytes = Buffer.byteLength(ch, "utf8");
+    if (bytes + chBytes > maxBytes) break;
+    out += ch;
+    bytes += chBytes;
+  }
+  return out;
+}
+function resolveInstructions(env, vaultRoot2, log2) {
+  const raw = (env.SEEKSTONE_INSTRUCTIONS ?? "").trim();
+  if (raw === "") return void 0;
+  const path2 = isAbsolute(raw) ? raw : resolve2(vaultRoot2, raw);
+  let content;
+  try {
+    content = readFileSync(path2, "utf8");
+  } catch (err) {
+    log2.warn("cannot read SEEKSTONE_INSTRUCTIONS file; starting without instructions", {
+      path: path2,
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return void 0;
+  }
+  let trimmed = content.trim();
+  if (trimmed === "") return void 0;
+  const bytes = Buffer.byteLength(trimmed, "utf8");
+  if (bytes > MAX_BYTES) {
+    log2.warn("SEEKSTONE_INSTRUCTIONS file exceeds 16 KB; truncated", { path: path2, bytes });
+    trimmed = truncateUtf8(trimmed, MAX_BYTES).trim();
+    if (trimmed === "") return void 0;
+  }
+  log2.info("instructions attached", { bytes: Buffer.byteLength(trimmed, "utf8") });
+  return trimmed;
+}
+
 // src/process-guards.ts
 function installProcessGuards(log2) {
   const onUnhandledRejection = (reason) => {
@@ -4927,7 +4978,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 +4986,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"]
     }
@@ -5453,9 +5511,9 @@ function startWatcher(ctx2, log2, opts) {
     opts?.onRawEvent?.("unlink", abs, relPath);
     if (relPath.endsWith(".md")) remove(relPath);
   });
-  const ready = new Promise((resolve3) => {
+  const ready = new Promise((resolve4) => {
     watcher2.once("ready", () => {
-      resolve3();
+      resolve4();
     });
   });
   return {
@@ -5465,7 +5523,7 @@ function startWatcher(ctx2, log2, opts) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.18.0" : "0.0.0-dev";
+var VERSION = true ? "0.20.0" : "0.0.0-dev";
 var intent = parseCliIntent(process.argv.slice(2));
 if (intent === "version") {
   process.stdout.write(`${VERSION}
@@ -5512,7 +5570,7 @@ if (!rawVaultRoot) {
   log.error("SEEKSTONE_VAULT env var is required");
   process.exit(1);
 }
-var vaultRoot = resolve2(rawVaultRoot);
+var vaultRoot = resolve3(rawVaultRoot);
 var policy = parseWritePolicy(process.env);
 if (policy.readOnly) log.info("read-only mode", { env: "SEEKSTONE_READ_ONLY" });
 if (policy.writeGlobs) log.info("write paths scoped", { globs: policy.writeGlobs });
@@ -5564,7 +5622,11 @@ if (semanticCfg) {
 }
 var watcher = startWatcher(ctx, log);
 process.on("exit", () => void watcher.stop());
-var server = new Server({ name: "seekstone", version: VERSION }, { capabilities: { tools: {} } });
+var instructions = resolveInstructions(process.env, vaultRoot, log);
+var server = new Server(
+  { name: "seekstone", version: VERSION },
+  { capabilities: { tools: {} }, instructions }
+);
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: visibleTools(ctx.policy)
 }));