seekstone 0.14.0 → 0.15.0

package/dist/index.js

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
+import {
+  resolveSemanticConfig
+} from "./chunk-RRLYVK2X.js";
 
 // src/index.ts
+import { homedir } from "os";
 import { resolve as resolve2 } from "path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -17,6 +21,7 @@ function parseCliIntent(argv) {
     }
     return "init";
   }
+  if (argv[0] === "fetch-model") return "fetch-model";
   for (const arg of argv) {
     if (arg === "--version" || arg === "-v") return "version";
     if (arg === "--help" || arg === "-h") return "help";
@@ -33,10 +38,11 @@ Seekstone runs as a Model Context Protocol stdio server. It is normally
 launched by an MCP client (Claude Desktop, Claude Code, Cursor, \u2026), not run by hand.
 
 Usage:
-  seekstone            Start the MCP server (reads from stdin/stdout)
-  seekstone init       Validate a vault and print/patch the client MCP config
-  seekstone --version  Print the version and exit
-  seekstone --help     Print this help and exit
+  seekstone              Start the MCP server (reads from stdin/stdout)
+  seekstone init         Validate a vault and print/patch the client MCP config
+  seekstone fetch-model  Download the local embedding model for semantic search
+  seekstone --version    Print the version and exit
+  seekstone --help       Print this help and exit
 
 "seekstone init" options:
 ${initOptionLines}
@@ -48,6 +54,9 @@ Optional environment:
   SEEKSTONE_LOG_LEVEL  error | warn | info (default) | debug
   SEEKSTONE_LOG_FILE   Absolute path; append JSON-line logs here
   SEEKSTONE_WATCH_POLL Set to 1 to poll for changes (network drives, WSL)
+  SEEKSTONE_SEMANTIC   Set to 1 to enable semantic search (needs fetch-model first)
+  SEEKSTONE_MODEL_PATH Override the embedding-model directory
+  SEEKSTONE_CACHE_DIR  Override the cache root (default ~/.cache/seekstone)
 
 Add to Claude Code:
   claude mcp add seekstone --env SEEKSTONE_VAULT=/path/to/vault -- npx -y seekstone
@@ -370,8 +379,39 @@ function resolveLink(target, notes2) {
 
 // src/tools/search.ts
 import { z as z2 } from "zod";
+
+// src/semantic/excerpt.ts
+function chunkExcerpt(body, span, terms, maxLen) {
+  const normalized = body.includes("\r") ? body.replace(/\r\n/g, "\n") : body;
+  const start = Math.min(span.start, normalized.length);
+  const end = Math.min(Math.max(span.end, start), normalized.length);
+  const text = start === end ? normalized : normalized.slice(start, end);
+  return extractExcerpt(text, terms, maxLen);
+}
+
+// src/semantic/route.ts
+var MAX_ROUTE_WORDS = 6;
+function queryWords(query) {
+  return query.toLowerCase().split(/\W+/).filter(Boolean);
+}
+function routeToLexical(query, topPaths, topN = 3) {
+  const words = new Set(queryWords(query));
+  if (words.size === 0) return false;
+  return topPaths.slice(0, topN).some((path2) => {
+    const base = (path2.split(/[\\/]/).pop() ?? "").replace(/\.md$/, "").toLowerCase();
+    const parts = new Set(base.split(/\W+/).filter(Boolean));
+    return parts.size === words.size && [...parts].every((p) => words.has(p));
+  });
+}
+
+// src/tools/search.ts
 var SearchInput = z2.object({
   query: z2.string().min(1).describe("Search query. Supports fuzzy matching and prefix search."),
+  // Optional (not .default()) so the inferred type keeps existing direct
+  // callers compiling; search() itself defaults it to 'lexical'.
+  mode: z2.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."
+  ),
   limit: z2.number().int().min(1).max(50).default(10).describe("Maximum number of results to return."),
   folder: z2.string().optional().describe("Restrict results to notes under this vault-relative folder prefix."),
   tag: z2.string().optional().describe("Restrict results to notes containing this tag."),
@@ -379,44 +419,113 @@ var SearchInput = z2.object({
     "Max characters of match context per hit (default 120). Lower trims payload; higher gives more context."
   )
 });
+var SEMANTIC_CANDIDATES = 50;
 function basenameNoExt(path2) {
   const base = path2.slice(path2.lastIndexOf("/") + 1);
   const dot = base.lastIndexOf(".");
   return dot > 0 ? base.slice(0, dot) : base;
 }
 function search(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);
+    if (routeToLexical(
+      input.query,
+      lexHits.map((h) => h.path)
+    ))
+      return lexHits;
+  }
+  return semanticSearch(ctx2, semantic, input);
+}
+function requireSemantic(ctx2) {
+  if (!ctx2.semantic) {
+    throw new Error(
+      JSON.stringify({
+        error: "semantic_unavailable",
+        hint: 'Semantic search is not enabled. Set SEEKSTONE_SEMANTIC=1 in the server env and run `npx -y seekstone fetch-model` once to download the local embedding model, then restart the session. Meanwhile, mode: "lexical" works.'
+      })
+    );
+  }
+  const progress = ctx2.semantic.progress;
+  if (progress.state === "building") {
+    throw new Error(
+      JSON.stringify({
+        error: "semantic_building",
+        done: progress.done,
+        total: progress.total,
+        hint: 'The semantic index is still embedding this vault (first run only \u2014 later runs load a cache). Retry shortly, or use mode: "lexical".'
+      })
+    );
+  }
+  return ctx2.semantic;
+}
+function searchTerms(query) {
+  return query.toLowerCase().split(/\s+/).filter((t) => t.length > 1);
+}
+function lexicalSearch(ctx2, input) {
   const results = ctx2.index.search(input.query, {
     boost: { title: 3, tags: 2, body: 1 },
     fuzzy: 0.2,
     prefix: true
   });
-  const terms = input.query.toLowerCase().split(/\s+/).filter((t) => t.length > 1);
+  const terms = searchTerms(input.query);
   const hits = [];
   for (const r of results) {
-    if (input.folder && !r.id.startsWith(input.folder)) continue;
-    if (input.tag) {
-      const note2 = ctx2.notes.get(r.id);
-      if (!note2) continue;
-      const noteTags2 = note2.tags.split(" ");
-      if (!noteTags2.some((t) => t === input.tag || t === input.tag?.replace(/^#/, ""))) continue;
-    }
-    const note = ctx2.notes.get(r.id);
-    const body = note?.body ?? "";
-    const noteTags = note?.tags ? note.tags.split(" ").filter(Boolean) : [];
-    const title = r.title;
+    const note = filterNote(ctx2, input, r.id);
+    if (!note) continue;
     const hit = {
       path: r.id,
       // Round the raw MiniSearch score: 2 decimals preserve relevance gaps without 17-digit float tax.
       score: Math.round(r.score * 100) / 100,
-      excerpt: extractExcerpt(body, terms, input.excerptLength ?? 120)
+      excerpt: extractExcerpt(note.body, terms, input.excerptLength ?? 120)
+    };
+    decorate(hit, r.title, note.tags);
+    hits.push(hit);
+    if (hits.length >= input.limit) break;
+  }
+  return hits;
+}
+function semanticSearch(ctx2, semantic, input) {
+  const queryVec = semantic.embedQuery(input.query);
+  const candidates = semantic.store.topNotes(queryVec, SEMANTIC_CANDIDATES);
+  const terms = searchTerms(input.query);
+  const hits = [];
+  for (const c of candidates) {
+    const note = filterNote(ctx2, input, c.path);
+    if (!note) continue;
+    const hit = {
+      path: c.path,
+      // Cosine similarity ∈ [-1, 1]: 3 decimals keep the ranking legible.
+      score: Math.round(c.score * 1e3) / 1e3,
+      excerpt: chunkExcerpt(note.body, c, terms, input.excerptLength ?? 120)
     };
-    if (title && title !== basenameNoExt(r.id)) hit.title = title;
-    if (noteTags.length > 0) hit.tags = noteTags;
+    decorate(hit, note.title, note.tags);
     hits.push(hit);
     if (hits.length >= input.limit) break;
   }
   return hits;
 }
+function filterNote(ctx2, input, path2) {
+  if (input.folder && !path2.startsWith(input.folder)) return void 0;
+  const note = ctx2.notes.get(path2);
+  if (!note) return void 0;
+  if (input.tag) {
+    const noteTags = note.tags.split(" ");
+    if (!noteTags.some((t) => t === input.tag || t === input.tag?.replace(/^#/, ""))) {
+      return void 0;
+    }
+  }
+  return note;
+}
+function decorate(hit, title, tags) {
+  if (title && title !== basenameNoExt(hit.path)) hit.title = title;
+  const noteTags = tags ? tags.split(" ").filter(Boolean) : [];
+  if (noteTags.length > 0) hit.tags = noteTags;
+}
 
 // src/tools/context_pack.ts
 var ContextPackInput = z3.object({
@@ -2719,7 +2828,7 @@ function createLogger(opts = {}) {
       );
     }
   }
-  function writeFile3(record) {
+  function writeFile4(record) {
     if (!fileOk || filePath === void 0) return;
     const line = `${JSON.stringify(record)}
 `;
@@ -2741,7 +2850,7 @@ function createLogger(opts = {}) {
     const f = fields ?? {};
     stderr(`${lvl.toUpperCase().padEnd(5)} ${ts} ${msg}${fmtFields(f)}
 `);
-    writeFile3({ t: ts, level: lvl, msg, ...f });
+    writeFile4({ t: ts, level: lvl, msg, ...f });
   }
   return {
     level,
@@ -2772,6 +2881,664 @@ function installProcessGuards(log2) {
   };
 }
 
+// ../core/src/embed/chunk.ts
+var MIN_WINDOW_WORDS = 250;
+var MAX_WINDOW_WORDS = 400;
+function chunkNote(title, body) {
+  const normalized = body.replace(/\r\n/g, "\n");
+  const paragraphs = splitParagraphs(normalized).flatMap(splitOversized);
+  if (paragraphs.length === 0) return [{ text: title, words: 0, start: 0, end: 0 }];
+  const chunks = [];
+  let window = [];
+  let windowWords = 0;
+  const flush = () => {
+    const first = window[0];
+    const last = window[window.length - 1];
+    if (!first || !last) return;
+    chunks.push({
+      text: `${title}
+
+${window.map((p) => p.text).join("\n\n")}`,
+      words: windowWords,
+      start: first.start,
+      end: last.end
+    });
+    window = [];
+    windowWords = 0;
+  };
+  for (const para of paragraphs) {
+    if (windowWords >= MIN_WINDOW_WORDS || windowWords + para.words > MAX_WINDOW_WORDS) flush();
+    window.push(para);
+    windowWords += para.words;
+  }
+  flush();
+  return chunks;
+}
+function splitParagraphs(normalized) {
+  const out = [];
+  const push = (rawStart, raw) => {
+    const text = raw.trim();
+    if (text.length === 0) return;
+    const start = rawStart + (raw.length - raw.trimStart().length);
+    out.push({ text, words: countWords(text), start, end: start + text.length });
+  };
+  const sep4 = /\n[ \t]*\n+/g;
+  let prev = 0;
+  for (const m of normalized.matchAll(sep4)) {
+    push(prev, normalized.slice(prev, m.index));
+    prev = m.index + m[0].length;
+  }
+  push(prev, normalized.slice(prev));
+  return out;
+}
+function splitOversized(para) {
+  if (para.words <= MAX_WINDOW_WORDS) return [para];
+  const words = [...para.text.matchAll(/\S+/g)];
+  const pieces = [];
+  for (let i = 0; i < words.length; i += MAX_WINDOW_WORDS) {
+    const slice = words.slice(i, i + MAX_WINDOW_WORDS);
+    const first = slice[0];
+    const last = slice[slice.length - 1];
+    if (!first || !last) continue;
+    pieces.push({
+      text: slice.map((w) => w[0]).join(" "),
+      words: slice.length,
+      start: para.start + first.index,
+      end: para.start + last.index + last[0].length
+    });
+  }
+  return pieces;
+}
+function countWords(text) {
+  const m = text.match(/\S+/g);
+  return m ? m.length : 0;
+}
+
+// ../core/src/embed/model2vec.ts
+import { readFile as readFile14 } from "fs/promises";
+import { basename as basename4, join as join7 } from "path";
+
+// ../core/src/embed/safetensors.ts
+function readSafetensors(buf) {
+  if (buf.byteLength < 8) {
+    throw new Error(`safetensors: buffer too small (${buf.byteLength} bytes) to hold a header`);
+  }
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  const headerLen = Number(view.getBigUint64(0, true));
+  if (8 + headerLen > buf.byteLength) {
+    throw new Error(
+      `safetensors: header length ${headerLen} exceeds buffer (${buf.byteLength} bytes)`
+    );
+  }
+  const header = JSON.parse(new TextDecoder().decode(buf.subarray(8, 8 + headerLen)));
+  const dataStart = 8 + headerLen;
+  const out = /* @__PURE__ */ new Map();
+  const unsupported = [];
+  for (const [name, meta] of Object.entries(header)) {
+    if (name === "__metadata__") continue;
+    if (meta.dtype !== "F32") {
+      unsupported.push(`${name} (${meta.dtype})`);
+      continue;
+    }
+    const [begin, end] = meta.data_offsets;
+    const byteLen = end - begin;
+    const elems = meta.shape.reduce((a, b) => a * b, 1);
+    if (byteLen !== elems * 4) {
+      throw new Error(
+        `safetensors: tensor "${name}" data span ${byteLen} B does not match shape [${meta.shape.join(", ")}]`
+      );
+    }
+    if (dataStart + end > buf.byteLength) {
+      throw new Error(`safetensors: tensor "${name}" extends past the end of the buffer`);
+    }
+    const absStart = buf.byteOffset + dataStart + begin;
+    let data;
+    if (absStart % 4 === 0) {
+      data = new Float32Array(buf.buffer, absStart, elems);
+    } else {
+      const copy = new Uint8Array(byteLen);
+      copy.set(buf.subarray(dataStart + begin, dataStart + end));
+      data = new Float32Array(copy.buffer);
+    }
+    out.set(name, { dtype: meta.dtype, shape: meta.shape, data });
+  }
+  if (unsupported.length > 0) {
+    throw new Error(`safetensors: only F32 tensors are supported; found ${unsupported.join(", ")}`);
+  }
+  return out;
+}
+
+// ../core/src/embed/tokenizer.ts
+function loadWordPieceTokenizer(tokenizerJson) {
+  const tj = tokenizerJson;
+  const model = tj?.model;
+  if (model?.type !== "WordPiece" || !model.vocab) {
+    throw new Error(
+      `tokenizer: unsupported model type "${model?.type ?? "missing"}" (only WordPiece is implemented)`
+    );
+  }
+  const vocab = new Map(Object.entries(model.vocab));
+  const unkToken = model.unk_token ?? "[UNK]";
+  const unkId = vocab.get(unkToken);
+  if (unkId === void 0) {
+    throw new Error(`tokenizer: unk_token "${unkToken}" is not in the vocab`);
+  }
+  const prefix = model.continuing_subword_prefix ?? "##";
+  const maxChars = model.max_input_chars_per_word ?? 100;
+  const norm = tj.normalizer ?? {};
+  const cleanText = norm.clean_text ?? true;
+  const handleCjk = norm.handle_chinese_chars ?? true;
+  const lowercase = norm.lowercase ?? true;
+  const stripAccents = norm.strip_accents ?? lowercase;
+  const specialIds = new Set(
+    (tj.added_tokens ?? []).filter((t) => t.special).map((t) => t.id)
+  );
+  function normalize(text) {
+    let out = cleanText ? doCleanText(text) : text;
+    if (handleCjk) out = padCjkChars(out);
+    if (stripAccents) out = out.normalize("NFD").replace(new RegExp("\\p{Mn}", "gu"), "");
+    if (lowercase) out = out.toLowerCase();
+    return out;
+  }
+  function wordPiece(word) {
+    const chars = [...word];
+    if (chars.length > maxChars) return [unkId];
+    const ids = [];
+    let start = 0;
+    while (start < chars.length) {
+      let end = chars.length;
+      let id;
+      while (start < end) {
+        const piece = (start > 0 ? prefix : "") + chars.slice(start, end).join("");
+        const found = vocab.get(piece);
+        if (found !== void 0) {
+          id = found;
+          break;
+        }
+        end--;
+      }
+      if (id === void 0) return [unkId];
+      ids.push(id);
+      start = end;
+    }
+    return ids;
+  }
+  return {
+    vocabSize: vocab.size,
+    unkId,
+    specialIds,
+    encode(text) {
+      const ids = [];
+      for (const word of preTokenize(normalize(text))) {
+        for (const id of wordPiece(word)) ids.push(id);
+      }
+      return ids;
+    }
+  };
+}
+function preTokenize(text) {
+  const words = [];
+  let cur = "";
+  for (const ch of text) {
+    const cp = ch.codePointAt(0);
+    if (isWhitespace(ch, cp)) {
+      if (cur) {
+        words.push(cur);
+        cur = "";
+      }
+    } else if (isPunctuation(ch, cp)) {
+      if (cur) {
+        words.push(cur);
+        cur = "";
+      }
+      words.push(ch);
+    } else {
+      cur += ch;
+    }
+  }
+  if (cur) words.push(cur);
+  return words;
+}
+function doCleanText(text) {
+  let out = "";
+  for (const ch of text) {
+    const cp = ch.codePointAt(0);
+    if (cp === 0 || cp === 65533 || isControl(ch, cp)) continue;
+    out += isWhitespace(ch, cp) ? " " : ch;
+  }
+  return out;
+}
+function padCjkChars(text) {
+  let out = "";
+  for (const ch of text) {
+    out += isCjk(ch.codePointAt(0)) ? ` ${ch} ` : ch;
+  }
+  return out;
+}
+function isWhitespace(ch, cp) {
+  if (cp === 32 || cp === 9 || cp === 10 || cp === 13) return true;
+  return new RegExp("\\p{Zs}", "u").test(ch);
+}
+function isControl(ch, cp) {
+  if (cp === 9 || cp === 10 || cp === 13) return false;
+  return new RegExp("\\p{Cc}|\\p{Cf}", "u").test(ch);
+}
+function isPunctuation(ch, cp) {
+  if (cp >= 33 && cp <= 47 || cp >= 58 && cp <= 64 || cp >= 91 && cp <= 96 || cp >= 123 && cp <= 126) {
+    return true;
+  }
+  return new RegExp("\\p{P}", "u").test(ch);
+}
+function isCjk(cp) {
+  return cp >= 19968 && cp <= 40959 || cp >= 13312 && cp <= 19903 || cp >= 131072 && cp <= 173791 || cp >= 173824 && cp <= 177983 || cp >= 177984 && cp <= 178207 || cp >= 178208 && cp <= 183983 || cp >= 63744 && cp <= 64255 || cp >= 194560 && cp <= 195103;
+}
+
+// ../core/src/embed/model2vec.ts
+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"))
+  ]);
+  const config = JSON.parse(configRaw);
+  const tokenizer = loadWordPieceTokenizer(JSON.parse(tokenizerRaw));
+  const tensors = readSafetensors(weights);
+  const tensor = tensors.get(TENSOR_NAME) ?? (tensors.size === 1 ? [...tensors.values()][0] : void 0);
+  if (!tensor) {
+    throw new Error(
+      `model2vec: no "${TENSOR_NAME}" tensor in ${modelDir}; found: ${[...tensors.keys()].join(", ")}`
+    );
+  }
+  if (tensor.shape.length !== 2) {
+    throw new Error(`model2vec: expected a 2-D embedding matrix, got [${tensor.shape.join(", ")}]`);
+  }
+  const [rows, dim] = tensor.shape;
+  if (rows !== tokenizer.vocabSize) {
+    throw new Error(
+      `model2vec: embedding rows (${rows}) do not match tokenizer vocab size (${tokenizer.vocabSize})`
+    );
+  }
+  if (config.hidden_dim !== void 0 && config.hidden_dim !== dim) {
+    throw new Error(
+      `model2vec: config hidden_dim ${config.hidden_dim} does not match tensor dim ${dim}`
+    );
+  }
+  const table = tensor.data;
+  return {
+    id: basename4(modelDir),
+    dim,
+    embed(text) {
+      const out = new Float32Array(dim);
+      let pooled = 0;
+      for (const id of tokenizer.encode(text)) {
+        if (tokenizer.specialIds.has(id) && id !== tokenizer.unkId) continue;
+        const base = id * dim;
+        for (let j = 0; j < dim; j++) {
+          out[j] = out[j] + table[base + j];
+        }
+        pooled++;
+      }
+      if (pooled === 0) return out;
+      let sumSquares = 0;
+      for (let j = 0; j < dim; j++) {
+        const mean = out[j] / pooled;
+        out[j] = mean;
+        sumSquares += mean * mean;
+      }
+      const norm = Math.sqrt(sumSquares);
+      if (norm > 0) {
+        for (let j = 0; j < dim; j++) out[j] = out[j] / norm;
+      }
+      return out;
+    }
+  };
+}
+
+// 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";
+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`) };
+}
+async function loadCache(paths, modelId, dim) {
+  try {
+    const manifest = JSON.parse(await readFile15(paths.manifest, "utf8"));
+    if (manifest.version !== CACHE_VERSION || manifest.modelId !== modelId || manifest.dim !== dim) {
+      return void 0;
+    }
+    const buf = await readFile15(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;
+    const aligned = new Uint8Array(buf.byteLength);
+    aligned.set(buf);
+    const floats = new Float32Array(aligned.buffer, 0, totalChunks * dim);
+    const spans = new Uint32Array(aligned.buffer, vectorBytes, totalChunks * 2);
+    const vectors = /* @__PURE__ */ new Map();
+    const hashes = /* @__PURE__ */ new Map();
+    let chunkOffset = 0;
+    for (const e of manifest.entries) {
+      if (e.chunks <= 0) return void 0;
+      vectors.set(e.path, {
+        packed: floats.subarray(chunkOffset * dim, (chunkOffset + e.chunks) * dim),
+        spans: spans.subarray(chunkOffset * 2, (chunkOffset + e.chunks) * 2)
+      });
+      hashes.set(e.path, e.contentHash);
+      chunkOffset += e.chunks;
+    }
+    return { vectors, hashes };
+  } catch {
+    return void 0;
+  }
+}
+async function saveCache(paths, modelId, dim, notes2, hashes) {
+  const entries = [];
+  const kept = [];
+  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);
+    totalChunks += chunks;
+  }
+  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);
+  let floatOffset = 0;
+  let spanOffset = 0;
+  for (const note of kept) {
+    floats.set(note.packed, floatOffset);
+    spans.set(note.spans, spanOffset);
+    floatOffset += note.packed.length;
+    spanOffset += note.spans.length;
+  }
+  const manifest = { version: CACHE_VERSION, modelId, dim, entries };
+  await mkdir6(paths.dir, { recursive: true });
+  await atomicWriteBytes(paths.bin, bin);
+  await atomicWriteBytes(paths.manifest, new TextEncoder().encode(JSON.stringify(manifest)));
+}
+async function atomicWriteBytes(absPath, bytes) {
+  const tmpPath = `${absPath}.seekstone-cache-tmp`;
+  await writeFile3(tmpPath, bytes);
+  await rename4(tmpPath, absPath);
+}
+
+// src/semantic/store.ts
+var SemanticStore = class {
+  dim;
+  notes = /* @__PURE__ */ new Map();
+  chunks = 0;
+  constructor(dim) {
+    if (!Number.isInteger(dim) || dim <= 0) {
+      throw new Error(`semantic store: invalid dim ${dim}`);
+    }
+    this.dim = dim;
+  }
+  /** Total chunk vectors across all notes. */
+  get chunkCount() {
+    return this.chunks;
+  }
+  get noteCount() {
+    return this.notes.size;
+  }
+  /** Replace (or insert) a note's packed chunk vectors and spans. */
+  setNote(path2, packed, spans) {
+    if (packed.length === 0 || packed.length % this.dim !== 0) {
+      throw new Error(
+        `semantic store: packed length ${packed.length} is not a positive multiple of dim ${this.dim} (${path2})`
+      );
+    }
+    const n = packed.length / this.dim;
+    if (spans.length !== n * 2) {
+      throw new Error(
+        `semantic store: spans length ${spans.length} does not match ${n} chunks (${path2})`
+      );
+    }
+    const prev = this.notes.get(path2);
+    if (prev) this.chunks -= prev.packed.length / this.dim;
+    this.notes.set(path2, { packed, spans });
+    this.chunks += n;
+  }
+  removeNote(path2) {
+    const prev = this.notes.get(path2);
+    if (!prev) return;
+    this.chunks -= prev.packed.length / this.dim;
+    this.notes.delete(path2);
+  }
+  getNote(path2) {
+    return this.notes.get(path2);
+  }
+  /** Iterate (path, note vectors) — cache serialization uses this. */
+  entries() {
+    return this.notes.entries();
+  }
+  /** Top `k` notes by max-pooled chunk cosine, ties broken path-ascending. */
+  topNotes(query, k) {
+    if (query.length !== this.dim) {
+      throw new Error(`semantic store: query dim ${query.length} does not match ${this.dim}`);
+    }
+    const dim = this.dim;
+    const hits = [];
+    for (const [path2, { packed, spans }] of this.notes) {
+      let best = Number.NEGATIVE_INFINITY;
+      let bestChunk = 0;
+      const n = packed.length / dim;
+      for (let c = 0; c < n; c++) {
+        const base = c * dim;
+        let score = 0;
+        for (let j = 0; j < dim; j++) {
+          score += packed[base + j] * query[j];
+        }
+        if (score > best) {
+          best = score;
+          bestChunk = c;
+        }
+      }
+      hits.push({
+        path: path2,
+        score: best,
+        chunkIndex: bestChunk,
+        start: spans[bestChunk * 2],
+        end: spans[bestChunk * 2 + 1]
+      });
+    }
+    return hits.sort((a, b) => b.score - a.score || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)).slice(0, Math.max(0, k));
+  }
+};
+
+// src/semantic/state.ts
+var Semantic = class _Semantic {
+  embedder;
+  store;
+  progress;
+  ctx;
+  paths;
+  log;
+  debounceMs;
+  saveDebounceMs;
+  yieldEvery;
+  hashes = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  saveTimer;
+  stopped = false;
+  constructor(embedder, ctx2, cfg, deps) {
+    this.embedder = embedder;
+    this.store = new SemanticStore(embedder.dim);
+    this.ctx = ctx2;
+    this.paths = cachePathsFor(cfg.cacheDir, ctx2.vaultRoot, embedder.id);
+    this.log = deps.log;
+    this.debounceMs = deps.debounceMs ?? 300;
+    this.saveDebounceMs = deps.saveDebounceMs ?? 5e3;
+    this.yieldEvery = deps.yieldEvery ?? 8;
+    this.progress = { state: "building", done: 0, total: ctx2.notes.size };
+  }
+  /**
+   * Load the model and kick off the background index build. Rejects with an
+   * actionable message when the model files are missing — the user enabled
+   * the feature explicitly, so a broken setup should fail loudly at boot.
+   */
+  static async start(ctx2, cfg, deps = {}) {
+    let embedder;
+    try {
+      embedder = await (deps.loadModel ?? loadModel2Vec)(cfg.modelDir);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `semantic search: could not load the embedding model from ${cfg.modelDir} \u2014 run \`npx -y seekstone fetch-model\` to download it, or point SEEKSTONE_MODEL_PATH at a Model2Vec model directory (${reason})`
+      );
+    }
+    const semantic = new _Semantic(embedder, ctx2, cfg, deps);
+    void semantic.build();
+    return semantic;
+  }
+  /** Resolves when the initial build has finished (tests and progress checks). */
+  buildDone = Promise.resolve();
+  ready() {
+    return this.buildDone;
+  }
+  build() {
+    this.buildDone = this.buildInner().catch((err) => {
+      this.log?.error("semantic build failed", {
+        error: err instanceof Error ? err.message : String(err)
+      });
+    });
+    return this.buildDone;
+  }
+  async buildInner() {
+    const t0 = performance.now();
+    const cached = await loadCache(this.paths, this.embedder.id, this.embedder.dim);
+    const ids = [...this.ctx.notes.keys()];
+    this.progress = { state: "building", done: 0, total: ids.length };
+    let reused = 0;
+    let sinceYield = 0;
+    for (const id of ids) {
+      if (this.stopped) return;
+      if (!this.hashes.has(id)) {
+        const note = this.ctx.notes.get(id);
+        if (note) {
+          const current = contentHash(note.raw);
+          const cachedVecs = cached?.hashes.get(id) === current ? cached.vectors.get(id) : void 0;
+          if (cachedVecs !== void 0 && cachedVecs.packed.length > 0) {
+            this.store.setNote(id, cachedVecs.packed, cachedVecs.spans);
+            reused++;
+          } else {
+            const { packed, spans } = this.embedNote(note);
+            this.store.setNote(id, packed, spans);
+            if (++sinceYield >= this.yieldEvery) {
+              sinceYield = 0;
+              await new Promise((r) => setImmediate(r));
+            }
+          }
+          this.hashes.set(id, current);
+        }
+      }
+      if (this.progress.state === "building") this.progress.done++;
+    }
+    this.progress = { state: "ready" };
+    this.log?.info("semantic index ready", {
+      notes: this.store.noteCount,
+      chunks: this.store.chunkCount,
+      reusedFromCache: reused,
+      buildMs: Math.round(performance.now() - t0)
+    });
+    if (reused < this.store.noteCount) await this.save();
+  }
+  embedNote(note) {
+    const chunks = chunkNote(note.title, note.body);
+    const dim = this.embedder.dim;
+    const packed = new Float32Array(chunks.length * dim);
+    const spans = new Uint32Array(chunks.length * 2);
+    for (let i = 0; i < chunks.length; i++) {
+      const chunk = chunks[i];
+      packed.set(this.embedder.embed(chunk.text), i * dim);
+      spans[i * 2] = chunk.start;
+      spans[i * 2 + 1] = chunk.end;
+    }
+    return { packed, spans };
+  }
+  embedQuery(query) {
+    return this.embedder.embed(query);
+  }
+  /** Watcher hook: a note was added or changed (ctx.notes is already fresh). */
+  noteChanged(path2) {
+    if (this.stopped) return;
+    const existing = this.pending.get(path2);
+    if (existing) clearTimeout(existing);
+    const timer = setTimeout(() => {
+      this.pending.delete(path2);
+      this.reembed(path2);
+    }, this.debounceMs);
+    timer.unref?.();
+    this.pending.set(path2, timer);
+  }
+  /** Watcher hook: a note was deleted. */
+  noteRemoved(path2) {
+    const existing = this.pending.get(path2);
+    if (existing) {
+      clearTimeout(existing);
+      this.pending.delete(path2);
+    }
+    if (this.hashes.has(path2) || this.store.getNote(path2)) {
+      this.store.removeNote(path2);
+      this.hashes.delete(path2);
+      this.scheduleSave();
+    }
+  }
+  reembed(path2) {
+    const note = this.ctx.notes.get(path2);
+    if (!note) return;
+    const current = contentHash(note.raw);
+    const prior = this.hashes.get(path2);
+    if (prior === current) return;
+    const { packed, spans } = this.embedNote(note);
+    this.store.setNote(path2, packed, spans);
+    this.hashes.set(path2, current);
+    this.log?.debug("semantic re-embed", { path: path2 });
+    this.scheduleSave();
+  }
+  scheduleSave() {
+    if (this.saveTimer) clearTimeout(this.saveTimer);
+    this.saveTimer = setTimeout(() => {
+      this.saveTimer = void 0;
+      void this.save();
+    }, this.saveDebounceMs);
+    this.saveTimer.unref?.();
+  }
+  async save() {
+    if (this.stopped) return;
+    try {
+      await saveCache(
+        this.paths,
+        this.embedder.id,
+        this.embedder.dim,
+        this.store.entries(),
+        this.hashes
+      );
+      this.log?.debug("semantic cache saved", { notes: this.store.noteCount });
+    } catch (err) {
+      this.log?.warn("semantic cache save failed", {
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  /** Tear down timers (tests; the process otherwise runs for the session). */
+  stop() {
+    this.stopped = true;
+    for (const timer of this.pending.values()) clearTimeout(timer);
+    this.pending.clear();
+    if (this.saveTimer) clearTimeout(this.saveTimer);
+    this.saveTimer = void 0;
+  }
+};
+
 // src/tool-list.ts
 var READ_ONLY_ANNOTATIONS = {
   readOnlyHint: true,
@@ -2799,11 +3566,16 @@ 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.",
+    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.',
     inputSchema: {
       type: "object",
       properties: {
         query: { type: "string", description: "Search query." },
+        mode: {
+          type: "string",
+          enum: ["lexical", "semantic", "hybrid"],
+          description: "lexical = keyword search (default). semantic = meaning-based search (requires SEEKSTONE_SEMANTIC=1). hybrid = exact-title lookups go lexical, everything else semantic."
+        },
         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." }
@@ -3288,8 +4060,8 @@ function visibleTools(policy2) {
 
 // src/watcher.ts
 import { realpathSync } from "fs";
-import { readFile as readFile14 } from "fs/promises";
-import { join as join7, relative as relative2, sep as sep3 } from "path";
+import { readFile as readFile16 } from "fs/promises";
+import { join as join9, 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";
@@ -3301,10 +4073,11 @@ function startWatcher(ctx2, log2, opts) {
   const toRel = (abs) => relative2(vaultRoot2, abs).split(sep3).join("/");
   async function upsert(relPath, op) {
     try {
-      const raw = await readFile14(join7(vaultRoot2, relPath), "utf8");
+      const raw = await readFile16(join9(vaultRoot2, relPath), "utf8");
       removeNoteBacklinks(ctx2, relPath);
       upsertDoc(ctx2, buildDoc(relPath, raw));
       addNoteBacklinks(ctx2, relPath, raw);
+      ctx2.semantic?.noteChanged(relPath);
       log2?.debug("index updated", { path: relPath, op });
     } catch {
     }
@@ -3314,6 +4087,7 @@ function startWatcher(ctx2, log2, opts) {
       removeNoteBacklinks(ctx2, relPath);
       ctx2.index.discard(relPath);
       ctx2.notes.delete(relPath);
+      ctx2.semantic?.noteRemoved(relPath);
       log2?.debug("index removed", { path: relPath, op: "delete" });
     }
   }
@@ -3353,7 +4127,7 @@ function startWatcher(ctx2, log2, opts) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.14.0" : "0.0.0-dev";
+var VERSION = true ? "0.15.0" : "0.0.0-dev";
 var intent = parseCliIntent(process.argv.slice(2));
 if (intent === "version") {
   process.stdout.write(`${VERSION}
@@ -3381,6 +4155,14 @@ if (intent === "init") {
 `);
   process.exit(result.exitCode);
 }
+if (intent === "fetch-model") {
+  const { runFetchModel } = await import("./fetch-model-7TGOJMZL.js");
+  const { homedir: homedir2 } = await import("os");
+  const result = await runFetchModel({ env: process.env, homedir: homedir2() });
+  process.stdout.write(`${result.output.join("\n")}
+`);
+  process.exit(result.exitCode);
+}
 var log = createLogger();
 installProcessGuards(log);
 var rawVaultRoot = process.env.SEEKSTONE_VAULT;
@@ -3396,6 +4178,20 @@ log.info("building index", { vault: vaultRoot });
 var { index, notes, backlinks, buildMs } = await buildIndex(vaultRoot);
 log.info("index ready", { notes: notes.size, buildMs });
 var ctx = { vaultRoot, index, notes, backlinks, policy };
+var semanticCfg = resolveSemanticConfig(process.env, homedir());
+if (semanticCfg) {
+  try {
+    ctx.semantic = await Semantic.start(ctx, semanticCfg, { log });
+    log.info("semantic search enabled", {
+      model: ctx.semantic.embedder.id,
+      dim: ctx.semantic.embedder.dim,
+      notes: notes.size
+    });
+  } catch (err) {
+    log.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
 var watcher = startWatcher(ctx, log);
 process.on("exit", () => void watcher.stop());
 var server = new Server({ name: "seekstone", version: VERSION }, { capabilities: { tools: {} } });