--- title: "How Codex's memory works" description: "Codex memory, from OpenAI's docs: AGENTS.md loading order, the generated memories directory, cloud container caching, CLI sessions, and controls." canonical: https://past.dev/blog/codex-memory date: 2026-09-03 category: Research authors: The past.dev team --- # How Codex's memory works Codex is OpenAI's coding agent. It runs as a cloud agent in ChatGPT, as a CLI on your machine, and as an IDE extension, and what it remembers depends on the surface ([Codex docs](https://developers.openai.com/codex)). Codex memory has two documented layers as of September 2026: `AGENTS.md`, instruction files you write that load at startup ([AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md)), and Memories, an opt-in feature where Codex summarizes prior chats into files it reads in later ones ([memories docs](https://developers.openai.com/codex/memories)). Cloud tasks run in fresh containers, so state moves between tasks only through the repo, those files, and an infrastructure cache. This post documents each layer from OpenAI's official documentation, with the cloud and CLI differences called out where the docs draw them. ## Does Codex have memory? Yes, in two documented forms, both under user control. The first is `AGENTS.md`: static guidance Codex discovers and loads before doing any work ([AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md)). The second is Memories: summaries, durable entries, recent inputs, and supporting evidence extracted from eligible prior chats, stored under the Codex home directory and injected into future sessions when enabled ([memories docs](https://developers.openai.com/codex/memories)). On local Codex clients the Memories feature is opt-in and off by default ([memories docs](https://developers.openai.com/codex/memories)). Everything else that looks like memory is session and environment mechanics, covered below. For the general pattern behind that split, see [cross-session memory](/glossary/cross-session-memory). ## AGENTS.md: the layer you write `AGENTS.md` is authored configuration. The discovery rules are precise ([AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md)): - Global scope loads first: Codex checks `~/.codex/AGENTS.override.md`, then `~/.codex/AGENTS.md`, and uses only the first non-empty file at that level. - Project scope follows: starting at the Git root and walking down to the current working directory, each level is checked for `AGENTS.override.md`, then `AGENTS.md`, then any configured fallback names. - Files concatenate from the root down, joined with blank lines. Files closer to your current directory appear later in the combined prompt, so their guidance takes precedence. - The combined size is capped by `project_doc_max_bytes`, 32 KiB by default. The docs advise raising the limit or splitting instructions across nested directories when you hit it. - `project_doc_fallback_filenames` in `~/.codex/config.toml` lets alternate filenames such as a team guide count as instruction files. In the CLI, `/init` scaffolds an `AGENTS.md` for the current repository ([CLI docs](https://developers.openai.com/codex/cli/features)). The same instruction-file pattern shows up across coding agents; [Claude Code's memory](/blog/claude-code-memory) covers the `CLAUDE.md` equivalent. ## Codex long term memory: the Memories feature Memories is the generated layer, and the docs treat it as state rather than configuration ([memories docs](https://developers.openai.com/codex/memories)): - What gets stored: summaries, durable entries, recent inputs, and supporting evidence from prior chats. Secrets are automatically redacted from generated memory fields. - Where it lives: `~/.codex/memories/` under the Codex home directory (default `~/.codex`), treated as generated state rather than files you are expected to hand-edit. - When it is written: memories are generated from eligible prior chats. Codex waits until a chat has been idle long enough to avoid summarizing work still in progress, and short-lived sessions are excluded. - When it is read: with the feature enabled, Codex can inject existing memories into new sessions, subject to the per-chat controls. - Generation backs off under quota pressure: it pauses when remaining rate limit falls below the `memories.min_rate_limit_remaining_percent` threshold. - The models used for extraction and consolidation are configurable via `memories.extract_model` and `memories.consolidation_model`. Scope is narrow by design: memories are per user and per environment. ChatGPT web and local Codex clients maintain separate stores, and the IDE extension uses the store of the Codex host it is connected to ([memories docs](https://developers.openai.com/codex/memories)). ## The controls Every switch is documented on the memories page ([memories docs](https://developers.openai.com/codex/memories)): - Desktop app: Settings > Personalization > Enable memories. - Config file: a `[features]` section with `memories = true`. - Fine-grained keys: `memories.generate_memories` and `memories.use_memories` split writing from reading, and `memories.disable_on_external_context` guards sessions that pull in outside context. - Per chat: the `/memories` command controls whether the current chat can read existing memories or contribute to future ones. ## What persists in the CLI CLI chats persist on their own, independent of the Memories feature. `codex resume` reopens a recent chat from the current repository or searches across local chats for older work ([CLI docs](https://developers.openai.com/codex/cli/features)). The SDK documentation in OpenAI's open-source repo states that threads are persisted in `~/.codex/sessions`, and that a lost thread object can be reconstructed from there ([openai/codex SDK README](https://github.com/openai/codex/blob/main/sdk/typescript/README.md)). This is stored transcript, in the sense of [session memory](/glossary/session-memory): reopening a chat restores its history into context. Users have reported cases of truncated history after resuming a session ([issue #15709](https://github.com/openai/codex/issues/15709), a user report on the official repo). ## What persists in the cloud Cloud Codex is built around ephemeral containers, and the environments page is explicit about what carries over ([cloud environments](https://developers.openai.com/codex/cloud/environments)): - Each cloud chat gets a container with your repo checked out at the selected branch or commit SHA. - Containers are cached for up to 12 hours to speed up follow-ups and new chats. Changing setup scripts, maintenance scripts, environment variables, or secrets invalidates the cache. - A setup script runs at container creation with internet access. An optional maintenance script runs when a cached container is resumed. - `export` in a setup script does not persist into the agent phase. Durable environment variables go in `~/.bashrc` or the environment settings. - Secrets are available only to setup scripts and are removed before the agent phase starts. - If the repo contains an `AGENTS.md`, the cloud agent uses it to find project-specific lint and test commands. The page documents no mechanism that carries agent-learned state from one cloud task to the next. The cache exists to skip setup work; knowledge transfer between tasks goes through the repo, `AGENTS.md`, and the Memories feature where enabled. ## What Codex memory does not do - Nothing is remembered by default on local clients: Memories ships off, and until you opt in, a new session starts from `AGENTS.md`, the repo, and what you provide ([memories docs](https://developers.openai.com/codex/memories)). - Stores do not sync across surfaces. A memory created in ChatGPT web stays there; local clients keep their own ([memories docs](https://developers.openai.com/codex/memories)). - `AGENTS.md` never updates itself. It is configuration you author; generated state lives in the memories directory ([memories docs](https://developers.openai.com/codex/memories), [AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md)). - The docs describe no user-facing way to browse or edit individual generated memories beyond the files on disk; the documented controls are the toggles, config keys, and `/memories` ([memories docs](https://developers.openai.com/codex/memories)). ## For builders: memory as a layer you own Codex remembers for one user, one environment, one machine at a time. If you are building your own agent and need memory that spans users, sources, and time, past.dev is that infrastructure layer: `POST /api/v1/ingest` accepts raw text with its original timestamp, entity resolution links references to the same person across sources, and facts carry event time, validity windows, and supersession links. `POST /api/v1/recall` returns ranked, dated evidence with sources and one of four status values (Supported, Conflicted, NoKnownSupport, UnknownBecauseDegraded), running managed or self-hosted in your own Postgres. Start with the [quickstart](/docs/memory-api/quickstart) and the [benchmarks](/benchmarks); if you build on OpenAI's stack, the [OpenAI Agents SDK integration](/integrations/openai-agents-sdk) shows the wiring.