@llmnesia/mcp 0.2.7 → 0.2.9

package/README.md

@@ -24,12 +24,19 @@ Claude Desktop step on Windows:
 
 1. Install LLMnesia and import the chat history you want available.
 2. Open **Full settings → Connect desktop AI**.
-3. Follow every step shown for your computer, including fully quitting and
-   reopening the browser and connected AI app when instructed.
+3. Run the exact connector command shown there.
+4. Fully quit and reopen the browser.
+5. Return to **Connect desktop AI** and enable automatic sync.
+
+> **Installing the npm package is not setup.** Running
+> `npm install @llmnesia/mcp` only downloads package files; it does not register
+> the native browser connector or configure desktop AI apps. Use the exact
+> `npx -y @llmnesia/mcp@latest install` command below (or `npx.cmd` on Windows),
+> including the final `install` argument.
 
 The commands below are the connector-install step from that guided flow. They
-are also provided as a reference for technical users; running one by itself is
-not the complete LLMnesia setup.
+are also provided as a reference for technical users; the browser restart and
+permission step are still required afterward.
 
 ### Connector command
 
@@ -64,7 +71,7 @@ The installer:
    corpus,
 2. copies the server into `~/.llmnesia/bin` so it has a permanent home,
 3. sets up the supported desktop AI apps (Claude Code, Cursor,
-   and Codex/ChatGPT), and
+   Codex/ChatGPT, and ZCode), and
 4. registers that copy using the client's own CLI where available, or with an
    automatic backup before editing its documented user config. It prepares all
    of those standard config paths, so an app installed later does not require
@@ -175,24 +182,90 @@ quarantined input.
 
 ## Tools
 
-Once registered, your MCP client gains seven tools over the corpus:
+Once registered, your MCP client gains eight tools over the corpus:
 
 | Tool | Purpose |
 | --- | --- |
 | `search_conversations` | Full-text search across every past conversation. Returns ranked matches with highlighted snippets. Supports `platform`, `title`, `date_from`/`date_to` filters and a `match_mode` (`any` / `all` / `phrase`) for when a wrong hit matters. |
-| `get_conversation` | Fetch the full transcript of one conversation by its id (the `id` field from search results). |
+| `get_conversation` | Fetch the full transcript of one conversation by its id (the `id` field from search results). The response carries `contentFingerprint`, the current fingerprint of the returned transcript (see below). |
 | `list_conversations` | List conversations by chronology, including oldest-first for questions about the user's earliest chat. |
 | `list_recent` | List the most recently updated conversations with title, summary, and platform. |
+| `conversation_inventory` | Paginated, read-only inventory of every conversation as compact metadata: id, platform, title, and a versioned content fingerprint. Built for services that periodically process the corpus; see below. |
 | `corpus_status` | Report when the corpus last received data and how many conversations it holds. Use this when an expected conversation cannot be found, to tell a genuinely missing chat apart from a corpus that has stopped receiving updates. |
 | `save_conversation` | Add or update a conversation in the corpus, so MCP is also an ingestion route. |
 | `save_memory` | Record a durable fact (a decision, preference, or correction) worth carrying into later chats. Stored turned off until the user reviews and enables it. |
 
+### Conversation inventory
+
+`conversation_inventory` exists for programs that periodically process the
+whole corpus, not for interactive questions. Each item is compact metadata:
+the stable `id`, `platform`, `title`, and a versioned content `fingerprint`.
+It never returns transcripts.
+
+Call it with no arguments to start a scan, then pass each page's `nextCursor`
+back as `cursor` until a page comes back without one. Pages hold up to 100
+items (`limit` can go lower):
+
+```json
+{
+  "count": 100,
+  "total": 250,
+  "scanStartedAt": 1769000000000,
+  "items": [
+    { "id": "claude:rust-borrow", "platform": "claude",
+      "title": "Debugging a Rust borrow checker error",
+      "fingerprint": "fp1:9af3c0d7…" }
+  ],
+  "nextCursor": "inv1.eyJzIjoi…"
+}
+```
+
+Every page of a scan reads the same snapshot, captured (sorted by id) when the
+scan started. Conversations that arrive or change while you are paging never
+appear in, disappear from, or change values within an in-flight scan; start a
+new scan (omit `cursor`) to see them. Snapshots are bounded: at most eight are
+held at once (the oldest is evicted) and each expires after about 15 minutes.
+Cursors are opaque, they do not survive an MCP server restart, and an expired
+or unknown cursor returns a clear error telling the caller to begin a new
+scan.
+
+The fingerprint is `fp1:` followed by a SHA-256 hex digest. It covers exactly:
+
+- the conversation title, and the user's local alias (`localTitle`) when set;
+- every message in `msgIndex` order: its index, role, stored `text`, and
+  `formattedText` when present (because `get_conversation` prefers it, a
+  backfill that adds it changes what a caller would receive).
+
+It deliberately excludes every timestamp, including the provider's
+`updatedAt`: historical imports can retain old source dates, and a genuinely
+edited conversation can arrive with its source dates unchanged. URLs, pin
+state, account and model identifiers, summaries, and other derived fields are
+excluded too. An identical re-ingest therefore never changes the fingerprint,
+while an edited message or a rename always does, even when nothing else about
+the record moved. The fingerprint is stored in the derived search index
+(index format v5; opening an older index triggers a rebuild that computes
+fingerprints for the existing corpus), so a scan never decompresses a single
+transcript.
+
+A periodic-processing loop:
+
+1. Scan all pages of `conversation_inventory`, collecting each `id` and
+   `fingerprint`.
+2. Compare with the previous run: an id not seen before is new; a changed
+   fingerprint means that conversation's content changed. Everything else can
+   be skipped.
+3. Call `get_conversation` only for the new or changed ids. Its response
+   carries `contentFingerprint`, the fingerprint of the transcript it returns.
+   If that differs from the inventory entry, the conversation changed after
+   your snapshot was taken and the transcript you just fetched is the current
+   content.
+
 ### Read-only mode (`LLMNESIA_READ_ONLY`)
 
 The Claude Desktop extension (`.mcpb`) ships with `LLMNESIA_READ_ONLY=1`, which
 disables the two write tools (`save_conversation` and `save_memory`) so that
 ordinary history searches run without a per-call approval prompt. The general
-npm install exposes all seven tools.
+npm install exposes all eight tools.
 
 Search and list results carry a `corpus` block saying when the corpus last
 received data — check it before concluding a chat does not exist.
@@ -205,6 +278,7 @@ received data — check it before concluding a chat does not exist.
 | Claude Desktop | macOS uses the working local JSON registration. On Windows, run `install` for browser sync, then install the official `llmnesia.mcpb` once in Claude Desktop; Claude exposes no supported external installation API for custom desktop extensions. |
 | Cursor | Edits `~/.cursor/mcp.json`, preparing it in advance if Cursor is installed later. |
 | Codex / ChatGPT desktop | Runs `codex mcp add` with the absolute runtime paths when available. If the bundled CLI is unavailable, the installer safely edits `~/.codex/config.toml` itself and backs up existing settings first, including preparing it for a later installation. Read-only LLMnesia tools are configured to run without repeated approval prompts; writes still ask. |
+| ZCode | Edits the user-scope `~/.zcode/cli/config.json`, adding the server under ZCode's nested `mcp.servers` key with a backup first, and prepares that file in advance if ZCode is installed later. ZCode validates this file strictly and connects servers from it automatically at session start. |
 | Others (Windsurf, Zed, LM Studio, …) | Prints the generic stdio block for you to paste. |
 
 **Cloud-only clients cannot reach a local stdio server** (web ChatGPT, Lovable,

package/dist/{chunk-O34A5U2L.js → chunk-BWEDXPNM.js}

@@ -3,7 +3,7 @@ import { createRequire as __llmnesiaCreateRequire } from "node:module";
 const require = __llmnesiaCreateRequire(import.meta.url);
 import {
   VERSION
-} from "./chunk-CMQHGLAD.js";
+} from "./chunk-YT6GNKKG.js";
 
 // src/config.ts
 import { readFileSync } from "fs";
@@ -47,7 +47,7 @@ function expandHome(p) {
 import { join as join2 } from "path";
 import { readdir } from "fs/promises";
 import { createHash } from "crypto";
-var INDEX_FORMAT_VERSION = 4;
+var INDEX_FORMAT_VERSION = 5;
 function indexDbFilename(version) {
   return version === 1 ? "llmnesia.db" : `llmnesia-v${version}.db`;
 }
@@ -198,6 +198,8 @@ function canonicalConversationDoc(c) {
     indexLevel: c.indexLevel,
     estimatedBytes: c.estimatedBytes
   };
+  assignIfDefined(out, "localTitle", c.localTitle);
+  assignIfDefined(out, "localTitleUpdatedAt", c.localTitleUpdatedAt);
   assignIfDefined(out, "searchDocLength", c.searchDocLength);
   assignIfDefined(out, "contentHash", c.contentHash);
   assignIfDefined(out, "truncated", c.truncated);
@@ -208,6 +210,13 @@ function canonicalConversationDoc(c) {
   assignIfDefined(out, "origin", c.origin);
   assignIfDefined(out, "accountId", c.accountId);
   assignIfDefined(out, "accountLabel", c.accountLabel);
+  if (c.providerProject) {
+    out.providerProject = {
+      projectId: c.providerProject.projectId,
+      source: c.providerProject.source,
+      observedAt: c.providerProject.observedAt
+    };
+  }
   if (c.models && c.models.length > 0) out.models = [...c.models];
   assignIfDefined(out, "modelMetadataUpdatedAt", c.modelMetadataUpdatedAt);
   if (c.summary) {
@@ -938,6 +947,26 @@ function accumulate(total, report) {
   total.malformedLines += report.malformedLines;
 }
 
+// src/fingerprint.ts
+import { createHash as createHash2 } from "crypto";
+var FINGERPRINT_SCHEME = "fp1";
+function fingerprintConversation(record) {
+  const conversation = record.conversation;
+  const payload = {
+    v: 1,
+    title: conversation.title,
+    localTitle: conversation.localTitle ?? null,
+    messages: [...record.messages].sort((a, b) => a.msgIndex - b.msgIndex).map((message) => ({
+      i: message.msgIndex,
+      r: message.role,
+      t: message.text,
+      f: message.formattedText ?? null
+    }))
+  };
+  const digest = createHash2("sha256").update(JSON.stringify(payload), "utf8").digest("hex");
+  return `${FINGERPRINT_SCHEME}:${digest}`;
+}
+
 // src/searchIndex.ts
 import { promises as fs3, chmodSync, closeSync, openSync } from "fs";
 import { createRequire } from "module";
@@ -1015,7 +1044,8 @@ CREATE TABLE IF NOT EXISTS conversations (
   pinned INTEGER NOT NULL,
   accountId TEXT,
   accountLabel TEXT,
-  models TEXT
+  models TEXT,
+  fingerprint TEXT NOT NULL
 );
 CREATE INDEX IF NOT EXISTS idx_conversations_platform ON conversations(platform);
 CREATE INDEX IF NOT EXISTS idx_conversations_createdAt ON conversations(createdAt);
@@ -1089,8 +1119,8 @@ var SearchIndex = class {
       deleteConversation: this.db.prepare("DELETE FROM conversations WHERE docId = ?"),
       insertConversation: this.db.prepare(
         `INSERT INTO conversations
-           (docId, platform, title, url, createdAt, updatedAt, messageCount, preview, pinned, accountId, accountLabel, models)
-         VALUES (@docId, @platform, @title, @url, @createdAt, @updatedAt, @messageCount, @preview, @pinned, @accountId, @accountLabel, @models)`
+           (docId, platform, title, url, createdAt, updatedAt, messageCount, preview, pinned, accountId, accountLabel, models, fingerprint)
+         VALUES (@docId, @platform, @title, @url, @createdAt, @updatedAt, @messageCount, @preview, @pinned, @accountId, @accountLabel, @models, @fingerprint)`
       ),
       deleteMemoryFts: this.db.prepare("DELETE FROM memories_fts WHERE memoryId = ?"),
       insertMemoryFts: this.db.prepare(
@@ -1147,6 +1177,17 @@ var SearchIndex = class {
       return entry;
     });
   }
+  /**
+   * The full conversation inventory as compact metadata, sorted by stable
+   * docId. One statement, so the caller's snapshot is a consistent cut of the
+   * index (new conversations and edits that commit after this read belong to
+   * the next scan), and no transcript is ever decompressed: fingerprints are
+   * computed at upsert/rebuild time and stored in the index.
+   */
+  inventoryRows() {
+    const rows = this.db.prepare("SELECT docId, platform, title, fingerprint FROM conversations ORDER BY docId ASC").all();
+    return rows.map((r) => ({ id: r.docId, platform: r.platform, title: r.title, fingerprint: r.fingerprint }));
+  }
   /**
    * Run `fn` inside a transaction, rolling back if it throws. node:sqlite has
    * no transaction() wrapper, so this is the one place BEGIN/COMMIT/ROLLBACK
@@ -1208,9 +1249,14 @@ var SearchIndex = class {
   // transaction() helper for single upserts, or rebuildFrom's manual one).
   writeRecord(rec) {
     const { conversation, messages } = rec;
+    const displayTitle = conversation.localTitle?.trim() || conversation.title;
     this.deleteFtsRows(conversation.docId);
     this.stmts.deleteConversation.run(conversation.docId);
-    const titleText = [conversation.title, conversation.preview].filter(Boolean).join("\n");
+    const titleText = [
+      ...conversation.localTitle ? [conversation.localTitle, conversation.localTitle] : [],
+      conversation.title,
+      conversation.preview
+    ].filter(Boolean).join("\n");
     if (titleText.trim()) {
       this.insertFtsRow(conversation.docId, TITLE_ROW_INDEX, TITLE_ROLE, titleText);
     }
@@ -1222,7 +1268,7 @@ var SearchIndex = class {
     this.stmts.insertConversation.run({
       docId: conversation.docId,
       platform: conversation.platform,
-      title: conversation.title,
+      title: displayTitle,
       url: conversation.url,
       createdAt: conversation.createdAt,
       updatedAt: conversation.updatedAt ?? conversation.contentUpdatedAt ?? 0,
@@ -1231,7 +1277,8 @@ var SearchIndex = class {
       pinned: conversation.pinned ? 1 : 0,
       accountId: conversation.accountId ?? null,
       accountLabel: conversation.accountLabel ?? null,
-      models: conversation.models?.length ? JSON.stringify(conversation.models) : null
+      models: conversation.models?.length ? JSON.stringify(conversation.models) : null,
+      fingerprint: fingerprintConversation(rec)
     });
   }
   insertFtsRow(docId, msgIndex, role, text) {
@@ -1350,7 +1397,11 @@ var SearchIndex = class {
   }
   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;
+    const source = row.msgIndex === TITLE_ROW_INDEX ? [
+      record?.conversation.localTitle,
+      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);
@@ -2099,6 +2150,7 @@ export {
   ingestFile,
   pendingInboxFiles,
   drainInbox,
+  fingerprintConversation,
   SearchIndex,
   openSearchIndex,
   deleteIndexDb,

package/dist/{chunk-CMQHGLAD.js → chunk-YT6GNKKG.js}

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

package/dist/{cli-XQUMZ3BU.js → cli-KHY7ADCU.js}

@@ -17,13 +17,13 @@ import {
   runtimeBinDir,
   staleIndexFiles,
   uninstallRuntime
-} from "./chunk-O34A5U2L.js";
+} from "./chunk-BWEDXPNM.js";
 import {
   VERSION,
   __commonJS,
   __require,
   __toESM
-} from "./chunk-CMQHGLAD.js";
+} from "./chunk-YT6GNKKG.js";
 
 // ../node_modules/isexe/windows.js
 var require_windows = __commonJS({
@@ -543,6 +543,7 @@ var STORE_EXTENSION_ID = "leekfgbdojiaabifbjbbgiiclannjdkf";
 var here = dirname(fileURLToPath(import.meta.url));
 var home = homedir();
 var CLAUDE_PROJECTS_DIR = join(home, ".claude", "projects");
+var ZCODE_DB = join(home, ".zcode", "cli", "db", "db.sqlite");
 var osPlatform = process.env.LLMNESIA_FAKE_PLATFORM || platform();
 function expandHome(p) {
   if (p === "~") {
@@ -708,7 +709,7 @@ async function installNativeHost({ ids = [], corpus, codexHome, force = false, q
   log("\u2713 Helper installed");
   const manifestBase = {
     name: HOST_NAME,
-    description: "LLMnesia \u2014 reads local Claude Code and Codex sessions",
+    description: "LLMnesia: reads local Claude Code, Codex, and ZCode sessions",
     type: "stdio",
     allowed_origins: allowedOrigins
   };
@@ -742,9 +743,10 @@ async function installNativeHost({ ids = [], corpus, codexHome, force = false, q
     log(`  Conversation data: ${corpusRoot}`);
     log(`  Codex data: ${resolvedCodexHome}`);
   }
-  const [hasClaudeCode, hasCodex] = await Promise.all([
+  const [hasClaudeCode, hasCodex, hasZcode] = await Promise.all([
     exists(CLAUDE_PROJECTS_DIR),
-    exists(join(resolvedCodexHome, "sessions"))
+    exists(join(resolvedCodexHome, "sessions")),
+    exists(ZCODE_DB)
   ]);
   log("");
   log(
@@ -753,6 +755,9 @@ async function installNativeHost({ ids = [], corpus, codexHome, force = false, q
   log(
     hasCodex ? `\u2713 Found Codex sessions at ${resolvedCodexHome}` : `\u2013 No Codex sessions found yet (fine if you don't use Codex).`
   );
+  log(
+    hasZcode ? `\u2713 Found ZCode sessions at ${ZCODE_DB}` : `\u2013 No ZCode sessions found yet (fine if you don't use ZCode).`
+  );
   const extraIdCount = allIds.length - 1;
   if (extraIdCount > 0) {
     log(`\u2713 Also authorized ${extraIdCount} unpacked extension ${extraIdCount === 1 ? "build" : "builds"}`);
@@ -2841,7 +2846,8 @@ function paths(home2, osPlatform2, appData) {
     claudeCode: join4(claudeCodeRoot, ".claude.json"),
     claudeDesktop,
     cursor: join4(home2, ".cursor", "mcp.json"),
-    codex: join4(home2, ".codex", "config.toml")
+    codex: join4(home2, ".codex", "config.toml"),
+    zcode: join4(home2, ".zcode", "cli", "config.json")
   };
 }
 async function readJsonFile(path) {
@@ -2873,6 +2879,38 @@ function mcpServersOf(data, configPath) {
   }
   return data.mcpServers;
 }
+function nestedMcpServersOf(data, configPath) {
+  if (data.mcp === void 0) {
+    return {};
+  }
+  if (!data.mcp || typeof data.mcp !== "object" || Array.isArray(data.mcp)) {
+    throw new Error(`Could not update ${configPath}: "mcp" must be a JSON object. The file was left unchanged.`);
+  }
+  const mcp = data.mcp;
+  if (mcp.servers === void 0) {
+    return {};
+  }
+  if (!mcp.servers || typeof mcp.servers !== "object" || Array.isArray(mcp.servers)) {
+    throw new Error(
+      `Could not update ${configPath}: "mcp.servers" must be a JSON object. The file was left unchanged.`
+    );
+  }
+  return mcp.servers;
+}
+function asObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+var topLevelServers = {
+  read: (data, configPath) => mcpServersOf(data, configPath),
+  merge: (data, servers) => ({ ...data, mcpServers: servers }),
+  preview: (entry) => JSON.stringify({ mcpServers: { [SERVER_NAME]: entry } }, null, 2)
+};
+var zcodeNestedServers = {
+  read: (data, configPath) => nestedMcpServersOf(data, configPath),
+  // Keep any other settings ZCode stores beside `servers` inside its `mcp` key.
+  merge: (data, servers) => ({ ...data, mcp: { ...asObject(data.mcp), servers } }),
+  preview: (entry) => JSON.stringify({ mcp: { servers: { [SERVER_NAME]: entry } } }, null, 2)
+};
 function isErrnoException(value) {
   return value instanceof Error && "code" in value;
 }
@@ -3091,7 +3129,7 @@ codex mcp add ${SERVER_NAME} -- ${serve.command} ${serve.args.join(" ")}`
     detail: `Ran: codex mcp add ${SERVER_NAME} -- ${serve.command} ${serve.args.join(" ")}`
   };
 }
-async function registerJsonClient(clientLabel, configPath, serve, confirm, now, prepareMissing = false, prepareWhenConfigAbsent = false, includeTransportType = true) {
+async function registerJsonClient(clientLabel, configPath, serve, confirm, now, prepareMissing = false, prepareWhenConfigAbsent = false, includeTransportType = true, layout = topLevelServers) {
   const configDirExists = await clientDirExists(configPath);
   if (!configDirExists && !prepareMissing) {
     return {
@@ -3117,7 +3155,7 @@ async function registerJsonClient(clientLabel, configPath, serve, confirm, now,
   }
   let servers;
   try {
-    servers = mcpServersOf(data, configPath);
+    servers = layout.read(data, configPath);
   } catch (err) {
     return { client: clientLabel, action: "error", detail: errorMessage(err) };
   }
@@ -3126,7 +3164,7 @@ async function registerJsonClient(clientLabel, configPath, serve, confirm, now,
   if (already && JSON.stringify(already) === JSON.stringify(nextEntry)) {
     return { client: clientLabel, action: "skipped", detail: `Already registered at ${configPath}.` };
   }
-  const preview = JSON.stringify({ mcpServers: { [SERVER_NAME]: nextEntry } }, null, 2);
+  const preview = layout.preview(nextEntry);
   const message = existed ? `${clientLabel}: update ${configPath} to add the "${SERVER_NAME}" MCP server? Existing servers and settings are preserved.
 Add:
 ${preview}` : `${clientLabel}: create ${configPath} with the "${SERVER_NAME}" MCP server?
@@ -3140,7 +3178,7 @@ ${preview}`;
       const backupPath = `${configPath}.bak-${now()}`;
       await writeFile2(backupPath, raw ?? JSON.stringify(data, null, 2), "utf8");
     }
-    const nextData = { ...data, mcpServers: { ...servers, [SERVER_NAME]: nextEntry } };
+    const nextData = layout.merge(data, { ...servers, [SERVER_NAME]: nextEntry });
     await writeFile2(configPath, `${JSON.stringify(nextData, null, 2)}
 `, "utf8");
     return {
@@ -3245,7 +3283,7 @@ async function registerClients(options) {
   const osPlatform2 = options.osPlatform ?? platform2();
   const now = options.now ?? (() => Date.now());
   const prepareMissing = options.prepareMissingDesktopApps === true;
-  const { claudeCode, claudeDesktop, cursor, codex } = paths(home2, osPlatform2, options.appData);
+  const { claudeCode, claudeDesktop, cursor, codex, zcode } = paths(home2, osPlatform2, options.appData);
   const results = [];
   const safe = async (client, fn) => {
     try {
@@ -3292,6 +3330,22 @@ async function registerClients(options) {
       () => registerCodex(options.serve, options.codexCli ?? realCodexCli, codex, options.confirm, now, prepareMissing)
     )
   );
+  results.push(
+    await safe(
+      "ZCode",
+      () => registerJsonClient(
+        "ZCode",
+        zcode,
+        options.serve,
+        options.confirm,
+        now,
+        prepareMissing,
+        false,
+        true,
+        zcodeNestedServers
+      )
+    )
+  );
   results.push({
     client: "Other MCP clients (Windsurf, Zed, LM Studio, ...)",
     action: "printed",
@@ -3368,7 +3422,7 @@ async function unregisterCodex(cli, configPath, now) {
     return { client: "Codex", action: "error", detail: `codex mcp remove failed: ${errorMessage(err)}` };
   }
 }
-async function unregisterJsonClient(clientLabel, configPath, now) {
+async function unregisterJsonClient(clientLabel, configPath, now, layout = topLevelServers) {
   let data;
   let existed;
   let raw;
@@ -3382,7 +3436,7 @@ async function unregisterJsonClient(clientLabel, configPath, now) {
   }
   let servers;
   try {
-    servers = mcpServersOf(data, configPath);
+    servers = layout.read(data, configPath);
   } catch (err) {
     return { client: clientLabel, action: "error", detail: errorMessage(err) };
   }
@@ -3393,7 +3447,7 @@ async function unregisterJsonClient(clientLabel, configPath, now) {
   try {
     await writeFile2(backupPath, raw ?? JSON.stringify(data, null, 2), "utf8");
     const { [SERVER_NAME]: _removed, ...rest } = servers;
-    const nextData = { ...data, mcpServers: rest };
+    const nextData = layout.merge(data, rest);
     await writeFile2(configPath, `${JSON.stringify(nextData, null, 2)}
 `, "utf8");
     return { client: clientLabel, action: "registered", detail: `Removed from ${configPath} (backup: ${backupPath}).` };
@@ -3405,7 +3459,7 @@ async function unregisterClients(options = {}) {
   const home2 = options.home ?? homedir2();
   const osPlatform2 = options.osPlatform ?? platform2();
   const now = options.now ?? (() => Date.now());
-  const { claudeDesktop, cursor, codex } = paths(home2, osPlatform2);
+  const { claudeDesktop, cursor, codex, zcode } = paths(home2, osPlatform2);
   const safe = async (client, fn) => {
     try {
       return await fn();
@@ -3421,6 +3475,7 @@ async function unregisterClients(options = {}) {
   }
   results.push(await safe("Cursor", () => unregisterJsonClient("Cursor", cursor, now)));
   results.push(await safe("Codex", () => unregisterCodex(options.codexCli ?? realCodexCli, codex, now)));
+  results.push(await safe("ZCode", () => unregisterJsonClient("ZCode", zcode, now, zcodeNestedServers)));
   results.push({
     client: "Other MCP clients",
     action: "skipped",
@@ -3592,7 +3647,7 @@ function checkAutoUpdate(home2, env) {
   const latest = state.lastSeenVersion ? `; latest published ${state.lastSeenVersion}` : "";
   return { name, status: "ok", detail: `On. Last checked ${checkedAt}${latest}.` };
 }
-async function checkJsonClient(label, configPath) {
+async function checkJsonClient(label, configPath, nestedServers = false) {
   if (!existsSync(dirname5(configPath))) {
     return { name: label, status: "warn", detail: `Not installed (no ${dirname5(configPath)}).` };
   }
@@ -3605,7 +3660,8 @@ async function checkJsonClient(label, configPath) {
   }
   try {
     const data = JSON.parse(readFileSync(configPath, "utf8"));
-    const entry = data.mcpServers?.[SERVER_NAME];
+    const servers = nestedServers ? data.mcp?.servers : data.mcpServers;
+    const entry = servers?.[SERVER_NAME];
     if (!entry) {
       return {
         name: label,
@@ -3741,6 +3797,7 @@ async function runDoctor(options = {}) {
   await run("Cursor", () => checkJsonClient("Cursor", join5(home2, ".cursor", "mcp.json")));
   await run("Claude Code", () => checkClaudeCode(claudeCli));
   await run("Codex", () => checkCodex(home2, codexCli));
+  await run("ZCode", () => checkJsonClient("ZCode", join5(home2, ".zcode", "cli", "config.json"), true));
   checks.push({
     name: "Reminder",
     status: "warn",
@@ -3760,7 +3817,8 @@ Usage: llmnesia-mcp <command> [options]
 
 Setup:
   install [ext-id...]  Install the native host + register this MCP server with
-                        detected clients (Claude Code/Desktop, Cursor, Codex, ...)
+                        detected clients (Claude Code/Desktop, Cursor, Codex,
+                        ZCode, ...)
   doctor                Diagnose: host installed? corpus present? clients wired?
   uninstall             Remove native host + client registrations (never deletes
                         your corpus \u2014 see the printed path if you want that too)

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-CMQHGLAD.js";
+} from "./chunk-YT6GNKKG.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-XQUMZ3BU.js");
+  const { main } = await import("./cli-KHY7ADCU.js");
   return main();
 }
 bootstrap().then((code) => {

package/dist/llmnesia-claude-host.mjs

@@ -1,34 +1,40 @@
 #!/usr/bin/env node
 // LLMnesia native messaging host — reads local coding-agent sessions (Claude
-// Code from ~/.claude/projects, Codex from the configured Codex home) and
-// streams them to the LLMnesia browser extension, and writes corpus sync deltas
-// the extension sends back into the LLMnesia corpus's inbox/ directory (see
-// packages/../companion/src/paths.ts).
+// Code from ~/.claude/projects, Codex from the configured Codex home, ZCode
+// from ~/.zcode/cli/db/db.sqlite) and streams them to the LLMnesia browser
+// extension, and writes corpus sync deltas the extension sends back into the
+// LLMnesia corpus's inbox/ directory (see packages/../companion/src/paths.ts).
 //
-// It reads .jsonl session files under those two roots, and writes only inside
-// the corpus root named in its own config (~/.llmnesia/config.json) — never a
-// path the caller supplies. It makes no network calls. The browser launches it
-// on demand (see the installed com.llmnesia.claude_code.json manifest) and
-// talks to it over stdio using Chrome's native-messaging framing: a
-// little-endian uint32 byte-length prefix followed by that many bytes of UTF-8
-// JSON, in both directions.
+// It reads .jsonl session files under the first two roots, materializes ZCode
+// sessions out of its SQLite database, and writes only inside the corpus root
+// named in its own config (~/.llmnesia/config.json) — never a path the caller
+// supplies. It makes no network calls. The browser launches it on demand (see
+// the installed com.llmnesia.claude_code.json manifest) and talks to it over
+// stdio using Chrome's native-messaging framing: a little-endian uint32
+// byte-length prefix followed by that many bytes of UTF-8 JSON, in both
+// directions.
 //
 // The write path only ever activates for a user who has explicitly run the
 // installer with --corpus (see install.mjs) to opt into the MCP companion;
 // without ~/.llmnesia/config.json this host is exactly as read-only as it
 // has always been for plain session indexing.
 //
-// Protocol v3 (extension → host). v1 was Claude-Code-only: `list` carried no
+// Protocol v4 (extension → host). v1 was Claude-Code-only: `list` carried no
 // `source` and `get` took a bare sessionId. Both remain accepted, so an
 // extension older than this host keeps working; an extension NEWER than the
 // host detects v1 from the pong and syncs Claude Code only.
 //
+// v4 adds ZCode to `list`/`get` (the first source backed by a SQLite database
+// rather than per-session files; `get` materializes the transcript as JSONL).
+// The version is informational in both directions, as below: a v3 host never
+// lists zcode, and an extension gates the ZCode row on the reported version.
+//
 // v3 adds `listMemories`, the RC-03 reverse channel. A v2 host answers it with
 // `{ type: "error", error: "unknown command: listMemories" }` and the extension
 // treats that as "nothing to fetch", so the version is informational: hosts are
 // installed out of band and an extension upgraded ahead of its host is the
 // ordinary case, not a fault.
-//   { cmd: "ping" }                    → { type: "pong", version: 3 }
+//   { cmd: "ping" }                    → { type: "pong", version: 4 }
 //   { cmd: "list" }                    → { type: "list", sessions:
 //                                          [{source, sessionId, mtime, project?, title?}] }
 //   { cmd: "get", source, sessionId }  → one or more { type: "chunk", sessionId, seq, total, data }
@@ -53,14 +59,17 @@ import { chmod, mkdir, readdir, readFile, rename, stat, writeFile } from "node:f
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-// 3 adds `listMemories` (RC-03). A v2 host answers that command with
-// `{ type: "error", error: "unknown command: listMemories" }`, which the
-// extension treats as "this host is too old, there is nothing to fetch" — so
-// bumping this is informational, not a gate. Do not make it a gate: hosts are
-// installed out of band and a version check would strand every user who
+// 4 adds ZCode (see the protocol comment above). Do not make it a gate: hosts
+// are installed out of band and a version check would strand every user who
 // upgraded the extension first.
-const PROTOCOL_VERSION = 3;
+const PROTOCOL_VERSION = 4;
 const PROJECTS_DIR = join(homedir(), ".claude", "projects");
+// ZCode keeps every session in one SQLite database (WAL mode) — the first
+// source with no per-session file. The host opens it READ-ONLY and materializes
+// a session into the JSONL shape extension/src/background/zcode_import.ts
+// parses. node:sqlite is imported lazily so a Node without it (older than
+// 22.13) keeps serving every other source: ZCode just lists zero sessions.
+const ZCODE_DB = join(homedir(), ".zcode", "cli", "db", "db.sqlite");
 const CONFIG_FILE = join(homedir(), ".llmnesia", "config.json");
 // Codex's home, resolved at install time (--codex-home > CODEX_HOME > ~/.codex)
 // and persisted into config.json. The env var is read here too so a host
@@ -235,6 +244,192 @@ async function listCodexSessions(codexHome) {
   return sessions;
 }
 
+// --- ZCode (SQLite source) -------------------------------------------------
+
+let sqliteModule; // undefined = not yet imported, null = unavailable on this Node
+async function getSqlite() {
+  if (sqliteModule === undefined) {
+    try {
+      sqliteModule = await import("node:sqlite");
+    } catch {
+      sqliteModule = null; // Node without node:sqlite (< 22.13): degrade quietly
+    }
+  }
+  return sqliteModule;
+}
+
+async function openZcodeDb() {
+  const sqlite = await getSqlite();
+  if (!sqlite) {
+    return null;
+  }
+  try {
+    // readOnly: the database is ZCode's live WAL database, often being written
+    // as we read it. Opening read-only fails cleanly when the file is absent.
+    return new sqlite.DatabaseSync(ZCODE_DB, { readOnly: true });
+  } catch {
+    return null; // no ZCode install, or the db is momentarily unreadable
+  }
+}
+
+/**
+ * Interactive ZCode sessions. Subagent runs (`task_type = 'subagent_child'`)
+ * are the harness's internal workers, not chats the user searched for, so they
+ * stay out of the listing. `title_source = 'default'` marks a placeholder
+ * title ("New Session"); only real titles are attached, so the extension's
+ * derived "<project> · <first prompt>" still wins when ZCode has no name.
+ */
+async function listZcodeSessions() {
+  const db = await openZcodeDb();
+  if (!db) {
+    return [];
+  }
+  try {
+    const rows = db
+      .prepare(
+        `SELECT id, title, title_source, time_updated, task_type
+         FROM session
+         WHERE task_type = 'interactive' OR task_type IS NULL`
+      )
+      .all();
+    const sessions = [];
+    for (const row of rows) {
+      const updated = Math.floor(Number(row.time_updated));
+      if (!Number.isFinite(updated) || updated <= 0) {
+        continue;
+      }
+      const session = {
+        source: "zcode",
+        sessionId: String(row.id),
+        mtime: updated,
+        path: ZCODE_DB
+      };
+      if (typeof row.title === "string" && row.title && row.title_source !== "default") {
+        session.title = row.title;
+      }
+      sessions.push(session);
+    }
+    return sessions;
+  } catch {
+    return []; // unreadable or mid-migration database — ZCode contributes nothing
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Build one ZCode session's transcript as JSONL for the extension parser: a
+ * `session` header line naming the project directory, then one `message` line
+ * per user/assistant prose turn. Only text parts survive; parts flagged
+ * `synthetic` (ZCode-injected bookkeeping such as `<task-notification>`) are
+ * dropped here and defensively re-checked in the parser. Multi-part messages
+ * are joined with a blank line, mirroring how the file-based parsers treat
+ * text blocks.
+ *
+ * Returns null when the session id is unknown (or node:sqlite is unavailable —
+ * a session that could not be listed cannot be fetched either).
+ */
+async function materializeZcodeSession(sessionId) {
+  const db = await openZcodeDb();
+  if (!db) {
+    return null;
+  }
+  try {
+    const sessionRow = db.prepare("SELECT directory FROM session WHERE id = ?").get(sessionId);
+    if (!sessionRow) {
+      return null;
+    }
+    const lines = [];
+    const header = { type: "session" };
+    if (typeof sessionRow.directory === "string" && sessionRow.directory) {
+      header.directory = sessionRow.directory;
+    }
+    lines.push(JSON.stringify(header));
+
+    const rows = db
+      .prepare(
+        `SELECT m.id, m.time_created, m.data AS message_data, p.data AS part_data
+         FROM part p JOIN message m ON m.id = p.message_id
+         WHERE m.session_id = ?
+         ORDER BY m.sequence, p.sequence`
+      )
+      .all(sessionId);
+
+    // Rows arrive grouped by message (ORDER BY m.sequence, p.sequence), so a
+    // message's parts are contiguous: accumulate one outgoing line per group.
+    let currentId = null;
+    let current = null;
+    const flush = () => {
+      if (!current) {
+        return;
+      }
+      const text = current.texts.join("\n\n").trim();
+      if (text) {
+        const line = { type: "message", role: current.role, text };
+        if (current.timestamp !== undefined) {
+          line.timestamp = current.timestamp;
+        }
+        if (current.role === "assistant" && current.model) {
+          line.model = current.model;
+        }
+        lines.push(JSON.stringify(line));
+      }
+      current = null;
+    };
+    for (const row of rows) {
+      if (row.id !== currentId) {
+        flush();
+        currentId = row.id;
+        let meta = null;
+        try {
+          meta = JSON.parse(row.message_data);
+        } catch {
+          meta = null;
+        }
+        const role = meta && meta.role === "assistant" ? "assistant" : meta && meta.role === "user" ? "user" : null;
+        if (!role) {
+          current = null; // unknown shape — drop the whole message, keep the rest
+          continue;
+        }
+        const dataTs = meta && meta.time && typeof meta.time.created === "number" ? meta.time.created : undefined;
+        current = {
+          role,
+          texts: [],
+          timestamp:
+            dataTs !== undefined
+              ? dataTs
+              : typeof row.time_created === "number"
+                ? row.time_created
+                : undefined,
+          model: role === "assistant" && typeof meta.modelID === "string" && meta.modelID ? meta.modelID : null
+        };
+      }
+      if (!current) {
+        continue;
+      }
+      let part = null;
+      try {
+        part = JSON.parse(row.part_data);
+      } catch {
+        part = null;
+      }
+      if (!part || part.type !== "text" || part.synthetic === true || typeof part.text !== "string") {
+        continue;
+      }
+      const text = part.text.trim();
+      if (text) {
+        current.texts.push(text);
+      }
+    }
+    flush();
+    return lines.join("\n");
+  } catch {
+    return null;
+  } finally {
+    db.close();
+  }
+}
+
 /**
  * Every session across every source. Sources are listed independently and
  * failures are contained per source (each helper swallows its own errors), so
@@ -244,11 +439,12 @@ async function listCodexSessions(codexHome) {
 async function listSessions() {
   const config = await loadConfig();
   const codexHome = config?.codexHome || DEFAULT_CODEX_HOME;
-  const [claude, codex] = await Promise.all([
+  const [claude, codex, zcode] = await Promise.all([
     listClaudeCodeSessions().catch(() => []),
-    listCodexSessions(codexHome).catch(() => [])
+    listCodexSessions(codexHome).catch(() => []),
+    listZcodeSessions().catch(() => [])
   ]);
-  return [...claude, ...codex];
+  return [...claude, ...codex, ...zcode];
 }
 
 async function loadConfig() {
@@ -469,18 +665,31 @@ async function handle(message) {
     return;
   }
   if (message.cmd === "get") {
-    const sessions = await listSessions();
     // Session ids are only unique WITHIN a source, so a v2 caller names both.
     // A v1 caller sends no source; everything it knows about is Claude Code, so
     // that's what an absent source resolves to — never a bare id match that
     // could hand back the wrong source's file.
     const wantSource = typeof message.source === "string" ? message.source : "claude_code";
-    const match = sessions.find((s) => s.source === wantSource && s.sessionId === message.sessionId);
-    if (!match) {
-      send({ type: "session", sessionId: message.sessionId, notFound: true });
-      return;
+    let text;
+    if (wantSource === "zcode") {
+      // No file to read: the transcript is materialized out of the database.
+      // The session id is only ever a bound query parameter, never a path
+      // component, so the trust boundary holds unchanged.
+      const materialized = await materializeZcodeSession(String(message.sessionId ?? ""));
+      if (materialized === null) {
+        send({ type: "session", sessionId: message.sessionId, notFound: true });
+        return;
+      }
+      text = materialized;
+    } else {
+      const sessions = await listSessions();
+      const match = sessions.find((s) => s.source === wantSource && s.sessionId === message.sessionId);
+      if (!match) {
+        send({ type: "session", sessionId: message.sessionId, notFound: true });
+        return;
+      }
+      text = await readFile(match.path, "utf8");
     }
-    const text = await readFile(match.path, "utf8");
     const total = Math.max(1, Math.ceil(text.length / CHUNK_CHARS));
     for (let i = 0, seq = 0; seq < total; i += CHUNK_CHARS, seq++) {
       send({

package/dist/mcp.js

@@ -6,19 +6,20 @@ import {
   Corpus,
   describeOutcome,
   drainInbox,
+  fingerprintConversation,
   openSearchIndex,
   pendingInboxFiles,
   readNativeHostViewerExtensionId,
   resolveCorpusDir,
   runAutomaticMaintenance,
   scheduleSelfUpdate
-} from "./chunk-O34A5U2L.js";
+} from "./chunk-BWEDXPNM.js";
 import {
   VERSION,
   __commonJS,
   __export,
   __toESM
-} from "./chunk-CMQHGLAD.js";
+} from "./chunk-YT6GNKKG.js";
 
 // ../node_modules/ajv/dist/compile/codegen/code.js
 var require_code = __commonJS({
@@ -21141,6 +21142,109 @@ import { realpathSync } from "fs";
 import { fileURLToPath } from "url";
 import path from "path";
 
+// src/inventory.ts
+import { randomBytes } from "crypto";
+var InventoryCursorError = class extends Error {
+};
+var DEFAULT_INVENTORY_TTL_MS = 15 * 6e4;
+var MAX_INVENTORY_SNAPSHOTS = 8;
+var CURSOR_PREFIX = "inv1.";
+var DEFAULT_PAGE_LIMIT = 100;
+var MAX_PAGE_LIMIT = 100;
+var CURSOR_ERROR_MESSAGE = "The inventory cursor cannot be served: it is malformed, it has expired, it was evicted by newer scans, or the MCP server that created it was restarted. Begin a new scan by calling conversation_inventory again without a cursor.";
+var InventoryScanner = class {
+  constructor(loadRows, options = {}) {
+    this.loadRows = loadRows;
+    this.options = options;
+  }
+  loadRows;
+  options;
+  snapshots = /* @__PURE__ */ new Map();
+  page(cursor, limit) {
+    const pageSize = Math.min(MAX_PAGE_LIMIT, Math.max(1, limit ?? DEFAULT_PAGE_LIMIT));
+    if (cursor === void 0 || cursor === "") {
+      return this.startScan(pageSize);
+    }
+    const { snapshotId, offset } = decodeCursor(cursor);
+    const snapshot = this.snapshots.get(snapshotId);
+    if (!snapshot || Date.now() - snapshot.createdAt > this.ttlMs()) {
+      this.snapshots.delete(snapshotId);
+      throw new InventoryCursorError(CURSOR_ERROR_MESSAGE);
+    }
+    return this.slice(snapshot, offset, pageSize);
+  }
+  /** Drop all snapshots (called when the owning service closes). */
+  clear() {
+    this.snapshots.clear();
+  }
+  startScan(pageSize) {
+    const rows = this.loadRows();
+    const now = Date.now();
+    if (rows.length === 0) {
+      return { items: [], total: 0, scanStartedAt: now, nextCursor: null };
+    }
+    const snapshot = {
+      id: randomBytes(9).toString("base64url"),
+      createdAt: now,
+      rows
+    };
+    this.snapshots.set(snapshot.id, snapshot);
+    this.evict(now);
+    return this.slice(snapshot, 0, pageSize);
+  }
+  slice(snapshot, offset, pageSize) {
+    const items = snapshot.rows.slice(offset, offset + pageSize);
+    const end = offset + items.length;
+    return {
+      items,
+      total: snapshot.rows.length,
+      scanStartedAt: snapshot.createdAt,
+      nextCursor: end < snapshot.rows.length ? encodeCursor(snapshot.id, end) : null
+    };
+  }
+  ttlMs() {
+    return this.options.ttlMs ?? DEFAULT_INVENTORY_TTL_MS;
+  }
+  evict(now) {
+    const max = Math.max(1, this.options.maxSnapshots ?? MAX_INVENTORY_SNAPSHOTS);
+    for (const [id, snapshot] of this.snapshots) {
+      if (Date.now() - snapshot.createdAt > this.ttlMs()) {
+        this.snapshots.delete(id);
+      }
+    }
+    while (this.snapshots.size > max) {
+      let oldestId;
+      let oldestAt = now + 1;
+      for (const [id, snapshot] of this.snapshots) {
+        if (snapshot.createdAt < oldestAt) {
+          oldestAt = snapshot.createdAt;
+          oldestId = id;
+        }
+      }
+      if (oldestId === void 0) break;
+      this.snapshots.delete(oldestId);
+    }
+  }
+};
+function encodeCursor(snapshotId, offset) {
+  const payload = Buffer.from(JSON.stringify({ s: snapshotId, o: offset }), "utf8");
+  return `${CURSOR_PREFIX}${payload.toString("base64url")}`;
+}
+function decodeCursor(cursor) {
+  if (cursor.startsWith(CURSOR_PREFIX)) {
+    try {
+      const parsed = JSON.parse(
+        Buffer.from(cursor.slice(CURSOR_PREFIX.length), "base64url").toString("utf8")
+      );
+      if (typeof parsed?.s === "string" && parsed.s.length > 0 && typeof parsed?.o === "number" && Number.isInteger(parsed.o) && parsed.o >= 0) {
+        return { snapshotId: parsed.s, offset: parsed.o };
+      }
+    } catch {
+    }
+  }
+  throw new InventoryCursorError(CURSOR_ERROR_MESSAGE);
+}
+
 // src/saveSchema.ts
 import { createHash } from "crypto";
 var saveMessageSchema = external_exports.object({
@@ -21413,6 +21517,8 @@ var CompanionService = class _CompanionService {
   // Serialize drains so concurrent reads queue behind one ingest rather than
   // racing to consume the same file (mirrors Corpus.enqueueWrite).
   refreshChain = Promise.resolve();
+  /** Holds the bounded, in-memory snapshots behind inventoryPage. */
+  inventoryScanner = new InventoryScanner(() => this.index.inventoryRows());
   /** Memories written since this process started; the per-session cap counts these. */
   memoriesWritten = 0;
   activeOperations = 0;
@@ -21530,6 +21636,23 @@ var CompanionService = class _CompanionService {
   getConversation(docId) {
     return this.corpus.get(docId);
   }
+  /**
+   * One page of the paginated conversation inventory (metadata only, never
+   * transcripts). Passing no cursor starts a new scan: the inbox is drained so
+   * the snapshot reflects the corpus as of now, then a consistent docId-sorted
+   * snapshot is captured and held in memory. Passing a previous page's
+   * nextCursor serves later pages from that same snapshot, so conversations
+   * that arrive or change mid-scan cannot shuffle or rewrite earlier pages;
+   * resume pages deliberately skip the drain, which would only cost latency.
+   * Throws InventoryCursorError for a cursor that has expired or outlived the
+   * process; the caller should begin a new scan.
+   */
+  async inventoryPage(options = {}) {
+    if (!options.cursor) {
+      await this.refresh();
+    }
+    return this.inventoryScanner.page(options.cursor, options.limit);
+  }
   /** Recent conversations enriched with their cached summary when available. */
   async listRecent(n) {
     return this.listConversations(n, "recent");
@@ -21623,6 +21746,7 @@ var CompanionService = class _CompanionService {
     this.closed = true;
     if (this.maintenanceTimer) clearTimeout(this.maintenanceTimer);
     this.maintenanceTimer = void 0;
+    this.inventoryScanner.clear();
     this.index.close();
   }
 };
@@ -21847,6 +21971,12 @@ async function runServe() {
         return errorResult(`No conversation found with id '${args.id}'.`);
       }
       return sourcedJsonResult({
+        // The current fingerprint of the transcript being returned, matching
+        // the `fingerprint` a conversation_inventory entry carries for the
+        // same content. A caller diffing against an inventory snapshot taken
+        // earlier can detect a change made after that snapshot by comparing
+        // the two values.
+        contentFingerprint: fingerprintConversation(record2),
         conversation: {
           ...record2.conversation,
           ...sourceLinks(record2.conversation.docId, record2.conversation.url)
@@ -21946,6 +22076,43 @@ async function runServe() {
       });
     })
   );
+  server.registerTool(
+    "conversation_inventory",
+    {
+      title: "Conversation inventory",
+      description: "Read-only, paginated inventory of every conversation in the corpus as compact metadata: stable id, platform, title, and a versioned content fingerprint. Never returns transcripts. Built for services that periodically process the corpus: call it with no arguments to start a scan, then pass each page's nextCursor back as cursor until a page comes back without one. All pages of a scan reflect the same consistent snapshot taken when the scan started, so conversations that arrive or change mid-scan never shuffle the results; start a new scan (omit cursor) to see them. Compare ids and fingerprints against the previous scan and call get_conversation only for new or changed ids. Cursors expire and do not survive a server restart; on a cursor error, simply begin a new scan.",
+      inputSchema: {
+        cursor: external_exports.string().optional().describe("Opaque nextCursor from the previous page. Omit to start a new scan."),
+        limit: external_exports.number().int().min(1).max(100).optional().describe("Items per page (default 100).")
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async (args) => withService(async (service2) => {
+      try {
+        const page = await service2.inventoryPage({ cursor: args.cursor, limit: args.limit });
+        const payload = {
+          count: page.items.length,
+          total: page.total,
+          scanStartedAt: page.scanStartedAt,
+          items: page.items
+        };
+        if (page.nextCursor) {
+          payload.nextCursor = page.nextCursor;
+        }
+        return jsonResult(payload);
+      } catch (err) {
+        if (err instanceof InventoryCursorError) {
+          return errorResult(err.message);
+        }
+        throw err;
+      }
+    })
+  );
   server.registerTool(
     "corpus_status",
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llmnesia/mcp",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "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.7",
+  "version": "0.2.9",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@llmnesia/mcp",
-      "version": "0.2.7",
+      "version": "0.2.9",
       "transport": {
         "type": "stdio"
       }