Codex

Add persistent memory to OpenAI Codex with the Mem0 plugin. Codex forgets everything between tasks — this plugin fixes that by connecting to Mem0's cloud memory layer via MCP and using a skill-based memory protocol to automatically retrieve context and store learnings.

Overview

1. MCP Server — Connect to Mem0's remote MCP server for memory tools (add, search, update, delete)
2. Memory Protocol Skill — Instructs the agent to retrieve memories at task start, store learnings on completion, and capture session state before context loss
3. Plugin Marketplace — Install via Codex's repo-level or personal plugin marketplace
4. Zero local dependencies — Cloud-hosted MCP server, no local setup required

Prerequisites

Before setting up Mem0 with Codex, ensure you have:

1. A Mem0 Platform account and API key:

   • <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-codex" rel="nofollow">Sign up at app.mem0.ai</a>
   • <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-codex" rel="nofollow">Get your API key</a> (starts with m0-)

2. OpenAI Codex access

3. Your API key exported in your shell:

export MEM0_API_KEY="m0-your-api-key"

Installation

Option A — Direct MCP (Recommended)

The fastest way to connect Codex to Mem0 — no downloads, no marketplace. Codex reads MCP servers from ~/.codex/config.toml as TOML. Add:

[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.

Option B — Sideload the Plugin (Advanced)

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, so there's no JSON to author by hand. This follows the Codex build-plugins local-testing workflow.

Step 1. Clone the Mem0 repository anywhere on disk:

git clone https://github.com/mem0ai/mem0.git ~/codex-plugins/mem0-source

Step 2. Register the bundled marketplace with Codex's CLI:

codex plugin marketplace add ~/codex-plugins/mem0-source

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, 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 <repo>/.codex/hooks.json). Run the bundled installer once to merge the Mem0 entries into your global hooks file:

python3 ~/codex-plugins/mem0-source/mem0-plugin/scripts/install_codex_hooks.py

Then enable the hooks feature flag in ~/.codex/config.toml:

[features]
codex_hooks = true

Restart Codex. The installer registers three hooks pointing at scripts inside your clone:

Re-running the installer is idempotent. To remove the hooks: python3 ~/codex-plugins/mem0-source/mem0-plugin/scripts/install_codex_hooks.py --uninstall.

Managing the Plugin

Codex provides CLI commands for managing marketplaces after install:

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/<marketplace>/<plugin>/<version>/.

What's Included

Available MCP Tools

Once installed, the following tools are available in every Codex session:

Memory Protocol Skill

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
2. Review returned memories to understand what was learned in prior sessions
3. Optionally call get_memories to browse all stored memories

After Completing Significant Work

Store key learnings using add_memory with structured metadata:

Before Losing Context

Store a comprehensive session summary including goals, accomplishments, decisions, files modified, and current state with metadata {"type": "session_state"}.

Plugin Manifest

The Codex plugin manifest (.codex-plugin/plugin.json) follows the Codex plugin specification:

{
  "name": "mem0",
  "version": "0.1.0",
  "description": "Mem0 memory layer for AI applications.",
  "skills": "./skills/",
  "mcpServers": "./.codex-mcp.json",
  "interface": {
    "displayName": "Mem0",
    "shortDescription": "Persistent memory layer for AI coding workflows",
    "category": "Productivity",
    "capabilities": ["Read", "Write"]
  }
}

Example Workflow

# Task 1: Setting up a new service
You: Create a REST API for the notifications service using Express and TypeScript.

# Codex searches memories, finds user preferences from prior tasks.
# After completing the task, Mem0 stores:
#   - Decision: "Notifications service uses Express + TypeScript + Zod validation"
#   - Convention: "All API routes follow /api/v1/{resource} pattern"
#   - Preference: "User prefers explicit error types over generic catch-all"

# Task 2 (days later): Extending the service
You: Add WebSocket support for real-time notification delivery.

# Codex searches memories, retrieves the architecture decisions and conventions.
# Follows the same patterns established in the first task.

Troubleshooting

• "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
• 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 <path>, confirm the path is your clone root and that <clone>/.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 <new-clone>/mem0-plugin/scripts/install_codex_hooks.py from the new location — the installer is idempotent and replaces the old entries.