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, automatically capturing learnings at key lifecycle points, and retrieving relevant context on the first prompt of a session. Codex can use the search tool for recall later in the session.

Current plugin version: 0.3.1.

Sidekick is available only in the Claude Code plugin.

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
Python 3.10 or newer available as python3
Your API key added to your shell profile (persists across sessions):

echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.zshrc
source ~/.zshrc

echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.bashrc
source ~/.bashrc

Installation

Option A: Plugin Marketplace (Recommended)

Install the full plugin, including automatic capture and recall, the search_memories tool, and six memory skills.

Add the Mem0 marketplace:

codex plugin marketplace add mem0ai/mem0

Install the plugin:
codex plugin add mem0@mem0-plugins
Or, in the app: restart Codex, open the Plugin Directory, browse the Mem0 Plugins marketplace, and install Mem0.

Step 1 is required for the app UI. Mem0 isn’t in OpenAI’s curated directory yet, so without codex plugin marketplace add, Mem0 won’t appear in the Codex app’s Plugin Directory: searching for it returns nothing. Adding the marketplace surfaces it (under Created by you) and makes it installable.

Do not combine with Option B. The plugin manifest auto-registers the mem0 MCP server, so adding both will create a duplicate registration.

Option B: Direct MCP

The fastest way to connect Codex to Mem0 needs no plugin or marketplace. Add the MCP server with a single command:

codex mcp add mem0 --url https://mcp.mem0.ai/mcp/ --bearer-token-env-var MEM0_API_KEY

Or add it manually to ~/.codex/config.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. This gives you the hosted MCP tools but not the plugin’s lifecycle hooks or six memory skills.

Managing the Plugin

codex plugin marketplace upgrade               # pull latest plugin versions
codex plugin remove mem0@mem0-plugins          # uninstall the plugin (keeps the marketplace)
codex plugin marketplace remove mem0-plugins   # unregister the marketplace entirely

To update, run codex plugin marketplace upgrade to pull the latest from the Mem0 repo.

After Option A, ask Codex to search memory for a recent project decision. After Option B, ask it to list your Mem0 entities. If the matching tool responds, the connection is ready.

Codex Cloud

Codex Cloud tasks run setup scripts and the agent in separate phases with different variable scoping:

Environment Variables persist for the full duration of the task, through both the setup script and the agent phase.
Secrets are only available to the setup script; they are wiped before the agent phase starts, so the agent itself cannot read them.

Because the mem0 MCP server authenticates on every tool call the agent makes (not just during setup), set MEM0_API_KEY as an Environment Variable in your Codex Cloud environment configuration, not as a Secret. A Secret will let a setup script authenticate but the agent will lose access to MEM0_API_KEY once the task phase begins, breaking Mem0 MCP calls. Lifecycle hooks that shell out to local scripts (Option A) are not applicable in Codex Cloud’s ephemeral containers; use Option B (Direct MCP) with MEM0_API_KEY set as above.

What’s Included

Component	Plugin Install	MCP Only
Memory tools	`search_memories`	9 CRUD tools
Lifecycle hooks	Yes	No
Native subagent memory lifecycle	Yes	No
Memory skills	6	No

Mem0’s Codex package does not bundle a named custom agent. If you define project or user agents under .codex/agents/ or ~/.codex/agents/, the full Mem0 plugin gives every native subagent the parent turn’s retrieved memory context and records its completed result.

Direct MCP tools

Option B exposes the following hosted tools. The full plugin in Option A uses the focused search_memories tool and captures writes through lifecycle hooks.

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

Lifecycle hooks

Option A registers the hooks with the plugin. No separate hook installer or global hooks.json edit is required.

Hook	Event	What it does
Session start	`SessionStart`	Initializes the project session and recovers pending capture
User prompt	`UserPromptSubmit`	Records each prompt; searches on the first prompt when it has at least 20 characters
Post-tool	`PostToolUse`	Records useful tool outcomes for the completed exchange
Subagent start	`SubagentStart`	Reuses the parent turn’s retrieved memory context in the child
Subagent stop	`SubagentStop`	Records the child transcript path and completed result
Stop	`Stop`	Captures completed work and starts a background flush when needed
Pre-compact	`PreCompact`	Flushes pending capture before context compaction
Session end	`SessionEnd`	Flushes any remaining capture in the background

What you type is stored as yours. Codex’s captured responses are stored as the assistant’s, so its suggestions never become your stated preferences.

Example Workflow

# Task 1: Setting up a new service
You: Create a REST API for the notifications service using Express and TypeScript. Prefer explicit error types over generic catch-all handlers.

# Codex searches memories, finds your preferences from prior tasks.
# Mem0 stores what you said as yours:
#   - Your preference: "Prefers explicit error types over generic catch-all"
# ...and completed work reported by Codex as the assistant's:
#   - Decision: "Notifications service uses Express + TypeScript + Zod validation"
#   - Convention: "All API routes follow /api/v1/{resource} pattern"

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

Search and capture

The local search_memories tool accepts query, top_k, category, scope (repo, dir, or mine), and optional run_id with every scope. Use a known session ID to recall memories saved in that session; omit it to search across sessions. See search scopes for the shared Python search contract, including legacy repository memory compatibility. Captured prompts and responses retain their full redacted text without a per-message character cutoff. Large extraction inputs are split across requests without dropping message text; recall output and tool-result previews have separate limits.

Troubleshooting

“Connection failed”: Verify MEM0_API_KEY is set: echo $MEM0_API_KEY
No tools appearing: Restart your Codex session after installation
Duplicate mem0 MCP / “tool collision” errors: You combined Option A with Option B. Remove the [mcp_servers.mem0] block from ~/.codex/config.toml; the plugin registers it automatically
Hooks not firing: Confirm you installed Option A and restart Codex. MCP-only installs (Option B) do not include hooks.

Mem0 MCP Setup

Detailed MCP configuration for all clients

Claude Code Integration

Add Mem0 memory to Claude Code workflows

Using Mem0? Star us on GitHub to help more developers discover memory for AI apps.

Coding Agents

Agent Harness

Prerequisites

Installation

Option A: Plugin Marketplace (Recommended)

Option B: Direct MCP

Managing the Plugin

Codex Cloud

What’s Included

Direct MCP tools

Lifecycle hooks

Example Workflow

Search and capture

Troubleshooting

Mem0 MCP Setup

Claude Code Integration

​Prerequisites

​Installation

​Option A: Plugin Marketplace (Recommended)

​Option B: Direct MCP

​Managing the Plugin

​Codex Cloud

​What’s Included

​Direct MCP tools

​Lifecycle hooks

​Example Workflow

​Search and capture

​Troubleshooting

Mem0 MCP Setup

Claude Code Integration

Prerequisites

Installation

Option A: Plugin Marketplace (Recommended)

Option B: Direct MCP

Managing the Plugin

Codex Cloud

What’s Included

Direct MCP tools

Lifecycle hooks

Example Workflow

Search and capture

Troubleshooting