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

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

Prerequisites

Before setting up Mem0 with Codex, ensure you have:

A Mem0 Platform account and API key:
- Sign up at app.mem0.ai
- Get your API key (starts with m0-)
OpenAI Codex access
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.

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)

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.

Don’t combine Option B with Option A. The plugin manifest declares its MCP server via .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 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.

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 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:

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:

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

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

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

Tool	Description
`add_memory`	Save text or conversation history for a user/agent
`search_memories`	Semantic search across memories with filters
`get_memories`	List memories with filters and pagination
`get_memory`	Retrieve a specific memory by ID
`update_memory`	Overwrite a memory’s text by ID
`delete_memory`	Delete a single memory by ID
`delete_all_memories`	Bulk delete all memories in scope
`delete_entities`	Delete a user/agent/app/run entity and its memories
`list_entities`	List users/agents/apps/runs stored in Mem0

Memory Protocol Skill

When the plugin is sideloaded, the memory protocol skill instructs the agent to:

On Every New Task

Call search_memories with a query related to the current task to load relevant context
Review returned memories to understand what was learned in prior sessions
Optionally call get_memories to browse all stored memories

After Completing Significant Work

Store key learnings using add_memory with structured metadata:

What to store	Metadata type
Architectural decisions	`{"type": "decision"}`
Strategies that worked	`{"type": "task_learning"}`
Failed approaches	`{"type": "anti_pattern"}`
User preferences observed	`{"type": "user_preference"}`
Environment discoveries	`{"type": "environmental"}`
Conventions established	`{"type": "convention"}`

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.

Mem0 MCP Setup

Detailed MCP configuration for all clients

Claude Code Integration

Add Mem0 memory to Claude Code workflows

Coding Agents

Agent Harness

Overview

Prerequisites

Installation

Option A — Direct MCP (Recommended)

Option B — Sideload the Plugin (Advanced)

Managing the Plugin

What’s Included

Available MCP Tools

Memory Protocol Skill

On Every New Task

After Completing Significant Work

Before Losing Context

Plugin Manifest

Example Workflow

Troubleshooting

Mem0 MCP Setup

Claude Code Integration

Coding Agents

Agent Harness

Documentation Index

​Overview

​Prerequisites

​Installation

​Option A — Direct MCP (Recommended)

​Option B — Sideload the Plugin (Advanced)

​Managing the Plugin

​What’s Included

​Available MCP Tools

​Memory Protocol Skill

​On Every New Task

​After Completing Significant Work

​Before Losing Context

​Plugin Manifest

​Example Workflow

​Troubleshooting

Mem0 MCP Setup

Claude Code Integration

Overview

Prerequisites

Installation

Option A — Direct MCP (Recommended)

Option B — Sideload the Plugin (Advanced)

Managing the Plugin

What’s Included

Available MCP Tools

Memory Protocol Skill

On Every New Task

After Completing Significant Work

Before Losing Context

Plugin Manifest

Example Workflow

Troubleshooting