seekstone 0.17.2 → 0.19.0

package/README.md

@@ -4,7 +4,7 @@
 
 Seekstone is an Obsidian MCP server that gives Claude (and any [Model Context Protocol](https://modelcontextprotocol.io) client) direct read and write access to your Obsidian vault. No Obsidian app needs to be running, no plugins are required, and nothing leaves your machine.
 
-It reads your vault **directly from disk** instead of routing through the Obsidian Local REST API plugin, and holds a warm full-text index in-process. The practical difference: keyword searches return in **single-digit milliseconds** (semantic search in **~14 ms**) with **~2 KB payloads** that stay flat as your vault grows — a broad query that costs tens of megabytes of context through a REST-proxy server (up to **95 MB** at 10k notes) costs ~2 KB through Seekstone, up to a **~47,000× reduction**. Benchmarked against 7 other Obsidian MCP servers across committed 1k/5k/10k-note vaults — [fully reproducible](https://github.com/shaqmughal/seekstone/tree/main/packages/harness), full results at [seekstone.dev/benchmarks](https://seekstone.dev/benchmarks).
+It reads your vault **directly from disk** instead of routing through the Obsidian Local REST API plugin, and holds a warm full-text index in-process. The practical difference: keyword searches return in **single-digit milliseconds** (semantic search in **~26 ms**) with **~2 KB payloads** that stay flat as your vault grows — a broad query that costs tens of megabytes of context through a REST-proxy server (up to **95 MB** at 10k notes) costs ~2 KB through Seekstone, up to a **~47,000× reduction**. Benchmarked against 7 other Obsidian MCP servers across committed 1k/5k/10k-note vaults — [fully reproducible](https://github.com/shaqmughal/seekstone/tree/main/packages/harness), full results at [seekstone.dev/benchmarks](https://seekstone.dev/benchmarks).
 
 (Previously also published as `obsidian-mcp-seekstone` — that alias is deprecated; existing installs keep working, but install `seekstone` going forward.)
 
@@ -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,10 +158,11 @@ 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. |
+| `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. |
 
 ---
 
@@ -208,7 +209,7 @@ Any MCP-over-stdio client: Claude Desktop, Claude Code, Cursor, VS Code, Windsur
 Yes — tested on macOS, Linux, and Windows in CI on every commit.
 
 **Is it safe?**
-No network calls while running, no telemetry (the optional semantic-search model is downloaded once by the explicit `fetch-model` subcommand, SHA-256-verified, before any serving starts). The vault path is sandboxed — no tool reads or writes outside it. Writes are covered by the tested Write-Safety Contract above, and `SEEKSTONE_READ_ONLY=1` removes the write tools entirely.
+No network calls while running, no telemetry (the optional semantic-search model is downloaded once by the explicit `fetch-model` subcommand, SHA-256-verified, before any serving starts — or shipped inside the `seekstone-semantic.mcpb` bundle and reassembled from disk at boot, verified against the same pinned hashes). The vault path is sandboxed — no tool reads or writes outside it. Writes are covered by the tested Write-Safety Contract above, and `SEEKSTONE_READ_ONLY=1` removes the write tools entirely.
 
 ---
 

package/dist/index.js

@@ -71,9 +71,9 @@ var init_model_manifest = __esm({
 });
 
 // src/semantic/config.ts
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 function defaultCacheDir(env, homedir2) {
-  return env.SEEKSTONE_CACHE_DIR || join8(homedir2, ".cache", "seekstone");
+  return env.SEEKSTONE_CACHE_DIR || join9(homedir2, ".cache", "seekstone");
 }
 function resolveModel(raw) {
   const id = raw?.trim();
@@ -96,7 +96,7 @@ function resolveSemanticConfig(env, homedir2) {
   if (env.SEEKSTONE_SEMANTIC !== "1") return void 0;
   const modelId = resolveModelId(env.SEEKSTONE_SEMANTIC_MODEL);
   const cacheDir = defaultCacheDir(env, homedir2);
-  const modelDir = env.SEEKSTONE_MODEL_PATH || join8(cacheDir, "models", modelId);
+  const modelDir = env.SEEKSTONE_MODEL_PATH || join9(cacheDir, "models", modelId);
   return { modelId, modelDir, cacheDir };
 }
 var DEFAULT_MODEL_ID;
@@ -114,10 +114,10 @@ __export(fetch_model_exports, {
   runFetchModel: () => runFetchModel,
   selectManifest: () => selectManifest
 });
-import { createHash as createHash3 } from "crypto";
-import { existsSync } from "fs";
-import { mkdir as mkdir9, readFile as readFile19, writeFile as writeFile4 } from "fs/promises";
-import { join as join12 } from "path";
+import { createHash as createHash4 } from "crypto";
+import { existsSync as existsSync2 } from "fs";
+import { mkdir as mkdir10, readFile as readFile20, writeFile as writeFile5 } from "fs/promises";
+import { join as join13 } from "path";
 function selectManifest(argv, env) {
   let requested;
   for (let i = 0; i < argv.length; i++) {
@@ -146,15 +146,15 @@ async function runFetchModel(deps) {
     return { output, exitCode: 1 };
   }
   const fetchFn = deps.fetchFn ?? fetch;
-  const destDir = deps.env.SEEKSTONE_MODEL_PATH || join12(defaultCacheDir(deps.env, deps.homedir), "models", manifest.id);
+  const destDir = deps.env.SEEKSTONE_MODEL_PATH || join13(defaultCacheDir(deps.env, deps.homedir), "models", manifest.id);
   output.push(`fetch-model: ${manifest.id} \u2192 ${destDir}`);
   try {
-    await mkdir9(destDir, { recursive: true });
+    await mkdir10(destDir, { recursive: true });
     let fetched = 0;
     let skipped = 0;
     for (const file of manifest.files) {
-      const dest = join12(destDir, file.name);
-      if (existsSync(dest) && sha256(await readFile19(dest)) === file.sha256) {
+      const dest = join13(destDir, file.name);
+      if (existsSync2(dest) && sha2562(await readFile20(dest)) === file.sha256) {
         skipped++;
         continue;
       }
@@ -162,11 +162,11 @@ async function runFetchModel(deps) {
       const res = await fetchFn(file.url);
       if (!res.ok) throw new Error(`fetch ${file.url} failed: ${res.status}`);
       const buf = Buffer.from(await res.arrayBuffer());
-      const got = sha256(buf);
+      const got = sha2562(buf);
       if (got !== file.sha256) {
         throw new Error(`checksum mismatch for ${file.name}: expected ${file.sha256}, got ${got}`);
       }
-      await writeFile4(dest, buf);
+      await writeFile5(dest, buf);
       fetched++;
     }
     output.push(`\u2713 ${manifest.id}: ${fetched} fetched, ${skipped} already present (verified).`);
@@ -179,8 +179,8 @@ async function runFetchModel(deps) {
     return { output, exitCode: 1 };
   }
 }
-function sha256(buf) {
-  return createHash3("sha256").update(buf).digest("hex");
+function sha2562(buf) {
+  return createHash4("sha256").update(buf).digest("hex");
 }
 var init_fetch_model = __esm({
   "src/semantic/fetch-model.ts"() {
@@ -271,7 +271,7 @@ function createLogger(opts = {}) {
       );
     }
   }
-  function writeFile5(record) {
+  function writeFile6(record) {
     if (!fileOk || filePath === void 0) return;
     const line = `${JSON.stringify(record)}
 `;
@@ -293,7 +293,7 @@ function createLogger(opts = {}) {
     const f = fields ?? {};
     stderr(`${lvl.toUpperCase().padEnd(5)} ${ts} ${msg}${fmtFields(f)}
 `);
-    writeFile5({ t: ts, level: lvl, msg, ...f });
+    writeFile6({ t: ts, level: lvl, msg, ...f });
   }
   return {
     level,
@@ -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));
@@ -3794,6 +3802,82 @@ function installProcessGuards(log2) {
   };
 }
 
+// src/semantic/bundled-model.ts
+init_model_manifest();
+import { createHash as createHash2 } from "crypto";
+import { existsSync } from "fs";
+import { mkdir as mkdir8, readdir as readdir3, readFile as readFile16, rename as rename5, writeFile as writeFile3 } from "fs/promises";
+import { join as join8 } from "path";
+async function materializeBundledModel(cfg, bundledDir, deps = {}) {
+  if (!bundledDir) return;
+  if (!existsSync(bundledDir)) {
+    deps.log?.warn("bundled model dir missing \u2014 skipping materialization", { dir: bundledDir });
+    return;
+  }
+  let bundledId;
+  try {
+    const raw = await readFile16(join8(bundledDir, "manifest.json"), "utf8");
+    bundledId = String(JSON.parse(raw).id);
+  } catch (err) {
+    throw new Error(
+      `bundled model: cannot read ${join8(bundledDir, "manifest.json")} \u2014 the extension bundle is corrupt; reinstall it (${err instanceof Error ? err.message : String(err)})`
+    );
+  }
+  if (bundledId !== cfg.modelId) {
+    deps.log?.info("bundled model does not match the requested model \u2014 skipping", {
+      bundled: bundledId,
+      requested: cfg.modelId
+    });
+    return;
+  }
+  const manifest = (deps.manifestFor ?? findModel)(cfg.modelId);
+  if (!manifest) return;
+  await mkdir8(cfg.modelDir, { recursive: true });
+  let written = 0;
+  for (const file of manifest.files) {
+    const dest = join8(cfg.modelDir, file.name);
+    if (existsSync(dest) && sha256(await readFile16(dest)) === file.sha256) continue;
+    const buf = await concatParts(bundledDir, file.name);
+    const got = sha256(buf);
+    if (got !== file.sha256) {
+      throw new Error(
+        `bundled model: checksum mismatch for ${file.name} (expected ${file.sha256}, got ${got}) \u2014 the extension bundle is corrupt; reinstall it`
+      );
+    }
+    const tmp = `${dest}.tmp-${process.pid}`;
+    await writeFile3(tmp, buf);
+    await rename5(tmp, dest);
+    written++;
+  }
+  if (written > 0) {
+    deps.log?.info("bundled model materialized", {
+      model: manifest.id,
+      dir: cfg.modelDir,
+      files: written
+    });
+  }
+}
+async function concatParts(bundledDir, name) {
+  const prefix = `${name}.`;
+  const partNum = (f) => Number(f.slice(prefix.length, -".part".length));
+  const parts = (await readdir3(bundledDir)).filter((f) => {
+    if (!f.startsWith(prefix) || !f.endsWith(".part")) return false;
+    const middle = f.slice(prefix.length, -".part".length);
+    return /^\d+$/.test(middle);
+  }).sort((a, b) => partNum(a) - partNum(b));
+  if (parts.length === 0) {
+    throw new Error(
+      `bundled model: no shards for ${name} in ${bundledDir} \u2014 the extension bundle is corrupt; reinstall it`
+    );
+  }
+  const buffers = [];
+  for (const part of parts) buffers.push(await readFile16(join8(bundledDir, part)));
+  return Buffer.concat(buffers);
+}
+function sha256(buf) {
+  return createHash2("sha256").update(buf).digest("hex");
+}
+
 // src/index.ts
 init_config();
 
@@ -3945,8 +4029,8 @@ function candidateSetIdf(queryIds, docs) {
 }
 
 // ../core/src/embed/model2vec.ts
-import { readFile as readFile16 } from "fs/promises";
-import { basename as basename4, join as join9 } from "path";
+import { readFile as readFile17 } from "fs/promises";
+import { basename as basename4, join as join10 } from "path";
 
 // ../core/src/embed/safetensors.ts
 function readSafetensors(buf) {
@@ -4127,9 +4211,9 @@ function isCjk(cp) {
 var TENSOR_NAME = "embeddings";
 async function loadModel2Vec(modelDir) {
   const [configRaw, tokenizerRaw, weights] = await Promise.all([
-    readFile16(join9(modelDir, "config.json"), "utf8"),
-    readFile16(join9(modelDir, "tokenizer.json"), "utf8"),
-    readFile16(join9(modelDir, "model.safetensors"))
+    readFile17(join10(modelDir, "config.json"), "utf8"),
+    readFile17(join10(modelDir, "tokenizer.json"), "utf8"),
+    readFile17(join10(modelDir, "model.safetensors"))
   ]);
   const config = JSON.parse(configRaw);
   const tokenizer = loadWordPieceTokenizer(JSON.parse(tokenizerRaw));
@@ -4287,26 +4371,27 @@ function isTokenEmbedder(e) {
 }
 
 // src/semantic/cache.ts
-import { createHash as createHash2 } from "crypto";
-import { mkdir as mkdir8, readFile as readFile17, rename as rename5, writeFile as writeFile3 } from "fs/promises";
-import { join as join10 } from "path";
-var CACHE_VERSION = 2;
+import { createHash as createHash3 } from "crypto";
+import { mkdir as mkdir9, readFile as readFile18, rename as rename6, writeFile as writeFile4 } from "fs/promises";
+import { join as join11 } from "path";
+var CACHE_VERSION = 3;
 function cachePathsFor(cacheDir, vaultRoot2, modelId) {
-  const vaultKey = createHash2("sha256").update(vaultRoot2).digest("hex").slice(0, 16);
-  const dir = join10(cacheDir, "embeddings", vaultKey);
-  return { dir, bin: join10(dir, `${modelId}.bin`), manifest: join10(dir, `${modelId}.json`) };
+  const vaultKey = createHash3("sha256").update(vaultRoot2).digest("hex").slice(0, 16);
+  const dir = join11(cacheDir, "embeddings", vaultKey);
+  return { dir, bin: join11(dir, `${modelId}.bin`), manifest: join11(dir, `${modelId}.json`) };
 }
 async function loadCache(paths, modelId, dim) {
   try {
-    const manifest = JSON.parse(await readFile17(paths.manifest, "utf8"));
+    const manifest = JSON.parse(await readFile18(paths.manifest, "utf8"));
     if (manifest.version !== CACHE_VERSION || manifest.modelId !== modelId || manifest.dim !== dim) {
       return void 0;
     }
-    const buf = await readFile17(paths.bin);
+    const buf = await readFile18(paths.bin);
     const totalChunks = manifest.entries.reduce((a, e) => a + e.chunks, 0);
     const vectorBytes = totalChunks * dim * 4;
     const spanBytes = totalChunks * 2 * 4;
     if (buf.byteLength !== vectorBytes + spanBytes) return void 0;
+    if (binHashOf(buf) !== manifest.binHash) return void 0;
     const aligned = new Uint8Array(buf.byteLength);
     aligned.set(buf);
     const floats = new Float32Array(aligned.buffer, 0, totalChunks * dim);
@@ -4329,17 +4414,22 @@ async function loadCache(paths, modelId, dim) {
   }
 }
 async function saveCache(paths, modelId, dim, notes2, hashes) {
-  const entries = [];
-  const kept = [];
+  const rows = [];
   let totalChunks = 0;
   for (const [path2, note] of notes2) {
     const contentHash2 = hashes.get(path2);
     if (!contentHash2) continue;
     const chunks = note.packed.length / dim;
-    entries.push({ path: path2, contentHash: contentHash2, chunks });
-    kept.push(note);
+    rows.push({ path: path2, contentHash: contentHash2, chunks, note });
     totalChunks += chunks;
   }
+  rows.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const entries = rows.map(({ path: path2, contentHash: contentHash2, chunks }) => ({
+    path: path2,
+    contentHash: contentHash2,
+    chunks
+  }));
+  const kept = rows.map((r) => r.note);
   const bin = new Uint8Array(totalChunks * dim * 4 + totalChunks * 2 * 4);
   const floats = new Float32Array(bin.buffer, 0, totalChunks * dim);
   const spans = new Uint32Array(bin.buffer, totalChunks * dim * 4, totalChunks * 2);
@@ -4351,15 +4441,29 @@ async function saveCache(paths, modelId, dim, notes2, hashes) {
     floatOffset += note.packed.length;
     spanOffset += note.spans.length;
   }
-  const manifest = { version: CACHE_VERSION, modelId, dim, entries };
-  await mkdir8(paths.dir, { recursive: true });
+  const manifest = {
+    version: CACHE_VERSION,
+    modelId,
+    dim,
+    binHash: binHashOf(bin),
+    entries
+  };
+  await mkdir9(paths.dir, { recursive: true });
   await atomicWriteBytes(paths.bin, bin);
   await atomicWriteBytes(paths.manifest, new TextEncoder().encode(JSON.stringify(manifest)));
 }
+function binHashOf(bin) {
+  return createHash3("sha256").update(bin).digest("hex");
+}
+var tempSeq = 0;
+function tempPathFor(absPath) {
+  tempSeq += 1;
+  return `${absPath}.${process.pid}.${tempSeq}.seekstone-cache-tmp`;
+}
 async function atomicWriteBytes(absPath, bytes) {
-  const tmpPath = `${absPath}.seekstone-cache-tmp`;
-  await writeFile3(tmpPath, bytes);
-  await rename5(tmpPath, absPath);
+  const tmpPath = tempPathFor(absPath);
+  await writeFile4(tmpPath, bytes);
+  await rename6(tmpPath, absPath);
 }
 
 // src/semantic/state.ts
@@ -4831,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: {
@@ -4839,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"]
     }
@@ -5283,8 +5394,8 @@ function visibleTools(policy2) {
 
 // src/watcher.ts
 import { realpathSync } from "fs";
-import { readFile as readFile18 } from "fs/promises";
-import { join as join11, relative as relative2, sep as sep3 } from "path";
+import { readFile as readFile19 } from "fs/promises";
+import { join as join12, relative as relative2, sep as sep3 } from "path";
 import chokidar from "chokidar";
 var DEFAULT_POLL_INTERVAL_MS = 1e4;
 function resolvePollInterval(optValue, envValue, log2) {
@@ -5315,7 +5426,7 @@ function startWatcher(ctx2, log2, opts) {
   const toRel = (abs) => relative2(vaultRoot2, abs).split(sep3).join("/");
   async function upsert(relPath, op) {
     try {
-      const raw = await readFile18(join11(vaultRoot2, relPath), "utf8");
+      const raw = await readFile19(join12(vaultRoot2, relPath), "utf8");
       removeNoteBacklinks(ctx2, relPath);
       upsertDoc(ctx2, buildDoc(relPath, raw));
       addNoteBacklinks(ctx2, relPath, raw);
@@ -5369,7 +5480,7 @@ function startWatcher(ctx2, log2, opts) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.17.2" : "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}
@@ -5454,6 +5565,7 @@ if (auditCfg) {
 var semanticCfg = resolveSemanticConfig(process.env, homedir());
 if (semanticCfg) {
   try {
+    await materializeBundledModel(semanticCfg, process.env.SEEKSTONE_BUNDLED_MODEL_DIR, { log });
     ctx.semantic = await Semantic.start(ctx, semanticCfg, { log });
     log.info("semantic search enabled", {
       model: ctx.semantic.embedder.id,