docs(codex): lead sideload with CLI, flag auto-MCP, align server name

Rework the Codex install flow around `codex plugin marketplace add
<clone>` so users can lean on the repo's bundled
`.agents/plugins/marketplace.json` instead of hand-authoring one.
This removes the "path must be under ~/" constraint that was tripping
people up.

Also:
- Call out that sideloading auto-registers `mem0` via .codex-mcp.json,
  so Option A (Direct MCP) and Option B (sideload) must not be combined.
- Rename the Direct MCP snippet on the platform page from `mem0-mcp`
  to `mem0` to match the bundled plugin — prevents silent duplicate
  servers for users who follow one path then try the other.
- Drop the trailing slash in .codex-mcp.json's URL to match the rest
  of the docs.
- Add `codex plugin marketplace upgrade` / `remove` and the plugin
  cache path (~/.codex/plugins/cache/...).
- New troubleshooting entries for duplicate MCP registration and for
  hooks breaking after a clone is moved (the installer bakes absolute
  paths, so moving the clone requires re-running it).
This commit is contained in:
gabrielstein-mem0
2026-04-24 16:53:30 -07:00
parent a723cb485a
commit 674bb92423
4 changed files with 104 additions and 89 deletions
+16 -3
View File
@@ -87,17 +87,30 @@ You can also configure individual clients:
</Accordion>
<Accordion title="Codex">
Codex reads MCP servers from `~/.codex/config.toml` as TOML (not JSON). Add:
**Direct MCP (fastest, MCP only).** Codex reads MCP servers from `~/.codex/config.toml` as TOML (not JSON). Add:
```toml
[mcp_servers.mem0-mcp]
[mcp_servers.mem0]
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).
<Note>
Codex uses the server name `mem0` (not `mem0-mcp` like the other clients on this page) so it matches the name the bundled plugin registers if you ever sideload it later.
</Note>
**Sideloaded plugin (full experience).** If you want the memory protocol skill, Mem0 SDK skill, and opt-in lifecycle hooks alongside the MCP server, sideload the plugin from a clone of `mem0ai/mem0`. The repo ships a marketplace manifest at `.agents/plugins/marketplace.json`, so you can register it with one CLI call:
```bash
git clone https://github.com/mem0ai/mem0.git ~/codex-plugins/mem0-source
codex plugin marketplace add ~/codex-plugins/mem0-source
```
Then run `codex` and `/plugins`, browse the **Mem0 Plugins** marketplace, and install **Mem0**. Don't combine this with the Direct MCP setup above — the sideloaded plugin auto-registers `mem0` via `.codex-mcp.json`, so a manual `[mcp_servers.mem0]` block would create a duplicate.
See the [Codex integration guide](/integrations/codex) for full details, lifecycle-hook setup, and management commands (`codex plugin marketplace upgrade` / `remove`).
</Accordion>
<Accordion title="Cursor">