Developer workflow
Codex Memory: MEMORY.md, Setup, and AGENTS.md
Find Codex's MEMORY.md, understand how it loads, and enable native memories. Keep required rules in AGENTS.md; use shared MCP memory when other AI tools need the same project knowledge.
01
Codex memories are off by default. Turn them on in settings or with memories = true in config.toml.
02
MEMORY.md is a generated handbook under ~/.codex/memories/. Codex looks up relevant entries rather than loading the whole file.
03
Codex manages its own local memories. Use a shared MCP memory server when Claude Code or Cursor need the same capture and recall tools.
01
Quick answer
Codex has native memories. Its generated MEMORY.md normally lives at ~/.codex/memories/MEMORY.md and holds lessons from earlier chats. You do not need to create a project MEMORY.md to enable the feature.
AGENTS.md serves a different purpose: it contains instructions you maintain, such as test commands and repository rules. Keep required guidance there; use memories to help Codex recall past work.
Memories are off by default. Once on, Codex updates them in the background after a chat has been idle for a while, not the moment it ends.
| AGENTS.md | Codex memories | |
|---|---|---|
| Who writes it | You | Codex, from earlier chats |
| Where it lives | ~/.codex/AGENTS.md and AGENTS.md files in your repository | ~/.codex/memories/ |
| When it loads | Every session, every time | When memories are on for that chat |
| Use it for | Rules, commands, and conventions that must always apply | Preferences and lessons Codex picks up as you work |
| On by default | Yes, if the file exists | No |
02
How to turn Codex memories on or off
In the ChatGPT desktop app, open Settings > Personalization and turn on Enable Codex memories. For the Codex CLI, add the feature flag to ~/.codex/config.toml.
If you don't see the setting, check the current Codex memories docs for regional availability.
[features]
memories = true03
Control memories for one chat with /memories
In the Codex TUI and the ChatGPT desktop app, type /memories to decide whether the current chat can use existing memories and whether Codex may learn from it. This only affects the current chat; your global setting stays the same.
For finer control, these settings go under memories in config.toml:
- memories.use_memories: whether Codex puts existing memories into new sessions.
- memories.generate_memories: whether new chats can be turned into memories.
- memories.disable_on_external_context: keep chats that used MCP tools or web search out of memory.
- memories.min_rate_limit_remaining_percent: skip memory updates when you're close to your usage limit.
04
Where is Codex MEMORY.md?
The default path is ~/.codex/memories/MEMORY.md. If you set CODEX_HOME, use $CODEX_HOME/memories/MEMORY.md instead. This is separate from AGENTS.md in your repository.
The file map below follows the OpenAI Codex memory templates checked on October 18, 2026, linked under Official references. These are implementation details, so names and loading behavior can change between versions.
| File or folder | What it does |
|---|---|
| memory_summary.md | Compact overview that helps Codex decide where to look |
| MEMORY.md | Searchable handbook of lessons and pointers to earlier work |
| raw_memories.md | Intermediate input for memory consolidation |
| rollout_summaries/ | Summaries of earlier sessions with supporting evidence and references |
~/.codex/memories/
├── memory_summary.md
├── MEMORY.md
├── raw_memories.md
└── rollout_summaries/05
Does Codex load the whole MEMORY.md automatically?
No. In the implementation checked here, Codex receives a compact memory summary and can search MEMORY.md for relevant entries, then open supporting material when needed. It does not put the entire handbook into every new conversation.
A file existing on disk does not prove it was used in a particular answer. Memories must be enabled for that host and chat; Codex may skip a lookup for a self-contained task. If a rule must apply on every task, put it in AGENTS.md.
06
How to check whether MEMORY.md exists
On macOS or Linux, run this read-only command in your terminal. It lists the memory folder; it does not print your private memories or change them. Look for the exact uppercase filename MEMORY.md.
If the folder or file is missing, first confirm that memories are enabled and that you are checking the Codex home folder on the machine running your session. Memory generation runs in the background and can skip short or still-active chats. A missing file just after enabling memories is not, by itself, a failure.
Do not create a blank MEMORY.md as a setup step or use hand edits as your main control. OpenAI treats these files as generated state. Use settings and /memories to control the feature, and inspect contents for sensitive details before sharing any memory files.
ls -la "${CODEX_HOME:-$HOME/.codex}/memories"07
What goes in AGENTS.md instead
OpenAI's own advice is to keep required guidance in AGENTS.md, not in memories. Memories help Codex recall things; they are not guaranteed to load every time.
Codex reads ~/.codex/AGENTS.md first, then each AGENTS.md from your repository root down to the folder you're working in. A file closer to your folder wins when rules conflict. An AGENTS.override.md in the same folder replaces the AGENTS.md there.
- Put build, test, and lint commands in the repository's AGENTS.md.
- Put personal working preferences in ~/.codex/AGENTS.md.
- Codex stops reading once the combined files reach 32 KiB. Raise project_doc_max_bytes or split the instructions into folders if you hit the limit.
- To check what loaded, run: codex --ask-for-approval never "Summarize the current instructions."
08
Why Codex doesn't remember your last session
A new Codex session starts a new conversation. It reloads AGENTS.md and, if memories are on, relevant memories, but not the previous chat itself. Memories also arrive late: Codex waits until a chat has been idle before it summarizes it.
To pick up exactly where you left off, resume the conversation instead.
codex resume # pick from recent sessions
codex resume --last # most recent session in this folder
codex resume --all # search sessions from every folder
codex fork --last # start a new chat from the last one09
Codex memories not working
Most problems come from one of these:
- Nothing in ~/.codex/memories/: memories are off, or your chats were too short or still active. Give it time after a chat goes idle.
- Codex ignores a rule: move the rule to AGENTS.md. Memories are a recall aid, not a guarantee.
- Chats that used MCP tools or web search never become memories: check memories.disable_on_external_context.
- No updates while you work hard: Codex skips memory updates when your remaining usage is below memories.min_rate_limit_remaining_percent.
- Edited the wrong file: run echo $CODEX_HOME. A custom value points Codex at a different home folder.
10
Codex memory plugins and MCP servers
Codex stores generated memories locally, including supporting evidence from earlier chats. You can inspect those files, but other AI tools do not automatically use the same memory store.
If you want Codex, Claude Code, and Cursor to share one memory store, connect them to a compatible MCP memory server. This gives the tools a common way to capture and recall project knowledge.
| Option | How it works | Good for |
|---|---|---|
| Codex memories | Codex writes notes from earlier chats into ~/.codex/memories/ | Local recall from earlier Codex chats |
| AGENTS.md | You write instructions Codex loads every session | Rules that must always apply |
| An MCP memory server | Stores memories behind MCP tools that any compatible client can call | Sharing memory between Codex, Claude Code, Cursor, and others |
| Wenlan | Local MCP memory plus wiki pages that cite their sources and flag when a source changes | Project knowledge you want to read, check, and share across tools |
11
Add Wenlan to Codex
Wenlan is an open-source desktop app with a Codex plugin. It keeps memory on your computer, turns related notes into wiki pages that cite their sources, and serves the same memory to Claude Code, Cursor, Claude Desktop, and other MCP clients.
Install the Wenlan runtime first, then add the plugin, start a new Codex task, and run $wenlan. Test one capture and one recall before relying on it for real project memory.
npx -y wenlan setup # macOS Apple Silicon; other platforms: see setup docs
codex plugin marketplace add wenlan-app/wenlan
codex plugin add wenlan@7xuanlu-wenlan
# start a new Codex task, then:
$wenlan12
Use Wenlan in a Codex session
The Codex plugin adds the same session commands as Claude Code. Name the concrete decision, file area, or gotcha; a capture like "worked on repo" will not help a later session.
- /brief: load project status and relevant memories before you start.
- /capture: save one decision, gotcha, or constraint and why it matters.
- /recall: look up a past decision by project name or failure mode.
- /handoff: record what changed and what is open, so a later Codex or Claude Code session can continue.
Share Codex memory with your other AI tools
Install the Wenlan plugin for Codex, run $wenlan, then test one capture and recall before adding real project context.
FAQ