seekstone 0.15.0 → 0.15.1

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: searches return in **single-digit milliseconds** 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 **~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).
 
 (Previously also published as `obsidian-mcp-seekstone` — that alias is deprecated; existing installs keep working, but install `seekstone` going forward.)
 
@@ -131,7 +131,7 @@ Other MCP clients (Windsurf, Cline, …) take the Option 3 JSON block in their o
 | `rename_heading` | Rename a heading in a note — every `[[note#heading]]` wikilink and embed across the vault is rewritten so references keep working (aliases preserved, fenced code blocks left alone). |
 | `append_note` | Append to a note body without touching frontmatter. |
 | `patch_frontmatter` | Set/update/delete frontmatter keys without reordering existing keys or changing quote style. |
-| `patch_note` | Insert text immediately after a heading without touching frontmatter. |
+| `patch_note` | Append, prepend, or replace text at a heading or block reference (`createIfMissing` to add the section) — frontmatter untouched. |
 | `replace_in_note` | Find and replace text in the note body — literal or regex, whole-word, case sensitivity, optional `limit` (replaces **all** occurrences by default), dry-run preview. |
 | `append_periodic_note` | Append to today's periodic note, creating it from a template if it doesn't yet exist. |
 
@@ -183,7 +183,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, no telemetry. 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). 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

@@ -1,7 +1,126 @@
 #!/usr/bin/env node
-import {
-  resolveSemanticConfig
-} from "./chunk-RRLYVK2X.js";
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/semantic/config.ts
+import { join as join7 } from "path";
+function defaultCacheDir(env, homedir2) {
+  return env.SEEKSTONE_CACHE_DIR || join7(homedir2, ".cache", "seekstone");
+}
+function resolveSemanticConfig(env, homedir2) {
+  if (env.SEEKSTONE_SEMANTIC !== "1") return void 0;
+  const cacheDir = defaultCacheDir(env, homedir2);
+  const modelDir = env.SEEKSTONE_MODEL_PATH || join7(cacheDir, "models", DEFAULT_MODEL_ID);
+  return { modelDir, cacheDir };
+}
+var DEFAULT_MODEL_ID;
+var init_config = __esm({
+  "src/semantic/config.ts"() {
+    "use strict";
+    DEFAULT_MODEL_ID = "potion-base-8M";
+  }
+});
+
+// src/semantic/model-manifest.ts
+var DEFAULT_MODEL;
+var init_model_manifest = __esm({
+  "src/semantic/model-manifest.ts"() {
+    "use strict";
+    DEFAULT_MODEL = {
+      id: "potion-base-8M",
+      license: "MIT (https://huggingface.co/minishlab/potion-base-8M)",
+      files: [
+        {
+          name: "model.safetensors",
+          url: "https://huggingface.co/minishlab/potion-base-8M/resolve/main/model.safetensors",
+          sha256: "f65d0f325faadc1e121c319e2faa41170d3fa07d8c89abd48ca5358d9a223de2",
+          bytes: 30236760
+        },
+        {
+          name: "tokenizer.json",
+          url: "https://huggingface.co/minishlab/potion-base-8M/resolve/main/tokenizer.json",
+          sha256: "e67e803f624fb4d67dea1c730d06e1067e1b14d830e2c2202569e3ef0f70bb50",
+          bytes: 683666
+        },
+        {
+          name: "config.json",
+          url: "https://huggingface.co/minishlab/potion-base-8M/resolve/main/config.json",
+          sha256: "2a6ac0e9aaa356a68a5688070db78fc3a464fefe85d2f06a1905ce3718687553",
+          bytes: 202
+        }
+      ]
+    };
+  }
+});
+
+// src/semantic/fetch-model.ts
+var fetch_model_exports = {};
+__export(fetch_model_exports, {
+  runFetchModel: () => runFetchModel
+});
+import { createHash as createHash3 } from "crypto";
+import { existsSync } from "fs";
+import { mkdir as mkdir7, readFile as readFile17, writeFile as writeFile4 } from "fs/promises";
+import { join as join11 } from "path";
+async function runFetchModel(deps) {
+  const manifest = deps.manifest ?? DEFAULT_MODEL;
+  const fetchFn = deps.fetchFn ?? fetch;
+  const destDir = deps.env.SEEKSTONE_MODEL_PATH || join11(defaultCacheDir(deps.env, deps.homedir), "models", manifest.id);
+  const output = [];
+  output.push(`fetch-model: ${manifest.id} \u2192 ${destDir}`);
+  try {
+    await mkdir7(destDir, { recursive: true });
+    let fetched = 0;
+    let skipped = 0;
+    for (const file of manifest.files) {
+      const dest = join11(destDir, file.name);
+      if (existsSync(dest) && sha256(await readFile17(dest)) === file.sha256) {
+        skipped++;
+        continue;
+      }
+      output.push(`fetching ${file.name} (${file.bytes} bytes)\u2026`);
+      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);
+      if (got !== file.sha256) {
+        throw new Error(`checksum mismatch for ${file.name}: expected ${file.sha256}, got ${got}`);
+      }
+      await writeFile4(dest, buf);
+      fetched++;
+    }
+    output.push(`\u2713 ${manifest.id}: ${fetched} fetched, ${skipped} already present (verified).`);
+    output.push(
+      "Enable semantic search with SEEKSTONE_SEMANTIC=1 in your MCP server config, then restart the session."
+    );
+    return { output, exitCode: 0 };
+  } catch (err) {
+    output.push(`\u2717 ${err instanceof Error ? err.message : String(err)}`);
+    return { output, exitCode: 1 };
+  }
+}
+function sha256(buf) {
+  return createHash3("sha256").update(buf).digest("hex");
+}
+var init_fetch_model = __esm({
+  "src/semantic/fetch-model.ts"() {
+    "use strict";
+    init_config();
+    init_model_manifest();
+  }
+});
 
 // src/index.ts
 import { homedir } from "os";
@@ -2137,6 +2256,7 @@ var META_KEYS = [
   "to",
   "folder",
   "tag",
+  "mode",
   "limit",
   "overwrite",
   "pattern",
@@ -2828,7 +2948,7 @@ function createLogger(opts = {}) {
       );
     }
   }
-  function writeFile4(record) {
+  function writeFile5(record) {
     if (!fileOk || filePath === void 0) return;
     const line = `${JSON.stringify(record)}
 `;
@@ -2850,7 +2970,7 @@ function createLogger(opts = {}) {
     const f = fields ?? {};
     stderr(`${lvl.toUpperCase().padEnd(5)} ${ts} ${msg}${fmtFields(f)}
 `);
-    writeFile4({ t: ts, level: lvl, msg, ...f });
+    writeFile5({ t: ts, level: lvl, msg, ...f });
   }
   return {
     level,
@@ -2881,6 +3001,9 @@ function installProcessGuards(log2) {
   };
 }
 
+// src/index.ts
+init_config();
+
 // ../core/src/embed/chunk.ts
 var MIN_WINDOW_WORDS = 250;
 var MAX_WINDOW_WORDS = 400;
@@ -2956,7 +3079,7 @@ function countWords(text) {
 
 // ../core/src/embed/model2vec.ts
 import { readFile as readFile14 } from "fs/promises";
-import { basename as basename4, join as join7 } from "path";
+import { basename as basename4, join as join8 } from "path";
 
 // ../core/src/embed/safetensors.ts
 function readSafetensors(buf) {
@@ -3137,9 +3260,9 @@ function isCjk(cp) {
 var TENSOR_NAME = "embeddings";
 async function loadModel2Vec(modelDir) {
   const [configRaw, tokenizerRaw, weights] = await Promise.all([
-    readFile14(join7(modelDir, "config.json"), "utf8"),
-    readFile14(join7(modelDir, "tokenizer.json"), "utf8"),
-    readFile14(join7(modelDir, "model.safetensors"))
+    readFile14(join8(modelDir, "config.json"), "utf8"),
+    readFile14(join8(modelDir, "tokenizer.json"), "utf8"),
+    readFile14(join8(modelDir, "model.safetensors"))
   ]);
   const config = JSON.parse(configRaw);
   const tokenizer = loadWordPieceTokenizer(JSON.parse(tokenizerRaw));
@@ -3198,12 +3321,12 @@ async function loadModel2Vec(modelDir) {
 // src/semantic/cache.ts
 import { createHash as createHash2 } from "crypto";
 import { mkdir as mkdir6, readFile as readFile15, rename as rename4, writeFile as writeFile3 } from "fs/promises";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 var CACHE_VERSION = 2;
 function cachePathsFor(cacheDir, vaultRoot2, modelId) {
   const vaultKey = createHash2("sha256").update(vaultRoot2).digest("hex").slice(0, 16);
-  const dir = join8(cacheDir, "embeddings", vaultKey);
-  return { dir, bin: join8(dir, `${modelId}.bin`), manifest: join8(dir, `${modelId}.json`) };
+  const dir = join9(cacheDir, "embeddings", vaultKey);
+  return { dir, bin: join9(dir, `${modelId}.bin`), manifest: join9(dir, `${modelId}.json`) };
 }
 async function loadCache(paths, modelId, dim) {
   try {
@@ -3566,7 +3689,7 @@ var ALL_TOOLS = [
   {
     name: "search",
     annotations: READ_ONLY_ANNOTATIONS,
-    description: 'Full-text search across the vault. Returns ranked excerpts (~200 chars) \u2014 not full notes \u2014 to minimise context usage. Supports fuzzy matching and prefix search; with SEEKSTONE_SEMANTIC=1, mode "semantic"/"hybrid" searches by meaning via a local embedding model.',
+    description: 'Full-text search across the vault. Returns ranked excerpts (~120 chars, tunable) \u2014 not full notes \u2014 to minimise context usage. Supports fuzzy matching and prefix search; with SEEKSTONE_SEMANTIC=1, mode "semantic"/"hybrid" searches by meaning via a local embedding model.',
     inputSchema: {
       type: "object",
       properties: {
@@ -3578,7 +3701,11 @@ var ALL_TOOLS = [
         },
         limit: { type: "number", description: "Max results (1\u201350, default 10)." },
         folder: { type: "string", description: "Restrict to a vault-relative folder prefix." },
-        tag: { type: "string", description: "Restrict to notes with this tag." }
+        tag: { type: "string", description: "Restrict to notes with this tag." },
+        excerptLength: {
+          type: "number",
+          description: "Max characters of match context per hit (20\u20132000, default 120)."
+        }
       },
       required: ["query"]
     }
@@ -4061,7 +4188,7 @@ function visibleTools(policy2) {
 // src/watcher.ts
 import { realpathSync } from "fs";
 import { readFile as readFile16 } from "fs/promises";
-import { join as join9, relative as relative2, sep as sep3 } from "path";
+import { join as join10, relative as relative2, sep as sep3 } from "path";
 import chokidar from "chokidar";
 function startWatcher(ctx2, log2, opts) {
   const usePolling = opts?.usePolling ?? process.env.SEEKSTONE_WATCH_POLL === "1";
@@ -4073,7 +4200,7 @@ function startWatcher(ctx2, log2, opts) {
   const toRel = (abs) => relative2(vaultRoot2, abs).split(sep3).join("/");
   async function upsert(relPath, op) {
     try {
-      const raw = await readFile16(join9(vaultRoot2, relPath), "utf8");
+      const raw = await readFile16(join10(vaultRoot2, relPath), "utf8");
       removeNoteBacklinks(ctx2, relPath);
       upsertDoc(ctx2, buildDoc(relPath, raw));
       addNoteBacklinks(ctx2, relPath, raw);
@@ -4127,7 +4254,7 @@ function startWatcher(ctx2, log2, opts) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.15.0" : "0.0.0-dev";
+var VERSION = true ? "0.15.1" : "0.0.0-dev";
 var intent = parseCliIntent(process.argv.slice(2));
 if (intent === "version") {
   process.stdout.write(`${VERSION}
@@ -4156,9 +4283,9 @@ if (intent === "init") {
   process.exit(result.exitCode);
 }
 if (intent === "fetch-model") {
-  const { runFetchModel } = await import("./fetch-model-7TGOJMZL.js");
+  const { runFetchModel: runFetchModel2 } = await Promise.resolve().then(() => (init_fetch_model(), fetch_model_exports));
   const { homedir: homedir2 } = await import("os");
-  const result = await runFetchModel({ env: process.env, homedir: homedir2() });
+  const result = await runFetchModel2({ env: process.env, homedir: homedir2() });
   process.stdout.write(`${result.output.join("\n")}
 `);
   process.exit(result.exitCode);