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 capture every completed exchange, 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 exchange persists the moment it happens. 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
# 0. Get an API key at https://app.memorysync.io, then:# macOS/Linux: export MEMORYSYNC_API_KEY=ms_...# Windows: setx MEMORYSYNC_API_KEY ms_...# A. Full plugin (hooks + skills + MCP):codex plugin marketplace add Rafay121/memorysync-pluginscodex plugin add memorysync@memorysync# Trust the hooks once (Codex reviews non-managed hooks):# run /hooks inside codex and approve the memorysync entries# B. MCP only, one command:codex mcp add memorysync --url https://mcp.memorysync.io/mcp --bearer-token-env-var MEMORYSYNC_API_KEY# C. MCP only, by hand in ~/.codex/config.toml:# [mcp_servers.memorysync]# url = "https://mcp.memorysync.io/mcp"# bearer_token_env_var = "MEMORYSYNC_API_KEY"
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. 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 (≥ 24 chars) | Recalls memories relevant to that prompt (limit 3000 tokens); persists your message in a detached process. |
| Reply finishes | Persists the reply — an async hook with tolerant extraction: documented fields first, a bounded transcript-tail parse second, silent skip when neither is trustworthy. |
| Context compaction | Memory re-injected after the compact. |
# Same operation as the hooks perform, shown as the raw MemorySync REST call(s).## Per-prompt recall: hierarchical recall first, plain semantic query as# the fallback — the same production recall contract as every# MemorySync adapter.curl --request POST https://api.memorysync.io/v1/memory/recall \--header "X-API-Key: $MEMORYSYNC_API_KEY" \--header "Content-Type: application/json" \--data '{"tenant_id":"acme","user_id":"rafay","prompt":"what colour scheme did we pick?","k":6}'
Turns are stored under the codex:: transcript scope — separate from your Claude Code and Cursor transcripts, same memories. 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.1.0 | Codex CLI/IDE with hooks (stable feature flag), Node.js 18+ | Hook contract suite 37/37 with Codex-shape payloads (documented stdin fields, injection JSON, transcript fallback) |
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.