march-cli 0.1.0

package/src/memory/markdown/markdown-recall.mjs

@@ -0,0 +1,28 @@
+import { expandTags, normalizeText } from "./markdown-format.mjs";
+
+export function formatRecallHints(source, hints = []) {
+  if (!hints.length) return "";
+  const lines = [`[memory_hint source="${source}"]`];
+  for (const hint of hints) {
+    lines.push(`- ${hint.id} | ${hint.name} | ${hint.description}`);
+  }
+  return lines.join("\n");
+}
+
+export function scoreEntry(entry, terms, currentProject) {
+  const expanded = expandTags(entry.tags);
+  let score = 0;
+  for (const term of terms) {
+    if (entry.tags.map(normalizeText).includes(term)) score += 10;
+    else if (expanded.includes(term)) score += 5;
+  }
+  if (currentProject) {
+    const projectTag = normalizeText(`project/${currentProject}`);
+    if (entry.tags.map(normalizeText).includes(projectTag)) score += 2;
+  }
+  return score;
+}
+
+export function toHint(entry) {
+  return { id: entry.id, name: entry.name, description: entry.description };
+}

package/src/memory/markdown/ripgrep.mjs

@@ -0,0 +1,16 @@
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+export function resolveBundledRipgrepPath({ platform = process.platform, arch = process.env.npm_config_arch || process.arch, requireResolve = require.resolve } = {}) {
+  const binaryName = platform === "win32" ? "rg.exe" : "rg";
+  try {
+    return requireResolve(`@vscode/ripgrep-${platform}-${arch}/bin/${binaryName}`);
+  } catch {
+    return null;
+  }
+}
+
+export function resolveRipgrepCommand(options = {}) {
+  return resolveBundledRipgrepPath(options) ?? "rg";
+}

package/src/memory/markdown/sqlite-index.mjs

@@ -0,0 +1,87 @@
+import { DatabaseSync } from "node:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS memory_index (
+  id TEXT PRIMARY KEY,
+  path TEXT NOT NULL UNIQUE,
+  name TEXT NOT NULL,
+  description TEXT NOT NULL,
+  tags_json TEXT NOT NULL,
+  status TEXT NOT NULL,
+  created_at TEXT,
+  updated_at TEXT,
+  mtime_ms REAL NOT NULL,
+  size INTEGER NOT NULL
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS memory_tags_fts USING fts5(
+  id UNINDEXED,
+  tags_text,
+  tokenize = 'unicode61'
+);
+`;
+
+export function openMarkdownMemoryIndex(path) {
+  mkdirSync(dirname(path), { recursive: true });
+  const db = new DatabaseSync(path);
+  db.exec("PRAGMA busy_timeout = 5000");
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec(SCHEMA);
+  return db;
+}
+
+export function clearMarkdownMemoryIndex(db) {
+  db.exec("DELETE FROM memory_index");
+  db.exec("DELETE FROM memory_tags_fts");
+}
+
+export function loadMarkdownMemoryIndex(db) {
+  const rows = db.prepare("SELECT * FROM memory_index").all();
+  const entries = new Map();
+  const pathStats = new Map();
+  for (const row of rows) {
+    const entry = rowToEntry(row);
+    entries.set(entry.id, entry);
+    pathStats.set(entry.path, { mtimeMs: entry.mtimeMs, size: entry.size });
+  }
+  return { entries, pathStats };
+}
+
+export function replaceMarkdownMemoryIndex(db, entries, expandTags) {
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    clearMarkdownMemoryIndex(db);
+    const insertMeta = db.prepare(
+      "INSERT INTO memory_index (id, path, name, description, tags_json, status, created_at, updated_at, mtime_ms, size) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+    );
+    const insertFts = db.prepare("INSERT INTO memory_tags_fts (id, tags_text) VALUES (?, ?)");
+    for (const entry of entries.values()) {
+      insertMeta.run(entry.id, entry.path, entry.name, entry.description, JSON.stringify(entry.tags), entry.status, entry.createdAt, entry.updatedAt, entry.mtimeMs, entry.size);
+      insertFts.run(entry.id, expandTags(entry.tags).join(" "));
+    }
+    db.exec("COMMIT");
+  } catch (err) {
+    try { db.exec("ROLLBACK"); } catch {}
+    throw err;
+  }
+}
+
+export function queryMarkdownMemoryIndex(db, query) {
+  return db.prepare("SELECT id FROM memory_tags_fts WHERE tags_text MATCH ? LIMIT 50").all(query);
+}
+
+function rowToEntry(row) {
+  return {
+    id: String(row.id),
+    path: String(row.path),
+    name: String(row.name),
+    description: String(row.description),
+    tags: JSON.parse(row.tags_json || "[]"),
+    status: String(row.status),
+    createdAt: row.created_at ?? null,
+    updatedAt: row.updated_at ?? null,
+    mtimeMs: Number(row.mtime_ms),
+    size: Number(row.size),
+  };
+}

package/src/memory/markdown-store.mjs

@@ -0,0 +1,286 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import {
+  expandTags,
+  formatMemoryMarkdown,
+  generateMemoryId,
+  normalizeTags,
+  normalizeText,
+  parseMemoryMarkdown,
+  quoteFtsTerm,
+  slugify,
+  walkMarkdownFiles,
+} from "./markdown/markdown-format.mjs";
+import { formatRecallHints, scoreEntry, toHint } from "./markdown/markdown-recall.mjs";
+import { clearMarkdownMemoryIndex, loadMarkdownMemoryIndex, openMarkdownMemoryIndex, queryMarkdownMemoryIndex, replaceMarkdownMemoryIndex } from "./markdown/sqlite-index.mjs";
+import { resolveRipgrepCommand } from "./markdown/ripgrep.mjs";
+import { softDeleteMemoryFile } from "./markdown/markdown-delete.mjs";
+
+export { formatRecallHints } from "./markdown/markdown-recall.mjs";
+export { normalizeTags } from "./markdown/markdown-format.mjs";
+
+const DEFAULT_SCAN_INTERVAL_MS = 5000;
+
+export class MarkdownMemoryStore {
+  constructor({ root, now = () => new Date(), indexPath = null } = {}) {
+    if (!root) throw new Error("MarkdownMemoryStore requires a root path");
+    this.root = resolve(root);
+    this.now = now;
+    this.indexPath = indexPath ? resolve(indexPath) : join(this.root, ".march-memory-index.sqlite");
+    this.db = openMarkdownMemoryIndex(this.indexPath);
+    this.entries = new Map();
+    this.pathStats = new Map();
+    this.tagDictionary = new Set();
+    this.diagnostics = [];
+    this.lastScanAt = 0;
+    this.scanIntervalMs = DEFAULT_SCAN_INTERVAL_MS;
+    this.turnSeenMemoryIds = new Set();
+    this.scan();
+  }
+
+  scan({ force = false } = {}) {
+    mkdirSync(this.root, { recursive: true });
+    if (force) clearMarkdownMemoryIndex(this.db);
+    const cached = force ? { entries: new Map(), pathStats: new Map() } : loadMarkdownMemoryIndex(this.db);
+    const seenPaths = new Set();
+    const nextEntries = new Map(cached.entries);
+    const nextStats = new Map(cached.pathStats);
+    const diagnostics = [];
+
+    for (const path of walkMarkdownFiles(this.root)) {
+      seenPaths.add(path);
+      const stat = statSync(path);
+      const prev = this.pathStats.get(path);
+      if (!force && prev && prev.mtimeMs === stat.mtimeMs && prev.size === stat.size) continue;
+      try {
+        const parsed = parseMemoryMarkdown(readFileSync(path, "utf8"));
+        if (!parsed.frontmatter.id) {
+          diagnostics.push({ type: "warning", path, message: "Memory file is missing id" });
+          continue;
+        }
+        if (!parsed.frontmatter.description) {
+          diagnostics.push({ type: "warning", path, message: "Memory file is missing description; excluded from memory hint recall" });
+        }
+        const tags = normalizeTags(parsed.frontmatter.tags ?? []);
+        const entry = {
+          id: String(parsed.frontmatter.id),
+          path,
+          name: String(parsed.frontmatter.name ?? parsed.title ?? basename(path, extname(path))),
+          description: String(parsed.frontmatter.description ?? ""),
+          tags,
+          status: String(parsed.frontmatter.status ?? "active"),
+          createdAt: parsed.frontmatter.created_at ?? null,
+          updatedAt: parsed.frontmatter.updated_at ?? null,
+          mtimeMs: stat.mtimeMs,
+          size: stat.size,
+        };
+        const duplicate = [...nextEntries.values()].find((item) => item.id === entry.id && item.path !== path);
+        if (duplicate) {
+          diagnostics.push({ type: "error", path, message: `Duplicate memory id: ${entry.id} also in ${duplicate.path}` });
+          continue;
+        }
+        for (const [id, item] of nextEntries) {
+          if (item.path === path && id !== entry.id) nextEntries.delete(id);
+        }
+        nextEntries.set(entry.id, entry);
+        nextStats.set(path, { mtimeMs: stat.mtimeMs, size: stat.size });
+      } catch (err) {
+        diagnostics.push({ type: "error", path, message: `Failed to parse memory file: ${err.message}` });
+      }
+    }
+
+    for (const [id, entry] of nextEntries) {
+      if (!seenPaths.has(entry.path)) nextEntries.delete(id);
+    }
+    for (const path of nextStats.keys()) {
+      if (!seenPaths.has(path)) nextStats.delete(path);
+    }
+
+    this.entries = nextEntries;
+    this.pathStats = nextStats;
+    this.diagnostics = diagnostics;
+    this.#rebuildTagDictionary();
+    replaceMarkdownMemoryIndex(this.db, this.entries, expandTags);
+    this.lastScanAt = Date.now();
+    return { entries: this.entries.size, diagnostics };
+  }
+
+  ensureFresh() {
+    if (Date.now() - this.lastScanAt > this.scanIntervalMs) this.scan();
+  }
+
+  beginTurn() {
+    this.turnSeenMemoryIds = new Set();
+  }
+
+  endTurn() {
+    this.turnSeenMemoryIds = new Set();
+  }
+
+  close() {
+    this.db.close?.();
+  }
+
+  recallForUser(text, { limit = 3, currentProject = "", excludedIds = [] } = {}) {
+    const excluded = new Set([...excludedIds, ...this.turnSeenMemoryIds]);
+    const hints = this.#recall(text, { limit, excluded, currentProject });
+    for (const hint of hints) {
+      this.turnSeenMemoryIds.add(hint.id);
+    }
+    return hints;
+  }
+
+  recallForAssistant(text, { limit = 2, currentProject = "", excludedIds = [] } = {}) {
+    const excluded = new Set([...excludedIds, ...this.turnSeenMemoryIds]);
+    const hints = this.#recall(text, { limit, excluded, currentProject });
+    for (const hint of hints) this.turnSeenMemoryIds.add(hint.id);
+    return hints;
+  }
+
+  searchRipgrep(query, { limit = 20 } = {}) {
+    this.ensureFresh();
+    const trimmed = String(query ?? "").trim();
+    if (!trimmed) return [];
+    const max = Math.max(1, Number(limit) || 20);
+    const paths = this.#activeMemoryPaths();
+    if (paths.length === 0) return [];
+    const rg = spawnSync(resolveRipgrepCommand(), ["--line-number", "--context", "1", "--color", "never", trimmed, ...paths], {
+      encoding: "utf8",
+      timeout: 10000,
+      windowsHide: true,
+    });
+    if (rg.error || (rg.status !== 0 && !rg.stdout)) return this.#fallbackSearch(trimmed, max, paths);
+    return rg.stdout.split(/\r?\n/).filter(Boolean).slice(0, max).map((line) => ({ line }));
+  }
+
+  open(identifier) {
+    this.ensureFresh();
+    const raw = String(identifier ?? "").trim();
+    if (!raw) throw new Error("memory id or path is required");
+    const entry = this.entries.get(raw);
+    const path = entry ? entry.path : this.#resolveMemoryPath(raw);
+    if (!existsSync(path)) throw new Error(`memory not found: ${raw}`);
+    return { path, content: readFileSync(path, "utf8"), entry: entry ?? null };
+  }
+
+  save({ id = null, name = null, description = null, body = null, tags = null } = {}) {
+    this.ensureFresh();
+    const existing = id ? this.entries.get(String(id)) : null;
+    if (id && !existing) throw new Error(`memory not found: ${id}`);
+    const nextId = existing?.id ?? String(id ?? generateMemoryId());
+    const now = this.now().toISOString();
+    const nextTags = tags == null ? existing?.tags : normalizeTags(tags);
+    if (!existing && (!nextTags || nextTags.length === 0)) throw new Error("tags are required when creating a memory");
+    if (tags != null && nextTags.length === 0) throw new Error("tags must include at least one valid tag");
+    const nextName = name ?? existing?.name;
+    const nextDescription = description ?? existing?.description;
+    if (!nextName) throw new Error("name is required");
+    if (!nextDescription) throw new Error("description is required");
+    if (!existing && body == null) throw new Error("body is required");
+    const nextBody = body ?? (existing ? parseMemoryMarkdown(readFileSync(existing.path, "utf8")).body : "");
+    const nextPath = existing?.path ?? this.#newMemoryPath(now, nextName);
+    mkdirSync(dirname(nextPath), { recursive: true });
+    const content = formatMemoryMarkdown({
+      frontmatter: {
+        id: nextId,
+        name: nextName,
+        description: nextDescription,
+        tags: nextTags,
+        status: existing?.status ?? "active",
+        created_at: existing?.createdAt ?? now,
+        updated_at: now,
+      },
+      body: nextBody,
+    });
+    writeFileSync(nextPath, content, "utf8");
+    this.scan({ force: true });
+    return this.entries.get(nextId) ?? { id: nextId, path: nextPath, name: nextName, description: nextDescription, tags: nextTags };
+  }
+
+  delete(identifier) {
+    this.ensureFresh();
+    const raw = String(identifier ?? "").trim();
+    if (!raw) throw new Error("memory id or path is required");
+    const existing = this.entries.get(raw);
+    const path = existing ? existing.path : this.#resolveMemoryPath(raw);
+    const result = softDeleteMemoryFile({ path, entry: existing, now: this.now });
+    this.scan({ force: true });
+    return result;
+  }
+
+  #recall(text, { limit, excluded, currentProject }) {
+    this.ensureFresh();
+    const queryTerms = this.#extractKnownTagTerms(text);
+    if (queryTerms.length === 0) return [];
+    const query = queryTerms.map(quoteFtsTerm).join(" OR ");
+    let rows = [];
+    try {
+      rows = queryMarkdownMemoryIndex(this.db, query);
+    } catch {
+      return [];
+    }
+    const scored = [];
+    for (const row of rows) {
+      if (excluded.has(row.id)) continue;
+      const entry = this.entries.get(row.id);
+      if (!entry || entry.status !== "active" || !entry.description) continue;
+      const score = scoreEntry(entry, queryTerms, currentProject);
+      if (score <= 0) continue;
+      scored.push({ score, entry });
+    }
+    scored.sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name));
+    return scored.slice(0, limit).map(({ entry }) => toHint(entry));
+  }
+
+  #extractKnownTagTerms(text) {
+    const normalized = normalizeText(text);
+    if (!normalized) return [];
+    const terms = [];
+    for (const term of this.tagDictionary) {
+      if (term.length < 2) continue;
+      if (normalized.includes(term)) terms.push(term);
+    }
+    return [...new Set(terms)].sort((a, b) => b.length - a.length).slice(0, 16);
+  }
+
+  #rebuildTagDictionary() {
+    this.tagDictionary = new Set();
+    for (const entry of this.entries.values()) {
+      for (const term of expandTags(entry.tags)) this.tagDictionary.add(normalizeText(term));
+    }
+  }
+
+  #newMemoryPath(isoDate, name) {
+    const date = isoDate.slice(0, 10);
+    const [year, month, day] = date.split("-");
+    const week = `week${Math.ceil(Number(day) / 7)}`;
+    return join(this.root, year, month, week, `${date}-${slugify(name)}.md`);
+  }
+
+  #resolveMemoryPath(raw) {
+    const path = isAbsolute(raw) ? raw : resolve(this.root, raw);
+    const rel = relative(this.root, path);
+    if (rel.startsWith("..") || isAbsolute(rel)) throw new Error(`memory path is outside root: ${raw}`);
+    return path;
+  }
+
+  #activeMemoryPaths() {
+    return [...this.entries.values()]
+      .filter((entry) => entry.status === "active")
+      .map((entry) => entry.path);
+  }
+
+  #fallbackSearch(query, limit, paths = this.#activeMemoryPaths()) {
+    const matches = [];
+    for (const path of paths) {
+      if (!existsSync(path)) continue;
+      const lines = readFileSync(path, "utf8").split(/\r?\n/);
+      for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes(query)) matches.push({ line: `${path}:${i + 1}:${lines[i]}` });
+        if (matches.length >= limit) return matches;
+      }
+    }
+    return matches;
+  }
+}

package/src/memory/markdown-tools.mjs

@@ -0,0 +1,103 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toolText } from "../agent/tool-result.mjs";
+
+export function createMarkdownMemoryTools(store) {
+  if (!store) return [];
+  return [
+    defineTool({
+      name: "memory_search",
+      label: "Memory Search",
+      description:
+        "Search the Markdown memory vault using ripgrep. This is literal text search over memory Markdown files, not semantic search and not March's internal tags-only memory hint recall. Use it when memory hints are insufficient or you need to find a memory by phrase, term, or detail.",
+      parameters: Type.Object({
+        query: Type.String({ description: "Ripgrep query to search in Markdown memory files" }),
+        limit: Type.Optional(Type.Number({ description: "Maximum matching lines to return. Default: 20" })),
+      }),
+      execute: async (_toolCallId, params) => {
+        const results = store.searchRipgrep(params.query, { limit: params.limit ?? 20 });
+        if (results.length === 0) return toolText(formatMemorySearchMiss(params.query));
+        return toolText(results.map((result) => result.line).join("\n"), { results });
+      },
+    }),
+
+    defineTool({
+      name: "memory_open",
+      label: "Memory Open",
+      description: "Open a Markdown memory by id or by path. Use this after memory hint or memory_search when you need the full memory body. To edit an existing memory, use the returned path with edit_file for targeted edits.",
+      parameters: Type.Object({
+        id: Type.Optional(Type.String({ description: "Memory id from memory hint, e.g. mem_..." })),
+        path: Type.Optional(Type.String({ description: "Path returned by memory_search" })),
+      }),
+      execute: async (_toolCallId, params) => {
+        try {
+          const identifier = params.id || params.path;
+          const opened = store.open(identifier);
+          return toolText(
+            `path: ${opened.path}\nUse edit_file with this path for targeted edits.\n\n---\n${opened.content}`,
+            opened,
+          );
+        } catch (err) {
+          return toolText(`Error: ${err.message}`, { error: true });
+        }
+      },
+    }),
+
+    defineTool({
+      name: "memory_save",
+      label: "Memory Save",
+      description:
+        "Create a Markdown memory or update whole fields on an existing memory. For targeted edits to an existing memory body or frontmatter, use memory_open to get the path, then edit_file. Before creating a new memory, merge related updates into an existing memory when they share the same topic or decision thread. New memories require name, description, body, and at least one tag because memory hints only use tags. When updating by id, omitted fields keep their existing values; passing tags replaces the full tag list.",
+      parameters: Type.Object({
+        id: Type.Optional(Type.String({ description: "Existing memory id to update. Omit to create a new memory." })),
+        name: Type.Optional(Type.String({ description: "Memory name. Required when creating." })),
+        description: Type.Optional(Type.String({ description: "Short natural-language summary shown in memory hint. Required when creating." })),
+        body: Type.Optional(Type.String({ description: "Markdown memory body. Required when creating." })),
+        tags: Type.Optional(Type.Array(Type.String(), { description: "Tags used for memory hint. Required and non-empty when creating; replaces tags when updating. Prefer stable retrieval keys: project name, technology, feature/domain, user/person, and decision topic. Use lowercase kebab-case when possible. Use shared tags to keep related facts discoverable and merge them into one memory when they belong to the same topic. Examples: ['march-cli', 'tooling', 'permissions'], ['memory', 'sqlite-index']." })),
+      }),
+      execute: async (_toolCallId, params) => {
+        try {
+          const entry = store.save(params);
+          return toolText(
+            `Saved ${entry.id}\npath: ${entry.path}\ntags: ${entry.tags.join(", ")}`,
+            { memory: entry },
+          );
+        } catch (err) {
+          return toolText(`Error: ${err.message}`, { error: true });
+        }
+      },
+    }),
+
+    defineTool({
+      name: "memory_delete",
+      label: "Memory Delete",
+      description: "Soft-delete a Markdown memory by id or path. This marks status as deleted so memory hint and memory_search exclude it; the file remains on disk for audit/recovery.",
+      parameters: Type.Object({
+        id: Type.Optional(Type.String({ description: "Memory id to delete, e.g. mem_..." })),
+        path: Type.Optional(Type.String({ description: "Memory file path to delete" })),
+      }),
+      execute: async (_toolCallId, params) => {
+        try {
+          const identifier = params.id || params.path;
+          const result = store.delete(identifier);
+          if (result.alreadyDeleted) return toolText(`Memory ${result.id} is already deleted.\npath: ${result.path}`, { memory: result });
+          return toolText(`Deleted ${result.id}\npath: ${result.path}`, { memory: result });
+        } catch (err) {
+          return toolText(`Error: ${err.message}`, { error: true });
+        }
+      },
+    }),
+  ];
+}
+
+function formatMemorySearchMiss(query) {
+  const text = String(query ?? "");
+  const lines = [
+    `No memory files matched "${text}".`,
+    "memory_search is literal ripgrep over Markdown files; it is not semantic search and does not use memory-hint hints.",
+  ];
+  if (/^mem_[a-z0-9_\-]+$/i.test(text.trim())) {
+    lines.push("This looks like a memory id. Use memory_open({ id }) to open it directly.");
+  }
+  return lines.join("\n");
+}

package/src/memory/search.mjs

@@ -0,0 +1,142 @@
+export class SearchIndexer {
+  constructor(db) {
+    this.db = db;
+    this.#ensureSchema();
+  }
+
+  #ensureSchema() {
+    this.db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS search_fts USING fts5(
+        node_uuid,
+        namespace,
+        content,
+        tokenize = 'porter unicode61'
+      );
+    `);
+  }
+
+  /**
+   * Index a memory's content for full-text search.
+   * Replaces any existing entry for the same (node_uuid, namespace).
+   */
+  index(nodeUuid, content, namespace = "") {
+    this.remove(nodeUuid, namespace);
+    this.db.prepare(
+      "INSERT INTO search_fts (node_uuid, namespace, content) VALUES (?, ?, ?)",
+    ).run(nodeUuid, namespace, content);
+  }
+
+  /**
+   * Remove a document from the FTS index.
+   */
+  remove(nodeUuid, namespace = "") {
+    this.db.prepare(
+      "DELETE FROM search_fts WHERE node_uuid = ? AND namespace = ?",
+    ).run(nodeUuid, namespace);
+  }
+
+  /**
+   * Full-text search with ranking.
+   * Returns matching node UUIDs, ranked by relevance.
+   */
+  search(query, { namespace = "", limit = 20, offset = 0 } = {}) {
+    // Sanitize FTS5 query: escape special chars, wrap in quotes for phrase matching
+    const sanitized = query.replace(/["*()]/g, "").trim();
+    if (!sanitized) return [];
+
+    const ftsQuery = sanitized.split(/\s+/).map(w => `"${w}"`).join(" OR ");
+
+    let sql;
+    let params;
+    if (namespace) {
+      sql = `
+        SELECT node_uuid, namespace, content,
+               rank AS score,
+               snippet(search_fts, 1, '<mark>', '</mark>', '...', 32) AS snippet
+        FROM search_fts
+        WHERE search_fts MATCH ? AND namespace = ?
+        ORDER BY rank
+        LIMIT ? OFFSET ?
+      `;
+      params = [ftsQuery, namespace, limit, offset];
+    } else {
+      sql = `
+        SELECT node_uuid, namespace, content,
+               rank AS score,
+               snippet(search_fts, 1, '<mark>', '</mark>', '...', 32) AS snippet
+        FROM search_fts
+        WHERE search_fts MATCH ?
+        ORDER BY rank
+        LIMIT ? OFFSET ?
+      `;
+      params = [ftsQuery, limit, offset];
+    }
+
+    return this.db.prepare(sql).all(...params);
+  }
+
+  /**
+   * Quick count of indexed documents.
+   */
+  count(namespace = "") {
+    if (namespace) {
+      return this.db.prepare("SELECT COUNT(*) AS cnt FROM search_fts WHERE namespace = ?").get(namespace).cnt;
+    }
+    return this.db.prepare("SELECT COUNT(*) AS cnt FROM search_fts").get().cnt;
+  }
+
+  /**
+   * Delete all entries for a namespace.
+   */
+  clearNamespace(namespace) {
+    const result = this.db.prepare("DELETE FROM search_fts WHERE namespace = ?").run(namespace);
+    return result.changes;
+  }
+
+  /**
+   * Rebuild the FTS index from the search_documents table.
+   */
+  rebuildFromDocuments() {
+    this.db.exec("DELETE FROM search_fts");
+    const docs = this.db.prepare("SELECT * FROM search_documents").all();
+    const insert = this.db.prepare(
+      "INSERT INTO search_fts (node_uuid, namespace, content) VALUES (?, ?, ?)",
+    );
+    for (const doc of docs) {
+      insert.run(doc.node_uuid, doc.namespace, doc.content);
+    }
+    return docs.length;
+  }
+
+  /**
+   * Suggest completions based on prefix matching.
+   */
+  suggest(prefix, { namespace = "", limit = 8 } = {}) {
+    const sanitized = prefix.replace(/[*"]/g, "").trim();
+    if (!sanitized || sanitized.length < 2) return [];
+
+    let sql;
+    let params;
+    if (namespace) {
+      sql = `
+        SELECT DISTINCT content
+        FROM search_fts
+        WHERE search_fts MATCH ? AND namespace = ?
+        ORDER BY rank
+        LIMIT ?
+      `;
+      params = [`"${sanitized}"*`, namespace, limit];
+    } else {
+      sql = `
+        SELECT DISTINCT content
+        FROM search_fts
+        WHERE search_fts MATCH ?
+        ORDER BY rank
+        LIMIT ?
+      `;
+      params = [`"${sanitized}"*`, limit];
+    }
+
+    return this.db.prepare(sql).all(...params).map(r => r.content);
+  }
+}