@llmnesia/mcp 0.1.3 → 0.1.5

package/README.md

@@ -12,22 +12,36 @@ over stdio.
 
 Requires **Node.js ≥ 22.13.0** (for the built-in `node:sqlite` module). The
 installer checks this before changing anything and prints the exact recovery
-steps when the installed version is too old.
+steps when the installed version is too old. If that happens in an interactive
+terminal, it offers the official Node.js installer through an OS-specific
+LLMnesia download link for you.
 
 ## Install
 
+On macOS or Linux:
+
 ```bash
 npx -y @llmnesia/mcp@latest install
 ```
 
-That is the same command in Terminal on macOS/Linux and PowerShell on Windows.
+On Windows PowerShell:
+
+```powershell
+npx.cmd -y @llmnesia/mcp@latest install
+```
+
+Windows uses `npx.cmd` because PowerShell commonly blocks npm's `npx.ps1`
+wrapper even when Node.js installed correctly.
 It requires Node.js 22.13 or newer; there is no global package install and no
 client config to edit by hand in the normal path.
 
-If `npx` is not recognised, Node.js is not installed. Install the current LTS
-release from [nodejs.org](https://nodejs.org/), reopen Terminal/PowerShell, and
-run the command again. `npx` cannot prompt for or install Node.js because it is
-itself part of Node.js.
+If your installed Node.js is too old, LLMnesia offers to open the right official
+installer; install it, reopen Terminal/PowerShell, and run the command again. If
+`npx` is not recognised at all, Node.js is not
+installed yet, so the command cannot start far enough to show that prompt. In
+that case, install the current LTS release from
+[Mac installer](https://www.llmnesia.com/download/node/macos) on macOS, or the
+[Windows installer](https://www.llmnesia.com/download/node/windows) on Windows.
 
 The installer:
 
@@ -63,9 +77,7 @@ The copy is self-contained (no `node_modules` beside it) and re-running
 
 ### Updating
 
-```bash
-npx -y @llmnesia/mcp@latest install
-```
+Run the same OS-specific install command above again.
 
 Your corpus is untouched; only the server copy is replaced.
 
@@ -88,12 +100,13 @@ If nothing has written to the corpus yet, search results will be empty.
 
 ## Tools
 
-Once registered, your MCP client gains five tools over the corpus:
+Once registered, your MCP client gains six 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). |
+| `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. |
 | `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. |
@@ -108,7 +121,7 @@ received data — check it before concluding a chat does not exist.
 | Claude Code | Runs `claude mcp add --scope user` with the absolute Node and installed runtime paths, making it available in every project (detects `claude` on PATH). |
 | Claude Desktop | Edits `claude_desktop_config.json` at the standard OS-specific path. |
 | Cursor | Edits `~/.cursor/mcp.json`. |
-| Codex | Runs `codex mcp add` with the absolute runtime paths. It also detects the CLI bundled in the macOS desktop app; prints a TOML fallback only if no Codex CLI is available. |
+| Codex | Runs `codex mcp add` with the absolute runtime paths when available. If Windows does not expose the app's bundled CLI, the installer safely edits `~/.codex/config.toml` itself and backs up existing settings first. Read-only LLMnesia tools are configured to run without repeated approval prompts; writes still ask. |
 | 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,
@@ -117,9 +130,8 @@ close it.
 
 ## Diagnose an install
 
-```bash
-npx -y @llmnesia/mcp@latest doctor
-```
+Use `npx -y @llmnesia/mcp@latest doctor` on macOS/Linux, or
+`npx.cmd -y @llmnesia/mcp@latest doctor` in Windows PowerShell.
 
 Checks whether the native host is installed, the server runtime is present, the
 corpus is receiving data, and each detected client is correctly wired —
@@ -132,9 +144,8 @@ reminder).
 
 ## Uninstall
 
-```bash
-npx -y @llmnesia/mcp@latest uninstall
-```
+Use `npx -y @llmnesia/mcp@latest uninstall` on macOS/Linux, or
+`npx.cmd -y @llmnesia/mcp@latest uninstall` in Windows PowerShell.
 
 Removes native-host manifests and registry keys, the copied server in
 `~/.llmnesia/bin`, and client registrations. The shared config file and your

package/dist/{chunk-7BW63ZTP.js → chunk-3JQ7CGCP.js}

@@ -643,10 +643,15 @@ var SearchIndex = class {
   }
   /** Most-recently-updated conversations (metadata only), newest first. */
   listRecent(n) {
+    return this.listConversations(n, "recent");
+  }
+  /** Conversation metadata in a caller-selected, deterministic chronology. */
+  listConversations(n, sort) {
     const limit = Math.max(1, n);
+    const orderBy = sort === "oldest" ? "createdAt ASC, updatedAt ASC" : sort === "newest" ? "createdAt DESC, updatedAt DESC" : "updatedAt DESC, createdAt DESC";
     const rows = this.db.prepare(
       `SELECT docId, platform, title, url, createdAt, updatedAt, messageCount, preview, pinned
-         FROM conversations ORDER BY updatedAt DESC, createdAt DESC LIMIT ?`
+         FROM conversations ORDER BY ${orderBy} LIMIT ?`
     ).all(limit);
     return rows.map((r) => ({ ...r, pinned: r.pinned === 1 }));
   }

package/dist/{chunk-EBVGUZX2.js → chunk-YVBAQ5VA.js}

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

package/dist/{cli-JFZO44NP.js → cli-TVE63AWC.js}

@@ -9,13 +9,13 @@ import {
   ingestFile,
   openSearchIndex,
   resolveCorpusDir
-} from "./chunk-7BW63ZTP.js";
+} from "./chunk-3JQ7CGCP.js";
 import {
   VERSION,
   __commonJS,
   __require,
   __toESM
-} from "./chunk-EBVGUZX2.js";
+} from "./chunk-YVBAQ5VA.js";
 
 // ../node_modules/isexe/windows.js
 var require_windows = __commonJS({
@@ -533,6 +533,7 @@ var HOST_NAME = "com.llmnesia.claude_code";
 var STORE_EXTENSION_ID = "leekfgbdojiaabifbjbbgiiclannjdkf";
 var here = dirname(fileURLToPath(import.meta.url));
 var home = homedir();
+var CLAUDE_PROJECTS_DIR = join(home, ".claude", "projects");
 var osPlatform = process.env.LLMNESIA_FAKE_PLATFORM || platform();
 function expandHome(p) {
   if (p === "~") {
@@ -547,6 +548,11 @@ function resolveCorpusDir2(explicit) {
   const raw = explicit ?? process.env.LLMNESIA_CORPUS_DIR ?? "~/.llmnesia/corpus";
   return expandHome(raw);
 }
+function resolveCodexHome(explicit) {
+  const candidates = [explicit, process.env.CODEX_HOME, "~/.codex"];
+  const raw = candidates.find((value) => typeof value === "string" && value.trim() !== "");
+  return expandHome(raw.trim());
+}
 async function exists(path) {
   try {
     await stat(path);
@@ -573,21 +579,24 @@ async function readExistingConfig(configPath) {
     if (err && typeof err === "object" && err.code === "ENOENT") {
       return null;
     }
-    throw new Error(`Could not read existing native-host config at ${configPath}: ${err instanceof Error ? err.message : String(err)}`);
+    throw new Error(`LLMnesia couldn't read its settings at ${configPath}: ${err instanceof Error ? err.message : String(err)}. Nothing was changed.`);
   }
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch (err) {
     throw new Error(
-      `Could not parse existing native-host config at ${configPath}: ${err instanceof Error ? err.message : String(err)}. The file was left unchanged.`
+      `LLMnesia found invalid JSON in its settings at ${configPath}: ${err instanceof Error ? err.message : String(err)}. Nothing was changed; repair or move that file aside, then retry.`
     );
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`Existing native-host config at ${configPath} must be a JSON object. The file was left unchanged.`);
+    throw new Error(`LLMnesia settings at ${configPath} must contain a JSON object. Nothing was changed.`);
   }
   if ("corpusRoot" in parsed && typeof parsed.corpusRoot !== "string") {
-    throw new Error(`Existing native-host config at ${configPath} has an invalid corpusRoot. The file was left unchanged.`);
+    throw new Error(`LLMnesia settings at ${configPath} contain an invalid conversation-data folder. Nothing was changed.`);
+  }
+  if ("codexHome" in parsed && typeof parsed.codexHome !== "string") {
+    throw new Error(`LLMnesia settings at ${configPath} contain an invalid Codex data folder. Nothing was changed.`);
   }
   return parsed;
 }
@@ -620,7 +629,7 @@ async function installPosix(manifestBase, hostPath, log) {
     await mkdir(dir, { recursive: true });
     await writeFile(join(dir, `${HOST_NAME}.json`), `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
-    log(`Manifest \u2192 ${label}: ${join(dir, `${HOST_NAME}.json`)}`);
+    log(`\u2713 ${label} connected`);
     installed += 1;
   }
   return installed;
@@ -639,12 +648,11 @@ async function installWindows(manifestBase, hostPath, installDir, log) {
   await writeFile(batPath, `@echo off\r
 "${process.execPath}" "${hostPath}" %*\r
 `, "utf8");
-  log(`Launcher \u2192 ${batPath}`);
+  log("\u2713 Windows launcher ready");
   const manifest = { ...manifestBase, path: batPath };
   const manifestPath = join(installDir, `${HOST_NAME}.json`);
   await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
-  log(`Manifest \u2192 ${manifestPath}`);
   let installed = 0;
   for (const [label, userDataDir, vendorKey] of windowsBrowsers()) {
     if (!await exists(userDataDir)) {
@@ -653,23 +661,27 @@ async function installWindows(manifestBase, hostPath, installDir, log) {
     const key = `HKCU\\${vendorKey}\\NativeMessagingHosts\\${HOST_NAME}`;
     const regExe = join(process.env.SystemRoot || "C:\\Windows", "System32", "reg.exe");
     await execFileAsync(regExe, ["add", key, "/ve", "/t", "REG_SZ", "/d", manifestPath, "/f"]);
-    log(`Registry \u2192 ${label}: ${key}`);
+    log(`\u2713 ${label} connected`);
     installed += 1;
   }
   return installed;
 }
-async function installNativeHost({ ids = [], corpus, force = false, quiet = false } = {}) {
+async function installNativeHost({ ids = [], corpus, codexHome, force = false, quiet = false } = {}) {
   const log = quiet ? () => {
   } : console.log;
   const isWindows2 = osPlatform === "win32";
   const invalidId = ids.find((id) => !/^[a-p]{32}$/.test(id));
   if (invalidId) {
-    throw new Error(`Invalid Chromium extension id: ${JSON.stringify(invalidId)}. Expected 32 letters from a through p.`);
+    throw new Error(
+      `${JSON.stringify(invalidId)} is not a Chromium extension ID. Only unpacked/development builds need an ID; it must be 32 letters from a through p. Run with --help for an example.`
+    );
   }
   const allIds = [.../* @__PURE__ */ new Set([STORE_EXTENSION_ID, ...ids])];
   const allowedOrigins = allIds.map((id) => `chrome-extension://${id}/`);
   if (await supportedBrowserCount(isWindows2) === 0) {
-    throw new Error("No supported Chromium browser found (Chrome, Brave, Edge, or Chromium) \u2014 the browser helper was not installed.");
+    throw new Error(
+      "LLMnesia couldn't find Chrome, Brave, Edge, or Chromium. Open your browser once so it creates a profile, then retry. Safari and Firefox are not supported yet. Nothing was installed."
+    );
   }
   const installDir = join(home, ".llmnesia");
   const configPath = join(installDir, "config.json");
@@ -683,38 +695,68 @@ async function installNativeHost({ ids = [], corpus, force = false, quiet = fals
   if (!isWindows2) {
     await chmod(hostPath, 493);
   }
-  log(`Host script \u2192 ${hostPath}`);
+  log("\u2713 Helper installed");
   const manifestBase = {
     name: HOST_NAME,
-    description: "LLMnesia \u2014 reads local Claude Code sessions",
+    description: "LLMnesia \u2014 reads local Claude Code and Codex sessions",
     type: "stdio",
     allowed_origins: allowedOrigins
   };
   const installedCount = isWindows2 ? await installWindows(manifestBase, hostPath, installDir, log) : await installPosix(manifestBase, hostPath, log);
   const corpusRoot = resolveCorpusDir2(corpus);
+  const resolvedCodexHome = resolveCodexHome(codexHome);
   const existingRoot = existing && typeof existing.corpusRoot === "string" ? existing.corpusRoot : null;
   let corpusRootChanged = true;
   if (existingRoot && existingRoot !== corpusRoot && !force) {
     corpusRootChanged = false;
-    log(`Corpus config kept \u2192 ${configPath}`);
-    log(`  already points at: ${existingRoot}`);
-    log(`  to change it: re-run with --corpus <dir> --force`);
+    await writeFile(
+      configPath,
+      `${JSON.stringify({ ...existing, corpusRoot: existingRoot, codexHome: resolvedCodexHome }, null, 2)}
+`,
+      { encoding: "utf8", mode: 384 }
+    );
+    await chmod(configPath, 384);
+    log("\u2713 Kept your existing conversation-data folder");
+    log(`  Conversation data: ${existingRoot}`);
+    log(`  To change it: re-run with --corpus <dir> --force`);
+    log(`  Codex data: ${resolvedCodexHome}`);
   } else {
-    await writeFile(configPath, `${JSON.stringify({ corpusRoot }, null, 2)}
-`, { encoding: "utf8", mode: 384 });
+    await writeFile(
+      configPath,
+      `${JSON.stringify({ ...existing ?? {}, corpusRoot, codexHome: resolvedCodexHome }, null, 2)}
+`,
+      { encoding: "utf8", mode: 384 }
+    );
     await chmod(configPath, 384);
-    log(`Corpus config \u2192 ${configPath}`);
-    log(`  corpus root: ${corpusRoot}`);
+    log("\u2713 Settings saved");
+    log(`  Conversation data: ${corpusRoot}`);
+    log(`  Codex data: ${resolvedCodexHome}`);
+  }
+  const [hasClaudeCode, hasCodex] = await Promise.all([
+    exists(CLAUDE_PROJECTS_DIR),
+    exists(join(resolvedCodexHome, "sessions"))
+  ]);
+  log("");
+  log(
+    hasClaudeCode ? `\u2713 Found Claude Code sessions at ${CLAUDE_PROJECTS_DIR}` : `\u2013 No Claude Code sessions found yet (fine if you don't use Claude Code).`
+  );
+  log(
+    hasCodex ? `\u2713 Found Codex sessions at ${resolvedCodexHome}` : `\u2013 No Codex sessions found yet (fine if you don't use Codex).`
+  );
+  const extraIdCount = allIds.length - 1;
+  if (extraIdCount > 0) {
+    log(`\u2713 Also authorized ${extraIdCount} unpacked extension ${extraIdCount === 1 ? "build" : "builds"}`);
   }
-  log(`
-Done. Allowed extension id(s): ${allIds.join(", ")}`);
-  log("Fully quit and reopen the browser, then open LLMnesia Settings.");
+  log("\nAll set \u2014 LLMnesia can now read your local coding-agent sessions.");
+  log("Next: fully quit your browser (not just close its window), reopen it, then open LLMnesia Settings.");
+  log("If it doesn't connect, run: npx -y @llmnesia/local-agent-host@latest doctor");
   return {
     installedCount,
     allowedIds: allIds,
     configPath,
     corpusRoot: existingRoot && !corpusRootChanged ? existingRoot : corpusRoot,
-    corpusRootChanged
+    corpusRootChanged,
+    codexHome: resolvedCodexHome
   };
 }
 async function uninstallNativeHost() {
@@ -2570,6 +2612,7 @@ import { dirname as dirname4, join as join4 } from "path";
 import { promisify as promisify2 } from "util";
 var execFileAsync2 = promisify2(execFile2);
 var SERVER_NAME = "llmnesia";
+var CODEX_APPROVAL_MODE = "writes";
 async function commandOnPath(name) {
   try {
     const { stdout } = await execFileAsync2(process.platform === "win32" ? "where" : "which", [name]);
@@ -2912,7 +2955,7 @@ claude mcp add --scope user ${SERVER_NAME} -- ${serve.command} ${serve.args.join
 function sameServeCommand(left, right) {
   return left.command === right.command && JSON.stringify(left.args) === JSON.stringify(right.args);
 }
-async function registerCodex(serve, cli, configPath, confirm) {
+async function registerCodex(serve, cli, configPath, confirm, now) {
   if (!await cli.detect()) {
     if (!await clientDirExists(configPath)) {
       return {
@@ -2921,12 +2964,34 @@ async function registerCodex(serve, cli, configPath, confirm) {
         detail: `Not installed (no Codex CLI and no ${dirname4(configPath)}).`
       };
     }
-    return {
-      client: "Codex",
-      action: "printed",
-      detail: `Codex's CLI was not found. Add this to ${configPath}:
-${codexBlock(serve)}Then fully quit and reopen Codex.`
-    };
+    try {
+      const raw = await readFile2(configPath, "utf8");
+      if (renderCodexConfig(raw, serve) === raw) {
+        return { client: "Codex", action: "skipped", detail: `Already registered at ${configPath}.` };
+      }
+    } catch (err) {
+      if (!(isErrnoException(err) && err.code === "ENOENT")) {
+        return { client: "Codex", action: "error", detail: `Could not inspect ${configPath}: ${errorMessage(err)}` };
+      }
+    }
+    const ok2 = await confirm(
+      `Codex: update ${configPath} to register LLMnesia? Existing settings are preserved and backed up.
+Add:
+${codexBlock(serve)}`
+    );
+    if (!ok2) {
+      return { client: "Codex", action: "declined", detail: "Skipped by user." };
+    }
+    try {
+      const update = await writeCodexConfig(configPath, serve, now);
+      return {
+        client: "Codex",
+        action: update.changed ? "registered" : "skipped",
+        detail: update.changed ? `Wrote ${configPath}${update.backupPath ? ` (backup: ${update.backupPath})` : ""}.` : `Already registered at ${configPath}.`
+      };
+    } catch (err) {
+      return { client: "Codex", action: "error", detail: `Could not update ${configPath}: ${errorMessage(err)}` };
+    }
   }
   let existing;
   try {
@@ -2935,7 +3000,20 @@ ${codexBlock(serve)}Then fully quit and reopen Codex.`
     return { client: "Codex", action: "error", detail: `Could not inspect Codex MCP settings: ${errorMessage(err)}` };
   }
   if (existing?.serve && sameServeCommand(existing.serve, serve)) {
-    return { client: "Codex", action: "skipped", detail: "Already registered." };
+    try {
+      const update = await writeCodexConfig(configPath, serve, now);
+      return {
+        client: "Codex",
+        action: update.changed ? "registered" : "skipped",
+        detail: update.changed ? `Already registered; updated tool approval policy in ${configPath}.` : "Already registered."
+      };
+    } catch (err) {
+      return {
+        client: "Codex",
+        action: "error",
+        detail: `Already registered, but could not set its tool approval policy: ${errorMessage(err)}`
+      };
+    }
   }
   if (existing && !existing.serve) {
     return {
@@ -2975,6 +3053,15 @@ codex mcp add ${SERVER_NAME} -- ${serve.command} ${serve.args.join(" ")}`
     }
     return { client: "Codex", action: "error", detail: `codex mcp add failed: ${errorMessage(err)}` };
   }
+  try {
+    await writeCodexConfig(configPath, serve, now);
+  } catch (err) {
+    return {
+      client: "Codex",
+      action: "error",
+      detail: `Registered the server, but could not set its tool approval policy in ${configPath}: ${errorMessage(err)}`
+    };
+  }
   return {
     client: "Codex",
     action: "registered",
@@ -3035,8 +3122,82 @@ function codexBlock(serve) {
   return `[mcp_servers.${SERVER_NAME}]
 command = ${JSON.stringify(serve.command)}
 args = [${argsToml}]
+default_tools_approval_mode = ${JSON.stringify(CODEX_APPROVAL_MODE)}
 `;
 }
+function codexHeaders(raw) {
+  const headers = [];
+  const pattern = /^[ \t]*\[([^\]\r\n]+)\][ \t]*(?:#.*)?$/gm;
+  for (let match = pattern.exec(raw); match; match = pattern.exec(raw)) {
+    headers.push({ start: match.index, name: match[1].replace(/[ \t]/g, "") });
+  }
+  return headers;
+}
+function isCodexRootHeader(name) {
+  return /^mcp_servers\.(?:llmnesia|"llmnesia"|'llmnesia')$/.test(name);
+}
+function isCodexChildHeader(name) {
+  return /^mcp_servers\.(?:llmnesia|"llmnesia"|'llmnesia')\./.test(name);
+}
+function codexSectionRange(raw) {
+  const headers = codexHeaders(raw);
+  const roots = headers.filter((header) => isCodexRootHeader(header.name));
+  if (roots.length > 1) {
+    throw new Error(`found more than one [mcp_servers.${SERVER_NAME}] table; the file was left unchanged`);
+  }
+  const root = roots[0];
+  if (!root) {
+    if (headers.some((header) => isCodexChildHeader(header.name))) {
+      throw new Error(
+        `found LLMnesia MCP subtables without a [mcp_servers.${SERVER_NAME}] table; the file was left unchanged`
+      );
+    }
+    return null;
+  }
+  const rootIndex = headers.indexOf(root);
+  let end = raw.length;
+  for (let i = rootIndex + 1; i < headers.length; i += 1) {
+    if (!isCodexChildHeader(headers[i].name)) {
+      end = headers[i].start;
+      break;
+    }
+  }
+  return { start: root.start, end };
+}
+function renderCodexConfig(raw, serve) {
+  const newline = raw.includes("\r\n") ? "\r\n" : "\n";
+  const block = codexBlock(serve).replace(/\n/g, newline);
+  const range = codexSectionRange(raw);
+  if (range) {
+    return `${raw.slice(0, range.start)}${block}${raw.slice(range.end)}`;
+  }
+  const base = raw.replace(/[ \t\r\n]+$/g, "");
+  return `${base}${base ? `${newline}${newline}` : ""}${block}`;
+}
+async function writeCodexConfig(configPath, serve, now) {
+  let raw = "";
+  let existed = true;
+  try {
+    raw = await readFile2(configPath, "utf8");
+  } catch (err) {
+    if (isErrnoException(err) && err.code === "ENOENT") {
+      existed = false;
+    } else {
+      throw err;
+    }
+  }
+  const next = renderCodexConfig(raw, serve);
+  if (next === raw) {
+    return { changed: false };
+  }
+  let backupPath;
+  if (existed) {
+    backupPath = `${configPath}.bak-${now()}`;
+    await writeFile2(backupPath, raw, "utf8");
+  }
+  await writeFile2(configPath, next, { encoding: "utf8", mode: 384 });
+  return { changed: true, ...backupPath ? { backupPath } : {} };
+}
 function genericBlock(serve) {
   return JSON.stringify({ mcpServers: { [SERVER_NAME]: { command: serve.command, args: serve.args } } }, null, 2);
 }
@@ -3069,7 +3230,10 @@ async function registerClients(options) {
   }
   results.push(await safe("Cursor", () => registerJsonClient("Cursor", cursor, options.serve, options.confirm, now)));
   results.push(
-    await safe("Codex", () => registerCodex(options.serve, options.codexCli ?? realCodexCli, codex, options.confirm))
+    await safe(
+      "Codex",
+      () => registerCodex(options.serve, options.codexCli ?? realCodexCli, codex, options.confirm, now)
+    )
   );
   results.push({
     client: "Other MCP clients (Windsurf, Zed, LM Studio, ...)",
@@ -3111,20 +3275,27 @@ async function unregisterClaudeCode(cli) {
     };
   }
 }
-async function unregisterCodex(cli, configPath) {
+async function unregisterCodex(cli, configPath, now) {
   if (!await cli.detect()) {
     try {
-      const text = await readFile2(configPath, "utf8");
-      if (new RegExp(`^\\s*\\[mcp_servers\\.${SERVER_NAME}\\]\\s*$`, "m").test(text)) {
-        return {
-          client: "Codex",
-          action: "error",
-          detail: `A registration remains in ${configPath}, but the Codex CLI is unavailable to remove it safely. Restore the CLI and retry. The runtime was retained.`
-        };
+      const raw = await readFile2(configPath, "utf8");
+      const range = codexSectionRange(raw);
+      if (!range) {
+        return { client: "Codex", action: "skipped", detail: "`codex` not found and no registration was detected." };
       }
+      const backupPath = `${configPath}.bak-${now()}`;
+      await writeFile2(backupPath, raw, "utf8");
+      const next = `${raw.slice(0, range.start)}${raw.slice(range.end)}`.replace(/[ \t\r\n]+$/g, "");
+      await writeFile2(configPath, next ? `${next}
+` : "", "utf8");
+      return {
+        client: "Codex",
+        action: "registered",
+        detail: `Removed from ${configPath} (backup: ${backupPath}).`
+      };
     } catch (err) {
       if (!(isErrnoException(err) && err.code === "ENOENT")) {
-        return { client: "Codex", action: "error", detail: `Could not inspect ${configPath}: ${errorMessage(err)}` };
+        return { client: "Codex", action: "error", detail: `Could not update ${configPath}: ${errorMessage(err)}` };
       }
     }
     return { client: "Codex", action: "skipped", detail: "`codex` not found and no registration was detected." };
@@ -3192,7 +3363,7 @@ async function unregisterClients(options = {}) {
     results.push(await safe("Claude Desktop", () => unregisterJsonClient("Claude Desktop", claudeDesktop, now)));
   }
   results.push(await safe("Cursor", () => unregisterJsonClient("Cursor", cursor, now)));
-  results.push(await safe("Codex", () => unregisterCodex(options.codexCli ?? realCodexCli, codex)));
+  results.push(await safe("Codex", () => unregisterCodex(options.codexCli ?? realCodexCli, codex, now)));
   results.push({
     client: "Other MCP clients",
     action: "skipped",
@@ -3671,9 +3842,11 @@ async function runInstall(positionals, options, flags) {
   printRegistrationResults(results);
   hadProblems ||= results.some((result) => result.action === "error");
   process.stdout.write(
-    "\nDone. Fully quit and reopen your MCP apps (and browser) to load LLMnesia.\nFor browser-history sync, open LLMnesia Settings and click \u2018Enable automatic sync\u2019 once.\n"
+    "\nDesktop helper installed. Fully quit and reopen your MCP apps and browser.\nBrowser sync is required or your MCP history will be empty. If you did not start in LLMnesia Settings, open it and click \u2018Enable automatic sync\u2019 once. LLMnesia will finish the first sync automatically.\n"
   );
-  process.stdout.write("Then run `npx -y @llmnesia/mcp@latest doctor` to check what's wired up.\n");
+  const npxCommand = process.platform === "win32" ? "npx.cmd" : "npx";
+  process.stdout.write(`Then run \`${npxCommand} -y @llmnesia/mcp@latest doctor\` to check what's wired up.
+`);
   if (hadProblems) {
     process.stderr.write(
       "\nInstall completed with problems. Review the error messages above; no failure was silently treated as success.\n"

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-EBVGUZX2.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-JFZO44NP.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-EBVGUZX2.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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llmnesia/mcp",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": false,
   "type": "module",
   "comment:mcpName": "The MCP Registry's ownership marker: it must equal server.json's `name`, and the namespace must match how you authenticate with mcp-publisher. `com.llmnesia/...` requires DNS auth (a TXT record on llmnesia.com) — see docs/MCP_INSTALLER_BOARD.md.",
@@ -48,7 +48,7 @@
   },
   "comment:deps": "This package publishes with ZERO runtime dependencies — everything is bundled into dist by tsup (see noExternal in tsup.config.ts). That is not just an optimisation: `install` copies dist/ to ~/.llmnesia/bin so MCP clients can spawn it by absolute path, and nothing puts a node_modules beside that copy, so any unbundled import would fail there with ERR_MODULE_NOT_FOUND. Listing them as runtime deps would also be false comfort — npm would install them next to the package, not next to the copy that actually runs. The workspace packages additionally must not appear in the install graph at all: shared-types does not exist on the registry, and the published claude-code-host is an older build without the exports this package needs.",
   "devDependencies": {
-    "@llmnesia/claude-code-host": "*",
+    "@llmnesia/local-agent-host": "*",
     "@llmnesia/shared-types": "*",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@types/node": "^22.13.0",