Codex memory: native memories, AGENTS.md, or an external workspace
Codex can carry context in several ways that are easy to confuse. Separating instruction files, generated local memories, and external workspaces makes each one easier to choose and to check.
Codex keeps context in more than one place
Ask where Codex memory lives and you may hear about AGENTS.md, about a memories folder, or about a tool server that stores notes. All three are real, and they do different jobs. Treating them as one feature leads to rules that silently fail or preferences that never apply.
The official Codex documentation describes several customization layers that are complementary rather than competing: instruction files you write, a local memory store the client generates, and external tools the agent calls. The Model Context Protocol, an open standard for connecting AI applications to outside services, is one common way to reach the third layer.
One sentence is enough to keep them apart. AGENTS.md tells the agent what must be true. Native memories are a recall layer the client fills from earlier sessions. An external workspace is a separate service the client calls when the records must outlive one client or must carry their own sources.
Sources: OpenAI, Customization overview (Codex); Model Context Protocol
AGENTS.md: guidance you author and version
AGENTS.md is a plain Markdown file that Codex reads before doing any work. The official guide describes a discovery chain built once when a session starts. Codex first reads one global file in the Codex home directory, typically ~/.codex/AGENTS.md, then walks from the project root down to the current working directory and includes at most one instruction file per directory.
At each level Codex checks AGENTS.override.md before AGENTS.md, so an override replaces the sibling file rather than adding to it. The files are concatenated from the root downward and joined with blank lines, which means guidance closest to the working directory appears later and takes precedence when two rules conflict. Codex skips empty files and stops adding content once the combined size reaches project_doc_max_bytes, 32 KiB by default.
That design suggests a division of labor. Mandatory, team-wide rules belong in a committed repository file, because it travels with the code and every session reads it. Personal working agreements that apply across repositories belong in the global file. When a correction should always apply, write it here rather than hoping a generated memory will reintroduce it.
Two limits are worth remembering. The file is only as good as what you put in it, and the size cap is shared across the chain, so a large global file can crowd out more specific project guidance. The format itself is deliberately minimal: it is standard Markdown with no required fields, and several coding agents beyond Codex read it too.
Sources: OpenAI, Custom instructions with AGENTS.md (Codex); AGENTS.md open format
Native memories: what the client generates for you
Codex also ships a memories feature that turns useful context from eligible earlier sessions into local memory files. It is off by default in the configuration reference this article used, and the same reference marks the feature experimental, so it should be treated as optional. It is enabled with a feature flag, memories = true under the [features] table in ~/.codex/config.toml, or through the client settings.
When enabled, Codex stores its memory files under the Codex home directory, by default ~/.codex/memories/. The official documentation describes those files as summaries, durable entries, recent inputs, and supporting evidence from prior chats. Generation happens in the background rather than at the moment a chat ends, and Codex skips active or short-lived sessions. A session may need to sit idle before it is considered.
The documentation is explicit that these files are generated state: you can inspect them for troubleshooting, but editing them by hand is not the supported control surface. Because the content is produced by a model pass, it can be incomplete or stale, and it is absent whenever the feature is disabled. That is why the documentation says to keep required team guidance in AGENTS.md or checked-in documentation rather than relying on memories for rules that must always hold.
The feature separates producing memories from consuming them, and the current reference lists settings such as generate_memories, use_memories, and a switch that keeps sessions which used external context, including MCP tool calls and web search, out of memory generation. A per-chat command, /memories, changes behavior for the current chat without altering the global settings.
Sources: OpenAI, Memories (Codex); OpenAI, Config basics and feature flags (Codex)
An external workspace keeps records across clients
The third option moves the records out of the coding client entirely. A workspace service stores documents, tasks, and saved context, and the agent reaches them through a tool protocol. MCP is one common way to expose those tools to an AI application, and it is the mechanism a client uses to call servers it does not ship with.
This option is worth considering when context must cross a boundary that a single client cannot. If the same notes should be readable from two different agent tools, or if a record must outlive a laptop’s local state or a fresh container, a separate store is the natural home. It is also the option that can keep a source next to a claim: a saved statement can point back to the document revision it came from, so a later reader can check the evidence.
The tradeoffs are real. The service must be running and reachable, and the client must support the transport and the authorization the service expects; a protocol name alone does not guarantee a connection. A hosted service receives the records you send and may process them with configured providers. A locally run MCP server has a different hosting boundary, so inspect where each operation runs. Connecting an agent also does not import earlier conversations, so useful context still has to be saved deliberately. As an illustrative example, a person might keep release criteria in a saved document and the next release action in a task, both reachable by the authorized agent they use that day. That shows the shape of the workflow, not a measured result.
Sources: Model Context Protocol
A decision workflow you can use today
The three layers overlap, so the practical question is which one should own a given piece of context. One rule prevents most confusion: keep each fact or rule in exactly one place, and choose the layer by how it has to behave.
Choosing where a piece of context should live
- StartWrite down what must always holdPut mandatory rules in AGENTS.md first, before considering any generated layer.
- ObserveEnable memories for learned contextLet the client capture recurring preferences, then review the generated files.
- DecideMove shared records outWhen another client or a durable source is required, store the records in an external workspace.
- CheckTest the layer you rely onStart a fresh session and confirm which guidance and records actually arrive.
Keep one source of truth per item. Duplicating a rule across layers makes conflicts hard to reason about.
| What you have | Where it belongs | Why |
|---|---|---|
| A rule that must always apply | AGENTS.md in the repository | It is read before work begins, committed with the code, and does not depend on a background pass. |
| A personal default across repos | The global ~/.codex/AGENTS.md | It applies in every project, while files closer to the working directory still take precedence. |
| A preference or correction learned over time | Native memories, with review | The client can infer and reuse it across sessions, but the result may be incomplete or stale. |
| Context another tool must read | An external workspace | A separate store can be reached by more than one client and can outlive any single client. |
| A decision that must keep its source | An external workspace with revisions | A claim can link back to the revision behind it, so the evidence stays inspectable. |
| A secret or credential | None of these layers | Generated memory files can be copied, and external stores can be shared beyond their intended scope. |
In practice the sequence is short. Write the non-negotiable rules into AGENTS.md first. Turn on native memories for the softer preferences you are willing to review. Reach for an external workspace only when the context has to cross clients or carry a source. Then test each layer instead of assuming it works.
Check which layer actually worked
A memory workflow is only as trustworthy as the evidence that it ran. When an agent says it remembered something, it helps to locate the mechanism. A small, repeatable check is more useful than a single convincing demonstration.
- Instruction check: start a new session, ask Codex to list the instruction sources it loaded, and compare that with the files you expected the chain to include.
- Generated-memory check: inspect the files under the Codex home directory for the preference you expected, and note whether it was produced or only available.
- External-workspace check: read the saved record back through the client, and open the source revision it cites if it cites one.
- Negative check: ask about something you never saved. A useful system should report a gap rather than invent a recollection.
- Boundary check: confirm whether the current settings allow new memories to be produced, allow existing memories to be used, or exclude sessions that used external tools.
Recording the input, the saved state, the retrieved material, and the final answer turns one lucky result into a pattern you can judge. A failure at any step can look like forgetting, so it matters which step you actually observed.
Sources: OpenAI, Memories (Codex); OpenAI, Custom instructions with AGENTS.md (Codex)
What no layer promises
None of these mechanisms guarantees that the right context will always arrive. AGENTS.md discovery is deterministic, but it is bounded and reflects only what someone wrote; loading a rule does not guarantee that a model follows it. Native memories are convenient, but they are generated, optional, and can lag behind the current work. An external workspace can preserve sources and support several clients, but it depends on a reachable, authorized service. Its storage and model-processing boundaries depend on how it is hosted.
Defaults and availability change. The memories feature was experimental and off by default in the reference this article used, so confirm the current settings on the official pages before relying on a specific behavior. The goal of the workflow above is not to find one winner. It is to put each kind of context where it can do its job, then check that it did.
Sources: OpenAI, Memories (Codex); OpenAI, Config basics and feature flags (Codex)