@llmnesia/mcp 0.2.11 → 0.2.13

package/README.md

@@ -160,6 +160,15 @@ the canonical conversation and active index have accepted it. Malformed input
 is kept under `inbox/quarantine/` for inspection. Older releases archived every
 successful payload and may also have left versioned indexes behind.
 
+Valid blank-text turns are retained with their message metadata. If an older
+importer quarantined a backup containing those turns, close connected MCP
+clients and run `llmnesia-mcp retry-quarantine`. The command validates each
+entire file before retrying, updates the active index, and moves successfully
+recovered originals into `inbox/recovered/` without deleting their contents.
+Files with unresolved malformed records remain quarantined. The warning clears
+on the next MCP read once no pending or quarantined files remain. This does not
+require rebuilding local history.
+
 No maintenance command is required. After an upgrade, the MCP service waits
 through a three-day compatibility window, then reclaims the historical files
 automatically while the service is ready and idle. Work is single-process,
@@ -187,6 +196,7 @@ Once registered, your MCP client gains eight tools over the corpus:
 | Tool | Purpose |
 | --- | --- |
 | `search_conversations` | Full-text search across every past conversation. Returns ranked matches with highlighted snippets. Supports `platform`, `title`, `date_from`/`date_to` filters and a `match_mode` (`any` / `all` / `phrase`) for when a wrong hit matters. |
+| `get_conversation_image` | Read a retained local raster image using the message and image index returned by `get_conversation`. No private provider URL fetching or OCR. |
 | `get_conversation` | Fetch the full transcript of one conversation by its id (the `id` field from search results). The response carries `contentFingerprint`, the current fingerprint of the returned transcript (see below). |
 | `list_conversations` | List conversations by chronology, including oldest-first for questions about the user's earliest chat. |
 | `list_recent` | List the most recently updated conversations with title, summary, and platform. |
@@ -214,7 +224,7 @@ items (`limit` can go lower):
   "items": [
     { "id": "claude:rust-borrow", "platform": "claude",
       "title": "Debugging a Rust borrow checker error",
-      "fingerprint": "fp1:9af3c0d7…" }
+      "fingerprint": "fp2:9af3c0d7…" }
   ],
   "nextCursor": "inv1.eyJzIjoi…"
 }
@@ -229,12 +239,32 @@ Cursors are opaque, they do not survive an MCP server restart, and an expired
 or unknown cursor returns a clear error telling the caller to begin a new
 scan.
 
-The fingerprint is `fp1:` followed by a SHA-256 hex digest. It covers exactly:
+Images are included in the `fp2` fingerprint. MCP 0.2.13 automatically rebuilds
+the derived index as format v8 on first use, recomputing every inventory
+fingerprint from the same canonical records used by retrieval. This repairs
+mixed `fp1`/`fp2` inventories left by earlier versions. The canonical transcripts
+are unchanged, and later opens reuse the rebuilt index. Stop all MCP clients
+before updating and restart them afterward; the first read can take longer
+while rebuilding. Clients starting together wait for the index to become ready.
+An interrupted initial rebuild is retried on the next open. No extension
+history rebuild or backup reimport is needed.
+
+Consumer migration: begin a new complete inventory scan without an old cursor.
+Replace the saved `fp1` baseline with the new `fp2` values and reverify those
+records. Different scheme prefixes are not comparable content revisions.
+Existing `fp2` digests retain their definition and values for unchanged content.
+Future incompatible fingerprint changes require a new scheme prefix, an index
+migration and a documented consumer migration before release.
+
+Local raster copies are bounded to 2 MiB per image and 8 MiB per captured conversation. Vault sync retains URL metadata only. Protected or expired images without a retained copy need recapture or a supported bundled export.
+
+The fingerprint is `fp2:` followed by a SHA-256 hex digest. It covers exactly:
 
 - the conversation title, and the user's local alias (`localTitle`) when set;
 - every message in `msgIndex` order: its index, role, stored `text`, and
-  `formattedText` when present (because `get_conversation` prefers it, a
-  backfill that adds it changes what a caller would receive).
+  `formattedText` when present;
+- image references, metadata and retained local bytes. Image-only changes are
+  visible to an inventory client even when transcript text is unchanged.
 
 It deliberately excludes every timestamp, including the provider's
 `updatedAt`: historical imports can retain old source dates, and a genuinely
@@ -243,8 +273,8 @@ state, account and model identifiers, summaries, and other derived fields are
 excluded too. An identical re-ingest therefore never changes the fingerprint,
 while an edited message or a rename always does, even when nothing else about
 the record moved. The fingerprint is stored in the derived search index
-(index format v5; opening an older index triggers a rebuild that computes
-fingerprints for the existing corpus), so a scan never decompresses a single
+(index format v8; opening an older index triggers a rebuild that computes
+`fp2` fingerprints for the existing corpus), so a scan never decompresses a single
 transcript.
 
 A periodic-processing loop:
@@ -256,9 +286,9 @@ A periodic-processing loop:
    be skipped.
 3. Call `get_conversation` only for the new or changed ids. Its response
    carries `contentFingerprint`, the fingerprint of the transcript it returns.
-   If that differs from the inventory entry, the conversation changed after
-   your snapshot was taken and the transcript you just fetched is the current
-   content.
+   Within the same scheme, a different digest means the conversation changed
+   after your snapshot was taken and the fetched transcript is current. A
+   different scheme prefix requires the baseline migration described above.
 
 ### Read-only mode (`LLMNESIA_READ_ONLY`)
 
@@ -322,6 +352,7 @@ llmnesia-mcp uninstall     # remove manifests, config, client entries
 llmnesia-mcp init          # create an empty corpus
 llmnesia-mcp ingest <…>    # ingest an NDJSON backup file
 llmnesia-mcp drain         # ingest everything in <corpus>/inbox
+llmnesia-mcp retry-quarantine # repair eligible files; retain original backups
 llmnesia-mcp watch         # ingest new inbox deltas live (Ctrl+C to stop)
 llmnesia-mcp stats         # corpus summary
 llmnesia-mcp compact --dry-run # exact read-only storage/savings report

package/dist/{chunk-ZYE6VY6A.js → chunk-GHKXNM7R.js}

@@ -38,7 +38,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/version.ts
-var VERSION = true ? "0.2.11" : "0.0.0-dev";
+var VERSION = true ? "0.2.13" : "0.0.0-dev";
 
 export {
   __require,

package/dist/{chunk-7ISC4REX.js → chunk-QIRYUQIU.js}

@@ -3,7 +3,45 @@ import { createRequire as __llmnesiaCreateRequire } from "node:module";
 const require = __llmnesiaCreateRequire(import.meta.url);
 import {
   VERSION
-} from "./chunk-ZYE6VY6A.js";
+} from "./chunk-GHKXNM7R.js";
+
+// src/images.ts
+var MAX_BYTES = 2 * 1024 * 1024;
+function decodeImage(value) {
+  if (typeof value !== "string" || value.length > Math.ceil(MAX_BYTES * 4 / 3) + 80) return null;
+  const match = /^data:(image\/(?:png|jpeg|webp|gif));base64,([A-Za-z0-9+/]+={0,2})$/.exec(value);
+  if (!match || match[2].length % 4 !== 0) return null;
+  const bytes = Buffer.from(match[2], "base64");
+  if (!bytes.length || bytes.length > MAX_BYTES || bytes.toString("base64") !== match[2]) return null;
+  const head = bytes.toString("latin1", 0, 12);
+  const valid = match[1] === "image/png" ? head.startsWith("\x89PNG\r\n\n") : match[1] === "image/jpeg" ? head.startsWith("\xFF\xD8\xFF") : match[1] === "image/gif" ? /^GIF8[79]a/.test(head) : head.startsWith("RIFF") && head.slice(8, 12) === "WEBP";
+  if (!valid) return null;
+  return { mimeType: match[1], data: match[2] };
+}
+function normalizeImages(value) {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, 12).flatMap((raw) => {
+    if (!raw || typeof raw !== "object") return [];
+    const row = raw;
+    const dataUrl = decodeImage(row.dataUrl) ? row.dataUrl : void 0;
+    let url = "";
+    try {
+      if (typeof row.url === "string" && row.url.length <= 8e3) {
+        const parsed = new URL(row.url);
+        if (["http:", "https:"].includes(parsed.protocol)) url = parsed.href;
+      }
+    } catch {
+    }
+    if (!url && !dataUrl) return [];
+    return [{
+      url,
+      ...dataUrl ? { dataUrl } : {},
+      ...typeof row.alt === "string" ? { alt: row.alt.slice(0, 500) } : {},
+      ...typeof row.width === "number" && row.width > 0 && row.width <= 2e4 ? { width: row.width } : {},
+      ...typeof row.height === "number" && row.height > 0 && row.height <= 2e4 ? { height: row.height } : {}
+    }];
+  });
+}
 
 // src/config.ts
 import { readFileSync } from "fs";
@@ -47,7 +85,7 @@ function expandHome(p) {
 import { join as join2 } from "path";
 import { readdir } from "fs/promises";
 import { createHash } from "crypto";
-var INDEX_FORMAT_VERSION = 7;
+var INDEX_FORMAT_VERSION = 8;
 function indexDbFilename(version) {
   return version === 1 ? "llmnesia.db" : `llmnesia-v${version}.db`;
 }
@@ -147,6 +185,31 @@ import { dirname, join as join3 } from "path";
 import { promisify } from "util";
 import { gzip as gzipCallback, gunzip as gunzipCallback, gunzipSync } from "zlib";
 
+// src/sourceHealth.ts
+function parseSourceHealth(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const row = value;
+  if (!["claude_code", "codex", "zcode"].includes(String(row.source))) return null;
+  if (row.connection !== "connected" && row.connection !== "disconnected") return null;
+  if (!["ok", "partial", "missing", "error", "unknown"].includes(String(row.state))) return null;
+  const time = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+  if (!time(row.observedAt) || !time(row.lastAttemptAt)) return null;
+  if (row.observedAt > Date.now() + 3e5 || row.lastAttemptAt > row.observedAt) return null;
+  if (row.lastSuccessfulSyncAt !== null && (!time(row.lastSuccessfulSyncAt) || row.lastSuccessfulSyncAt > row.observedAt)) return null;
+  if (row.lastCaptureAt !== null && (!time(row.lastCaptureAt) || row.lastCaptureAt > row.observedAt)) return null;
+  if (!time(row.failedSessions)) return null;
+  return {
+    source: row.source,
+    observedAt: row.observedAt,
+    connection: row.connection,
+    state: row.state,
+    lastAttemptAt: row.lastAttemptAt,
+    lastSuccessfulSyncAt: row.lastSuccessfulSyncAt,
+    lastCaptureAt: row.lastCaptureAt,
+    failedSessions: row.failedSessions
+  };
+}
+
 // src/serialize.ts
 function canonicalizeConversation(record) {
   return {
@@ -244,6 +307,8 @@ function canonicalMessageDoc(m) {
     role: m.role,
     text: m.text
   };
+  const images = normalizeImages(m.images);
+  if (images.length) out.images = images;
   assignIfDefined(out, "formattedText", m.formattedText);
   assignIfDefined(out, "model", m.model);
   out.createdAt = m.createdAt;
@@ -586,14 +651,46 @@ var Corpus = class {
     return { conversationCount, messageCount, byPlatform };
   }
   /** Refresh meta.json's conversationCount / lastIngestAt after an ingest run. */
-  async touchIngestMeta(receipt) {
+  async touchIngestMeta(receipt, sources = {}) {
     const { conversationCount } = await this.stats();
+    const previous = (await this.readMeta())?.sourceLastIngestAt ?? {};
+    const sourceLastIngestAt = { ...previous };
+    for (const [source, at] of Object.entries(sources)) {
+      sourceLastIngestAt[source] = Math.max(previous[source] ?? 0, at);
+    }
     await this.writeMeta({
       lastIngestAt: Date.now(),
       conversationCount,
+      sourceLastIngestAt,
       ...receipt ? { lastIngestReceipt: receipt } : {}
     });
   }
+  async readSourceHealth() {
+    try {
+      const rows = JSON.parse(await fs.readFile(join3(this.paths.root, "source-health-v1.json"), "utf8"));
+      return Array.isArray(rows) ? rows.flatMap((value) => {
+        const parsed = parseSourceHealth(value);
+        return parsed ? [parsed] : [];
+      }) : [];
+    } catch {
+      return [];
+    }
+  }
+  async recordSourceHealth(value) {
+    const row = parseSourceHealth(value);
+    if (!row) return false;
+    await this.enqueueWrite(async () => {
+      const current = new Map((await this.readSourceHealth()).map((entry) => [entry.source, entry]));
+      if ((current.get(row.source)?.observedAt ?? -1) >= row.observedAt) return;
+      current.set(row.source, row);
+      await writeFileAtomic(
+        join3(this.paths.root, "source-health-v1.json"),
+        `${JSON.stringify([...current.values()])}
+`
+      );
+    });
+    return true;
+  }
   enqueueWrite(fn) {
     const run = this.writeChain.then(fn, fn);
     this.writeChain = run.then(
@@ -787,7 +884,7 @@ async function upsertIndexedConversation(corpus, record, index) {
   }
   return result;
 }
-async function ingestFile(corpus, file, index) {
+async function ingestFile(corpus, file, index, options = {}) {
   const report = { ...EMPTY_REPORT };
   let current = null;
   let buffered = [];
@@ -796,7 +893,11 @@ async function ingestFile(corpus, file, index) {
       return;
     }
     const record = { conversation: current, messages: buffered };
-    const result = await upsertIndexedConversation(corpus, record, index);
+    const result = options.validateOnly ? { docId: current.docId, outcome: "skipped" } : await upsertIndexedConversation(corpus, record, index);
+    if (result.outcome !== "skipped") {
+      report.sourceLastIngestAt ??= {};
+      report.sourceLastIngestAt[record.conversation.platform] = Date.now();
+    }
     tally(report, result);
     report.conversations += 1;
     report.messages += buffered.length;
@@ -825,6 +926,12 @@ async function ingestFile(corpus, file, index) {
     if (type === "meta") {
       continue;
     }
+    if (type === "source_health") {
+      await flush();
+      const valid = options.validateOnly ? Boolean(parseSourceHealth(record.health)) : await corpus.recordSourceHealth(record.health);
+      if (!valid) report.malformedLines += 1;
+      continue;
+    }
     if (type === "conversation") {
       await flush();
       current = coerceConversation(record.conversation);
@@ -846,7 +953,9 @@ async function ingestFile(corpus, file, index) {
       } else {
         report.malformedLines += 1;
       }
+      continue;
     }
+    report.malformedLines += 1;
   }
   await flush();
   return report;
@@ -859,6 +968,30 @@ async function pendingInboxFiles(corpus) {
     throw error;
   }
 }
+async function retryQuarantine(corpus, index) {
+  await corpus.init();
+  const entries = (await fs2.readdir(corpus.paths.quarantineDir, { withFileTypes: true })).filter((entry) => entry.isFile() && isNdjson(entry.name)).map((entry) => entry.name).sort();
+  const result = { files: entries.length, recovered: 0, remaining: 0, failed: 0, archiveDir: null };
+  for (const name of entries) {
+    const src = join4(corpus.paths.quarantineDir, name);
+    try {
+      if ((await ingestFile(corpus, src, void 0, { validateOnly: true })).malformedLines > 0) continue;
+      const report = await ingestFile(corpus, src, index);
+      if (report.malformedLines > 0) continue;
+      if (!result.archiveDir) {
+        const recoveredDir = join4(corpus.paths.inboxDir, "recovered");
+        await fs2.mkdir(recoveredDir, { recursive: true, mode: 448 });
+        result.archiveDir = await fs2.mkdtemp(join4(recoveredDir, "quarantine-"));
+      }
+      await fs2.rename(src, join4(result.archiveDir, name));
+      result.recovered += 1;
+    } catch {
+      result.failed += 1;
+    }
+  }
+  result.remaining = (await fs2.readdir(corpus.paths.quarantineDir, { withFileTypes: true })).filter((entry) => entry.isFile()).length;
+  return result;
+}
 async function drainInbox(corpus, index, options = {}) {
   await corpus.init();
   const inbox = corpus.paths.inboxDir;
@@ -894,7 +1027,7 @@ async function drainInbox(corpus, index, options = {}) {
       }
     }
   }
-  if (total.files > 0) {
+  if (total.conversations > 0) {
     await corpus.touchIngestMeta({
       files: total.files,
       conversations: total.conversations,
@@ -902,7 +1035,7 @@ async function drainInbox(corpus, index, options = {}) {
       malformedLines: total.malformedLines,
       discarded: total.discarded,
       quarantined: total.quarantined
-    });
+    }, total.sourceLastIngestAt);
   }
   return total;
 }
@@ -947,12 +1080,12 @@ function coerceConversation(value) {
     return null;
   }
   const c = value;
-  if (typeof c.docId !== "string" || !c.docId) {
+  if (typeof c.docId !== "string" || !c.docId || typeof c.platform !== "string" || !c.platform || typeof c.title !== "string" || typeof c.url !== "string" || typeof c.createdAt !== "number" || !Number.isFinite(c.createdAt)) {
     return null;
   }
   const conversation = { ...c };
-  if (typeof conversation.updatedAt !== "number") {
-    conversation.updatedAt = typeof conversation.contentUpdatedAt === "number" ? conversation.contentUpdatedAt : 0;
+  if (typeof conversation.updatedAt !== "number" || !Number.isFinite(conversation.updatedAt)) {
+    conversation.updatedAt = typeof conversation.contentUpdatedAt === "number" && Number.isFinite(conversation.contentUpdatedAt) ? conversation.contentUpdatedAt : 0;
   }
   return conversation;
 }
@@ -961,11 +1094,12 @@ function coerceMessage(docId, value) {
     return null;
   }
   const m = value;
-  const text = typeof m.text === "string" ? m.text : "";
-  if (!text.trim()) {
-    return null;
-  }
-  const msgIndex = typeof m.msgIndex === "number" ? m.msgIndex : 0;
+  if (!Number.isSafeInteger(m.msgIndex) || m.msgIndex < 0) return null;
+  const formattedText = typeof m.formattedText === "string" ? m.formattedText : "";
+  const text = typeof m.text === "string" && m.text.trim() ? m.text : formattedText.trim() ? formattedText : typeof m.text === "string" ? m.text : "";
+  const images = normalizeImages(m.images);
+  if (typeof m.text !== "string" && !formattedText.trim() && !images.length) return null;
+  const msgIndex = m.msgIndex;
   const message = {
     // The backup line omits msgKey; reconstruct the extension's convention.
     msgKey: `${docId}:${msgIndex}`,
@@ -973,6 +1107,7 @@ function coerceMessage(docId, value) {
     msgIndex,
     role: coerceRole(m.role),
     text,
+    ...images.length ? { images } : {},
     createdAt: typeof m.createdAt === "number" ? m.createdAt : 0,
     updatedAt: typeof m.updatedAt === "number" ? m.updatedAt : 0,
     contentHash: typeof m.contentHash === "string" ? m.contentHash : ""
@@ -1003,6 +1138,10 @@ function tally(report, result) {
   }
 }
 function accumulate(total, report) {
+  for (const [source, at] of Object.entries(report.sourceLastIngestAt ?? {})) {
+    total.sourceLastIngestAt ??= {};
+    total.sourceLastIngestAt[source] = Math.max(total.sourceLastIngestAt[source] ?? 0, at);
+  }
   total.conversations += report.conversations;
   total.created += report.created;
   total.updated += report.updated;
@@ -1013,18 +1152,19 @@ function accumulate(total, report) {
 
 // src/fingerprint.ts
 import { createHash as createHash2 } from "crypto";
-var FINGERPRINT_SCHEME = "fp1";
+var FINGERPRINT_SCHEME = "fp2";
 function fingerprintConversation(record) {
   const conversation = record.conversation;
   const payload = {
-    v: 1,
+    v: 2,
     title: conversation.title,
     localTitle: conversation.localTitle ?? null,
     messages: [...record.messages].sort((a, b) => a.msgIndex - b.msgIndex).map((message) => ({
       i: message.msgIndex,
       r: message.role,
       t: message.text,
-      f: message.formattedText ?? null
+      f: message.formattedText ?? null,
+      images: message.images ?? []
     }))
   };
   const digest = createHash2("sha256").update(JSON.stringify(payload), "utf8").digest("hex");
@@ -1077,6 +1217,8 @@ var TITLE_ROW_INDEX = -1;
 var TITLE_ROLE = "title";
 var DEFAULT_LIMIT = 10;
 var SNIPPET_TOKENS = 12;
+var INDEX_OPEN_BUSY_TIMEOUT_MS = 5 * 6e4;
+var INDEX_OPEN_BUSY_RETRY_MS = 50;
 var META_SQL = `
 CREATE TABLE IF NOT EXISTS index_meta (
   key TEXT PRIMARY KEY,
@@ -1161,52 +1303,64 @@ var SearchIndex = class {
     this.corpus = corpus;
     hardenDbFile(dbPath);
     this.db = new (loadSqlite()).DatabaseSync(dbPath);
-    this.db.exec("PRAGMA journal_mode = WAL");
-    this.db.exec("PRAGMA foreign_keys = OFF");
-    this.db.exec(META_SQL);
-    this.staleOnOpen = this.getMeta("format_version") !== String(INDEX_FORMAT_VERSION);
-    if (this.staleOnOpen) {
-      this.db.exec(DROP_DERIVED_SQL);
-    }
-    this.db.exec(SCHEMA_SQL);
-    this.db.exec("PRAGMA temp_store = MEMORY");
-    this.db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS temp.snippet_fts USING fts5(
-      text, tokenize = 'porter unicode61'
-    )`);
-    this.setMeta("format_version", String(INDEX_FORMAT_VERSION));
-    this.stmts = {
-      selectFtsRows: this.db.prepare("SELECT rowid FROM message_rows WHERE docId = ?"),
-      deleteFts: this.db.prepare("DELETE FROM messages_fts WHERE rowid = ?"),
-      deleteMessageRows: this.db.prepare("DELETE FROM message_rows WHERE docId = ?"),
-      insertMessageRow: this.db.prepare(
-        "INSERT INTO message_rows (docId, msgIndex, role) VALUES (?, ?, ?) RETURNING rowid"
-      ),
-      insertFts: this.db.prepare("INSERT INTO messages_fts (rowid, text) VALUES (?, ?)"),
-      deleteConversation: this.db.prepare("DELETE FROM conversations WHERE docId = ?"),
-      insertConversation: this.db.prepare(
-        `INSERT INTO conversations
-           (docId, platform, title, url, createdAt, updatedAt, messageCount, preview, pinned, accountId, accountLabel, providerProject, providerWorkspace, models, fingerprint)
-         VALUES (@docId, @platform, @title, @url, @createdAt, @updatedAt, @messageCount, @preview, @pinned, @accountId, @accountLabel, @providerProject, @providerWorkspace, @models, @fingerprint)`
-      ),
-      deleteMemoryFts: this.db.prepare("DELETE FROM memories_fts WHERE memoryId = ?"),
-      insertMemoryFts: this.db.prepare(
-        "INSERT INTO memories_fts (memoryId, label, text) VALUES (?, ?, ?)"
-      ),
-      deleteMemory: this.db.prepare("DELETE FROM memories WHERE memoryId = ?"),
-      insertMemory: this.db.prepare(
-        `INSERT INTO memories
-           (memoryId, kind, label, text, source, pinned, enabled, createdAt, updatedAt)
-         VALUES (@memoryId, @kind, @label, @text, @source, @pinned, @enabled, @createdAt, @updatedAt)`
-      ),
-      clearSnippetFts: this.db.prepare("DELETE FROM temp.snippet_fts"),
-      insertSnippetFts: this.db.prepare("INSERT INTO temp.snippet_fts (text) VALUES (?)"),
-      renderSnippet: this.db.prepare(
-        `SELECT snippet(snippet_fts, 0, '[', ']', '\u2026', ${SNIPPET_TOKENS}) AS snippet
-         FROM temp.snippet_fts WHERE snippet_fts MATCH ?`
-      )
-    };
-    for (const statement of Object.values(this.stmts)) {
-      statement.setReadBigInts(true);
+    try {
+      this.db.exec("PRAGMA journal_mode = WAL");
+      this.db.exec("PRAGMA foreign_keys = OFF");
+      this.db.exec("BEGIN IMMEDIATE");
+      try {
+        this.db.exec(META_SQL);
+        this.staleOnOpen = this.getMeta("format_version") !== String(INDEX_FORMAT_VERSION);
+        if (this.staleOnOpen) {
+          this.db.exec(DROP_DERIVED_SQL);
+        }
+        this.db.exec(SCHEMA_SQL);
+        this.setMeta("format_version", String(INDEX_FORMAT_VERSION));
+        this.db.exec("COMMIT");
+      } catch (error) {
+        this.db.exec("ROLLBACK");
+        throw error;
+      }
+      this.db.exec("PRAGMA temp_store = MEMORY");
+      this.db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS temp.snippet_fts USING fts5(
+        text, tokenize = 'porter unicode61'
+      )`);
+      this.stmts = {
+        selectFtsRows: this.db.prepare("SELECT rowid FROM message_rows WHERE docId = ?"),
+        deleteFts: this.db.prepare("DELETE FROM messages_fts WHERE rowid = ?"),
+        deleteMessageRows: this.db.prepare("DELETE FROM message_rows WHERE docId = ?"),
+        insertMessageRow: this.db.prepare(
+          "INSERT INTO message_rows (docId, msgIndex, role) VALUES (?, ?, ?) RETURNING rowid"
+        ),
+        insertFts: this.db.prepare("INSERT INTO messages_fts (rowid, text) VALUES (?, ?)"),
+        deleteConversation: this.db.prepare("DELETE FROM conversations WHERE docId = ?"),
+        insertConversation: this.db.prepare(
+          `INSERT INTO conversations
+             (docId, platform, title, url, createdAt, updatedAt, messageCount, preview, pinned, accountId, accountLabel, providerProject, providerWorkspace, models, fingerprint)
+           VALUES (@docId, @platform, @title, @url, @createdAt, @updatedAt, @messageCount, @preview, @pinned, @accountId, @accountLabel, @providerProject, @providerWorkspace, @models, @fingerprint)`
+        ),
+        deleteMemoryFts: this.db.prepare("DELETE FROM memories_fts WHERE memoryId = ?"),
+        insertMemoryFts: this.db.prepare(
+          "INSERT INTO memories_fts (memoryId, label, text) VALUES (?, ?, ?)"
+        ),
+        deleteMemory: this.db.prepare("DELETE FROM memories WHERE memoryId = ?"),
+        insertMemory: this.db.prepare(
+          `INSERT INTO memories
+             (memoryId, kind, label, text, source, pinned, enabled, createdAt, updatedAt)
+           VALUES (@memoryId, @kind, @label, @text, @source, @pinned, @enabled, @createdAt, @updatedAt)`
+        ),
+        clearSnippetFts: this.db.prepare("DELETE FROM temp.snippet_fts"),
+        insertSnippetFts: this.db.prepare("INSERT INTO temp.snippet_fts (text) VALUES (?)"),
+        renderSnippet: this.db.prepare(
+          `SELECT snippet(snippet_fts, 0, '[', ']', '\u2026', ${SNIPPET_TOKENS}) AS snippet
+           FROM temp.snippet_fts WHERE snippet_fts MATCH ?`
+        )
+      };
+      for (const statement of Object.values(this.stmts)) {
+        statement.setReadBigInts(true);
+      }
+    } catch (error) {
+      this.db.close();
+      throw error;
     }
   }
   /** True when the stored format version was missing or stale — caller rebuilds. */
@@ -1218,6 +1372,10 @@ var SearchIndex = class {
     const row = this.db.prepare("SELECT COUNT(*) AS n FROM conversations").get();
     return row.n;
   }
+  sourceSummary() {
+    return this.db.prepare(`SELECT platform AS source, COUNT(*) AS conversationCount,
+      MAX(updatedAt) AS newestConversationAt FROM conversations GROUP BY platform`).all();
+  }
   /** Number of indexed memories. */
   countMemories() {
     const row = this.db.prepare("SELECT COUNT(*) AS n FROM memories").get();
@@ -1517,15 +1675,24 @@ var SearchIndex = class {
 };
 async function openSearchIndex(corpus, options = {}) {
   await corpus.init();
-  const index = new SearchIndex(corpus.paths.indexDbFile, corpus);
-  try {
-    if (options.autoBuild !== false && (index.needsRebuild() || index.count() === 0 && index.countMemories() === 0)) {
-      await index.rebuildFrom(corpus);
+  const deadline = Date.now() + (options.busyTimeoutMs ?? INDEX_OPEN_BUSY_TIMEOUT_MS);
+  for (; ; ) {
+    let index;
+    try {
+      index = new SearchIndex(corpus.paths.indexDbFile, corpus);
+      if (options.autoBuild !== false && (index.needsRebuild() || index.count() === 0 && index.countMemories() === 0)) {
+        await index.rebuildFrom(corpus);
+      }
+      return index;
+    } catch (error) {
+      index?.close();
+      const code = error?.errcode;
+      if (typeof code !== "number" || ![5, 6].includes(code & 255)) throw error;
+      if (Date.now() >= deadline) {
+        throw new Error("The local conversation index is busy. Wait for other MCP clients to finish updating it, then restart this client.", { cause: error });
+      }
+      await new Promise((resolve2) => setTimeout(resolve2, INDEX_OPEN_BUSY_RETRY_MS));
     }
-    return index;
-  } catch (error) {
-    index.close();
-    throw error;
   }
 }
 async function deleteIndexDb(dbFile) {
@@ -2254,6 +2421,7 @@ function describeOutcome(outcome) {
 }
 
 export {
+  decodeImage,
   readNativeHostViewerExtensionId,
   resolveCorpusDir,
   staleIndexFiles,
@@ -2261,6 +2429,7 @@ export {
   upsertIndexedConversation,
   ingestFile,
   pendingInboxFiles,
+  retryQuarantine,
   drainInbox,
   fingerprintConversation,
   SearchIndex,