diff --git a/docs/integrations/codex.mdx b/docs/integrations/codex.mdx index e9f4a6f90..0a8831250 100644 --- a/docs/integrations/codex.mdx +++ b/docs/integrations/codex.mdx @@ -48,59 +48,69 @@ Make sure `MEM0_API_KEY` is exported in the shell you launch Codex from, then re ### 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. +For 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. The Mem0 repo already ships a marketplace manifest at [`.agents/plugins/marketplace.json`](https://github.com/mem0ai/mem0/blob/main/.agents/plugins/marketplace.json), so there's no JSON to author by hand. This follows the Codex [build-plugins](https://developers.openai.com/codex/plugins/build) local-testing workflow. - Codex requires `source.path` in `marketplace.json` to be **relative** (start with `./`) and **inside the marketplace root**. For a personal install (`~/.agents/plugins/marketplace.json`), that root is your home directory (`~`), so the cloned plugin must live somewhere under `~/`. + Don't combine Option B with Option A. The plugin manifest declares its MCP server via [`.codex-mcp.json`](https://github.com/mem0ai/mem0/blob/main/mem0-plugin/.codex-mcp.json), so Codex auto-registers the `mem0` MCP server when the plugin loads. Adding the same `[mcp_servers.mem0]` block to `~/.codex/config.toml` will create a duplicate registration. -**Step 1.** Clone the Mem0 repository somewhere under your home directory: +**Step 1.** Clone the Mem0 repository anywhere on disk: ```bash git clone https://github.com/mem0ai/mem0.git ~/codex-plugins/mem0-source ``` -**Step 2.** Create `~/.agents/plugins/marketplace.json` with a path **relative to `~/`**: +**Step 2.** Register the bundled marketplace with Codex's CLI: -```json -{ - "name": "mem0-plugins", - "interface": { "displayName": "Mem0 Plugins" }, - "plugins": [ - { - "name": "mem0", - "source": { - "source": "local", - "path": "./codex-plugins/mem0-source/mem0-plugin" - }, - "policy": { - "installation": "AVAILABLE", - "authentication": "ON_INSTALL" - }, - "category": "Productivity" - } - ] -} +```bash +codex plugin marketplace add ~/codex-plugins/mem0-source ``` -If you cloned somewhere else, substitute the path relative to `~/`. For example, a clone at `~/work/projects/mem0` becomes `./work/projects/mem0/mem0-plugin`. +This points Codex at the repo's `.agents/plugins/marketplace.json`. The bundled file uses `path: "./mem0-plugin"`, which Codex resolves relative to the clone root. -**Step 3.** Restart Codex, then run `codex /plugins`, browse the `Mem0 Plugins` marketplace, and install Mem0. + + **Why we recommend this over hand-authoring `~/.agents/plugins/marketplace.json`:** Codex requires `source.path` in any marketplace manifest to be **relative** (starting with `./`) and **inside the marketplace root**. The repo's bundled manifest already satisfies this — the marketplace root is the clone directory, and `mem0-plugin/` lives inside it. With a personal `~/.agents/plugins/marketplace.json`, the root is `~/` and the clone has to live under `~/` too. The CLI form sidesteps that constraint. + -**Step 4 (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`: +**Step 3.** Restart Codex, run `/plugins`, browse the `Mem0 Plugins` marketplace, and install **Mem0**. + +**Step 4 (optional) — enable lifecycle hooks.** Codex doesn't auto-wire hooks from plugin manifests; it only reads them from `~/.codex/hooks.json` (or `/.codex/hooks.json`). Run the bundled installer once to merge the Mem0 entries into your global hooks file: ```bash python3 ~/codex-plugins/mem0-source/mem0-plugin/scripts/install_codex_hooks.py ``` -Then add the feature flag to `~/.codex/config.toml`: +Then enable the hooks feature flag in `~/.codex/config.toml`: ```toml [features] codex_hooks = true ``` -Restart Codex. 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`. +Restart Codex. The installer registers three hooks pointing at scripts inside your clone: + +| Event | Behavior | +|-------|----------| +| `SessionStart` | Loads prior memories as bootstrap context | +| `UserPromptSubmit` | Injects relevant memories before each prompt | +| `Stop` | Reminds the agent to persist learnings at turn end | + +Re-running the installer is idempotent. To remove the hooks: `python3 ~/codex-plugins/mem0-source/mem0-plugin/scripts/install_codex_hooks.py --uninstall`. + + + The hooks file stores absolute paths into your clone (e.g. `~/codex-plugins/mem0-source/mem0-plugin/scripts/...`). If you move or delete the clone, the hooks will break silently — re-run the installer from the new location, or run `--uninstall` first. + + +### Managing the Plugin + +Codex provides CLI commands for managing marketplaces after install: + +```bash +codex plugin marketplace upgrade # pull latest plugin versions +codex plugin marketplace remove mem0-plugins # unregister the marketplace +``` + +To pull updates to the plugin source itself, `git pull` inside your clone (`~/codex-plugins/mem0-source`) and then run `codex plugin marketplace upgrade` to refresh Codex's plugin cache. Plugins are cached at `~/.codex/plugins/cache////`. 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. @@ -198,10 +208,12 @@ 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/read failed in TUI`** — The `source.path` in your `marketplace.json` points to a directory that doesn't exist. Confirm you actually cloned the repo, then use a relative path (starting with `./`) from `~/` to `mem0-plugin/` inside your clone — e.g. if you cloned to `~/codex-plugins/mem0-source`, use `"./codex-plugins/mem0-source/mem0-plugin"`. The plugin must live inside the marketplace root (`~/` for personal installs). -- **Plugin not found** — Ensure `marketplace.json` lives at `~/.agents/plugins/marketplace.json` (or `$REPO_ROOT/.agents/plugins/marketplace.json`) and `source.path` ends in `mem0-plugin` (not `plugins/mem0`). +- **Duplicate `mem0` MCP server / "tool collision" errors** — You combined Option A (Direct MCP) with Option B (sideload). The sideloaded plugin auto-registers `mem0` from `.codex-mcp.json`, so remove the `[mcp_servers.mem0]` block from `~/.codex/config.toml`. +- **`plugin/read failed in TUI`** — Codex can't find the plugin directory the marketplace points at. If you used `codex plugin marketplace add `, confirm the path is your clone root and that `/.agents/plugins/marketplace.json` exists. If you hand-authored `~/.agents/plugins/marketplace.json`, `source.path` must be relative (start with `./`), inside the marketplace root (`~/` for personal installs), and end in `mem0-plugin` — e.g. `"./codex-plugins/mem0-source/mem0-plugin"`. +- **Plugin not found in `/plugins`** — Run `codex plugin marketplace add ~/path/to/clone` again, or confirm the marketplace was registered with `codex plugin marketplace remove mem0-plugins` then re-add. - **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. +- **Hooks broke after moving the clone** — The installer bakes absolute paths into `~/.codex/hooks.json` pointing at scripts inside your clone. If you moved or renamed the clone directory, run `python3 /mem0-plugin/scripts/install_codex_hooks.py` from the new location — the installer is idempotent and replaces the old entries. diff --git a/docs/platform/mem0-mcp.mdx b/docs/platform/mem0-mcp.mdx index ef7a977f8..45568eef4 100644 --- a/docs/platform/mem0-mcp.mdx +++ b/docs/platform/mem0-mcp.mdx @@ -87,17 +87,30 @@ You can also configure individual clients: - 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). + + 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. + + + **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`). diff --git a/mem0-plugin/.codex-mcp.json b/mem0-plugin/.codex-mcp.json index 8282c95a3..eba6c6609 100644 --- a/mem0-plugin/.codex-mcp.json +++ b/mem0-plugin/.codex-mcp.json @@ -1,7 +1,7 @@ { "mcpServers": { "mem0": { - "url": "https://mcp.mem0.ai/mcp/", + "url": "https://mcp.mem0.ai/mcp", "bearer_token_env_var": "MEM0_API_KEY" } } diff --git a/mem0-plugin/README.md b/mem0-plugin/README.md index 77e91f9b9..95415e7b8 100644 --- a/mem0-plugin/README.md +++ b/mem0-plugin/README.md @@ -49,52 +49,7 @@ This installs the full plugin including the MCP server, lifecycle hooks (automat ### Codex -**Option A — Repo marketplace** (recommended for teams): - -Add the plugin marketplace to your repo root (already included in this repository): - -``` -.agents/plugins/marketplace.json -``` - -Then in Codex, browse the repo's plugin directory and install Mem0. - -**Option B — Personal marketplace**: - -Clone the repo somewhere under your home directory (Codex requires `source.path` to be relative and inside the marketplace root, which is `~/` for personal installs): - -```bash -git clone https://github.com/mem0ai/mem0.git ~/codex-plugins/mem0-source -``` - -Then add `~/.agents/plugins/marketplace.json` with a path relative to `~/`: - -```json -{ - "name": "mem0-plugins", - "interface": { - "displayName": "Mem0 Plugins" - }, - "plugins": [ - { - "name": "mem0", - "source": { - "source": "local", - "path": "./codex-plugins/mem0-source/mem0-plugin" - }, - "policy": { - "installation": "AVAILABLE", - "authentication": "ON_INSTALL" - }, - "category": "Productivity" - } - ] -} -``` - -Restart Codex, then run `codex /plugins` and install Mem0 from the `Mem0 Plugins` marketplace. - -**Option C — Direct MCP configuration** (fastest, MCP-only): +**Option A — Direct MCP** (fastest, MCP only): Codex reads MCP servers from `~/.codex/config.toml` as TOML. Add: @@ -104,7 +59,42 @@ url = "https://mcp.mem0.ai/mcp" bearer_token_env_var = "MEM0_API_KEY" ``` -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). +Export `MEM0_API_KEY` in your shell and restart Codex. `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). + +**Option B — Sideload the plugin** (full experience: MCP + skills + opt-in hooks): + +Clone the repo and register the bundled marketplace 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 +``` + +This points Codex at the repo's `.agents/plugins/marketplace.json`, which references `mem0-plugin/` as the local source. Restart Codex, run `/plugins`, and install **Mem0** from the **Mem0 Plugins** marketplace. + +> **Don't combine with Option A.** The plugin manifest auto-registers `mem0` as an MCP server via `mem0-plugin/.codex-mcp.json` — adding a manual `[mcp_servers.mem0]` block would duplicate the registration. + +**Optional — enable lifecycle hooks.** Codex doesn't auto-wire hooks from plugin manifests; it only reads `~/.codex/hooks.json` (or `/.codex/hooks.json`). Run the bundled installer once to merge Mem0's entries: + +```bash +python3 ~/codex-plugins/mem0-source/mem0-plugin/scripts/install_codex_hooks.py +``` + +Then enable the feature flag in `~/.codex/config.toml`: + +```toml +[features] +codex_hooks = true +``` + +Restart Codex. This registers `SessionStart` (loads prior memories), `UserPromptSubmit` (injects relevant memories before each prompt), and `Stop` (reminds the agent to persist learnings at turn end). The installer is idempotent. To remove: `python3 .../install_codex_hooks.py --uninstall`. If you move or delete the clone directory, re-run the installer from the new location — the hooks file stores absolute paths into your clone. + +**Managing the plugin:** + +```bash +codex plugin marketplace upgrade # pull latest plugin versions +codex plugin marketplace remove mem0-plugins # unregister the marketplace +``` ### Cursor @@ -145,17 +135,17 @@ After installing, confirm the MCP server is connected: ## What's included -| Component | Claude Code / Cowork | Cursor (Marketplace) | Cursor (Deeplink/Manual) | Codex | -|-----------|:--------------------:|:--------------------:|:------------------------:|:-----:| -| MCP Server | Yes | Yes | Yes | Yes | -| Lifecycle Hooks | Yes | Yes | No | No | -| Mem0 SDK Skill | Yes | Yes | No | Yes | -| Memory Protocol Skill | No | No | No | Yes | +| Component | Claude Code / Cowork | Cursor (Marketplace) | Cursor (Deeplink/Manual) | Codex (Sideload) | Codex (Direct MCP) | +|-----------|:--------------------:|:--------------------:|:------------------------:|:----------------:|:------------------:| +| MCP Server | Yes | Yes | Yes | Yes | Yes | +| Lifecycle Hooks | Yes | Yes | No | Opt-in | No | +| Mem0 SDK Skill | Yes | Yes | No | Yes | No | +| Memory Protocol Skill | No | No | No | Yes | No | - **MCP Server** — Connects to the Mem0 remote MCP server (`mcp.mem0.ai`), providing tools to add, search, update, and delete memories. No local dependencies required. -- **Lifecycle Hooks** — Automatic memory capture at key points: session start, context compaction, task completion, and session end. (Claude Code/Cursor only) +- **Lifecycle Hooks** — Automatic memory capture at key points. Claude Code and Cursor wire hooks up natively when the plugin is installed (session start, context compaction, task completion, session end). Codex hooks are opt-in via a one-time installer (`scripts/install_codex_hooks.py`) that writes entries into `~/.codex/hooks.json` for `SessionStart`, `UserPromptSubmit`, and `Stop`. - **Mem0 SDK Skill** — Guides the AI on how to integrate the Mem0 SDK (Python & TypeScript) into your applications. -- **Memory Protocol Skill** — Codex-specific skill that instructs the agent to retrieve relevant memories at task start, store learnings on completion, and capture session state before context loss. Replaces lifecycle hooks on platforms that don't support them. +- **Memory Protocol Skill** — Codex-specific skill that instructs the agent to retrieve relevant memories at task start, store learnings on completion, and capture session state before context loss. Complements the lifecycle hooks on Codex. ## MCP Tools