@llmnesia/mcp 0.2.4 → 0.2.5

package/README.md

@@ -151,15 +151,24 @@ dropped to save space.
 Current builds discard a clean browser-to-corpus transport payload after both
 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. Preview the
-exact recoverable space without writing anything:
+successful payload and may also have left versioned indexes behind.
+
+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,
+resumable, yields between small batches, and retries later without interrupting
+search if any verification or filesystem step fails. Quarantine is never
+removed. Set `LLMNESIA_NO_AUTO_MAINTENANCE=1` only if you need to opt out.
+
+For support or an immediate attended cleanup, preview the exact recoverable
+space without writing anything:
 
 ```bash
 npx -y @llmnesia/mcp@latest compact --dry-run
 ```
 
-To apply it, fully quit connected desktop AI/MCP clients, then run `compact`
-without `--dry-run`. It asks for confirmation, verifies every compressed
+To apply it immediately, fully quit connected desktop AI/MCP clients, then run
+`compact` without `--dry-run`. It asks for confirmation, verifies every compressed
 conversation by reading it back before removing the legacy JSON, builds the
 current index before deleting older derived versions, and never removes
 quarantined input.

package/dist/{chunk-JSNSTAFD.js → chunk-BDR4JVMF.js}

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

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

@@ -3,7 +3,7 @@ import { createRequire as __llmnesiaCreateRequire } from "node:module";
 const require = __llmnesiaCreateRequire(import.meta.url);
 import {
   VERSION
-} from "./chunk-JSNSTAFD.js";
+} from "./chunk-BDR4JVMF.js";
 
 // src/config.ts
 import { readFileSync } from "fs";
@@ -63,6 +63,14 @@ 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");
   }
@@ -228,6 +236,8 @@ 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 +
@@ -291,6 +301,7 @@ 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.compressedConversationFile(conversation.platform, conversation.docId);
@@ -473,6 +484,7 @@ var Corpus = class {
    */
   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,
@@ -495,18 +507,22 @@ var Corpus = class {
         const legacyFile = join3(dir, name);
         const compressedFile = join3(dir, `${name}.gz`);
         try {
-          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);
-          }
+          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) {
@@ -515,6 +531,9 @@ var Corpus = class {
             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) {
@@ -558,6 +577,23 @@ var Corpus = class {
     );
   }
 };
+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");
@@ -1359,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",
@@ -1429,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,
@@ -1450,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";
@@ -1460,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 : {};
@@ -1470,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");
@@ -1522,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(),
@@ -1561,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;
@@ -1570,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" };
   }
@@ -1578,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" };
   }
@@ -1586,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(() => {
       });
     }
   }
@@ -1658,6 +2072,11 @@ export {
   SearchIndex,
   openSearchIndex,
   deleteIndexDb,
+  inspectCorpusStorage,
+  compactCorpus,
+  AUTO_MAINTENANCE_RECHECK_MS,
+  runAutomaticMaintenance,
+  readAutomaticMaintenanceState,
   runtimeBinDir,
   installRuntime,
   uninstallRuntime,

package/dist/{cli-ZEA7WTVW.js → cli-OXKBAUBE.js}

@@ -4,23 +4,26 @@ const require = __llmnesiaCreateRequire(import.meta.url);
 import {
   Corpus,
   SearchIndex,
+  compactCorpus,
   deleteIndexDb,
   drainInbox,
   ingestFile,
+  inspectCorpusStorage,
   installRuntime,
   isSelfUpdateDisabled,
   openSearchIndex,
+  readAutomaticMaintenanceState,
   resolveCorpusDir,
   runtimeBinDir,
   staleIndexFiles,
   uninstallRuntime
-} from "./chunk-NSVHWVEK.js";
+} from "./chunk-MTPXE734.js";
 import {
   VERSION,
   __commonJS,
   __require,
   __toESM
-} from "./chunk-JSNSTAFD.js";
+} from "./chunk-BDR4JVMF.js";
 
 // ../node_modules/isexe/windows.js
 var require_windows = __commonJS({
@@ -28,7 +31,7 @@ var require_windows = __commonJS({
     "use strict";
     module.exports = isexe;
     isexe.sync = sync;
-    var fs2 = __require("fs");
+    var fs = __require("fs");
     function checkPathExt(path, options) {
       var pathext = options.pathExt !== void 0 ? options.pathExt : process.env.PATHEXT;
       if (!pathext) {
@@ -53,12 +56,12 @@ var require_windows = __commonJS({
       return checkPathExt(path, options);
     }
     function isexe(path, options, cb) {
-      fs2.stat(path, function(er, stat6) {
+      fs.stat(path, function(er, stat6) {
         cb(er, er ? false : checkStat(stat6, path, options));
       });
     }
     function sync(path, options) {
-      return checkStat(fs2.statSync(path), path, options);
+      return checkStat(fs.statSync(path), path, options);
     }
   }
 });
@@ -69,14 +72,14 @@ var require_mode = __commonJS({
     "use strict";
     module.exports = isexe;
     isexe.sync = sync;
-    var fs2 = __require("fs");
+    var fs = __require("fs");
     function isexe(path, options, cb) {
-      fs2.stat(path, function(er, stat6) {
+      fs.stat(path, function(er, stat6) {
         cb(er, er ? false : checkStat(stat6, options));
       });
     }
     function sync(path, options) {
-      return checkStat(fs2.statSync(path), options);
+      return checkStat(fs.statSync(path), options);
     }
     function checkStat(stat6, options) {
       return stat6.isFile() && checkMode(stat6, options);
@@ -101,7 +104,7 @@ var require_mode = __commonJS({
 var require_isexe = __commonJS({
   "../node_modules/isexe/index.js"(exports, module) {
     "use strict";
-    var fs2 = __require("fs");
+    var fs = __require("fs");
     var core;
     if (process.platform === "win32" || global.TESTING_WINDOWS) {
       core = require_windows();
@@ -366,16 +369,16 @@ var require_shebang_command = __commonJS({
 var require_readShebang = __commonJS({
   "../node_modules/cross-spawn/lib/util/readShebang.js"(exports, module) {
     "use strict";
-    var fs2 = __require("fs");
+    var fs = __require("fs");
     var shebangCommand = require_shebang_command();
     function readShebang(command) {
       const size = 150;
       const buffer = Buffer.alloc(size);
       let fd;
       try {
-        fd = fs2.openSync(command, "r");
-        fs2.readSync(fd, buffer, 0, size, 0);
-        fs2.closeSync(fd);
+        fd = fs.openSync(command, "r");
+        fs.readSync(fd, buffer, 0, size, 0);
+        fs.closeSync(fd);
       } catch (e) {
       }
       return shebangCommand(buffer.toString());
@@ -525,7 +528,7 @@ var require_cross_spawn = __commonJS({
 
 // src/cli.ts
 import { createInterface } from "readline/promises";
-import { join as join7 } from "path";
+import { join as join6 } from "path";
 
 // ../packages/native-host/install.mjs
 import { execFile } from "child_process";
@@ -3749,157 +3752,6 @@ function formatDoctorReport(report) {
   return report.checks.map((c) => `${icon[c.status]} ${c.name}: ${c.detail}`).join("\n");
 }
 
-// src/storageMaintenance.ts
-import { promises as fs } from "fs";
-import { join as join6 } 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 = join6(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 = await openSearchIndex(corpus);
-  try {
-    index.compact();
-  } finally {
-    index.close();
-  }
-  const appliedCompression = await corpus.migrateLegacyConversations();
-  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 paths2 = names.flatMap((name) => {
-    const base = join6(corpus.paths.indexDir, name);
-    return [base, `${base}-wal`, `${base}-shm`];
-  });
-  const before = await explicitFiles(paths2);
-  for (const name of names) {
-    await deleteIndexDb(join6(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 fs.readdir(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    const path = join6(dir, entry.name);
-    if (entry.isDirectory()) await removeFilesRecursively(path);
-    else if (entry.isFile()) await fs.rm(path, { force: true });
-  }
-}
-async function explicitFiles(files) {
-  let count = 0;
-  let bytes = 0;
-  for (const file of files) {
-    try {
-      const stat6 = await fs.stat(file);
-      if (stat6.isFile()) {
-        count += 1;
-        bytes += stat6.size;
-      }
-    } catch {
-    }
-  }
-  return { files: count, bytes };
-}
-async function directoryFiles(dir) {
-  let entries;
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true });
-  } catch {
-    return { files: 0, bytes: 0 };
-  }
-  let files = 0;
-  let bytes = 0;
-  for (const entry of entries) {
-    const path = join6(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 fs.stat(path)).size;
-    }
-  }
-  return { files, bytes };
-}
-
 // src/cli.ts
 var USAGE = `llmnesia-mcp ${VERSION}
 
@@ -4168,6 +4020,7 @@ async function main() {
     case "stats": {
       const stats = await corpus.stats();
       const storage = await inspectCorpusStorage(corpus);
+      const maintenance = await readAutomaticMaintenanceState(corpus);
       const platforms = Object.entries(stats.byPlatform).sort((a, b) => b[1] - a[1]).map(([p, n]) => `    ${p}: ${n}`).join("\n");
       process.stdout.write(
         `Corpus: ${root}
@@ -4181,7 +4034,8 @@ ${platforms}
     processed:     ${formatBytes(storage.processed.bytes)} (${storage.processed.files} reclaimable files)
     stale indexes: ${formatBytes(storage.staleIndexes.bytes)}
     quarantine:    ${formatBytes(storage.quarantine.bytes)}
-`
+` + (maintenance ? `  maintenance:   ${formatMaintenanceState(maintenance)}
+` : "")
       );
       return 0;
     }
@@ -4220,7 +4074,7 @@ Corpus now uses ${formatBytes(result.after?.totalBytes ?? 0)}.
       }
       const stale = await staleIndexFiles(corpus.paths.indexDir);
       for (const name of stale) {
-        await deleteIndexDb(join7(corpus.paths.indexDir, name));
+        await deleteIndexDb(join6(corpus.paths.indexDir, name));
       }
       if (stale.length > 0) {
         process.stdout.write(
@@ -4287,6 +4141,18 @@ function formatBytes(bytes) {
   }
   return `${value.toFixed(value >= 10 ? 1 : 2)} ${unit}`;
 }
+function formatMaintenanceState(state) {
+  if (state.status === "complete") {
+    return `complete${state.completedAt ? ` (${new Date(state.completedAt).toISOString()})` : ""}`;
+  }
+  if (state.status === "waiting" && state.nextEligibleAt) {
+    return `automatic cleanup scheduled after ${new Date(state.nextEligibleAt).toISOString()}`;
+  }
+  if (state.status === "failed" && state.nextEligibleAt) {
+    return `will retry after ${new Date(state.nextEligibleAt).toISOString()}`;
+  }
+  return state.status;
+}
 function formatCompactPreview(result) {
   const { before, compression } = result;
   const compressionSavings = Math.max(

package/dist/cli.js

@@ -3,7 +3,7 @@ import { createRequire as __llmnesiaCreateRequire } from "node:module";
 const require = __llmnesiaCreateRequire(import.meta.url);
 import {
   VERSION
-} from "./chunk-JSNSTAFD.js";
+} from "./chunk-BDR4JVMF.js";
 
 // src/nodeDownload.ts
 var NODE_DOWNLOAD_URLS = {
@@ -141,7 +141,7 @@ async function bootstrap() {
     await guideUnsupportedNodeVersion(process.versions.node);
     return 1;
   }
-  const { main } = await import("./cli-ZEA7WTVW.js");
+  const { main } = await import("./cli-OXKBAUBE.js");
   return main();
 }
 bootstrap().then((code) => {

package/dist/mcp.js

@@ -2,20 +2,22 @@
 import { createRequire as __llmnesiaCreateRequire } from "node:module";
 const require = __llmnesiaCreateRequire(import.meta.url);
 import {
+  AUTO_MAINTENANCE_RECHECK_MS,
   Corpus,
   describeOutcome,
   drainInbox,
   openSearchIndex,
   pendingInboxFiles,
   resolveCorpusDir,
+  runAutomaticMaintenance,
   scheduleSelfUpdate
-} from "./chunk-NSVHWVEK.js";
+} from "./chunk-MTPXE734.js";
 import {
   VERSION,
   __commonJS,
   __export,
   __toESM
-} from "./chunk-JSNSTAFD.js";
+} from "./chunk-BDR4JVMF.js";
 
 // ../node_modules/ajv/dist/compile/codegen/code.js
 var require_code = __commonJS({
@@ -21393,6 +21395,9 @@ function describeIssues(error2) {
 
 // src/service.ts
 var STALE_AFTER_HOURS = 48;
+var AUTO_MAINTENANCE_START_DELAY_MS = 6e4;
+var AUTO_MAINTENANCE_IDLE_MS = 3e4;
+var AUTO_MAINTENANCE_BUSY_RETRY_MS = 3e4;
 var CompanionService = class _CompanionService {
   constructor(corpus, index, onDrainError, memoryWriteCap) {
     this.corpus = corpus;
@@ -21409,6 +21414,10 @@ var CompanionService = class _CompanionService {
   refreshChain = Promise.resolve();
   /** Memories written since this process started; the per-session cap counts these. */
   memoriesWritten = 0;
+  activeOperations = 0;
+  lastOperationAt = Date.now();
+  maintenanceTimer;
+  closed = false;
   static async open(root, options = {}) {
     const corpus = new Corpus(root);
     const index = await openSearchIndex(corpus);
@@ -21419,8 +21428,71 @@ var CompanionService = class _CompanionService {
       options.memoryWriteCap ?? DEFAULT_MEMORY_WRITE_CAP
     );
     await service.refresh();
+    if (options.automaticMaintenance) {
+      service.scheduleAutomaticMaintenance(options.automaticMaintenance);
+    }
     return service;
   }
+  /** Let the MCP wrapper expose activity to the idle-only maintenance scheduler. */
+  async runWithActivity(operation) {
+    this.activeOperations += 1;
+    this.lastOperationAt = Date.now();
+    try {
+      return await operation();
+    } finally {
+      this.activeOperations -= 1;
+      this.lastOperationAt = Date.now();
+    }
+  }
+  scheduleAutomaticMaintenance(options) {
+    const {
+      delayMs = AUTO_MAINTENANCE_START_DELAY_MS,
+      idleMs = AUTO_MAINTENANCE_IDLE_MS,
+      busyRetryMs = AUTO_MAINTENANCE_BUSY_RETRY_MS,
+      onOutcome,
+      ...runOptions
+    } = options;
+    const schedule = (delay) => {
+      if (this.closed) return;
+      this.maintenanceTimer = setTimeout(
+        attempt,
+        Math.max(0, Math.min(delay, 2147483647))
+      );
+      this.maintenanceTimer.unref?.();
+    };
+    const attempt = () => {
+      this.maintenanceTimer = void 0;
+      if (this.closed) return;
+      const idleFor = Date.now() - this.lastOperationAt;
+      if (this.activeOperations > 0 || idleFor < idleMs) {
+        schedule(Math.max(busyRetryMs, idleMs - idleFor));
+        return;
+      }
+      void runAutomaticMaintenance(this.corpus, this.index, runOptions).then(
+        (outcome) => {
+          onOutcome?.(outcome);
+          const current = Date.now();
+          if (outcome.action === "deferred") schedule(outcome.until - current);
+          else if (outcome.action === "failed") schedule(outcome.retryAt - current);
+          else if (outcome.action === "locked") schedule(busyRetryMs);
+          else if (outcome.action === "recently-checked") {
+            schedule(outcome.completedAt + (runOptions.recheckMs ?? AUTO_MAINTENANCE_RECHECK_MS) - current);
+          } else if (outcome.action === "compacted" || outcome.action === "no-work") {
+            schedule(runOptions.recheckMs ?? AUTO_MAINTENANCE_RECHECK_MS);
+          }
+        },
+        (error2) => {
+          onOutcome?.({
+            action: "failed",
+            error: error2 instanceof Error ? error2.message : String(error2),
+            retryAt: Date.now() + busyRetryMs
+          });
+          schedule(busyRetryMs);
+        }
+      );
+    };
+    schedule(delayMs);
+  }
   /**
    * Ingest whatever is waiting in `inbox/`. Never throws: a corrupt or
    * unreadable delta is reported and skipped rather than failing the read.
@@ -21547,6 +21619,9 @@ var CompanionService = class _CompanionService {
     };
   }
   close() {
+    this.closed = true;
+    if (this.maintenanceTimer) clearTimeout(this.maintenanceTimer);
+    this.maintenanceTimer = void 0;
     this.index.close();
   }
 };
@@ -21636,12 +21711,28 @@ async function runServe() {
       onDrainError: (error2) => process.stderr.write(
         `llmnesia: inbox drain failed, serving the existing index: ${error2 instanceof Error ? error2.message : String(error2)}
 `
-      )
+      ),
+      automaticMaintenance: {
+        onOutcome: (outcome) => {
+          if (outcome.action === "failed") {
+            process.stderr.write(
+              `llmnesia: automatic storage maintenance will retry later: ${outcome.error}
+`
+            );
+          } else if (outcome.action === "compacted" && outcome.report.reclaimedBytes > 0) {
+            process.stderr.write(
+              `llmnesia: automatic storage maintenance reclaimed ${outcome.report.reclaimedBytes} bytes
+`
+            );
+          }
+        }
+      }
     })
   );
   const withService = async (operation) => {
     try {
-      return await operation(await service.get(5e3));
+      const ready = await service.get(5e3);
+      return await ready.runWithActivity(() => operation(ready));
     } catch (err) {
       if (err instanceof ResourcePreparingError) {
         return errorResult("LLMnesia is still preparing the local conversation index. Retry this tool shortly.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llmnesia/mcp",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "private": false,
   "type": "module",
   "comment:mcpName": "The MCP Registry's ownership marker: it must equal server.json's `name`, and the namespace must match how you authenticate with mcp-publisher. `com.llmnesia/...` requires DNS auth (a TXT record on llmnesia.com) — see docs/MCP_INSTALLER_BOARD.md.",

package/server.json

@@ -3,13 +3,13 @@
   "name": "com.llmnesia/mcp",
   "title": "LLMnesia",
   "description": "Search your AI chat history from Claude, Cursor, Codex, and other MCP clients.",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@llmnesia/mcp",
-      "version": "0.2.4",
+      "version": "0.2.5",
       "transport": {
         "type": "stdio"
       }