@llmnesia/mcp 0.2.8 → 0.2.9

package/README.md

@@ -182,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.

package/dist/{chunk-FIH7ZNYH.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-RJJRIPHA.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`;
 }
@@ -210,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) {
@@ -940,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";
@@ -1017,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);
@@ -1091,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(
@@ -1149,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
@@ -1238,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) {
@@ -2110,6 +2150,7 @@ export {
   ingestFile,
   pendingInboxFiles,
   drainInbox,
+  fingerprintConversation,
   SearchIndex,
   openSearchIndex,
   deleteIndexDb,

package/dist/{chunk-RJJRIPHA.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.8" : "0.0.0-dev";
+var VERSION = true ? "0.2.9" : "0.0.0-dev";
 
 export {
   __require,

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

@@ -17,13 +17,13 @@ import {
   runtimeBinDir,
   staleIndexFiles,
   uninstallRuntime
-} from "./chunk-FIH7ZNYH.js";
+} from "./chunk-BWEDXPNM.js";
 import {
   VERSION,
   __commonJS,
   __require,
   __toESM
-} from "./chunk-RJJRIPHA.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"}`);

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-RJJRIPHA.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-D2IVH5S2.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-FIH7ZNYH.js";
+} from "./chunk-BWEDXPNM.js";
 import {
   VERSION,
   __commonJS,
   __export,
   __toESM
-} from "./chunk-RJJRIPHA.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.8",
+  "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.8",
+  "version": "0.2.9",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@llmnesia/mcp",
-      "version": "0.2.8",
+      "version": "0.2.9",
       "transport": {
         "type": "stdio"
       }