Codex memory is two built-in layers. AGENTS.md files hold instructions you write, and Codex loads them at the start of every run. Codex memories, off by default, turn useful context from past chats into local files under ~/.codex/memories_v2/ (older setups: memories/). For memory that is searchable, shared across agents or kept on a server, add a hook-based plugin such as Hindsight.
Codex is OpenAI’s coding agent for the terminal, IDE and ChatGPT desktop app. Each session starts with an empty context window, so anything Codex should know must come back in from a file or a tool. Facts below come from OpenAI’s Codex memories docs and AGENTS.md guide, checked 13 October 2026, and from the Codex source and release notes up to 0.167.0 (6 November 2026). For Claude Code, Cursor and Copilot, see AI coding agent memory. For the two tools side by side (instruction files, defaults, skill folders), see Claude Code vs Codex.
What is Codex memory?
Codex memory is what Codex carries into a new session so it does not start from zero: AGENTS.md instruction files that you write and commit, and generated memory files that Codex builds in the background from eligible past chats. Instructions are rules; memories are a recall layer that may or may not be there.
OpenAI draws the line plainly: “Keep required team guidance in AGENTS.md or checked-in documentation,” and “treat memories as a helpful recall layer, not as the only source for rules that must always apply.”
| AGENTS.md | Codex memories | |
|---|---|---|
| Who writes it | You | Codex, in the background |
| Where | ~/.codex/AGENTS.md plus files in your repo | ~/.codex/memories_v2/ (older setups: memories/) |
| Default | Always read if present | Off |
| Edit by hand? | Yes, it’s the point | No: OpenAI calls it “generated state” |
| Shared with the team | Yes, via git | No, local to one machine |
| Size limit | 32 KiB combined (project_doc_max_bytes) | None published |
How Codex loads AGENTS.md
Codex rebuilds its instruction chain on every run:
- Global file. In the Codex home (
~/.codex, orCODEX_HOME), Codex readsAGENTS.override.mdif it exists, elseAGENTS.md. Only the first non-empty file counts at this level. - Project files. From the project root (usually the git root) down to the current directory, Codex checks each directory for
AGENTS.override.md, thenAGENTS.md, then any names inproject_doc_fallback_filenames. It takes at most one file per directory. - Merge. Files join root-first, separated by blank lines. Files closer to your working directory come later, so they win on conflicts.
- Cap. Empty files are skipped, and Codex stops adding files once the total reaches
project_doc_max_bytes, 32 KiB by default.
To use another file name, set project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"] in ~/.codex/config.toml and restart. To see what loaded, the guide suggests asking Codex directly: codex --ask-for-approval never "Summarize the current instructions."
AGENTS.md is an open format that Cursor, Copilot’s coding agent, Gemini CLI and others read too, so one file can serve several agents. Claude Code reads it when there is no CLAUDE.md; details in Claude Code memory.
How Codex memories work
Codex memories are off by default. Turn them on in either place:
- ChatGPT desktop app: Settings > Personalization > Enable Codex memories (per machine).
- CLI config: in
~/.codex/config.toml:
1[features]
2memories = true
Once on, Codex turns eligible past chats into files under ~/.codex/memories_v2/ (older setups: memories/): summaries, durable entries, recent inputs and supporting evidence. Generation runs in the background, not at the end of each chat. Codex waits until a chat has been idle long enough, skips active or short-lived sessions, and skips a pass when your remaining rate limit is below a threshold. Secrets are redacted from generated fields, though the docs still say “Don’t store secrets in memories.”
The /memories command (desktop app and CLI) sets, for the current chat only, whether it can use existing memories and whether it can feed new ones. To wipe everything, use Delete Codex memories in Settings.
Memory config keys
| Key | What it controls |
|---|---|
memories.generate_memories | Whether new chats can become memory inputs |
memories.use_memories | Whether existing memories are injected into new sessions |
memories.disable_on_external_context | Keeps chats that used MCP tools, web search or tool search out of memory |
memories.min_rate_limit_remaining_percent | Minimum rate limit left before generation starts |
memories.extract_model | Model for per-chat extraction; gpt-6-luna by default since 0.167.0 (was gpt-5.6-luna) |
memories.consolidation_model | Model for the global consolidation pass; gpt-6.1-terra by default since 0.167.0 (was gpt-5.6-terra) |
memories.consolidation_service_tier | Service tier for the consolidation pass, "default" (Standard) unless set; since 0.166.0 |
For every other config.toml key, with its allowed values and where the file is read from, see the Codex CLI config reference.
Default limits (Codex 0.167.0)
The docs don’t say when memories update. The source does. These are the defaults in codex-rs/config/src/types.rs and the config schema at tag rust-v0.167.0 (released 6 November 2026; the limits are unchanged since 0.164.0, 0.166.0 added consolidation_service_tier and 0.167.0 changed only the default models):
| Key | Default | What it means |
|---|---|---|
min_rollout_idle_hours | 6 | A chat must sit idle 6 hours before it can become a memory (the schema recommends more than 12) |
max_rollouts_per_startup | 2 | At most 2 past chats are processed per pass (1 to 128) |
max_rollout_age_days | 10 | Chats older than 10 days are not used |
max_unused_days | 30 | A memory unused for 30 days drops out of consolidation |
max_raw_memories_for_consolidation | 256 | Recent raw memories kept for the global pass (1 to 4,096) |
min_rate_limit_remaining_percent | 25 | Generation is skipped if less than 25% of your rate limit is left |
dedicated_tools | false | When true, the model gets dedicated memory tools |
version | v2 for new users, v1 if ~/.codex/memories/ already exists | Picks the memory pipeline: v1 or v2 (see below) |
So with defaults, a busy week of chats can take several passes to show up in memory: two chats per pass, each idle for at least six hours.
What changed in October and November 2026
| Version (date) | Memory change | Source |
|---|---|---|
| 0.167.0 (6 Nov) | Default memory models move to gpt-6-luna (extraction) and gpt-6.1-terra (consolidation), from gpt-5.6-luna and gpt-5.6-terra | PR #58091 |
| 0.167.0 (6 Nov) | Context-size estimates now count retained output from failed responses and responses with no usage data, so automatic compaction isn’t delayed | PR #58404 |
| 0.166.0 (29 Oct) | Consolidation gets its own service tier (Standard by default) instead of inheriting the session’s | PR #57568 |
| 0.166.0 (29 Oct) | Memory baseline snapshots capped at 10 MiB per file and rebuilt when broken, without losing memory files | PR #57240 |
| 0.166.0 (29 Oct) | Resumed and forked chats no longer count reasoning tokens twice, so they don’t compact too early | PR #57839 |
| 0.165.0 (27 Oct) | v2 is the default pipeline for profiles with no v1 memory folder | PR #56211 |
| 0.165.0 (27 Oct) | Claude Code memory files can be imported into v2 | PR #56414 |
| 0.165.0 (27 Oct) | Imports and consolidation lock the memory folder, so they can’t half-overwrite each other | PR #56462 |
| 0.164.0 (23 Oct) | v2 pipeline added behind memories.version, with dual_write | PR #55262 |
| 0.163.0 (15 Oct) | Memory reads run in parallel with other read-only tools | PR #52245 |
- Newer default models for memory (0.167.0). The models Codex picks when you don’t set
memories.extract_modelormemories.consolidation_modelare constants incodex-rs/model-provider/src/provider.rs. 0.167.0 moves per-chat extraction fromgpt-5.6-lunatogpt-6-lunaand the global consolidation pass fromgpt-5.6-terratogpt-6.1-terra, “when the provider does not require a backend-specific model ID” (PR #58091, merged 29 October). Extraction and consolidation use different models, so the two config keys matter separately. - Compaction counts failed responses too (0.167.0). Output kept from a failed response, or from one that came back without token usage, used to be left out of the context estimate, so automatic compaction could run late while reasoning piled up. Codex now tracks the point in history that the last usable usage report covered and estimates everything added after it (PR #58404). Like the 0.166.0 resume fix below, this is about the context window, not memory files.
- Consolidation stops using your fast tier (0.166.0). Before, the background consolidation pass ran on the same service tier as the chat that started it, so a session on a priority (“fast”) tier also ran consolidation on it. Now
memories.consolidation_service_tiersets it apart, and it defaults to"default", the Standard tier. Set it to"flex"or"priority"to change that;"fast"is read as"priority"(PR #57568). - Safer memory snapshots (0.166.0). Codex keeps a baseline snapshot of the memory folder to see what changed since the last consolidation. Baseline files are now capped at 10 MiB, oversized files are skipped, and a missing, outdated or broken baseline is replaced by an empty one, so existing memory files count as new input to consolidation instead of being treated as already processed. A cross-process lock stops two Codex processes from updating the baseline at once (PR #57240).
- Less early compaction after resume (0.166.0). Resuming or forking a chat used to lose a flag that said the token count already included reasoning. Codex then counted reasoning twice and could compact the context too early. The flag is now saved with the chat (PR #57839). This is about the context window, not memories, but it means a resumed chat keeps more of its history.
- v2 is now the default for new users (0.165.0). If memories are on and
~/.codex/memories/does not exist, Codex picks v2 and runs only the v2 pipeline. Anyone who already has a v1 memory folder stays on v1, and an explicitmemories.versionormemories.dual_write = falsestill wins (PR #56211). The v2 store lives in~/.codex/memories_v2/. - Import from Claude Code (0.165.0). Codex’s import from Claude Code now covers memory: it copies every Markdown file in
~/.claude/projects/<project>/memory/into Codex memories, then queues a consolidation pass that reads each project’sMEMORY.mdfirst and keeps the other files as detail to read when needed (PR #56414, source incodex-rs/external-agent-migration). Only Claude Code is a memory source; the Cursor import skips memory. It is a one-time copy, so the two tools still keep separate memories afterwards. - No more half-finished imports (0.165.0). Imports and consolidation share a lock on the memory folder. An import that hits a running consolidation returns a “busy, retry” error instead of writing part of its files (PR #56462).
- A second memory pipeline (v2, 0.164.0).
memories.versionselectsv1orv2. Withmemories.dual_write = trueand v1 selected, Codex builds both, so v2 memories are ready when you switch; once v2 is selected, only v2 runs (PR #55262, in 0.164.0). OpenAI hasn’t documented what v2 does differently. - Bounded extraction input. Extraction reads a chat newest-first and keeps up to 8 MiB of cleaned items, skipping malformed records and any record over 1 MiB (PR #53940). Very long chats lose their oldest part, not their newest.
- 14-day retention for memory extension resources, up from 7 days, before pruning (PR #54033).
- Parallel memory reads. Since 0.163.0, memory listing, reading and searching run in parallel with other read-only tools such as skill reads and conversation-history search (PR #52245).
The extract-then-consolidate design is the same pattern described in memory consolidation for AI agents, run locally on your own rate limit.
Limits of Codex’s built-in memory
The built-in layers cover rules and a light personal recall. They leave gaps that show up on long projects:
- Search belongs to the model, not to you. Codex can list, read and search its memories with internal tools, but you get no query of your own to ask “what did we decide about the cache last month?”
- One machine, one agent. The store is local to the machine, and Claude Code or Cursor on the same repo can’t read it. Codex can import Claude Code’s memory files once, but nothing flows back and the two drift apart after that.
- Slow and partial by design. With defaults, a chat waits 6 idle hours, only 2 chats are processed per pass, and chats older than 10 days are skipped (see the table above).
- Opt-in exclusions. With
disable_on_external_contexton, chats that used MCP or web search never become memories. - Instructions are capped. AGENTS.md past 32 KiB gets cut unless you raise the limit, and every byte costs tokens on every run.
Can Codex just search the raw history instead? A small October 2026 study, MemoryTax (Peng, Shanghai Jiao Tong University), gave Codex 0.159.2 one LoCoMo conversation as a file and asked 152 questions. With Claude Opus 5.5 driving it, Codex scored 98% ($25.41 for the run); with GPT-4o-mini it scored 28%: it opened the file for about three questions in four and otherwise answered from the question alone. The author’s limits: one conversation, one run per cell, a history that fits in context, and a lenient GPT-4o-mini judge. It tests chat recall, not coding work, so it says little about remembering project decisions across weeks.
Adding long-term memory to Codex
Codex CLI supports hooks and MCP servers, so external memory plugs in without changing how you work.
| Codex memories | Hindsight | agentmemory | |
|---|---|---|---|
| How it captures | Background pass over idle chats | Hooks: recall before each prompt, retain at stop | Hooks record each session |
| Where data lives | ~/.codex/memories_v2/ (older setups: memories/) | Hindsight Cloud, your own server or a local daemon | Local files, or Redis |
| Shared with other agents | No | Yes: one bank per repo, shared by Claude Code, Codex, Cursor CLI and others | Claude Code, Cursor, Gemini CLI and others |
| Search | Not exposed | Semantic + keyword + graph + time-range, reranked | BM25 + vector + graph, fused |
| License | Part of Codex | MIT | Apache 2.0 |
| Install | memories = true | npx @vectorize-io/hindsight-coding-agents install codex | codex plugin marketplace add rohitg00/agentmemory, then codex plugin add agentmemory@agentmemory |
agentmemory is the light option: free, local, no LLM key. General MCP memory servers also work, listed in AI memory MCP servers.
Where Hindsight fits
Hindsight is an MIT-licensed memory server from Vectorize. Its Coding Agents integration installs for Codex with one command. The installer adds three hooks to ~/.codex/hooks.json and an MCP server entry to config.toml; Codex needs codex_hooks = true under [features]. It asks where memory should live: Hindsight Cloud, a self-hosted server, or a local hindsight-embed daemon on 127.0.0.1:9077.
What it adds over Codex memories:
- One memory per repo, across agents. The default bank is
coding-agent::{gitProject}, so Codex, Claude Code, Cursor CLI, Copilot CLI and 20 other supported agents share what they learn on the same repo. Linked git worktrees share it too. Unlike Codex 0.165.0’s one-time import of Claude Code memory, the bank stays shared as both agents keep working. - Consolidation with evidence. Retained sessions become facts with time and entities, then observations: beliefs with supporting quotes that are refined as new sessions add evidence.
- Reasoned answers. Before each prompt it runs a low-budget
reflectby default, and the agent can callhindsight_reflectto answer “why did we drop Redis?” from many memories. - Long-history data. It reports LongMemEval 94.6 and BEAM 10M 64.1; Mem0’s own comparison page lists Mem0 at 48.6 on BEAM 10M. All of these are vendor-run numbers.
- Model freedom. 25+ LLM providers, including local ones (Ollama, LM Studio, llama.cpp).
The limits: each retain calls an LLM, so writes cost more than Codex’s built-in pass, and the local daemon needs uv and an LLM key. Recall injects context on every prompt; the default caps it at 2,000 tokens of observations, which you can lower. For a solo developer whose AGENTS.md already holds what matters, it’s more than you need. Comparisons with Mem0 are in Mem0 vs Hindsight.
How to choose
| If you need | Use |
|---|---|
| Rules every session must follow | AGENTS.md, committed to the repo |
| Light personal recall on one machine | Codex memories (memories = true) |
| Free, local session memory, no LLM key | agentmemory |
| Memory shared by Codex, Claude Code and other agents on a repo, with search and reasoning | Hindsight |
| Memory for a non-coding agent you build | See how to give AI agents memory |
Start with AGENTS.md. Turn on memories if you want Codex to pick up your habits. Add a memory server when the project outlives what a 32 KiB file and a background summary can hold, or when more than one agent works on the same code.