From 43b222ca578051f1243185535bd2f945868b3e02 Mon Sep 17 00:00:00 2001 From: gabrielstein-mem0 Date: Thu, 23 Apr 2026 15:04:35 -0700 Subject: [PATCH] docs(codex): fix broken install instructions, lead with direct MCP MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The support ticket that surfaced this found three overlapping issues: 1. docs/integrations/codex.mdx shipped a marketplace.json snippet with path "./plugins/mem0" — a directory that does not exist, with no clone prerequisite documented, and using a folder name that does not match the actual mem0-plugin/ directory. Users copy-pasted it verbatim and hit "plugin/read failed in TUI". 2. The "Manual MCP Configuration" option used a JSON mcpServers block. Codex reads MCP servers as TOML in ~/.codex/config.toml, not JSON. Same bug in docs/platform/mem0-mcp.mdx (no Codex accordion at all on main) and mem0-plugin/README.md Option C. 3. The page claimed "Codex uses a skill-based approach instead of lifecycle hooks" — stale; hooks are now available via opt-in installer (mem0-plugin/scripts/install_codex_hooks.py). Lead with the working TOML MCP config (zero dependencies, works today), demote the marketplace.json to a "Sideload (Advanced)" section with the required git clone step and the correct mem0-plugin path, and point sideloaders at the hooks installer + codex_hooks feature flag. Added troubleshooting entries for the TUI read error and hooks-not-firing. --- docs/integrations/codex.mdx | 99 ++++++++++++++++++------------------- docs/platform/mem0-mcp.mdx | 16 +++++- mem0-plugin/README.md | 22 +++------ 3 files changed, 69 insertions(+), 68 deletions(-) diff --git a/docs/integrations/codex.mdx b/docs/integrations/codex.mdx index e0647e1cc..98abcf81c 100644 --- a/docs/integrations/codex.mdx +++ b/docs/integrations/codex.mdx @@ -30,22 +30,44 @@ export MEM0_API_KEY="m0-your-api-key" ## Installation -### Option A — Repo Marketplace (Recommended for Teams) +### Option A — Direct MCP (Recommended) -Add a `.agents/plugins/marketplace.json` to your repository root: +The fastest way to connect Codex to Mem0 — no downloads, no marketplace. Codex reads MCP servers from `~/.codex/config.toml` as TOML. Add: + +```toml +[mcp_servers.mem0] +url = "https://mcp.mem0.ai/mcp" +bearer_token_env_var = "MEM0_API_KEY" +``` + +Make sure `MEM0_API_KEY` is exported in the shell you launch Codex from, then restart Codex. + + + Codex's `codex mcp add` CLI only supports stdio MCP servers. Because Mem0's MCP is HTTP/streamable, you configure it by editing `config.toml` directly (or via the **Plugins → Connect to a custom MCP → Streamable HTTP** UI in the Codex app). + + +### Option B — Sideload the Plugin (Advanced) + +If you want the full plugin experience — MCP server **plus** the Mem0 SDK skill, memory protocol skill, and opt-in lifecycle hooks — sideload the plugin from a local clone. This follows the Codex [build-plugins](https://developers.openai.com/codex/plugins/build) local-testing workflow. + +**Step 1.** Clone the Mem0 repository: + +```bash +git clone https://github.com/mem0ai/mem0.git ~/src/mem0 +``` + +**Step 2.** Add a marketplace entry at `~/.agents/plugins/marketplace.json`, pointing at the **absolute path** of the `mem0-plugin` directory inside your clone: ```json { "name": "mem0-plugins", - "interface": { - "displayName": "Mem0 Plugins" - }, + "interface": { "displayName": "Mem0 Plugins" }, "plugins": [ { "name": "mem0", "source": { "source": "local", - "path": "./plugins/mem0" + "path": "/Users/YOU/src/mem0/mem0-plugin" }, "policy": { "installation": "AVAILABLE", @@ -57,64 +79,35 @@ Add a `.agents/plugins/marketplace.json` to your repository root: } ``` -Then in Codex, browse the repo's plugin directory and install Mem0. +Swap `/Users/YOU/src/mem0/mem0-plugin` for wherever you cloned. Restart Codex, then run `codex /plugins`, browse the `Mem0 Plugins` marketplace, and install Mem0. -### Option B — Personal Marketplace +**Step 3 (optional) — enable lifecycle hooks.** Codex hooks aren't wired in through the plugin manifest; run the installer once to write them into `~/.codex/hooks.json`: -Add to `~/.agents/plugins/marketplace.json`: - -```json -{ - "name": "mem0-plugins", - "interface": { - "displayName": "Mem0 Plugins" - }, - "plugins": [ - { - "name": "mem0", - "source": { - "source": "local", - "path": "/path/to/mem0-plugin" - }, - "policy": { - "installation": "AVAILABLE", - "authentication": "ON_INSTALL" - }, - "category": "Productivity" - } - ] -} +```bash +python3 ~/src/mem0/mem0-plugin/scripts/install_codex_hooks.py ``` -### Option C — Manual MCP Configuration +Then add the feature flag to `~/.codex/config.toml`: -Add to your Codex MCP config: - -```json -{ - "mcpServers": { - "mem0": { - "type": "http", - "url": "https://mcp.mem0.ai/mcp/", - "headers": { - "Authorization": "Token ${MEM0_API_KEY}" - } - } - } -} +```toml +[features] +codex_hooks = true ``` +This registers three hooks: `SessionStart` (loads prior memories as bootstrap context), `UserPromptSubmit` (injects relevant memories before each prompt), and `Stop` (reminds the agent to persist learnings at turn end). Re-running the installer is idempotent. To remove: `python3 .../install_codex_hooks.py --uninstall`. + - Start a new Codex task and ask: *"List my mem0 entities"* or *"Search my memories for hello"*. If the `mem0` tools appear and respond, you're all set. + After either option, start a new Codex task and ask: *"List my mem0 entities"* or *"Search my memories for hello"*. If the `mem0` tools appear and respond, you're all set. ## What's Included -| Component | Plugin Install | MCP Only | -|-----------|:--------------:|:--------:| +| Component | Sideloaded Plugin | Direct MCP | +|-----------|:-----------------:|:----------:| | MCP Server (9 memory tools) | Yes | Yes | | Memory Protocol Skill | Yes | No | | Mem0 SDK Skill | Yes | No | +| Lifecycle Hooks (opt-in) | Yes | No | ## Available MCP Tools @@ -134,7 +127,7 @@ Once installed, the following tools are available in every Codex session: ## Memory Protocol Skill -Codex uses a skill-based approach instead of lifecycle hooks. When installed via the plugin marketplace, the memory protocol skill instructs the agent to: +When the plugin is sideloaded, the memory protocol skill instructs the agent to: ### On Every New Task 1. Call `search_memories` with a query related to the current task to load relevant context @@ -199,8 +192,10 @@ You: Add WebSocket support for real-time notification delivery. - **"Connection failed"** — Verify `MEM0_API_KEY` is set in your shell: `echo $MEM0_API_KEY` - **No tools appearing** — Restart your Codex session after plugin installation -- **Plugin not found** — Ensure `.agents/plugins/marketplace.json` is at the repository root and `source.path` points to the correct plugin directory -- **Skills not loading** — Verify the `skills` field in `plugin.json` points to a valid directory containing `SKILL.md` files +- **`plugin/read failed in TUI`** — The `source.path` in your `marketplace.json` points to a directory that doesn't exist. Use the **absolute path** to `mem0-plugin/` inside your clone (e.g. `/Users/YOU/src/mem0/mem0-plugin`), not a relative path, and make sure you've actually run `git clone` first. +- **Plugin not found** — Ensure `marketplace.json` lives at `~/.agents/plugins/marketplace.json` (or `$REPO_ROOT/.agents/plugins/marketplace.json`) and `source.path` points to the `mem0-plugin` directory (note: not `plugins/mem0`). +- **Skills not loading** — Verify the `skills` field in `plugin.json` points to a valid directory containing `SKILL.md` files. +- **Hooks not firing** — Confirm `codex_hooks = true` is in `~/.codex/config.toml` under `[features]`, and that `~/.codex/hooks.json` contains the Mem0 entries (re-run the installer if not). Restart Codex after enabling the flag. diff --git a/docs/platform/mem0-mcp.mdx b/docs/platform/mem0-mcp.mdx index 7c9bbd7e0..ef7a977f8 100644 --- a/docs/platform/mem0-mcp.mdx +++ b/docs/platform/mem0-mcp.mdx @@ -10,7 +10,7 @@ estimatedTime: "~2 minutes" - Mem0 Platform account (Sign up here) - API key (Get one from dashboard) - Node.js 14+ (for npx) - - An MCP-compatible client (Claude, Claude Code, Cursor, Windsurf, VS Code, OpenCode) + - An MCP-compatible client (Claude, Claude Code, Codex, Cursor, Windsurf, VS Code, OpenCode) ## What is Mem0 MCP? @@ -86,6 +86,20 @@ You can also configure individual clients: ``` + + Codex reads MCP servers from `~/.codex/config.toml` as TOML (not JSON). Add: + + ```toml + [mcp_servers.mem0-mcp] + url = "https://mcp.mem0.ai/mcp" + bearer_token_env_var = "MEM0_API_KEY" + ``` + + Export `MEM0_API_KEY` in the shell you launch Codex from, then restart Codex. `codex mcp add` only supports stdio servers, so HTTP servers must be added via `config.toml` directly — or via the **Plugins → Connect to a custom MCP → Streamable HTTP** UI in the Codex app. + + For the full plugin experience (memory protocol skill + opt-in lifecycle hooks), see the [Codex integration guide](/integrations/codex). + + ```bash npx mcp-add \ diff --git a/mem0-plugin/README.md b/mem0-plugin/README.md index b2a41d347..e014c7776 100644 --- a/mem0-plugin/README.md +++ b/mem0-plugin/README.md @@ -86,25 +86,17 @@ Add to `~/.agents/plugins/marketplace.json`: } ``` -**Option C — Manual MCP configuration**: +**Option C — Direct MCP configuration** (fastest, MCP-only): -Add to your Codex MCP config: +Codex reads MCP servers from `~/.codex/config.toml` as TOML. Add: -```json -{ - "mcpServers": { - "mem0": { - "type": "http", - "url": "https://mcp.mem0.ai/mcp/", - "headers": { - "Authorization": "Token ${MEM0_API_KEY}" - } - } - } -} +```toml +[mcp_servers.mem0] +url = "https://mcp.mem0.ai/mcp" +bearer_token_env_var = "MEM0_API_KEY" ``` -This installs the MCP server and the Mem0 SDK skill. Codex uses the skill-based memory protocol instead of lifecycle hooks. +Export `MEM0_API_KEY` in your shell and restart Codex. This gives you the MCP tools without the plugin skills or lifecycle hooks. `codex mcp add` only supports stdio servers, so HTTP servers like Mem0's must be added via `config.toml` directly (or via the **Plugins → Connect to a custom MCP → Streamable HTTP** UI in the Codex app). ### Cursor