seekstone 0.17.2 → 0.18.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.)
 
@@ -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` 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_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,
@@ -3794,6 +3794,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 +4021,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 +4203,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 +4363,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 +4406,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 +4433,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
@@ -5283,8 +5379,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 +5411,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 +5465,7 @@ function startWatcher(ctx2, log2, opts) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.17.2" : "0.0.0-dev";
+var VERSION = true ? "0.18.0" : "0.0.0-dev";
 var intent = parseCliIntent(process.argv.slice(2));
 if (intent === "version") {
   process.stdout.write(`${VERSION}
@@ -5454,6 +5550,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,