@llmnesia/mcp 0.1.2 → 0.1.5

package/dist/cli.js

@@ -3,7 +3,19 @@ import { createRequire as __llmnesiaCreateRequire } from "node:module";
 const require = __llmnesiaCreateRequire(import.meta.url);
 import {
   VERSION
-} from "./chunk-BQM5Q4XX.js";
+} from "./chunk-YVBAQ5VA.js";
+
+// src/nodeDownload.ts
+var NODE_DOWNLOAD_URLS = {
+  darwin: "https://www.llmnesia.com/download/node/macos",
+  win32: "https://www.llmnesia.com/download/node/windows",
+  other: "https://nodejs.org/en/download"
+};
+function nodeDownloadUrl(platform = process.platform) {
+  if (platform === "darwin") return NODE_DOWNLOAD_URLS.darwin;
+  if (platform === "win32") return NODE_DOWNLOAD_URLS.win32;
+  return NODE_DOWNLOAD_URLS.other;
+}
 
 // src/nodeVersion.ts
 var MINIMUM_NODE_VERSION = "22.13.0";
@@ -24,15 +36,98 @@ function supportsNodeVersion(version) {
   }
   return true;
 }
-function unsupportedNodeMessage(version) {
-  return `LLMnesia MCP requires Node.js ${MINIMUM_NODE_VERSION} or newer, but this command is running on Node.js ${version}.
 
-Install the current Node.js LTS release from https://nodejs.org/ and then run:
-  npx -y @llmnesia/mcp@latest install
-
-npx cannot install Node.js for you. If \`npx\` itself is not found, Node.js is not installed yet.
+// src/nodeUpgrade.ts
+import { spawn } from "child_process";
+import { createInterface } from "readline/promises";
+var INSTALL_COMMAND = "npx -y @llmnesia/mcp@latest install";
+function nodeDownloadOpenCommand(platform) {
+  const downloadUrl = nodeDownloadUrl(platform);
+  switch (platform) {
+    case "darwin":
+      return { command: "open", args: [downloadUrl] };
+    case "win32":
+      return { command: "cmd.exe", args: ["/d", "/s", "/c", "start", "", downloadUrl] };
+    case "linux":
+      return { command: "xdg-open", args: [downloadUrl] };
+    default:
+      return null;
+  }
+}
+async function openNodeDownloadPage(platform = process.platform) {
+  const spec = nodeDownloadOpenCommand(platform);
+  if (!spec) {
+    return false;
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (opened) => {
+      if (!settled) {
+        settled = true;
+        resolve(opened);
+      }
+    };
+    try {
+      const child = spawn(spec.command, spec.args, {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true
+      });
+      child.once("error", () => finish(false));
+      child.once("spawn", () => {
+        child.unref();
+        finish(true);
+      });
+    } catch {
+      finish(false);
+    }
+  });
+}
+async function askInTerminal(prompt) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(prompt);
+  } finally {
+    rl.close();
+  }
+}
+function nextSteps(opened, platform) {
+  const downloadUrl = nodeDownloadUrl(platform);
+  return (opened ? `Opened ${downloadUrl}
+` : `Download the current Node.js LTS release: ${downloadUrl}
+`) + `After installing it, reopen Terminal or PowerShell and run:
+  ${INSTALL_COMMAND}
 `;
 }
+async function guideUnsupportedNodeVersion(version, options = {}) {
+  const interactive = options.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const platform = options.platform ?? process.platform;
+  const ask = options.ask ?? askInTerminal;
+  const openDownload = options.openDownload ?? openNodeDownloadPage;
+  const writeOut = options.writeOut ?? ((text) => process.stdout.write(text));
+  const writeErr = options.writeErr ?? ((text) => process.stderr.write(text));
+  writeErr(
+    `LLMnesia MCP requires Node.js ${MINIMUM_NODE_VERSION} or newer, but this command is running on Node.js ${version}.
+`
+  );
+  if (!interactive) {
+    writeOut(nextSteps(false, platform));
+    return;
+  }
+  let answer = "";
+  try {
+    answer = await ask("Open the Node.js installer now? [Y/n] ");
+  } catch {
+    writeOut(nextSteps(false, platform));
+    return;
+  }
+  if (answer.trim() !== "" && !/^y(es)?$/i.test(answer.trim())) {
+    writeOut(nextSteps(false, platform));
+    return;
+  }
+  const opened = await openDownload(platform);
+  writeOut(nextSteps(opened, platform));
+}
 
 // src/bootstrap.ts
 async function bootstrap() {
@@ -43,10 +138,10 @@ async function bootstrap() {
     return 0;
   }
   if (!supportsNodeVersion(process.versions.node)) {
-    process.stderr.write(unsupportedNodeMessage(process.versions.node));
+    await guideUnsupportedNodeVersion(process.versions.node);
     return 1;
   }
-  const { main } = await import("./cli-CNIF4XT3.js");
+  const { main } = await import("./cli-TVE63AWC.js");
   return main();
 }
 bootstrap().then((code) => {

package/dist/llmnesia-claude-host.mjs

@@ -1,26 +1,31 @@
 #!/usr/bin/env node
-// LLMnesia native messaging host — reads local Claude Code sessions from
-// ~/.claude/projects 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).
+// 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).
 //
-// It reads .jsonl session files under ~/.claude/projects, 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 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.
 //
 // 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 Claude Code indexing.
+// has always been for plain session indexing.
 //
-// Protocol (extension → host):
-//   { cmd: "ping" }                    → { type: "pong", version }
-//   { cmd: "list" }                    → { type: "list", sessions: [{sessionId, mtime, project}] }
-//   { cmd: "get", sessionId }          → one or more { type: "chunk", sessionId, seq, total, data }
+// Protocol v2 (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.
+//   { cmd: "ping" }                    → { type: "pong", version: 2 }
+//   { cmd: "list" }                    → { type: "list", sessions:
+//                                          [{source, sessionId, mtime, project?, title?}] }
+//   { cmd: "get", source, sessionId }  → one or more { type: "chunk", sessionId, seq, total, data }
 //                                        then { type: "sessionDone", sessionId }
 //                                        (or { type: "session", sessionId, notFound: true })
 //   { cmd: "corpusInfo" }              → { type: "corpusInfo", present, root? }
@@ -28,13 +33,25 @@
 //     seq, total, data }               → { type: "chunkAck", seq }
 //                                        (writes <root>/inbox/<filename> once
 //                                        every chunk 0..total-1 has arrived)
+//
+// The extension never names a path in either direction: it asks for a
+// (source, sessionId) pair and the host resolves it against its own roots. That
+// is what keeps a compromised or buggy caller from reading arbitrary files.
 
 import { chmod, mkdir, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+const PROTOCOL_VERSION = 2;
 const PROJECTS_DIR = join(homedir(), ".claude", "projects");
 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
+// installed before Codex support still honours a non-default CODEX_HOME.
+const DEFAULT_CODEX_HOME = process.env.CODEX_HOME || join(homedir(), ".codex");
+// Codex nests rollouts as sessions/<year>/<month>/<day>/*.jsonl. Bounded so a
+// misconfigured codexHome can't turn into an unbounded filesystem walk.
+const CODEX_MAX_DEPTH = 3;
 // Conservative chunk size (chars). After JSON-escaping + any multibyte chars the
 // on-wire message stays well under native messaging's 1 MB per-message ceiling.
 const CHUNK_CHARS = 256 * 1024;
@@ -43,6 +60,15 @@ const CHUNK_CHARS = 256 * 1024;
 // than the browser profile it was copied out of.
 const DIR_MODE = 0o700;
 const FILE_MODE = 0o600;
+// Defend the host process from malformed or compromised callers. The extension
+// currently sends 256 KiB chunks and waits for each ack, so these limits leave
+// ample headroom without permitting unbounded arrays or abandoned transfers.
+const MAX_PUT_CHUNK_CHARS = 512 * 1024;
+const MAX_PUT_CHUNKS = 256;
+const MAX_PUT_TRANSFER_CHARS = 64 * 1024 * 1024;
+const MAX_PENDING_WRITE_CHARS = 64 * 1024 * 1024;
+const MAX_PENDING_WRITES = 8;
+const PENDING_WRITE_TTL_MS = 5 * 60 * 1000;
 
 function send(message) {
   const body = Buffer.from(JSON.stringify(message), "utf8");
@@ -52,7 +78,11 @@ function send(message) {
   process.stdout.write(body);
 }
 
-async function listSessions() {
+// --- session discovery ----------------------------------------------------
+// One entry per session: { source, sessionId, mtime, project?, title?, path }.
+// `path` is stripped before anything goes on the wire.
+
+async function listClaudeCodeSessions() {
   const sessions = [];
   let projectDirs;
   try {
@@ -79,6 +109,7 @@ async function listSessions() {
       try {
         const info = await stat(path);
         sessions.push({
+          source: "claude_code",
           sessionId: file.replace(/\.jsonl$/, ""),
           mtime: Math.floor(info.mtimeMs),
           project: entry.name,
@@ -92,14 +123,128 @@ async function listSessions() {
   return sessions;
 }
 
+// Codex names rollouts `rollout-<ISO timestamp>-<uuid>.jsonl`; the trailing
+// UUID is the thread id (it matches session_meta.payload.id). Mirrors
+// codexSessionIdFromFilename in the extension.
+const CODEX_UUID_RE = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
+
+function codexSessionId(filename) {
+  const base = filename.replace(/\.jsonl$/i, "");
+  const match = CODEX_UUID_RE.exec(base);
+  return match ? match[1].toLowerCase() : base;
+}
+
+async function walkCodexDir(dir, depth, out) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return out; // missing or unreadable — nothing to add
+  }
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (depth > 0) {
+        await walkCodexDir(path, depth - 1, out);
+      }
+      continue;
+    }
+    if (!entry.name.endsWith(".jsonl")) {
+      continue;
+    }
+    try {
+      const info = await stat(path);
+      out.push({
+        source: "codex",
+        sessionId: codexSessionId(entry.name),
+        mtime: Math.floor(info.mtimeMs),
+        path
+      });
+    } catch {
+      // Skip unreadable files.
+    }
+  }
+  return out;
+}
+
+// Codex's user-facing thread names, so search results read as the titles the
+// user sees in the app rather than a derived "<project> · <first prompt>".
+async function readCodexThreadNames(codexHome) {
+  const titles = new Map();
+  let raw;
+  try {
+    raw = await readFile(join(codexHome, "session_index.jsonl"), "utf8");
+  } catch {
+    return titles; // absent is normal — the extension falls back to a derived title
+  }
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    try {
+      const row = JSON.parse(trimmed);
+      if (row && typeof row.id === "string" && typeof row.thread_name === "string") {
+        const name = row.thread_name.trim();
+        if (name) {
+          titles.set(row.id.toLowerCase(), name);
+        }
+      }
+    } catch {
+      // Skip malformed lines (including a truncated final one).
+    }
+  }
+  return titles;
+}
+
+async function listCodexSessions(codexHome) {
+  const sessions = await walkCodexDir(join(codexHome, "sessions"), CODEX_MAX_DEPTH, []);
+  if (sessions.length === 0) {
+    return sessions;
+  }
+  const titles = await readCodexThreadNames(codexHome);
+  for (const session of sessions) {
+    const title = titles.get(session.sessionId);
+    if (title) {
+      session.title = title;
+    }
+  }
+  return sessions;
+}
+
+/**
+ * Every session across every source. Sources are listed independently and
+ * failures are contained per source (each helper swallows its own errors), so
+ * an absent or unreadable Codex home can never stop Claude Code from syncing,
+ * or vice versa.
+ */
+async function listSessions() {
+  const config = await loadConfig();
+  const codexHome = config?.codexHome || DEFAULT_CODEX_HOME;
+  const [claude, codex] = await Promise.all([
+    listClaudeCodeSessions().catch(() => []),
+    listCodexSessions(codexHome).catch(() => [])
+  ]);
+  return [...claude, ...codex];
+}
+
 async function loadConfig() {
   try {
     const raw = await readFile(CONFIG_FILE, "utf8");
     const parsed = JSON.parse(raw);
-    if (parsed && typeof parsed.corpusRoot === "string" && parsed.corpusRoot.length > 0) {
-      return { corpusRoot: parsed.corpusRoot };
+    if (!parsed || typeof parsed !== "object") {
+      return null;
     }
-    return null;
+    const corpusRoot =
+      typeof parsed.corpusRoot === "string" && parsed.corpusRoot.length > 0 ? parsed.corpusRoot : null;
+    const codexHome =
+      typeof parsed.codexHome === "string" && parsed.codexHome.length > 0 ? parsed.codexHome : null;
+    // A config that names only codexHome is still useful for listing, but the
+    // corpus write path requires corpusRoot — callers check that field.
+    if (!corpusRoot && !codexHome) {
+      return null;
+    }
+    return { corpusRoot, codexHome };
   } catch {
     return null; // no config yet, or unreadable/invalid — treat as "not installed"
   }
@@ -121,14 +266,22 @@ function sanitizeFilename(name) {
   return name;
 }
 
-// filename → { chunks: string[], receivedSeqs: Set<number>, total } while a
-// multi-chunk putChunk transfer is in flight. Completeness is tracked via
-// receivedSeqs.size rather than scanning chunks for holes — `new Array(total)`
-// is sparse, and Array#some skips unset indices entirely, so a hole-scan would
-// silently call a partial transfer "complete" the moment the last-received
-// (not last-index) chunk lands.
+// filename → { chunks: Map<number, string>, total, receivedChars, updatedAt }
+// while a multi-chunk putChunk transfer is in flight. A Map avoids allocating
+// from caller-controlled `total`, and lets duplicate chunks replace their old
+// contribution without inflating the byte/character budget.
 const pendingWrites = new Map();
 
+function prunePendingWrites(now) {
+  for (const [filename, entry] of pendingWrites) {
+    if (now - entry.updatedAt > PENDING_WRITE_TTL_MS) {
+      pendingWrites.delete(filename);
+    }
+  }
+}
+
+setInterval(() => prunePendingWrites(Date.now()), 60 * 1000).unref();
+
 async function handlePutChunk(message) {
   const { filename, seq, total, data } = message;
   const safeName = sanitizeFilename(filename);
@@ -136,25 +289,56 @@ async function handlePutChunk(message) {
     send({ type: "error", error: `putChunk: rejected filename ${JSON.stringify(filename)}` });
     return;
   }
-  if (!Number.isInteger(seq) || !Number.isInteger(total) || seq < 0 || total < 1 || seq >= total) {
+  if (
+    !Number.isInteger(seq) ||
+    !Number.isInteger(total) ||
+    seq < 0 ||
+    total < 1 ||
+    total > MAX_PUT_CHUNKS ||
+    seq >= total
+  ) {
     send({ type: "error", error: `putChunk: invalid seq/total for ${safeName}` });
     return;
   }
+  if (typeof data !== "string" || data.length > MAX_PUT_CHUNK_CHARS) {
+    send({ type: "error", error: `putChunk: invalid or oversized data for ${safeName}` });
+    return;
+  }
   const config = await loadConfig();
-  if (!config) {
+  if (!config?.corpusRoot) {
     send({ type: "error", error: "putChunk: no corpus configured (run the installer)" });
     return;
   }
 
+  const now = Date.now();
+  prunePendingWrites(now);
   let entry = pendingWrites.get(safeName);
   if (!entry || entry.total !== total) {
-    entry = { chunks: new Array(total).fill(""), receivedSeqs: new Set(), total };
+    if (!entry && pendingWrites.size >= MAX_PENDING_WRITES) {
+      send({ type: "error", error: "putChunk: too many transfers in progress" });
+      return;
+    }
+    entry = { chunks: new Map(), total, receivedChars: 0, updatedAt: now };
     pendingWrites.set(safeName, entry);
   }
-  entry.chunks[seq] = typeof data === "string" ? data : "";
-  entry.receivedSeqs.add(seq);
+  const previous = entry.chunks.get(seq);
+  const nextReceivedChars = entry.receivedChars - (previous?.length ?? 0) + data.length;
+  if (nextReceivedChars > MAX_PUT_TRANSFER_CHARS) {
+    pendingWrites.delete(safeName);
+    send({ type: "error", error: `putChunk: transfer too large for ${safeName}` });
+    return;
+  }
+  const pendingChars = [...pendingWrites.values()].reduce((sum, pending) => sum + pending.receivedChars, 0);
+  if (pendingChars - (previous?.length ?? 0) + data.length > MAX_PENDING_WRITE_CHARS) {
+    pendingWrites.delete(safeName);
+    send({ type: "error", error: "putChunk: pending transfer budget exceeded" });
+    return;
+  }
+  entry.chunks.set(seq, data);
+  entry.receivedChars = nextReceivedChars;
+  entry.updatedAt = now;
 
-  if (entry.receivedSeqs.size < total) {
+  if (entry.chunks.size < total) {
     send({ type: "chunkAck", seq });
     return;
   }
@@ -165,7 +349,8 @@ async function handlePutChunk(message) {
   await chmod(inboxDir, DIR_MODE).catch(() => {}); // mkdir's mode is masked by umask
   const tmpPath = join(inboxDir, `${safeName}.part-${process.pid}`);
   const finalPath = join(inboxDir, safeName);
-  await writeFile(tmpPath, entry.chunks.join(""), { encoding: "utf8", mode: FILE_MODE });
+  const text = Array.from({ length: total }, (_, index) => entry.chunks.get(index) ?? "").join("");
+  await writeFile(tmpPath, text, { encoding: "utf8", mode: FILE_MODE });
   await rename(tmpPath, finalPath);
   send({ type: "chunkAck", seq });
 }
@@ -175,12 +360,12 @@ async function handle(message) {
     return;
   }
   if (message.cmd === "ping") {
-    send({ type: "pong", version: 1 });
+    send({ type: "pong", version: PROTOCOL_VERSION });
     return;
   }
   if (message.cmd === "corpusInfo") {
     const config = await loadConfig();
-    if (!config) {
+    if (!config?.corpusRoot) {
       send({ type: "corpusInfo", present: false });
       return;
     }
@@ -198,7 +383,12 @@ async function handle(message) {
   }
   if (message.cmd === "get") {
     const sessions = await listSessions();
-    const match = sessions.find((s) => s.sessionId === message.sessionId);
+    // 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;

package/dist/mcp.js

@@ -7,13 +7,13 @@ import {
   openSearchIndex,
   pendingInboxFiles,
   resolveCorpusDir
-} from "./chunk-7BW63ZTP.js";
+} from "./chunk-3JQ7CGCP.js";
 import {
   VERSION,
   __commonJS,
   __export,
   __toESM
-} from "./chunk-BQM5Q4XX.js";
+} from "./chunk-YVBAQ5VA.js";
 
 // ../node_modules/ajv/dist/compile/codegen/code.js
 var require_code = __commonJS({
@@ -21300,8 +21300,12 @@ var CompanionService = class _CompanionService {
   }
   /** Recent conversations enriched with their cached summary when available. */
   async listRecent(n) {
+    return this.listConversations(n, "recent");
+  }
+  /** Conversations in the requested chronology, enriched with cached summaries. */
+  async listConversations(n, sort) {
     await this.refresh();
-    const recent = this.index.listRecent(n);
+    const recent = this.index.listConversations(n, sort);
     const entries = [];
     for (const row of recent) {
       const record2 = await this.corpus.get(row.docId);
@@ -21393,14 +21397,14 @@ async function runServe() {
   const server = new McpServer(
     { name: "llmnesia", version: VERSION },
     {
-      instructions: "Search and retrieve the user's own past AI conversations (ChatGPT, Claude, Gemini, etc.) from their local LLMnesia corpus. Use search_conversations to find relevant prior chats before answering from scratch, get_conversation to read a full transcript, and list_recent to see what they worked on lately. Search and list results carry a `corpus` block saying when the corpus last received data; if a chat the user expects is missing, check corpus_status before concluding it does not exist."
+      instructions: "LLMnesia is the user's searchable archive of past AI chats. Whenever the user asks about 'my chats', 'my conversations', or anything they previously said, discussed, decided, or worked on, use LLMnesia before built-in task/thread lists, local file scans, or memory, unless they explicitly ask only about Codex tasks. Use list_conversations with sort='oldest' for their earliest chat, search_conversations to find relevant prior chats, get_conversation to read a full transcript, and list_recent to see what they worked on lately. Search and list results carry a `corpus` block saying when the corpus last received data; if a chat the user expects is missing, check corpus_status before concluding it does not exist."
     }
   );
   server.registerTool(
     "search_conversations",
     {
       title: "Search conversations",
-      description: "Full-text search across the user's past AI conversations. Returns matching conversations with a highlighted snippet, ranked by relevance. Defaults to recall-first matching (any term); pass match_mode to answer questions where a wrong hit matters, such as whether or how often something was discussed.",
+      description: "Full-text search across the user's past AI conversations. Call this whenever the user asks what they said, thought, discussed, decided, or worked on previously \u2014 even if the question doesn't say 'search' \u2014 rather than answering from conversation memory alone or claiming no record exists. Returns matching conversations with a highlighted snippet, ranked by relevance. Defaults to recall-first matching (any term); pass match_mode to answer questions where a wrong hit matters, such as whether or how often something was discussed.",
       inputSchema: {
         query: external_exports.string().describe("Search terms (natural words; FTS operators are not needed)."),
         match_mode: external_exports.enum(["any", "all", "phrase"]).optional().describe(
@@ -21411,6 +21415,12 @@ async function runServe() {
         date_from: external_exports.string().optional().describe("Only conversations created on/after this date (ISO or epoch ms)."),
         date_to: external_exports.string().optional().describe("Only conversations created on/before this date (ISO or epoch ms)."),
         limit: external_exports.number().int().min(1).max(50).optional().describe("Max results (default 10).")
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     async (args) => {
@@ -21449,6 +21459,12 @@ async function runServe() {
       description: "Return the full transcript of one conversation by its id (the `id` from search results).",
       inputSchema: {
         id: external_exports.string().describe("The conversation id (docId), e.g. 'claude:abc-123'.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     async (args) => {
@@ -21474,6 +21490,12 @@ async function runServe() {
       description: "List the user's most recently updated conversations (title + summary), newest first.",
       inputSchema: {
         limit: external_exports.number().int().min(1).max(100).optional().describe("How many to return (default 10).")
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     async (args) => {
@@ -21494,12 +21516,54 @@ async function runServe() {
       });
     }
   );
+  server.registerTool(
+    "list_conversations",
+    {
+      title: "List conversations by date",
+      description: "List conversation metadata in chronological order. Use sort='oldest' for the user's earliest or oldest chat, sort='newest' for most recently created chats, and sort='recent' for most recently updated chats. This is the complete corpus chronology, so do not scan LLMnesia's private files with shell commands.",
+      inputSchema: {
+        sort: external_exports.enum(["recent", "oldest", "newest"]).optional().describe("Chronology: recent (default, updated), oldest (created), or newest (created)."),
+        limit: external_exports.number().int().min(1).max(100).optional().describe("How many to return (default 10).")
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async (args) => {
+      const entries = await service.listConversations(args.limit ?? 10, args.sort ?? "recent");
+      const status = await service.corpusStatus({ refresh: false });
+      return jsonResult({
+        count: entries.length,
+        sort: args.sort ?? "recent",
+        corpus: corpusField(status),
+        conversations: entries.map((e) => ({
+          id: e.docId,
+          title: e.title,
+          platform: e.platform,
+          createdAt: e.createdAt,
+          updatedAt: e.updatedAt,
+          messageCount: e.messageCount,
+          pinned: e.pinned,
+          summary: e.summary ?? e.preview
+        }))
+      });
+    }
+  );
   server.registerTool(
     "corpus_status",
     {
       title: "Corpus status",
       description: "Report how current the local corpus is: when browser data last reached it, how many conversations it holds, and the newest conversation it knows about. Use this when a conversation the user is sure they had cannot be found, to tell a genuinely missing chat apart from a corpus that has stopped receiving updates from the browser extension.",
-      inputSchema: {}
+      inputSchema: {},
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
     },
     async () => {
       const status = await service.corpusStatus();
@@ -21511,7 +21575,13 @@ async function runServe() {
     {
       title: "Save conversation",
       description: "Add or update a conversation in the user's local corpus. Provide platform, title, and the messages; identity is keyed on docId (or platform:sourceId), so re-saving the same conversation updates it in place.",
-      inputSchema: saveConversationSchema.shape
+      inputSchema: saveConversationSchema.shape,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
     },
     async (args) => {
       try {