@lotargo/memory_plugin 1.6.2 → 1.6.3

package/CHANGELOG.md

@@ -3,9 +3,36 @@
 All notable changes to `@lotargo/memory_plugin` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.6.2] - 2026-08-12
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.6.3] - 2026-08-13
+
+### Added
+
+- `memory_plugin doctor --codex` validates the configured executable and Node.js
+  version, performs direct MCP `initialize` / `tools/list`, and calls both
+  `memory_info` and `recall(scope="all")`.
+- Codex regression coverage for Windows paths with spaces, legacy config migration,
+  duplicate removal, standalone MCP protocol smoke testing, two-repository project
+  isolation, global-only recall outside Git, and prompt idempotency.
+
+### Fixed
+
+- Codex setup no longer launches the memory MCP through `npx` or a Windows `.cmd`
+  shim. It writes absolute paths for the active Node executable and packaged
+  `mcp-server/boot.js` entry point after validating Node.js >= 22.5.0.
+- Existing plugin-owned `[mcp_servers.memory-agent]` sections, including the legacy
+  `opencode-memory-plugin` entry, are migrated in place without modifying unrelated
+  TOML sections or creating duplicates.
+- Repeated prompt setup now collapses duplicate plugin-owned blocks while preserving
+  user-authored AGENTS.md / CLAUDE.md content.
+- README tool counts now match the implementations: 15 MCP tools, 16 native
+  OpenCode tools, and 17 unique tool names across both surfaces. The OpenCode tool
+  list and the MCP-only status of `batch_query_knowledge_base` are documented explicitly.
+
+## [1.6.2] - 2026-08-12
 
 ### Added
 

package/README.md

@@ -77,9 +77,25 @@ memory_plugin setup --opencode
 # Claude Code
 memory_plugin setup --claude
 
-# Codex
-memory_plugin setup --codex
-```
+# Codex
+memory_plugin setup --codex
+```
+
+Codex is configured with a direct executable chain (`node` → `mcp-server/boot.js`),
+not `npx`. This avoids Windows stdio handshake failures caused by `.cmd` launchers.
+Running setup again safely migrates legacy `npx` entries and preserves unrelated
+sections in `~/.codex/config.toml`.
+
+To verify registration, the Node runtime, MCP initialization, tool discovery, and
+real `memory_info` / `recall(scope="all")` calls:
+
+```bash
+memory_plugin doctor --codex
+```
+
+The doctor checks the server process itself. If it passes but a fresh Codex Desktop
+task still does not expose the tools, the remaining fault is in Desktop tool
+exposure rather than the memory MCP launcher.
 
 `setup` also accepts `--gemini` (alias for Antigravity) and `--local` (registers the MCP server in the project-local `.agents/` directory). Without a specific flag, all detected environments are configured.
 
@@ -107,7 +123,7 @@ memory_plugin setup --mode only-cloud
    - **Project Identity**: Project stores are bound to a **Git-based project identity** — the normalized remote URL (`git:github.com/owner/repo`) or `git:local:<repo basename>` — never to a directory path. Memories follow the repository across machines, OSes, and subdirectories. Legacy path/basename stores can be linked and merged via `link_project_memory`.
 
 2. **Layer 2: RAG Knowledge Base (Technical Documents & Codebases)**
-   - **Tools**: `ingest_document`, `query_knowledge_base`, `manage_knowledge_base`, `reindex_knowledge_base`
+   - **Tools**: `ingest_document`, `query_knowledge_base`, `batch_query_knowledge_base`, `manage_knowledge_base`, `reindex_knowledge_base`
    - **Capabilities**: Ingests raw text files, Markdown, HTML, Web URLs, office documents (PDF, DOCX, XLSX, CSV), and codebases.
    - **Engine Components**: 3-tier hierarchy chunking (Big / Medium / Small), SQLite FTS5 BM25 search, ONNX dense vector embeddings (`multilingual-e5-small`), Reciprocal Rank Fusion (RRF / RSF), cross-encoder reranking (optional), and GraphRAG Lite code symbol extraction.
 
@@ -147,11 +163,22 @@ Cloud authentication tokens are never written to `config.json`. They are stored
 
 ---
 
-## Available MCP Tools
-
-The MCP server registers **14 MCP tools** accessible across all connected AI environments, plus **2 OpenCode-plugin helper tools** available only inside OpenCode:
-
-### 1. Memory Notebook Tools (Layer 1)
+## Available Tools
+
+The package currently exposes **17 unique tool names** across its two integration surfaces:
+
+| Integration surface | Tool count | Composition |
+| :------------------ | ---------: | :---------- |
+| **MCP server** (Codex, Claude Code, Antigravity / Gemini CLI and other MCP clients) | **15** | 6 Notebook + 4 identity/graph + 5 RAG tools |
+| **Native OpenCode plugin** | **16** | 14 shared memory/identity/RAG tools + 2 OpenCode-only helpers |
+
+The two surfaces are intentionally counted separately. The OpenCode plugin adds
+`list-mcp-tools` and `mcp-reminder`, but currently does not register the MCP-only
+`batch_query_knowledge_base` tool.
+
+### MCP Server Tools (15)
+
+#### 1. Memory Notebook Tools (Layer 1)
 
 | Tool | Scope / Target | Key Parameters | Description |
 | :--- | :------------- | :------------- | :---------- |
@@ -162,7 +189,7 @@ The MCP server registers **14 MCP tools** accessible across all connected AI env
 | `forget` | `project` / `global` | `id` / `range` / `query`, `scope`, `force` | Remove a fact by index number, ID, range (e.g. `"3-30"`), or query. Requires `force: true` for protected (`[KEEP]`) facts. |
 | `memory_info` | - | - | Show storage paths, fact counts, RAG statistics, git identity bindings, and package version. |
 
-### 2. Project Identity Tools
+#### 2. Project Identity Tools
 
 | Tool | Key Parameters | Description |
 | :--- | :------------- | :---------- |
@@ -170,7 +197,7 @@ The MCP server registers **14 MCP tools** accessible across all connected AI env
 | `unlink_project_memory` | `directory`, `purge` | Remove a path alias binding for a directory. Optionally purge the project identity entry if `purge: true`. |
 | `relink_project_memory` | `directory`, `remote` | Switch a project's primary identity to a new remote URL and merge all stored facts into the target store with fact-text deduplication. |
 
-### 3. RAG Knowledge Base & Graph Tools (Layers 2 & 3)
+#### 3. RAG Knowledge Base & Graph Tools (Layers 2 & 3)
 
 | Tool | Key Parameters | Description |
 | :--- | :------------- | :---------- |
@@ -181,12 +208,21 @@ The MCP server registers **14 MCP tools** accessible across all connected AI env
 | `reindex_knowledge_base` | `model`, `dimension` | Re-embed all stored vectors with the active (or specified) embedding model and vector dimension. Use after switching the embedding model or vector dimension so previously indexed documents remain retrievable. Preserves documents, FTS index, graph edges, and fact links. |
 | `link_knowledge` | `action`, `factText`, `docId`, `scope`, `startLine`, `endLine`, `relationType` | Create, list, or retrieve semantic graph links connecting Notebook facts to Knowledge Base documents, sections, or line ranges. Actions: `link`, `list_links`, `get_doc_links`. |
 
-### 4. Agent & OpenCode Helpers (OpenCode plugin only, not exposed by the MCP server)
-
-| Tool | Key Parameters | Description |
-| :--- | :------------- | :---------- |
-| `list-mcp-tools` | - | Discover all connected MCP servers and their available tool definitions. |
-| `mcp-reminder` | `task` | Recommends the appropriate MCP tool or server for a specific developer task. |
+### Native OpenCode Plugin Tools (16)
+
+| Group | Count | Tools |
+| :---- | ----: | :---- |
+| **Memory Notebook** | 6 | `remember`, `recall`, `get_fact`, `forget`, `update_fact`, `memory_info` |
+| **Project Identity & Knowledge Graph** | 4 | `link_knowledge`, `link_project_memory`, `unlink_project_memory`, `relink_project_memory` |
+| **RAG Knowledge Base** | 4 | `ingest_document`, `query_knowledge_base`, `manage_knowledge_base`, `reindex_knowledge_base` |
+| **OpenCode-only helpers** | 2 | `list-mcp-tools`, `mcp-reminder` |
+
+The OpenCode-only helpers have the following purpose:
+
+| Tool | Key Parameters | Description |
+| :--- | :------------- | :---------- |
+| `list-mcp-tools` | - | Discover connected MCP servers and their intended use cases. |
+| `mcp-reminder` | `task` | Recommend the appropriate MCP tool or server for a developer task. |
 
 ---
 
@@ -216,7 +252,8 @@ Both binaries accept the same commands. `memory_plugin` with **no** command star
 | **`identity`** | `--dir <path>` | Inspects Git project identity key, primary remote, name, and toplevel path for a directory. |
 | **`migrate_titles`** | `--key <key>` | Auto-generates `**Title**` prefixes for legacy facts without titles. |
 | **`enable-prompt`** | - | Injects memory agent instructions into client agent files (`AGENTS.md`, `CLAUDE.md`). |
-| **`disable-prompt`** | - | Removes memory agent instructions from client agent files. |
+| **`disable-prompt`** | - | Removes memory agent instructions from client agent files. |
+| **`doctor`** | `--codex` | Validates Codex config, direct Node runtime, MCP initialize/tools/list, and live `memory_info` + `recall` calls. |
 | **`login`** | `--api-token`, `--from-env`, `--db-url <URL> --db-token`, `$TURSO_API_TOKEN`, `$TURSO_DB_TOKEN` | Authenticates with Turso Cloud via API token, direct DB token, or environment variables. Token values are read from the environment or a hidden stdin prompt. |
 | **`logout`** | `--api-key` | Signs out of Turso Cloud or removes stored API key while retaining DB session. |
 | **`auth-status`** | - | Displays authentication source, endpoint URL, username, organization, database, and sync mode. |
@@ -295,7 +332,7 @@ During `ingest_document`, code symbols are extracted from code blocks using fast
 | Platform | Status | Configuration Mechanism |
 | :--- | :--- | :--- |
 | **Antigravity / Gemini CLI** | Supported | MCP Server (`~/.gemini/config/mcp_config.json` & `.agents/mcp_config.json`) |
-| **OpenCode** | Native | Native plugin + MCP Server (`~/.config/opencode/opencode.json`) |
+| **OpenCode** | Native | Native plugin with 16 tools (`~/.config/opencode/opencode.json`) |
 | **Claude Code** | Supported | MCP Server (`~/.claude.json`) |
 | **Codex** | Supported | MCP Server (`~/.codex/config.toml`) |
 | **Google Jules** | Supported | MCP Server via global install + setup (`memory_plugin setup`) |
@@ -339,7 +376,7 @@ The engine is configured through `<memory-dir>/config.json` (created with defaul
 To run the automated test suite and benchmarks locally, from the repository root:
 
 ```bash
-# Unit + integration + cloud suites (12 files) — fast and fully offline
+# Unit + integration + cloud suites (16 files) — fast and fully offline
 npm test
 
 # End-to-end smoke test with REAL ONNX embeddings — run before a release

package/mcp-server/cli/direct_commands.js

@@ -11,7 +11,16 @@ import {
 } from "../memory.js";
 import { factBody } from "../fact_format.js";
 
-export async function handleDirectCommands(cliArgs) {
+export async function handleDirectCommands(cliArgs) {
+  if (cliArgs[0] === "doctor" && cliArgs.includes("--codex")) {
+    const { runCodexDoctor } = await import("../codex_diagnostics.js");
+    console.log("\nCodex memory-agent diagnostics\n");
+    const result = await runCodexDoctor();
+    console.log("");
+    if (!result.ok) process.exitCode = 1;
+    return true;
+  }
+
   if (cliArgs[0] === "link") {
     const dirIdx = cliArgs.indexOf("--dir");
     const dir = dirIdx >= 0 && cliArgs[dirIdx + 1] ? cliArgs[dirIdx + 1] : process.cwd();

package/mcp-server/cli.js

@@ -23,7 +23,8 @@ Usage:
   memory-cli auth-status
   memory-cli link|unlink|relink|identity [--dir <path>] [--remote <url>]
   memory-cli migrate_titles [--key <key>]
-  memory-cli enable-prompt | disable-prompt
+  memory-cli enable-prompt | disable-prompt
+  memory-cli doctor --codex
 
 Options:
   -h, --help                         Show this help text`);

package/mcp-server/codex_config.js

@@ -0,0 +1,171 @@
+import { existsSync } from "node:fs";
+
+export const MIN_NODE_VERSION = Object.freeze({ major: 22, minor: 5, patch: 0 });
+export const DEFAULT_CODEX_STARTUP_TIMEOUT_SEC = 60;
+
+function parseVersion(version) {
+  const match = String(version || "").trim().replace(/^v/i, "").match(/^(\d+)\.(\d+)(?:\.(\d+))?/);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3] || 0),
+  };
+}
+
+export function isSupportedNodeVersion(version) {
+  const parsed = parseVersion(version);
+  if (!parsed) return false;
+  if (parsed.major !== MIN_NODE_VERSION.major) return parsed.major > MIN_NODE_VERSION.major;
+  if (parsed.minor !== MIN_NODE_VERSION.minor) return parsed.minor > MIN_NODE_VERSION.minor;
+  return parsed.patch >= MIN_NODE_VERSION.patch;
+}
+
+export function validateCodexRuntime({
+  nodePath,
+  nodeVersion = process.versions.node,
+  bootPath,
+  pathExists = existsSync,
+} = {}) {
+  const errors = [];
+  if (!nodePath || !pathExists(nodePath)) {
+    errors.push(`Node executable not found: ${nodePath || "<empty>"}`);
+  }
+  if (!isSupportedNodeVersion(nodeVersion)) {
+    errors.push(
+      `@lotargo/memory_plugin requires Node.js >= ${MIN_NODE_VERSION.major}.${MIN_NODE_VERSION.minor}.0; detected ${nodeVersion || "unknown"}`
+    );
+  }
+  if (!bootPath || !pathExists(bootPath)) {
+    errors.push(`MCP boot entry point not found: ${bootPath || "<empty>"}`);
+  }
+  return { ok: errors.length === 0, errors, nodePath, nodeVersion, bootPath };
+}
+
+export function escapeTomlBasicString(value) {
+  return String(value)
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\u0008/g, "\\b")
+    .replace(/\t/g, "\\t")
+    .replace(/\n/g, "\\n")
+    .replace(/\f/g, "\\f")
+    .replace(/\r/g, "\\r");
+}
+
+export function buildCodexMemoryAgentSection({
+  nodePath,
+  bootPath,
+  startupTimeoutSec = DEFAULT_CODEX_STARTUP_TIMEOUT_SEC,
+} = {}) {
+  if (!nodePath || !bootPath) throw new Error("nodePath and bootPath are required");
+  if (!Number.isInteger(startupTimeoutSec) || startupTimeoutSec <= 0) {
+    throw new Error("startupTimeoutSec must be a positive integer");
+  }
+  return [
+    "[mcp_servers.memory-agent]",
+    `command = "${escapeTomlBasicString(nodePath)}"`,
+    `args = ["${escapeTomlBasicString(bootPath)}"]`,
+    `startup_timeout_sec = ${startupTimeoutSec}`,
+  ].join("\n");
+}
+
+function tableHeaderName(line) {
+  const match = String(line).match(/^\s*\[\s*([^\[\]]+?)\s*\]\s*(?:#.*)?$/);
+  return match ? match[1] : null;
+}
+
+function isMemoryAgentHeader(name, { exact = false } = {}) {
+  if (!name) return false;
+  const suffix = exact ? "$" : "(?:\\s*\\.|$)";
+  return new RegExp(
+    `^mcp_servers\\s*\\.\\s*(?:memory-agent|"memory-agent"|'memory-agent')${suffix}`,
+    "i"
+  ).test(name);
+}
+
+export function isMemoryPluginOwnedSection(sectionText) {
+  return /@lotargo[\\/]memory_plugin|opencode-memory-plugin|(?:^|[\\/])memory_plugin(?:[\\/]|\b)|mcp-server[\\/]+boot\.js/i.test(
+    String(sectionText || "")
+  );
+}
+
+function sectionRanges(lines) {
+  const headers = [];
+  for (let i = 0; i < lines.length; i++) {
+    const name = tableHeaderName(lines[i]);
+    if (name) headers.push({ start: i, name });
+  }
+  return headers.map((header, index) => ({
+    ...header,
+    end: index + 1 < headers.length ? headers[index + 1].start : lines.length,
+  }));
+}
+
+export function getCodexMemoryAgentSections(content) {
+  const lines = String(content || "").split(/\r?\n/);
+  return sectionRanges(lines)
+    .filter((range) => isMemoryAgentHeader(range.name))
+    .map((range) => ({
+      ...range,
+      exact: isMemoryAgentHeader(range.name, { exact: true }),
+      text: lines.slice(range.start, range.end).join("\n").trimEnd(),
+    }));
+}
+
+export function updateCodexMemoryAgentConfig(content, options) {
+  const source = String(content || "");
+  const eol = source.includes("\r\n") ? "\r\n" : "\n";
+  const lines = source.split(/\r?\n/);
+  const desired = buildCodexMemoryAgentSection(options).split("\n");
+  const ranges = sectionRanges(lines);
+  const targets = ranges.filter((range) => isMemoryAgentHeader(range.name));
+  const exactTargets = targets.filter((range) => isMemoryAgentHeader(range.name, { exact: true }));
+
+  const unowned = exactTargets.filter((range) => {
+    const text = lines.slice(range.start, range.end).join("\n");
+    return !isMemoryPluginOwnedSection(text);
+  });
+  if (unowned.length > 0) {
+    return {
+      content: source,
+      changed: false,
+      status: "conflict",
+      reason: "Existing [mcp_servers.memory-agent] section is not recognized as owned by @lotargo/memory_plugin",
+    };
+  }
+
+  if (targets.length === 0) {
+    const prefix = source.length === 0 ? "" : source.replace(/[\r\n]+$/, "") + eol + eol;
+    return { content: prefix + desired.join(eol) + eol, changed: true, status: "added" };
+  }
+
+  const targetStarts = new Map(targets.map((target) => [target.start, target]));
+  const targetLineIndexes = new Set();
+  for (const target of targets) {
+    for (let i = target.start; i < target.end; i++) targetLineIndexes.add(i);
+  }
+
+  const firstStart = Math.min(...targets.map((target) => target.start));
+  const result = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (i === firstStart) {
+      while (result.length > 0 && result[result.length - 1] === "") result.pop();
+      if (result.length > 0) result.push("");
+      result.push(...desired, "");
+    }
+    if (targetLineIndexes.has(i)) continue;
+    if (targetStarts.has(i)) continue;
+    result.push(lines[i]);
+  }
+
+  while (result.length > 1 && result[result.length - 1] === "" && result[result.length - 2] === "") {
+    result.pop();
+  }
+  const updated = result.join(eol);
+  return {
+    content: updated,
+    changed: updated !== source,
+    status: updated === source ? "unchanged" : "migrated",
+  };
+}

package/mcp-server/codex_diagnostics.js

@@ -0,0 +1,263 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { getCodexMemoryAgentSections, isSupportedNodeVersion } from "./codex_config.js";
+
+function decodeTomlString(raw) {
+  const value = String(raw || "").trim();
+  if (value.startsWith('"')) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  if (value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1).replace(/''/g, "'");
+  return null;
+}
+
+export function parseCodexMemoryAgentConfig(content) {
+  const exact = getCodexMemoryAgentSections(content).filter((section) => section.exact);
+  if (exact.length !== 1) {
+    return {
+      ok: false,
+      error: exact.length === 0
+        ? "[mcp_servers.memory-agent] section not found"
+        : `Found ${exact.length} memory-agent sections`,
+      sectionCount: exact.length,
+    };
+  }
+
+  const text = exact[0].text;
+  const commandMatch = text.match(/^\s*command\s*=\s*(.+?)\s*$/m);
+  const argsMatch = text.match(/^\s*args\s*=\s*\[([\s\S]*?)\]\s*$/m);
+  const timeoutMatch = text.match(/^\s*startup_timeout_sec\s*=\s*(\d+)\s*$/m);
+  const command = decodeTomlString(commandMatch?.[1]);
+  const args = [];
+  if (argsMatch) {
+    const stringPattern = /"(?:\\.|[^"\\])*"|'(?:''|[^'])*'/g;
+    for (const match of argsMatch[1].matchAll(stringPattern)) {
+      const decoded = decodeTomlString(match[0]);
+      if (decoded === null) return { ok: false, error: "Unable to parse memory-agent args", sectionCount: 1 };
+      args.push(decoded);
+    }
+  }
+
+  if (!command) return { ok: false, error: "Unable to parse memory-agent command", sectionCount: 1 };
+  if (!argsMatch) return { ok: false, error: "Unable to parse memory-agent args", sectionCount: 1 };
+  return {
+    ok: true,
+    command,
+    args,
+    startupTimeoutSec: timeoutMatch ? Number(timeoutMatch[1]) : null,
+    sectionCount: 1,
+    text,
+  };
+}
+
+function toolText(result) {
+  return (result?.content || [])
+    .filter((item) => item.type === "text")
+    .map((item) => item.text)
+    .join("\n");
+}
+
+export async function runDirectMcpSmoke({
+  command,
+  args = [],
+  cwd = process.cwd(),
+  env = process.env,
+  timeoutMs = 30_000,
+} = {}) {
+  if (!command) throw new Error("MCP command is required");
+  const child = spawn(command, args, { cwd, env: { ...env }, stdio: ["pipe", "pipe", "pipe"] });
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+
+  let nextId = 0;
+  let stdoutBuffer = "";
+  let stderr = "";
+  let settled = false;
+  const pending = new Map();
+
+  const rejectAll = (error) => {
+    for (const { reject } of pending.values()) reject(error);
+    pending.clear();
+  };
+  child.stderr.on("data", (chunk) => { stderr += chunk; });
+  child.stdout.on("data", (chunk) => {
+    stdoutBuffer += chunk;
+    let newline;
+    while ((newline = stdoutBuffer.indexOf("\n")) >= 0) {
+      const line = stdoutBuffer.slice(0, newline).trim();
+      stdoutBuffer = stdoutBuffer.slice(newline + 1);
+      if (!line) continue;
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch (error) {
+        rejectAll(new Error(`Invalid JSON-RPC output: ${error.message}; line=${line.slice(0, 200)}`));
+        continue;
+      }
+      const waiter = pending.get(message.id);
+      if (!waiter) continue;
+      pending.delete(message.id);
+      if (message.error) waiter.reject(new Error(message.error.message || JSON.stringify(message.error)));
+      else waiter.resolve(message.result);
+    }
+  });
+  child.on("error", (error) => rejectAll(error));
+  child.on("exit", (code, signal) => {
+    if (!settled && pending.size > 0) {
+      rejectAll(new Error(`MCP server exited before completing diagnostics (code=${code}, signal=${signal}): ${stderr.trim()}`));
+    }
+  });
+
+  const request = (method, params = {}) => {
+    const id = ++nextId;
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject });
+      child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+    });
+  };
+  const withTimeout = (promise, label) => new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`Timed out waiting for ${label} after ${timeoutMs}ms`)), timeoutMs);
+    promise.then(
+      (value) => { clearTimeout(timer); resolve(value); },
+      (error) => { clearTimeout(timer); reject(error); }
+    );
+  });
+
+  try {
+    await withTimeout(request("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "memory-plugin-codex-doctor", version: "1.0.0" },
+    }), "initialize");
+    child.stdin.write(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }) + "\n");
+
+    const toolsResult = await withTimeout(request("tools/list"), "tools/list");
+    const toolNames = (toolsResult?.tools || []).map((tool) => tool.name);
+    for (const required of ["memory_info", "recall"]) {
+      if (!toolNames.includes(required)) throw new Error(`Required MCP tool is missing: ${required}`);
+    }
+    const infoResult = await withTimeout(
+      request("tools/call", { name: "memory_info", arguments: {} }),
+      "memory_info"
+    );
+    const recallResult = await withTimeout(
+      request("tools/call", { name: "recall", arguments: { scope: "all" } }),
+      "recall(scope=all)"
+    );
+    settled = true;
+    return {
+      ok: true,
+      toolNames,
+      memoryInfo: toolText(infoResult),
+      recall: toolText(recallResult),
+      stderr: stderr.trim(),
+    };
+  } finally {
+    settled = true;
+    rejectAll(new Error("MCP diagnostics finished"));
+    if (child.exitCode === null) child.kill();
+  }
+}
+
+function countOccurrences(text, needle) {
+  let count = 0;
+  let offset = 0;
+  while ((offset = text.indexOf(needle, offset)) !== -1) {
+    count++;
+    offset += needle.length;
+  }
+  return count;
+}
+
+export async function runCodexDoctor({
+  home = homedir(),
+  cwd = process.cwd(),
+  env = process.env,
+  output = console,
+} = {}) {
+  const checks = [];
+  const record = (level, label, detail = "") => {
+    checks.push({ level, label, detail });
+    output.log(`[${level}] ${label}${detail ? `: ${detail}` : ""}`);
+  };
+
+  const configPath = join(home, ".codex", "config.toml");
+  if (!existsSync(configPath)) {
+    record("FAIL", "Codex config found", configPath);
+    return { ok: false, checks, configPath };
+  }
+  record("OK", "Codex config found", configPath);
+  const config = readFileSync(configPath, "utf8");
+  const parsed = parseCodexMemoryAgentConfig(config);
+  if (!parsed.ok) {
+    record("FAIL", "memory-agent configuration", parsed.error);
+    return { ok: false, checks, configPath };
+  }
+  record("OK", "Single memory-agent section found");
+  record(parsed.command.toLowerCase().includes("npx") ? "FAIL" : "OK", "Direct executable launcher", parsed.command);
+  record(existsSync(parsed.command) ? "OK" : "FAIL", "Command executable exists", parsed.command);
+
+  const bootPath = parsed.args[0];
+  record(bootPath && existsSync(bootPath) ? "OK" : "FAIL", "boot.js exists", bootPath || "missing first arg");
+  record(parsed.args.length === 1 ? "OK" : "FAIL", "boot.js is the only launcher argument", JSON.stringify(parsed.args));
+
+  let detectedVersion = null;
+  try {
+    detectedVersion = await new Promise((resolve, reject) => {
+      const child = spawn(parsed.command, ["--version"], { cwd, env: { ...env }, stdio: ["ignore", "pipe", "pipe"] });
+      let stdout = "";
+      let stderr = "";
+      child.stdout.setEncoding("utf8");
+      child.stderr.setEncoding("utf8");
+      child.stdout.on("data", (chunk) => { stdout += chunk; });
+      child.stderr.on("data", (chunk) => { stderr += chunk; });
+      child.on("error", reject);
+      child.on("exit", (code) => code === 0 ? resolve(stdout.trim()) : reject(new Error(stderr.trim() || `exit ${code}`)));
+    });
+    record(isSupportedNodeVersion(detectedVersion) ? "OK" : "FAIL", "Node.js version >= 22.5.0", detectedVersion);
+  } catch (error) {
+    record("FAIL", "Node.js version check", error.message);
+  }
+
+  try {
+    const smoke = await runDirectMcpSmoke({ command: parsed.command, args: parsed.args, cwd, env });
+    record("OK", "MCP initialize");
+    record("OK", "MCP tools/list", `${smoke.toolNames.length} tools`);
+    record("OK", "memory_info tool call");
+    record("OK", "recall(scope=all) tool call");
+  } catch (error) {
+    record("FAIL", "Direct MCP protocol smoke test", error.message);
+  }
+
+  try {
+    const { resolveProjectIdentity } = await import("./identity.js");
+    const identity = await resolveProjectIdentity(cwd);
+    record("INFO", "Current project identity", identity?.key || "none (global memory only)");
+  } catch (error) {
+    record("WARN", "Current project identity", error.message);
+  }
+
+  const agentsPath = join(home, ".codex", "AGENTS.md");
+  if (existsSync(agentsPath)) {
+    const agents = readFileSync(agentsPath, "utf8");
+    const starts = countOccurrences(agents, "<!-- START MEMORY AGENT PROMPT -->");
+    const ends = countOccurrences(agents, "<!-- END MEMORY AGENT PROMPT -->");
+    record(starts === 1 && ends === 1 ? "OK" : "WARN", "Codex memory prompt block count", `start=${starts}, end=${ends}`);
+  } else {
+    record("WARN", "Codex memory prompt", `${agentsPath} not found`);
+  }
+
+  record(
+    "INFO",
+    "Codex Desktop exposure",
+    "Cannot be proven by the MCP server; start a new task after setup and verify that memory-agent tools are listed"
+  );
+  const ok = !checks.some((check) => check.level === "FAIL");
+  return { ok, checks, configPath, parsed, detectedVersion };
+}

package/mcp-server/index.js

@@ -36,7 +36,8 @@ const CLI_COMMANDS = new Set([
   "identity",
   "migrate_titles",
   "enable-prompt",
-  "disable-prompt",
+  "disable-prompt",
+  "doctor",
 ]);
 
 function printUsage() {
@@ -51,7 +52,8 @@ Usage:
   memory_plugin auth-status
   memory_plugin link|unlink|relink|identity [--dir <path>] [--remote <url>]
   memory_plugin migrate_titles [--key <key>]
-  memory_plugin enable-prompt | disable-prompt
+  memory_plugin enable-prompt | disable-prompt
+  memory_plugin doctor --codex
 
 Options:
   -h, --help                         Show this help text

package/mcp-server/prompt_manager.js

@@ -99,17 +99,21 @@ function buildIncludeBlock(promptFile) {
 ${END_MARKER}`;
 }
 
-function stripPromptBlock(content) {
-  const startIndex = content.indexOf(START_MARKER);
-  const endIndex = content.indexOf(END_MARKER);
-
-  if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
-    const before = content.substring(0, startIndex);
-    const after = content.substring(endIndex + END_MARKER.length);
-    return (before + after).replace(/\n{3,}/g, "\n\n").trim();
-  }
-  return content.trim();
-}
+export function stripPromptBlock(content) {
+  let clean = String(content || "");
+  while (true) {
+    const startIndex = clean.indexOf(START_MARKER);
+    const endIndex = clean.indexOf(END_MARKER, startIndex + START_MARKER.length);
+    if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex) break;
+    clean = clean.substring(0, startIndex) + clean.substring(endIndex + END_MARKER.length);
+  }
+  return clean.replace(/\r?\n(?:[ \t]*\r?\n){2,}/g, "\n\n").trim();
+}
+
+export function upsertPromptBlock(content, block = PROMPT_BLOCK) {
+  const clean = stripPromptBlock(content);
+  return clean ? `${clean}\n\n${block}\n` : `${block}\n`;
+}
 
 export async function enableGlobalPrompt() {
   const promptFile = await syncPromptFile();
@@ -126,12 +130,10 @@ export async function enableGlobalPrompt() {
 
       const existed = existsSync(target.filePath);
       const existing = existed ? await readFile(target.filePath, "utf-8") : "";
-      const clean = stripPromptBlock(existing);
-
-      const block = target.includeSupported
-        ? buildIncludeBlock(promptFile)
-        : PROMPT_BLOCK;
-      const updated = clean ? `${clean}\n\n${block}\n` : `${block}\n`;
+      const block = target.includeSupported
+        ? buildIncludeBlock(promptFile)
+        : PROMPT_BLOCK;
+      const updated = upsertPromptBlock(existing, block);
 
       const key = target.filePath;
       const prev = state[key];

package/mcp-server/setup.js

@@ -187,27 +187,43 @@ export async function runSetup() {
     }
   }
 
-  // 4. Codex (~/.codex/config.toml)
-  if (doCodex) {
-    try {
-      const codexDir = join(home, ".codex");
-      const codexConfig = join(codexDir, "config.toml");
-      if (existsSync(codexDir)) {
-        let content = existsSync(codexConfig) ? await readFile(codexConfig, "utf-8") : "";
-        if (!content.includes("memory-agent")) {
-          const tomlSnippet = `\n[mcp_servers.memory-agent]\ncommand = "npx"\nargs = ["-y", "@lotargo/memory_plugin"]\n`;
-          content += tomlSnippet;
-          await writeFile(codexConfig, content);
-          console.log("  [OK] Codex: added mcp_servers.memory-agent to ~/.codex/config.toml");
-          configuredCount++;
-        } else {
-          console.log("  [INFO] Codex: already configured");
-        }
-      }
-    } catch (err) {
-      console.log("  [SKIP] Codex setup skipped:", err.message);
-    }
-  }
+  // 4. Codex (~/.codex/config.toml)
+  if (doCodex) {
+    try {
+      const {
+        updateCodexMemoryAgentConfig,
+        validateCodexRuntime,
+      } = await import("./codex_config.js");
+      const codexDir = join(home, ".codex");
+      const codexConfig = join(codexDir, "config.toml");
+      const nodePath = process.execPath;
+      const bootPath = fileURLToPath(new URL("./boot.js", import.meta.url));
+      const runtime = validateCodexRuntime({ nodePath, nodeVersion: process.versions.node, bootPath });
+      if (!runtime.ok) {
+        throw new Error(`Codex direct launcher validation failed: ${runtime.errors.join("; ")}`);
+      }
+
+      await mkdir(codexDir, { recursive: true });
+      const content = existsSync(codexConfig) ? await readFile(codexConfig, "utf-8") : "";
+      const update = updateCodexMemoryAgentConfig(content, { nodePath, bootPath });
+      if (update.status === "conflict") {
+        throw new Error(update.reason);
+      }
+      if (update.changed) {
+        await writeFile(codexConfig, update.content, "utf-8");
+        console.log(
+          update.status === "added"
+            ? "  [OK] Codex: added direct Node.js memory-agent launcher to ~/.codex/config.toml"
+            : "  [OK] Codex: migrated memory-agent to a direct Node.js launcher in ~/.codex/config.toml"
+        );
+        configuredCount++;
+      } else {
+        console.log("  [INFO] Codex: direct Node.js memory-agent launcher already configured");
+      }
+    } catch (err) {
+      console.log("  [FAIL] Codex setup failed:", err.message);
+    }
+  }
 
   // 5. Global Prompt Instructions (Antigravity, Codex, Claude Code)
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotargo/memory_plugin",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "description": "100% local hybrid RAG memory for AI coding agents (OpenCode, Claude Code, Codex, Antigravity). MCP server + plugin: persistent user facts, document ingestion, vector + SQLite FTS5 retrieval across sessions.",
   "type": "module",
   "main": "opencode-plugin/index.js",
@@ -33,8 +33,10 @@
     "mcp-server/tools",
     "mcp-server/boot.js",
     "mcp-server/cli_boot.js",
-    "mcp-server/cli.js",
-    "mcp-server/index.js",
+    "mcp-server/cli.js",
+    "mcp-server/codex_config.js",
+    "mcp-server/codex_diagnostics.js",
+    "mcp-server/index.js",
     "mcp-server/fact_format.js",
     "mcp-server/identity.js",
     "mcp-server/logger.js",