OpenAI Codex Memory
Automatic long-term memory for OpenAI Codex (CLI and IDE extension): lifecycle hooks inject recalled context at session start and per prompt and send every prompt for fact extraction, with the MemorySync MCP server configured through Codex’s TOML config and bearer-token environment auth.
What the plugin provides
| Layer | What it does |
|---|---|
| Hooks (recall + capture) | Codex’s hook system supports additionalContext injection — recall lands at session start and alongside every prompt (re-injected after compaction), and every prompt goes to fact extraction the moment you send it — only the durable facts in it are stored, and replies are not. Dependency-free Node scripts, async capture. |
| MCP server | bearer_token_env_var = "MEMORYSYNC_API_KEY" — Codex’s documented env-auth field — plus the zero-auth docs server. OAuth fallback without a key. |
| Skills | The shared memory / status / remember / recall skills ($-invocable in the Codex TUI). |
| Plugin package | .codex-plugin/plugin.json with the full interface block; installable via codex plugin marketplace add. |
| Mem0 | Supermemory | Zep | MemorySync | |
|---|---|---|---|---|
| Codex integration exists | ✓ plugin | ✗ nothing — no page, no package | ✗ explicitly “not positioned for Codex” | ✓ plugin + TOML + hooks |
| Bearer-token env auth (the TOML pattern) | ✓ | ✗ OAuth-only — cannot do it | ✗ | ✓ |
| Hooks run natively on Windows | ✗ bash + a Python installer | — | — | ✓ Node, command works everywhere |
| Injected recall (additionalContext) | ✓ | ✗ | ✗ | ✓ session start + per prompt + post-compact |
| Session-safe failure contract | ❌ undocumented | — | — | ✓ every hook exits 0 on every path, tested |
Install
# Get an API key at https://app.memorysync.io, then:# macOS/Linux: export MEMORYSYNC_API_KEY=ms_...# Windows: setx MEMORYSYNC_API_KEY ms_...
Option A: Full plugin (recommended)
# Hooks + skills + MCP:codex plugin marketplace add memorysyncio/memorysync-pluginscodex plugin add memorysync@memorysync# Trust the hooks once (Codex reviews non-managed hooks):# run /hooks inside codex and approve the memorysync entries
Requires Node.js 18+ on PATH for the hook scripts. The trust step is Codex’s own security review for hooks — one /hooks visit, once per version.
Option B: MCP only, one command
codex mcp add memorysync --url https://mcp.memorysync.io/mcp --bearer-token-env-var MEMORYSYNC_API_KEY
Option C: MCP only, by hand
[mcp_servers.memorysync]url = "https://mcp.memorysync.io/mcp"bearer_token_env_var = "MEMORYSYNC_API_KEY"
Options B and C connect the memory tools without automatic capture. Without an API key the MCP server falls back to OAuth (codex mcp login memorysync).
What runs when
| Moment | What happens |
|---|---|
| Session start / resume / clear | Recalls your profile and this project’s context, injected as additional context (limit 4000 tokens). |
| Every prompt | Sends your prompt for fact extraction in a detached process, one add per prompt. Prompts of 24 characters or more also recall memories relevant to that prompt (limit 3000 tokens). |
| Reply finishes | Nothing is sent — replies are not stored. |
| Context compaction | Memory re-injected after the compact. |
Facts carry the codex:: session key plus the project — the server keeps the durable facts extracted from your prompts, not the prompts themselves — separate from your Claude Code and Cursor sessions, same memories. Each prompt carries a content-hash seed, so a retried hook is recognised server-side and extracted once. Every hook exits 0 on every failure: no key, network down, server errors, monthly quota exhausted in either server mode. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is honoured here too.
Supported versions
| Surface | Requires | Verified on |
|---|---|---|
memorysync Codex plugin 1.4.0 | Codex CLI/IDE with hooks (stable feature flag), Node.js 18+ | Hook contract suite 52/52 with Codex-shape payloads (documented stdin fields, injection JSON, replies never sent) |
Codex’s hook payloads mirror Claude Code’s, and CI pins that assumption: the shared scripts run under the codex platform argument against documented payload shapes on every push, including both monthly-quota server modes.