Persistent memory for Codex CLI: AGENTS.md, Codex memories, or an MCP memory server

Disclosure: I work on MemorySync (I'm Mohammed, the founder). I drafted this article with AI assistance and checked it against the official Codex docs and the MemorySync docs. Code status: on Oct 28, 2026 I installed Codex CLI 0.165.0 into a scratch folder with a throwaway CODEX_HOME, no ChatGPT login and no MemorySync API key. In that setup I ran the Step 4 codex mcp add command, codex mcp list, codex mcp get and codex features list, plus the two Step 5 plugin install commands. I also ran the plugin's session-start hook script once by hand with no key; it exited 0 and printed nothing. I did not run a Codex session with a model, so AGENTS.md loading, /memories, /hooks, the memory tools and every MemorySync request were not run. Those parts are adapted from the docs.

The MemorySync Codex guide covers the install. This article answers the question that comes before it: what does "memory" in Codex CLI actually mean, and which layer do you need?

openai/codex#3043 asked for "memory functionality similar to Claude code". A maintainer answered that "AGENTS.md is the correct answer" and the issue was closed in September 2025. A later commenter disagreed and asked for something closer to a memory bank that sets itself up. Both have a point, and today Codex covers more than AGENTS.md: it also has an opt-in local memories feature.

So there are three layers, and they do different jobs:

1. AGENTS.md for rules you write yourself and want in every session.
2. Codex memories for context Codex learns from your past chats, stored on your machine.
3. An MCP memory server for memory that lives outside ~/.codex and that other tools can use too.

Codex behaviour below comes from the official Codex docs (AGENTS.md, Memories, MCP, Hooks). The MemorySync parts come from the MemorySync Codex guide.

Step 1: Put the rules in AGENTS.md

Per the AGENTS.md docs, Codex reads AGENTS.md files before it does any work. It builds the instruction chain once per run (in the TUI, usually once per session):

• Global: ~/.codex/AGENTS.md (or AGENTS.override.md if it exists). If you set CODEX_HOME, it's read from there instead.
• Project: from the Git root down to your current directory, at most one file per directory. Files closer to where you are come later, so they win.
• Size cap: Codex stops adding files once the combined size hits project_doc_max_bytes (32 KiB by default). Empty files are skipped.

# ~/.codex/AGENTS.md

## Working agreements
- Prefer pnpm when installing dependencies.
- Run the tests after changing code.

The docs' own check is codex --ask-for-approval never "Summarize the current instructions.", which should quote your file back. This is the comment on #3043 that got it right: if you want a "global memory file" you maintain yourself, ~/.codex/AGENTS.md is it.

What AGENTS.md is not: it doesn't learn. Nothing gets added unless you (or the agent, if you ask it) edit the file.

Step 2: Turn on Codex memories for learned context

Per the Memories docs, local Codex memories are off by default. Turn them on in ~/.codex/config.toml:

[features]
memories = true

In my scratch install, codex features list showed memories as stable and off, and hooks as stable and on.

How they behave, per the docs:

• Codex turns useful context from eligible past chats into memory files under ~/.codex/memories/. It skips active or short-lived sessions and redacts secrets from generated fields.
• They update in the background, not at the end of every chat. A chat has to be idle for a while first, so don't expect a memory right after you close a session.
• /memories in the TUI controls the current chat: whether it can use existing memories, and whether it can feed future ones.
• Settings include memories.use_memories, memories.generate_memories and memories.disable_on_external_context (keeps chats that used MCP tools or web search out of memory generation).

The docs are clear about one thing: keep required guidance in AGENTS.md and treat memories as "a helpful recall layer, not as the only source for rules that must always apply." These memories are also local to the machine's Codex home, and the docs say to treat the files as generated state, not something you edit by hand.

Step 3: Decide whether you need memory outside Codex

Layers 1 and 2 are enough if you only use Codex, on one machine, and you're fine with Codex deciding what to keep. You need a third layer when:

• you switch between Codex, Claude Code and Cursor and want them to recall the same facts,
• you want memory you can search, list and delete through tools, not only files under ~/.codex,
• you want to save something on purpose, right now, instead of waiting for a background pass.

That's what an MCP memory server is for. The rest of this article uses MemorySync, which I'm building, as the example. It runs a hosted MCP server, so there's no local process to install or keep running.

Step 4: Connect a memory MCP server (MemorySync example)

Codex supports Streamable HTTP MCP servers, and per the Codex MCP docs, bearer_token_env_var names an environment variable whose value is sent as a bearer token. The MemorySync Codex guide uses exactly that.

# Get an API key in the MemorySync dashboard, then:
export MEMORYSYNC_API_KEY=ms_...

codex mcp add memorysync --url https://mcp.memorysync.io/mcp --bearer-token-env-var MEMORYSYNC_API_KEY
codex mcp list

When I ran codex mcp add in my scratch install, it printed Added global MCP server 'memorysync'. and wrote this to config.toml:

[mcp_servers.memorysync]
url = "https://mcp.memorysync.io/mcp"
bearer_token_env_var = "MEMORYSYNC_API_KEY"

codex mcp list then showed the server as enabled with Bearer token auth, and codex mcp get memorysync showed transport: streamable_http. You can also paste that TOML block by hand instead of running the command. If you don't set a key, the MemorySync guide says the server falls back to OAuth: run codex mcp login memorysync.

Inside the Codex TUI, /mcp lists your active servers. The MemorySync tool reference lists what the model gets, including search_memory, list_memories, add_memory, update_memory and delete_memory. The bulk deletes preview by default and need an explicit confirmation string.

With MCP only, the model uses memory when it decides to call a tool, or when you ask ("remember that we deploy on Fridays", "what do you remember about the auth refactor?"). Nothing is captured automatically.

Step 5 (optional): Add automatic recall and capture with hooks

Codex hooks can inject additionalContext at SessionStart and run on UserPromptSubmit. The MemorySync Codex plugin bundles hooks, skills and the MCP config:

codex plugin marketplace add memorysyncio/memorysync-plugins
codex plugin add memorysync@memorysync
# then, inside codex: /hooks  -> review and trust the memorysync entries

In my scratch install those two commands added the marketplace and installed plugin version 1.5.0. The plugin source, including the hook config, is in memorysyncio/memorysync-plugins. Its Codex hook config registers SessionStart (startup, resume, clear and compact), UserPromptSubmit and Stop. The guide says the hook scripts need Node.js 18+ on your PATH.

What the hooks do, per the MemorySync Codex guide:

Moment	What happens
Session start, resume or clear	Your profile and this project's context are recalled and injected
Every prompt	The prompt is sent for fact extraction, and only durable facts are stored. Longer prompts (24+ characters) also recall related memories
Reply finishes	Nothing is sent. Replies aren't stored
After compaction	Memory is injected again

Two Codex rules matter here (from the Hooks docs): non-managed hooks only run after you review and trust them in /hooks, and a changed hook needs trusting again. Also, per the MemorySync guide, Codex Web (the cloud surface) reads no local config and runs no hooks, so this part is CLI and IDE extension only.

Troubleshooting

• ~/.codex/AGENTS.md seems ignored. Run echo $CODEX_HOME: a non-default value means Codex reads a different folder. Also check for an AGENTS.override.md and make sure the file isn't empty (AGENTS.md docs).
• No memories appear after a session. Check [features] memories = true, then give it time. Generation waits until a chat is idle, and it can skip a pass when your remaining rate limit is below the configured threshold.
• Chats that use MemorySync never feed Codex memories. That's memories.disable_on_external_context = true working as designed: chats that called MCP tools are left out of memory generation.
• The MCP server is listed but calls fail. The variable named in bearer_token_env_var has to be set in the shell that launched Codex. Check with echo $MEMORYSYNC_API_KEY, or use codex mcp login memorysync for OAuth.
• Hooks don't run. Open /hooks. New or changed hooks are skipped until you trust them, and a [features] hooks = false line turns all hooks off.

Common questions

Does Codex CLI have memory like Claude Code?
It has two built-in pieces. ~/.codex/AGENTS.md and project AGENTS.md files are instructions you write, loaded at the start of every run. Codex memories (off by default, [features] memories = true) are generated from past chats and stored under ~/.codex/memories/ (Memories docs).

Where does Codex store memories?
Under your Codex home directory, ~/.codex/memories/ by default (or under CODEX_HOME if you set it). The docs call these files generated state and advise against hand-editing them as your main control.

Can Codex share memory with Claude Code or Cursor?
Not through AGENTS.md or Codex memories, which are Codex files. An MCP memory server can do it: per the MemorySync Codex guide, Codex facts carry a codex:: session key, separate from your Claude Code and Cursor sessions, but they go into the same memories.

Does the memory plugin work in Codex Web?
The hooks don't. The MemorySync guide notes that Codex's cloud surface reads no local config and runs no hooks. The MCP tools still work wherever Codex supports MCP.

Sources

• GitHub issue openai/codex#3043 (closed 2025-09-04 per the GitHub API, rechecked 2026-10-28; maintainer reply pointing to AGENTS.md)
• Codex docs: learn.chatgpt.com/docs/agent-configuration/agents-md, /customization/memories, /extend/mcp, /hooks
• Codex CLI 0.165.0 (npm @openai/codex), run in a scratch CODEX_HOME on 2026-10-28 with no login or key
• MemorySync Codex plugin 1.5.0 (installed from memorysyncio/memorysync-plugins and its hook config read on 2026-10-28)
• MemorySync docs: docs.memorysync.io/guides/codex, docs.memorysync.io/mcp/tools

Try it

If you want to see a memory survive a full page reload before you touch your Codex config, the MemorySync playground runs the save, reload and recall loop in your browser: memorysync.io/try.