@llmnesia/mcp 0.2.3 → 0.2.5

package/dist/{chunk-G42RV536.js → chunk-MTPXE734.js}

@@ -3,13 +3,13 @@ import { createRequire as __llmnesiaCreateRequire } from "node:module";
 const require = __llmnesiaCreateRequire(import.meta.url);
 import {
   VERSION
-} from "./chunk-6H2TI5IW.js";
+} from "./chunk-BDR4JVMF.js";
 
 // src/config.ts
 import { readFileSync } from "fs";
 import { homedir } from "os";
 import { join, resolve } from "path";
-var CORPUS_FORMAT_VERSION = 1;
+var CORPUS_FORMAT_VERSION = 2;
 function nativeHostConfigPath() {
   return join(homedir(), ".llmnesia", "config.json");
 }
@@ -39,7 +39,7 @@ function expandHome(p) {
 import { join as join2 } from "path";
 import { readdir } from "fs/promises";
 import { createHash } from "crypto";
-var INDEX_FORMAT_VERSION = 2;
+var INDEX_FORMAT_VERSION = 3;
 function indexDbFilename(version) {
   return version === 1 ? "llmnesia.db" : `llmnesia-v${version}.db`;
 }
@@ -63,12 +63,24 @@ var CorpusPaths = class {
   get metaFile() {
     return join2(this.root, "meta.json");
   }
+  /** Content-free state for automatic storage maintenance. */
+  get maintenanceStateFile() {
+    return join2(this.root, "maintenance-v1.json");
+  }
+  /** Cross-process lease preventing several MCP clients compacting together. */
+  get maintenanceLockFile() {
+    return join2(this.root, ".maintenance-v1.lock");
+  }
   get inboxDir() {
     return join2(this.root, "inbox");
   }
   get processedDir() {
     return join2(this.inboxDir, "processed");
   }
+  /** Input that was readable but not clean enough to discard automatically. */
+  get quarantineDir() {
+    return join2(this.inboxDir, "quarantine");
+  }
   get conversationsDir() {
     return join2(this.root, "conversations");
   }
@@ -87,6 +99,14 @@ var CorpusPaths = class {
   }
   /** Absolute path to the JSON file backing a given docId. */
   conversationFile(platform, docId) {
+    return this.compressedConversationFile(platform, docId);
+  }
+  /** Canonical v2 path. Compression is lossless and independently readable. */
+  compressedConversationFile(platform, docId) {
+    return join2(this.platformDir(platform), `${slugifyDocId(docId)}.json.gz`);
+  }
+  /** v1 path accepted until confirmed/resumable compaction migrates it. */
+  legacyConversationFile(platform, docId) {
     return join2(this.platformDir(platform), `${slugifyDocId(docId)}.json`);
   }
   /**
@@ -114,8 +134,10 @@ function safeSegment(value) {
 }
 
 // src/corpus.ts
-import { promises as fs } from "fs";
+import { promises as fs, readFileSync as readFileSync2 } from "fs";
 import { dirname, join as join3 } from "path";
+import { promisify } from "util";
+import { gzip as gzipCallback, gunzip as gunzipCallback, gunzipSync } from "zlib";
 
 // src/serialize.ts
 function canonicalizeConversation(record) {
@@ -212,6 +234,10 @@ function assignIfDefined(target, key, value) {
 // src/corpus.ts
 var DIR_MODE = 448;
 var FILE_MODE = 384;
+var gzip = promisify(gzipCallback);
+var gunzip = promisify(gunzipCallback);
+var MAINTENANCE_WRITE_WAIT_MS = 2e3;
+var MAINTENANCE_WRITE_POLL_MS = 50;
 var Corpus = class {
   paths;
   // Serialize writes within this process so concurrent upserts (inbox drain +
@@ -226,12 +252,14 @@ var Corpus = class {
     await fs.mkdir(this.paths.conversationsDir, { recursive: true, mode: DIR_MODE });
     await fs.mkdir(this.paths.memoriesDir, { recursive: true, mode: DIR_MODE });
     await fs.mkdir(this.paths.processedDir, { recursive: true, mode: DIR_MODE });
+    await fs.mkdir(this.paths.quarantineDir, { recursive: true, mode: DIR_MODE });
     await fs.mkdir(this.paths.indexDir, { recursive: true, mode: DIR_MODE });
     await hardenDir(this.paths.root);
     await hardenDir(this.paths.conversationsDir);
     await hardenDir(this.paths.memoriesDir);
     await hardenDir(this.paths.inboxDir);
     await hardenDir(this.paths.processedDir);
+    await hardenDir(this.paths.quarantineDir);
     await hardenDir(this.paths.indexDir);
     try {
       await fs.access(this.paths.metaFile);
@@ -273,10 +301,12 @@ var Corpus = class {
    */
   async upsert(record) {
     return this.enqueueWrite(async () => {
+      await waitForMaintenanceLease(this.paths.maintenanceLockFile);
       const canonical = canonicalizeConversation(record);
       const { conversation } = canonical;
-      const file = this.paths.conversationFile(conversation.platform, conversation.docId);
-      const existing = await readJsonIfExists(file);
+      const file = this.paths.compressedConversationFile(conversation.platform, conversation.docId);
+      const legacyFile = this.paths.legacyConversationFile(conversation.platform, conversation.docId);
+      const existing = await this.readBestConversation(conversation.platform, conversation.docId);
       if (existing) {
         const existingChangedAt = existing.conversation.corpusChangedAt ?? existing.conversation.updatedAt ?? 0;
         const incomingChangedAt = conversation.corpusChangedAt ?? conversation.updatedAt ?? 0;
@@ -286,8 +316,7 @@ var Corpus = class {
           return { docId: conversation.docId, outcome: "skipped" };
         }
       }
-      const serialized = `${JSON.stringify(canonical, null, 2)}
-`;
+      const serialized = serializeConversation(canonical);
       if (existing) {
         const existingSerialized = `${JSON.stringify(canonicalizeConversation(existing), null, 2)}
 `;
@@ -296,22 +325,39 @@ var Corpus = class {
         }
       }
       await fs.mkdir(dirname(file), { recursive: true, mode: DIR_MODE });
-      await writeFileAtomic(file, serialized);
+      await writeCompressedConversationAtomic(file, serialized);
+      await fs.rm(legacyFile, { force: true });
       return { docId: conversation.docId, outcome: existing ? "updated" : "created" };
     });
   }
   /** Read a conversation by docId, scanning platform dirs for the slug file. */
   async get(docId) {
-    const filename = `${slugifyDocId(docId)}.json`;
     for (const platform of await this.listPlatforms()) {
-      const candidate = join3(this.paths.platformDir(platform), filename);
-      const record = await readJsonIfExists(candidate);
+      const record = await this.readBestConversation(platform, docId);
       if (record && record.conversation.docId === docId) {
         return record;
       }
     }
     return null;
   }
+  /** Direct form used by search snippet hydration, avoiding a platform scan. */
+  async getFromPlatform(platform, docId) {
+    const record = await this.readBestConversation(platform, docId);
+    return record?.conversation.docId === docId ? record : null;
+  }
+  /**
+   * Synchronous twin used after SQLite has ranked a small result set. The
+   * search connection is synchronous already (`node:sqlite` DatabaseSync), and
+   * reading at most `limit` local gzip files keeps the public retriever API
+   * stable while avoiding a second raw-text store inside FTS5.
+   */
+  getFromPlatformSync(platform, docId) {
+    const record = readBestConversationFilesSync(
+      this.paths.compressedConversationFile(platform, docId),
+      this.paths.legacyConversationFile(platform, docId)
+    );
+    return record?.conversation.docId === docId ? record : null;
+  }
   /**
    * Write an agent-authored memory, keyed on memoryId.
    *
@@ -385,17 +431,116 @@ var Corpus = class {
       } catch {
         continue;
       }
+      const stems = /* @__PURE__ */ new Set();
       for (const name of files) {
-        if (!name.endsWith(".json")) {
-          continue;
-        }
-        const record = await readJsonIfExists(join3(dir, name));
+        if (name.endsWith(".json.gz")) stems.add(name.slice(0, -".json.gz".length));
+        else if (name.endsWith(".json")) stems.add(name.slice(0, -".json".length));
+      }
+      for (const stem of [...stems].sort()) {
+        const record = await readBestConversationFiles(
+          join3(dir, `${stem}.json.gz`),
+          join3(dir, `${stem}.json`)
+        );
         if (record) {
           yield record;
         }
       }
     }
   }
+  /** Byte/count breakdown used by `stats` and `compact --dry-run`. */
+  async conversationStorageStats() {
+    const stats = {
+      legacyFiles: 0,
+      legacyBytes: 0,
+      compressedFiles: 0,
+      compressedBytes: 0
+    };
+    for (const platform of await this.listPlatforms()) {
+      const dir = this.paths.platformDir(platform);
+      let entries;
+      try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (!entry.isFile()) continue;
+        const file = join3(dir, entry.name);
+        if (entry.name.endsWith(".json.gz")) {
+          stats.compressedFiles += 1;
+          stats.compressedBytes += (await fs.stat(file)).size;
+        } else if (entry.name.endsWith(".json")) {
+          stats.legacyFiles += 1;
+          stats.legacyBytes += (await fs.stat(file)).size;
+        }
+      }
+    }
+    return stats;
+  }
+  /**
+   * Convert every legacy conversation independently. Each candidate is written,
+   * read back, and byte-compared in canonical JSON form before its plaintext
+   * source is removed, making the operation resumable after any interruption.
+   */
+  async migrateLegacyConversations(options = {}) {
+    const dryRun = options.dryRun === true;
+    const yieldEvery = Math.max(0, Math.floor(options.yieldEvery ?? 0));
+    const before = await this.conversationStorageStats();
+    const report = {
+      ...before,
+      dryRun,
+      candidates: before.legacyFiles,
+      migrated: 0,
+      legacyRemoved: 0,
+      projectedCompressedBytes: before.compressedBytes,
+      failures: []
+    };
+    for (const platform of await this.listPlatforms()) {
+      const dir = this.paths.platformDir(platform);
+      let names;
+      try {
+        names = (await fs.readdir(dir)).filter((name) => name.endsWith(".json")).sort();
+      } catch {
+        continue;
+      }
+      for (const name of names) {
+        const legacyFile = join3(dir, name);
+        const compressedFile = join3(dir, `${name}.gz`);
+        try {
+          const migrateOne = async () => {
+            const legacy = await readPlainConversationIfExists(legacyFile);
+            if (!legacy) throw new Error("legacy JSON could not be parsed");
+            const compressed = await readCompressedConversationIfExists(compressedFile);
+            const winner = pickNewerConversation(compressed, legacy) ?? legacy;
+            const serialized = serializeConversation(canonicalizeConversation(winner));
+            const compressedBytes = await gzip(Buffer.from(serialized, "utf8"), { level: 9 });
+            report.projectedCompressedBytes -= await fileSizeIfExists(compressedFile);
+            report.projectedCompressedBytes += compressedBytes.byteLength;
+            if (!dryRun) {
+              await writeVerifiedCompressedConversationAtomic(compressedFile, compressedBytes, serialized);
+              await fs.rm(legacyFile);
+            }
+          };
+          if (dryRun) await migrateOne();
+          else await this.enqueueWrite(migrateOne);
+          report.migrated += 1;
+          report.legacyRemoved += 1;
+        } catch (error) {
+          report.failures.push({
+            file: legacyFile,
+            error: error instanceof Error ? error.message : String(error)
+          });
+        }
+        if (yieldEvery > 0 && (report.migrated + report.failures.length) % yieldEvery === 0) {
+          await yieldToEventLoop();
+        }
+      }
+    }
+    if (!dryRun && report.failures.length === 0) {
+      await this.writeMeta({ formatVersion: CORPUS_FORMAT_VERSION });
+    }
+    return report;
+  }
   async stats() {
     const byPlatform = {};
     let conversationCount = 0;
@@ -409,9 +554,13 @@ var Corpus = class {
     return { conversationCount, messageCount, byPlatform };
   }
   /** Refresh meta.json's conversationCount / lastIngestAt after an ingest run. */
-  async touchIngestMeta() {
+  async touchIngestMeta(receipt) {
     const { conversationCount } = await this.stats();
-    await this.writeMeta({ lastIngestAt: Date.now(), conversationCount });
+    await this.writeMeta({
+      lastIngestAt: Date.now(),
+      conversationCount,
+      ...receipt ? { lastIngestReceipt: receipt } : {}
+    });
   }
   enqueueWrite(fn) {
     const run = this.writeChain.then(fn, fn);
@@ -421,7 +570,30 @@ var Corpus = class {
     );
     return run;
   }
+  readBestConversation(platform, docId) {
+    return readBestConversationFiles(
+      this.paths.compressedConversationFile(platform, docId),
+      this.paths.legacyConversationFile(platform, docId)
+    );
+  }
 };
+function yieldToEventLoop() {
+  return new Promise((resolve2) => setImmediate(resolve2));
+}
+async function waitForMaintenanceLease(file) {
+  const deadline = Date.now() + MAINTENANCE_WRITE_WAIT_MS;
+  while (true) {
+    try {
+      await fs.access(file);
+    } catch {
+      return;
+    }
+    if (Date.now() >= deadline) {
+      throw new Error("automatic corpus maintenance is in progress; retry this write shortly");
+    }
+    await new Promise((resolve2) => setTimeout(resolve2, MAINTENANCE_WRITE_POLL_MS));
+  }
+}
 async function readJsonIfExists(file) {
   try {
     const raw = await fs.readFile(file, "utf8");
@@ -430,9 +602,83 @@ async function readJsonIfExists(file) {
     return null;
   }
 }
+function serializeConversation(record) {
+  return `${JSON.stringify(canonicalizeConversation(record), null, 2)}
+`;
+}
+async function readPlainConversationIfExists(file) {
+  return readJsonIfExists(file);
+}
+async function readCompressedConversationIfExists(file) {
+  try {
+    const raw = await fs.readFile(file);
+    return JSON.parse((await gunzip(raw)).toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+async function readBestConversationFiles(compressedFile, legacyFile) {
+  const [compressed, legacy] = await Promise.all([
+    readCompressedConversationIfExists(compressedFile),
+    readPlainConversationIfExists(legacyFile)
+  ]);
+  return pickNewerConversation(compressed, legacy);
+}
+function readBestConversationFilesSync(compressedFile, legacyFile) {
+  let compressed = null;
+  let legacy = null;
+  try {
+    compressed = JSON.parse(gunzipSync(readFileSync2(compressedFile)).toString("utf8"));
+  } catch {
+  }
+  try {
+    legacy = JSON.parse(readFileSync2(legacyFile, "utf8"));
+  } catch {
+  }
+  return pickNewerConversation(compressed, legacy);
+}
+function pickNewerConversation(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  const aChanged = a.conversation.corpusChangedAt ?? a.conversation.updatedAt ?? 0;
+  const bChanged = b.conversation.corpusChangedAt ?? b.conversation.updatedAt ?? 0;
+  if (aChanged !== bChanged) return aChanged > bChanged ? a : b;
+  const aUpdated = a.conversation.updatedAt ?? 0;
+  const bUpdated = b.conversation.updatedAt ?? 0;
+  return aUpdated >= bUpdated ? a : b;
+}
+async function writeCompressedConversationAtomic(file, serialized) {
+  const compressed = await gzip(Buffer.from(serialized, "utf8"), { level: 9 });
+  await writeFileAtomic(file, compressed);
+}
+async function writeVerifiedCompressedConversationAtomic(file, compressed, serialized) {
+  const tmp = `${file}.migration-${process.pid}-${Date.now()}`;
+  try {
+    await fs.writeFile(tmp, compressed, { mode: FILE_MODE });
+    const verified = await readCompressedConversationIfExists(tmp);
+    if (!verified || serializeConversation(canonicalizeConversation(verified)) !== serialized) {
+      throw new Error("compressed read-back verification failed");
+    }
+    await fs.rename(tmp, file);
+  } catch (error) {
+    await fs.rm(tmp, { force: true });
+    throw error;
+  }
+}
+async function fileSizeIfExists(file) {
+  try {
+    return (await fs.stat(file)).size;
+  } catch {
+    return 0;
+  }
+}
 async function writeFileAtomic(file, contents) {
   const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
-  await fs.writeFile(tmp, contents, { encoding: "utf8", mode: FILE_MODE });
+  if (typeof contents === "string") {
+    await fs.writeFile(tmp, contents, { encoding: "utf8", mode: FILE_MODE });
+  } else {
+    await fs.writeFile(tmp, contents, { mode: FILE_MODE });
+  }
   await fs.rename(tmp, file);
 }
 async function hardenDir(dir) {
@@ -533,23 +779,46 @@ async function drainInbox(corpus, index, options = {}) {
   await corpus.init();
   const inbox = corpus.paths.inboxDir;
   const entries = await pendingInboxFiles(corpus);
-  const total = { ...EMPTY_REPORT, files: 0, failed: 0 };
+  const total = {
+    ...EMPTY_REPORT,
+    files: 0,
+    failed: 0,
+    discarded: 0,
+    quarantined: 0
+  };
   for (const name of entries) {
     const src = join4(inbox, name);
     try {
       const report = await ingestFile(corpus, src, index);
       accumulate(total, report);
       total.files += 1;
-      await moveToProcessed(corpus, src, name);
+      if (report.malformedLines > 0) {
+        await moveToQuarantine(corpus, src, name);
+        total.quarantined += 1;
+      } else {
+        await fs2.unlink(src);
+        total.discarded += 1;
+      }
     } catch (error) {
       if (await stillPending(src)) {
         total.failed += 1;
+        if (isCorruptDeltaError(error)) {
+          await moveToQuarantine(corpus, src, name);
+          total.quarantined += 1;
+        }
         options.onFileError?.(name, error);
       }
     }
   }
   if (total.files > 0) {
-    await corpus.touchIngestMeta();
+    await corpus.touchIngestMeta({
+      files: total.files,
+      conversations: total.conversations,
+      messages: total.messages,
+      malformedLines: total.malformedLines,
+      discarded: total.discarded,
+      quarantined: total.quarantined
+    });
   }
   return total;
 }
@@ -561,16 +830,23 @@ async function stillPending(src) {
     return false;
   }
 }
-async function moveToProcessed(corpus, src, name) {
-  const dest = join4(corpus.paths.processedDir, name);
+async function moveToQuarantine(corpus, src, name) {
+  const dest = join4(corpus.paths.quarantineDir, name);
   try {
     await fs2.rename(src, dest);
   } catch {
-    const alt = join4(corpus.paths.processedDir, `${Date.now()}-${name}`);
+    const alt = join4(corpus.paths.quarantineDir, `${Date.now()}-${name}`);
     await fs2.copyFile(src, alt);
     await fs2.unlink(src);
   }
 }
+function isCorruptDeltaError(error) {
+  if (!error || typeof error !== "object" || !("code" in error)) {
+    return false;
+  }
+  const code = String(error.code ?? "");
+  return code === "Z_DATA_ERROR" || code === "Z_BUF_ERROR" || code.startsWith("ERR_ZLIB_");
+}
 function isNdjson(name) {
   const lower = name.toLowerCase();
   return lower.endsWith(".jsonl") || lower.endsWith(".ndjson") || lower.endsWith(".jsonl.gz") || lower.endsWith(".ndjson.gz");
@@ -703,6 +979,7 @@ CREATE TABLE IF NOT EXISTS index_meta (
 var DROP_DERIVED_SQL = `
 DROP TABLE IF EXISTS conversations;
 DROP TABLE IF EXISTS messages_fts;
+DROP TABLE IF EXISTS message_rows;
 DROP TABLE IF EXISTS memories;
 DROP TABLE IF EXISTS memories_fts;
 `;
@@ -728,11 +1005,18 @@ CREATE TABLE IF NOT EXISTS conversations (
 CREATE INDEX IF NOT EXISTS idx_conversations_platform ON conversations(platform);
 CREATE INDEX IF NOT EXISTS idx_conversations_createdAt ON conversations(createdAt);
 
+CREATE TABLE IF NOT EXISTS message_rows (
+  rowid INTEGER PRIMARY KEY,
+  docId TEXT NOT NULL,
+  msgIndex INTEGER NOT NULL,
+  role TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_message_rows_docId ON message_rows(docId);
+
 CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
-  docId UNINDEXED,
-  msgIndex UNINDEXED,
-  role UNINDEXED,
   text,
+  content = '',
+  contentless_delete = 1,
   tokenize = 'porter unicode61'
 );
 
@@ -760,7 +1044,10 @@ var SearchIndex = class {
   stmts;
   /** Whether the on-disk index was a stale format version when it was opened. */
   staleOnOpen;
-  constructor(dbPath) {
+  /** Canonical source used only to hydrate the few snippets returned by rank. */
+  corpus;
+  constructor(dbPath, corpus) {
+    this.corpus = corpus;
     hardenDbFile(dbPath);
     this.db = new (loadSqlite()).DatabaseSync(dbPath);
     this.db.exec("PRAGMA journal_mode = WAL");
@@ -771,12 +1058,19 @@ var SearchIndex = class {
       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 = {
-      deleteFts: this.db.prepare("DELETE FROM messages_fts WHERE docId = ?"),
-      insertFts: this.db.prepare(
-        "INSERT INTO messages_fts (docId, msgIndex, role, text) VALUES (?, ?, ?, ?)"
+      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 (?, ?, ?)"
       ),
+      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
@@ -792,6 +1086,12 @@ var SearchIndex = class {
         `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 ?`
       )
     };
   }
@@ -855,7 +1155,7 @@ var SearchIndex = class {
   }
   removeConversation(docId) {
     this.transaction(() => {
-      this.stmts.deleteFts.run(docId);
+      this.deleteFtsRows(docId);
       this.stmts.deleteConversation.run(docId);
     });
   }
@@ -865,7 +1165,8 @@ var SearchIndex = class {
    * reads, which the sync {@link transaction} helper cannot hold.
    */
   async rebuildFrom(corpus) {
-    this.db.exec("DELETE FROM messages_fts; DELETE FROM conversations;");
+    this.corpus = corpus;
+    this.db.exec("DELETE FROM messages_fts; DELETE FROM message_rows; DELETE FROM conversations;");
     this.db.exec("DELETE FROM memories_fts; DELETE FROM memories;");
     let conversations = 0;
     let memories = 0;
@@ -890,15 +1191,15 @@ var SearchIndex = class {
   // transaction() helper for single upserts, or rebuildFrom's manual one).
   writeRecord(rec) {
     const { conversation, messages } = rec;
-    this.stmts.deleteFts.run(conversation.docId);
+    this.deleteFtsRows(conversation.docId);
     this.stmts.deleteConversation.run(conversation.docId);
     const titleText = [conversation.title, conversation.preview].filter(Boolean).join("\n");
     if (titleText.trim()) {
-      this.stmts.insertFts.run(conversation.docId, TITLE_ROW_INDEX, TITLE_ROLE, titleText);
+      this.insertFtsRow(conversation.docId, TITLE_ROW_INDEX, TITLE_ROLE, titleText);
     }
     for (const message of messages) {
       if (message.text.trim()) {
-        this.stmts.insertFts.run(conversation.docId, message.msgIndex, message.role, message.text);
+        this.insertFtsRow(conversation.docId, message.msgIndex, message.role, message.text);
       }
     }
     this.stmts.insertConversation.run({
@@ -915,6 +1216,17 @@ var SearchIndex = class {
       accountLabel: conversation.accountLabel ?? null
     });
   }
+  insertFtsRow(docId, msgIndex, role, text) {
+    const inserted = this.stmts.insertMessageRow.run(docId, msgIndex, role);
+    this.stmts.insertFts.run(inserted.lastInsertRowid, text);
+  }
+  deleteFtsRows(docId) {
+    const rows = this.stmts.selectFtsRows.all(docId);
+    for (const row of rows) {
+      this.stmts.deleteFts.run(row.rowid);
+    }
+    this.stmts.deleteMessageRows.run(docId);
+  }
   // Replace a memory's index rows. Caller supplies the transaction, as with
   // writeRecord. Memories live in their own tables rather than in messages_fts:
   // a memory is not a turn in a conversation, and mixing them would let a
@@ -968,9 +1280,9 @@ var SearchIndex = class {
         c.docId, c.platform, c.title, c.url, c.createdAt, c.updatedAt,
         c.messageCount, c.preview, c.pinned, c.accountId, c.accountLabel,
         m.msgIndex AS msgIndex, m.role AS role,
-        snippet(messages_fts, 3, '[', ']', '\u2026', ${SNIPPET_TOKENS}) AS snippet,
         bm25(messages_fts) AS bm25
-      FROM messages_fts m
+      FROM messages_fts
+      JOIN message_rows m ON m.rowid = messages_fts.rowid
       JOIN conversations c ON c.docId = m.docId
       WHERE ${clauses.join(" AND ")}
       ORDER BY bm25
@@ -996,7 +1308,7 @@ var SearchIndex = class {
         pinned: row.pinned === 1,
         // BM25 is negative (more negative = better); expose a positive relevance.
         score: -row.bm25,
-        snippet: row.snippet,
+        snippet: this.hydrateSnippet(row, match),
         matchRole: normalizeMatchRole(row.role),
         matchMsgIndex: row.msgIndex
       };
@@ -1009,6 +1321,25 @@ var SearchIndex = class {
     }
     return hits;
   }
+  /** Reclaim free pages and merge FTS segments after a confirmed compaction. */
+  compact() {
+    this.db.exec("INSERT INTO messages_fts(messages_fts) VALUES('optimize')");
+    this.db.exec("INSERT INTO memories_fts(memories_fts) VALUES('optimize')");
+    this.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    this.db.exec("VACUUM");
+  }
+  hydrateSnippet(row, match) {
+    const record = this.corpus?.getFromPlatformSync(row.platform, row.docId);
+    const source = row.msgIndex === TITLE_ROW_INDEX ? [record?.conversation.title ?? row.title, record?.conversation.preview ?? row.preview].filter(Boolean).join("\n") : record?.messages.find((message) => message.msgIndex === row.msgIndex)?.text ?? row.preview;
+    this.stmts.clearSnippetFts.run();
+    try {
+      this.stmts.insertSnippetFts.run(source);
+      const rendered = this.stmts.renderSnippet.get(match);
+      return rendered?.snippet ?? fallbackSnippet(source, SNIPPET_TOKENS);
+    } finally {
+      this.stmts.clearSnippetFts.run();
+    }
+  }
   close() {
     this.db.close();
   }
@@ -1022,7 +1353,7 @@ var SearchIndex = class {
 };
 async function openSearchIndex(corpus, options = {}) {
   await corpus.init();
-  const index = new SearchIndex(corpus.paths.indexDbFile);
+  const index = new SearchIndex(corpus.paths.indexDbFile, corpus);
   if (options.autoBuild !== false && (index.needsRebuild() || index.count() === 0 && index.countMemories() === 0)) {
     await index.rebuildFrom(corpus);
   }
@@ -1034,7 +1365,7 @@ async function deleteIndexDb(dbFile) {
   }
 }
 function toMatchQuery(query, mode = "any") {
-  const terms = query.split(/[^\p{L}\p{N}]+/u).filter((t) => t.length > 0);
+  const terms = queryTerms(query);
   if (terms.length === 0) {
     return null;
   }
@@ -1043,6 +1374,17 @@ function toMatchQuery(query, mode = "any") {
   }
   return terms.map((t) => `"${t}"`).join(mode === "all" ? " AND " : " OR ");
 }
+function queryTerms(query) {
+  return query.split(/[^\p{L}\p{N}]+/u).filter((term) => term.length > 0);
+}
+function fallbackSnippet(source, maxTokens) {
+  const collapsed = source.replace(/\s+/g, " ").trim();
+  if (!collapsed) return "";
+  const words = collapsed.split(" ");
+  const width = Math.max(1, maxTokens);
+  const end = Math.min(words.length, width);
+  return `${words.slice(0, end).join(" ")}${end < words.length ? "\u2026" : ""}`;
+}
 function escapeLike(value) {
   return value.replace(/[\\%_]/g, "\\$&");
 }
@@ -1053,43 +1395,421 @@ function normalizeMatchRole(role) {
   return role === "assistant" || role === "user" || role === "system" ? role : "unknown";
 }
 
+// src/storageMaintenance.ts
+import { promises as fs4 } from "fs";
+import { join as join5 } from "path";
+async function inspectCorpusStorage(corpus) {
+  const conversations = await corpus.conversationStorageStats();
+  const processed = await directoryFiles(corpus.paths.processedDir);
+  const quarantine = await directoryFiles(corpus.paths.quarantineDir);
+  const activeNames = [
+    corpus.paths.indexDbFile,
+    `${corpus.paths.indexDbFile}-wal`,
+    `${corpus.paths.indexDbFile}-shm`
+  ];
+  const activeIndex = await explicitFiles(activeNames);
+  const staleNames = await staleIndexFiles(corpus.paths.indexDir);
+  const stalePaths = staleNames.flatMap((name) => {
+    const base = join5(corpus.paths.indexDir, name);
+    return [base, `${base}-wal`, `${base}-shm`];
+  });
+  const staleIndexes = await explicitFiles(stalePaths);
+  const root = await directoryFiles(corpus.paths.root);
+  const classifiedBytes = conversations.legacyBytes + conversations.compressedBytes + processed.bytes + quarantine.bytes + activeIndex.bytes + staleIndexes.bytes;
+  const classifiedFiles = conversations.legacyFiles + conversations.compressedFiles + processed.files + quarantine.files + activeIndex.files + staleIndexes.files;
+  const other = {
+    files: Math.max(0, root.files - classifiedFiles),
+    bytes: Math.max(0, root.bytes - classifiedBytes)
+  };
+  return {
+    root: corpus.paths.root,
+    conversations,
+    processed,
+    quarantine,
+    activeIndex,
+    staleIndexes,
+    other,
+    totalBytes: root.bytes,
+    immediatelyReclaimableBytes: processed.bytes + staleIndexes.bytes
+  };
+}
+async function compactCorpus(corpus, options = {}) {
+  const dryRun = options.dryRun === true;
+  const before = await inspectCorpusStorage(corpus);
+  if (dryRun) {
+    const compression = await corpus.migrateLegacyConversations({ dryRun: true });
+    const compressionSavings = Math.max(
+      0,
+      compression.legacyBytes + compression.compressedBytes - compression.projectedCompressedBytes
+    );
+    return {
+      dryRun: true,
+      before,
+      compression,
+      processedRemoved: before.processed,
+      staleIndexesRemoved: before.staleIndexes,
+      after: null,
+      reclaimedBytes: before.immediatelyReclaimableBytes + compressionSavings
+    };
+  }
+  await corpus.init();
+  const processedRemoved = await removeDirectoryFiles(corpus.paths.processedDir);
+  const index = options.index ?? await openSearchIndex(corpus);
+  try {
+    index.compact();
+  } finally {
+    if (!options.index) index.close();
+  }
+  const appliedCompression = await corpus.migrateLegacyConversations({
+    yieldEvery: options.yieldEvery
+  });
+  if (appliedCompression.failures.length > 0) {
+    throw new Error(
+      `Corpus compression left ${appliedCompression.failures.length} legacy file(s) untouched; stale indexes were preserved. Run compact again after fixing the reported files.`
+    );
+  }
+  const staleIndexesRemoved = await removeStaleIndexes(corpus);
+  const after = await inspectCorpusStorage(corpus);
+  return {
+    dryRun: false,
+    before,
+    compression: appliedCompression,
+    processedRemoved,
+    staleIndexesRemoved,
+    after,
+    reclaimedBytes: Math.max(0, before.totalBytes - after.totalBytes)
+  };
+}
+async function removeStaleIndexes(corpus) {
+  const names = await staleIndexFiles(corpus.paths.indexDir);
+  const paths = names.flatMap((name) => {
+    const base = join5(corpus.paths.indexDir, name);
+    return [base, `${base}-wal`, `${base}-shm`];
+  });
+  const before = await explicitFiles(paths);
+  for (const name of names) {
+    await deleteIndexDb(join5(corpus.paths.indexDir, name));
+  }
+  return before;
+}
+async function removeDirectoryFiles(dir) {
+  const before = await directoryFiles(dir);
+  await removeFilesRecursively(dir);
+  return before;
+}
+async function removeFilesRecursively(dir) {
+  let entries;
+  try {
+    entries = await fs4.readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const path = join5(dir, entry.name);
+    if (entry.isDirectory()) await removeFilesRecursively(path);
+    else if (entry.isFile()) await fs4.rm(path, { force: true });
+  }
+}
+async function explicitFiles(files) {
+  let count = 0;
+  let bytes = 0;
+  for (const file of files) {
+    try {
+      const stat = await fs4.stat(file);
+      if (stat.isFile()) {
+        count += 1;
+        bytes += stat.size;
+      }
+    } catch {
+    }
+  }
+  return { files: count, bytes };
+}
+async function directoryFiles(dir) {
+  let entries;
+  try {
+    entries = await fs4.readdir(dir, { withFileTypes: true });
+  } catch {
+    return { files: 0, bytes: 0 };
+  }
+  let files = 0;
+  let bytes = 0;
+  for (const entry of entries) {
+    const path = join5(dir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await directoryFiles(path);
+      files += nested.files;
+      bytes += nested.bytes;
+    } else if (entry.isFile()) {
+      files += 1;
+      bytes += (await fs4.stat(path)).size;
+    }
+  }
+  return { files, bytes };
+}
+
+// src/autoMaintenance.ts
+import { constants as fsConstants, promises as fs5 } from "fs";
+import { dirname as dirname2 } from "path";
+var FILE_MODE2 = 384;
+var STATE_SCHEMA_VERSION = 1;
+var FORMAT_KEY = `corpus-${CORPUS_FORMAT_VERSION}-index-${INDEX_FORMAT_VERSION}`;
+var AUTO_MAINTENANCE_GRACE_MS = 3 * 24 * 60 * 60 * 1e3;
+var AUTO_MAINTENANCE_RECHECK_MS = 7 * 24 * 60 * 60 * 1e3;
+var AUTO_MAINTENANCE_RETRY_MS = 24 * 60 * 60 * 1e3;
+var AUTO_MAINTENANCE_LOCK_STALE_MS = 6 * 60 * 60 * 1e3;
+var AUTO_MAINTENANCE_YIELD_EVERY = 25;
+var AUTO_MAINTENANCE_SETTLE_MS = 1e3;
+function isAutomaticMaintenanceDisabled(env = process.env) {
+  const raw = env.LLMNESIA_NO_AUTO_MAINTENANCE;
+  return raw === "1" || raw === "true";
+}
+async function runAutomaticMaintenance(corpus, index, options = {}) {
+  const env = options.env ?? process.env;
+  if (isAutomaticMaintenanceDisabled(env)) return { action: "disabled" };
+  await corpus.init();
+  const now = options.now ?? Date.now;
+  const at = now();
+  const graceMs = options.graceMs ?? AUTO_MAINTENANCE_GRACE_MS;
+  const recheckMs = options.recheckMs ?? AUTO_MAINTENANCE_RECHECK_MS;
+  const retryMs = options.retryMs ?? AUTO_MAINTENANCE_RETRY_MS;
+  const state = await readState(corpus);
+  if (state?.formatKey === FORMAT_KEY && state.status === "complete" && state.completedAt !== void 0 && at - state.completedAt < recheckMs) {
+    return { action: "recently-checked", completedAt: state.completedAt };
+  }
+  if (state?.formatKey === FORMAT_KEY && state.nextEligibleAt !== void 0 && at < state.nextEligibleAt) {
+    return { action: "deferred", until: state.nextEligibleAt };
+  }
+  const before = await inspectCorpusStorage(corpus);
+  if (!hasWork(before)) {
+    await writeState(corpus, {
+      schemaVersion: STATE_SCHEMA_VERSION,
+      formatKey: FORMAT_KEY,
+      status: "complete",
+      firstSeenAt: state?.formatKey === FORMAT_KEY ? state.firstSeenAt : at,
+      completedAt: at,
+      beforeBytes: before.totalBytes,
+      afterBytes: before.totalBytes,
+      reclaimedBytes: 0
+    });
+    return { action: "no-work" };
+  }
+  const firstSeenAt = state?.formatKey === FORMAT_KEY ? state.firstSeenAt : at;
+  const eligibleAt = firstSeenAt + Math.max(0, graceMs);
+  if (at < eligibleAt) {
+    await writeState(corpus, {
+      schemaVersion: STATE_SCHEMA_VERSION,
+      formatKey: FORMAT_KEY,
+      status: "waiting",
+      firstSeenAt,
+      nextEligibleAt: eligibleAt,
+      beforeBytes: before.totalBytes
+    });
+    return { action: "deferred", until: eligibleAt };
+  }
+  const lease = await acquireLease(
+    corpus,
+    at,
+    options.lockStaleMs ?? AUTO_MAINTENANCE_LOCK_STALE_MS
+  );
+  if (!lease) return { action: "locked" };
+  try {
+    await delay(options.settleMs ?? AUTO_MAINTENANCE_SETTLE_MS);
+    const lockedBefore = await inspectCorpusStorage(corpus);
+    if (!hasWork(lockedBefore)) {
+      await writeState(corpus, {
+        schemaVersion: STATE_SCHEMA_VERSION,
+        formatKey: FORMAT_KEY,
+        status: "complete",
+        firstSeenAt,
+        completedAt: now(),
+        beforeBytes: lockedBefore.totalBytes,
+        afterBytes: lockedBefore.totalBytes,
+        reclaimedBytes: 0
+      });
+      return { action: "no-work" };
+    }
+    await writeState(corpus, {
+      schemaVersion: STATE_SCHEMA_VERSION,
+      formatKey: FORMAT_KEY,
+      status: "running",
+      firstSeenAt,
+      lastAttemptAt: at,
+      beforeBytes: lockedBefore.totalBytes
+    });
+    try {
+      const report = await compactCorpus(corpus, {
+        index,
+        yieldEvery: options.yieldEvery ?? AUTO_MAINTENANCE_YIELD_EVERY
+      });
+      const completedAt = now();
+      await writeState(corpus, {
+        schemaVersion: STATE_SCHEMA_VERSION,
+        formatKey: FORMAT_KEY,
+        status: "complete",
+        firstSeenAt,
+        lastAttemptAt: at,
+        completedAt,
+        beforeBytes: report.before.totalBytes,
+        afterBytes: report.after?.totalBytes ?? report.before.totalBytes,
+        reclaimedBytes: report.reclaimedBytes
+      });
+      return { action: "compacted", report };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const retryAt = now() + Math.max(0, retryMs);
+      await writeState(corpus, {
+        schemaVersion: STATE_SCHEMA_VERSION,
+        formatKey: FORMAT_KEY,
+        status: "failed",
+        firstSeenAt,
+        lastAttemptAt: at,
+        nextEligibleAt: retryAt,
+        beforeBytes: lockedBefore.totalBytes,
+        lastError: message
+      });
+      return { action: "failed", error: message, retryAt };
+    }
+  } finally {
+    await lease.release();
+  }
+}
+async function readAutomaticMaintenanceState(corpus) {
+  return readState(corpus);
+}
+function hasWork(report) {
+  return report.conversations.legacyFiles > 0 || report.processed.files > 0 || report.staleIndexes.files > 0;
+}
+async function readState(corpus) {
+  try {
+    const parsed = JSON.parse(
+      await fs5.readFile(corpus.paths.maintenanceStateFile, "utf8")
+    );
+    return parsed?.schemaVersion === STATE_SCHEMA_VERSION ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+async function writeState(corpus, state) {
+  const file = corpus.paths.maintenanceStateFile;
+  const temp = `${file}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  await fs5.mkdir(dirname2(file), { recursive: true });
+  try {
+    const handle = await fs5.open(
+      temp,
+      fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY,
+      FILE_MODE2
+    );
+    try {
+      await handle.writeFile(`${JSON.stringify(state, null, 2)}
+`, "utf8");
+    } finally {
+      await handle.close();
+    }
+    await fs5.rename(temp, file);
+  } finally {
+    await fs5.rm(temp, { force: true }).catch(() => {
+    });
+  }
+}
+async function acquireLease(corpus, now, staleMs) {
+  const file = corpus.paths.maintenanceLockFile;
+  const token = `${process.pid}-${now}-${Math.random().toString(16).slice(2)}`;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const handle = await fs5.open(file, "wx", FILE_MODE2);
+      try {
+        await handle.writeFile(`${JSON.stringify({ token, pid: process.pid, startedAt: now })}
+`, "utf8");
+      } finally {
+        await handle.close();
+      }
+      return {
+        token,
+        release: async () => {
+          try {
+            const current = JSON.parse(await fs5.readFile(file, "utf8"));
+            if (current.token === token) await fs5.rm(file, { force: true });
+          } catch {
+          }
+        }
+      };
+    } catch (error) {
+      if (!isAlreadyExists(error)) throw error;
+      const existing = await readLease(file);
+      const alive = existing?.pid ? isProcessAlive(existing.pid) : false;
+      const age = existing?.startedAt ? now - existing.startedAt : Number.POSITIVE_INFINITY;
+      if (alive && age < staleMs) return null;
+      const stale = `${file}.stale-${token}`;
+      try {
+        await fs5.rename(file, stale);
+        await fs5.rm(stale, { force: true });
+      } catch {
+        return null;
+      }
+    }
+  }
+  return null;
+}
+async function readLease(file) {
+  try {
+    return JSON.parse(await fs5.readFile(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function isAlreadyExists(error) {
+  return error.code === "EEXIST";
+}
+function delay(ms) {
+  return ms > 0 ? new Promise((resolve2) => setTimeout(resolve2, ms)) : Promise.resolve();
+}
+
 // src/runtimeInstall.ts
 import { cp, mkdir, readdir as readdir2, rename, rm, writeFile } from "fs/promises";
 import { existsSync } from "fs";
 import { homedir as homedir2 } from "os";
-import { dirname as dirname2, join as join5 } from "path";
+import { dirname as dirname3, join as join6 } from "path";
 import { fileURLToPath } from "url";
 function defaultSourceDir() {
-  return dirname2(fileURLToPath(import.meta.url));
+  return dirname3(fileURLToPath(import.meta.url));
 }
 function runtimeBinDir(home = homedir2()) {
-  return join5(home, ".llmnesia", "bin");
+  return join6(home, ".llmnesia", "bin");
 }
 async function installRuntime(options = {}) {
   const home = options.home ?? homedir2();
   const sourceDir = options.sourceDir ?? defaultSourceDir();
   const nodePath = options.nodePath ?? process.execPath;
   const binDir = runtimeBinDir(home);
-  const sourceEntry = join5(sourceDir, "cli.js");
+  const sourceEntry = join6(sourceDir, "cli.js");
   if (!existsSync(sourceEntry)) {
     throw new Error(
       `Cannot locate the built runtime: no cli.js in ${sourceDir}. Run this from an installed package (npx -y @llmnesia/mcp@latest install) or build first (npm run build).`
     );
   }
-  const parentDir = dirname2(binDir);
+  const parentDir = dirname3(binDir);
   const nonce = `${process.pid}-${Date.now()}`;
-  const stagingDir = join5(parentDir, `.bin-install-${nonce}`);
-  const backupDir = join5(parentDir, `.bin-backup-${nonce}`);
+  const stagingDir = join6(parentDir, `.bin-install-${nonce}`);
+  const backupDir = join6(parentDir, `.bin-backup-${nonce}`);
   await mkdir(parentDir, { recursive: true });
   await rm(stagingDir, { recursive: true, force: true });
   await rm(backupDir, { recursive: true, force: true });
   await mkdir(stagingDir, { recursive: true });
   try {
     for (const name of await readdir2(sourceDir)) {
-      await cp(join5(sourceDir, name), join5(stagingDir, name), { recursive: true });
+      await cp(join6(sourceDir, name), join6(stagingDir, name), { recursive: true });
     }
     await writeFile(
-      join5(stagingDir, "package.json"),
+      join6(stagingDir, "package.json"),
       `${JSON.stringify(
         {
           name: "llmnesia-mcp-runtime",
@@ -1123,7 +1843,7 @@ async function installRuntime(options = {}) {
   } finally {
     await rm(stagingDir, { recursive: true, force: true });
   }
-  const entry = join5(binDir, "cli.js");
+  const entry = join6(binDir, "cli.js");
   return {
     binDir,
     entry,
@@ -1144,7 +1864,7 @@ async function uninstallRuntime(home = homedir2()) {
 // src/selfUpdate.ts
 import { spawn } from "child_process";
 import { mkdtemp, readFile, rm as rm2, writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname3, join as join6 } from "path";
+import { dirname as dirname4, join as join7 } from "path";
 import { homedir as homedir3, tmpdir } from "os";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var PACKAGE_NAME = "@llmnesia/mcp";
@@ -1154,9 +1874,9 @@ var REGISTRY_TIMEOUT_MS = 5e3;
 var INSTALL_TIMEOUT_MS = 12e4;
 var UPDATE_CHECK_DELAY_MS = 3e4;
 function stateFile(home) {
-  return join6(home, ".llmnesia", "update-state.json");
+  return join7(home, ".llmnesia", "update-state.json");
 }
-async function readState(home) {
+async function readState2(home) {
   try {
     const parsed = JSON.parse(await readFile(stateFile(home), "utf8"));
     return typeof parsed === "object" && parsed !== null ? parsed : {};
@@ -1164,7 +1884,7 @@ async function readState(home) {
     return {};
   }
 }
-async function writeState(home, state) {
+async function writeState2(home, state) {
   try {
     await writeFile2(stateFile(home), `${JSON.stringify(state, null, 2)}
 `, "utf8");
@@ -1216,11 +1936,11 @@ async function fetchLatestFromRegistry() {
   }
 }
 function npmCommand() {
-  const binDir = dirname3(process.execPath);
-  return process.platform === "win32" ? join6(binDir, "npm.cmd") : join6(binDir, "npm");
+  const binDir = dirname4(process.execPath);
+  return process.platform === "win32" ? join7(binDir, "npm.cmd") : join7(binDir, "npm");
 }
 async function npmDownload(version) {
-  const prefix = await mkdtemp(join6(tmpdir(), "llmnesia-update-"));
+  const prefix = await mkdtemp(join7(tmpdir(), "llmnesia-update-"));
   await new Promise((resolve2, reject) => {
     const child = spawn(
       npmCommand(),
@@ -1255,7 +1975,7 @@ async function npmDownload(version) {
       }
     });
   });
-  return join6(prefix, "node_modules", PACKAGE_NAME, "dist");
+  return join7(prefix, "node_modules", PACKAGE_NAME, "dist");
 }
 async function maybeSelfUpdate(options = {}) {
   const env = options.env ?? process.env;
@@ -1264,7 +1984,7 @@ async function maybeSelfUpdate(options = {}) {
   }
   const home = options.home ?? homedir3();
   const currentVersion = options.currentVersion ?? VERSION;
-  const runningDir = options.runningDir ?? dirname3(fileURLToPath2(import.meta.url));
+  const runningDir = options.runningDir ?? dirname4(fileURLToPath2(import.meta.url));
   if (runningDir !== runtimeBinDir(home)) {
     return { action: "not-installed-runtime" };
   }
@@ -1272,7 +1992,7 @@ async function maybeSelfUpdate(options = {}) {
     return { action: "not-a-release-build", currentVersion };
   }
   const now = options.now ?? Date.now;
-  const state = await readState(home);
+  const state = await readState2(home);
   if (state.lastCheckedAt !== void 0 && now() - state.lastCheckedAt < UPDATE_CHECK_INTERVAL_MS) {
     return { action: "throttled" };
   }
@@ -1280,30 +2000,30 @@ async function maybeSelfUpdate(options = {}) {
   try {
     latest = await (options.fetchLatestVersion ?? fetchLatestFromRegistry)();
   } catch (err) {
-    await writeState(home, { ...state, lastCheckedAt: now() });
+    await writeState2(home, { ...state, lastCheckedAt: now() });
     return { action: "check-failed", error: err instanceof Error ? err.message : String(err) };
   }
   const checked = { ...state, lastCheckedAt: now(), lastSeenVersion: latest };
   if (!isStableRelease(latest) || compareVersions(latest, currentVersion) <= 0) {
-    await writeState(home, checked);
+    await writeState2(home, checked);
     return { action: "up-to-date", latest };
   }
   if (state.lastFailedVersion === latest) {
-    await writeState(home, checked);
+    await writeState2(home, checked);
     return { action: "skipped-failed-before", latest };
   }
   let sourceDir;
   try {
     sourceDir = await (options.downloadPackage ?? npmDownload)(latest);
     await installRuntime({ home, sourceDir, version: latest });
-    await writeState(home, { ...checked, lastUpdatedTo: latest, lastFailedVersion: void 0 });
+    await writeState2(home, { ...checked, lastUpdatedTo: latest, lastFailedVersion: void 0 });
     return { action: "updated", from: currentVersion, to: latest };
   } catch (err) {
-    await writeState(home, { ...checked, lastFailedVersion: latest });
+    await writeState2(home, { ...checked, lastFailedVersion: latest });
     return { action: "update-failed", latest, error: err instanceof Error ? err.message : String(err) };
   } finally {
     if (sourceDir) {
-      await rm2(join6(sourceDir, "..", "..", ".."), { recursive: true, force: true }).catch(() => {
+      await rm2(join7(sourceDir, "..", "..", ".."), { recursive: true, force: true }).catch(() => {
       });
     }
   }
@@ -1352,6 +2072,11 @@ export {
   SearchIndex,
   openSearchIndex,
   deleteIndexDb,
+  inspectCorpusStorage,
+  compactCorpus,
+  AUTO_MAINTENANCE_RECHECK_MS,
+  runAutomaticMaintenance,
+  readAutomaticMaintenanceState,
   runtimeBinDir,
   installRuntime,
   uninstallRuntime,