How to Give Codex Persistent Project Memory
Codex's context model is unusually explicit: it tells you exactly what it reads and when.
Once you know the mechanism, the memory question turns into a different and more answerable one.
Short answer
Codex does not carry project knowledge between sessions on its own. It rebuilds an instruction chain from AGENTS.md files on every run, concatenating from the Git root down so nearer files win. Persistence therefore comes from what those files say, from nesting them per directory, or from a layer outside Codex that supplies context each run.
What this covers
- The chain is built in order: ~/.codex/AGENTS.override.md, then ~/.codex/AGENTS.md, then a walk from the Git root down to the current directory checking override files and then standard files at each level.
- Files are concatenated from the root down and joined with blank lines. Files nearer the working directory appear later in the combined prompt and therefore override earlier guidance.
- The chain is rebuilt on every run and at the start of each TUI session, so edits take effect immediately and there is no cache to clear.
- Because the mechanism is file-based and deterministic, persistence for Codex is a question about what the files say and where they sit, not about Codex remembering anything.
- Nested AGENTS.md files are the first real answer and they scale further than most teams expect, but they are still static: every file in scope ships in full on every run regardless of the task.
- An external layer can supply context per run instead, which is what Pathrule does by attaching memories, rules and skills to paths and delivering the matching slice through Codex's hook support.
Before and after
| Area | One AGENTS.md at the root | Knowledge supplied per run |
|---|---|---|
| Working in `services/billing` | The whole file ships, including the mobile and data-pipeline rules | The slice attached to that path ships |
| A convention learned yesterday by a teammate | Arrives when someone remembers to commit it | Arrives on the next run, without a commit |
| A constraint that must not be violated | A line in a document the model weighs | A rule with a scope and an enforcement level |
| Switching to a different agent next quarter | Rewrite the guidance in that tool's format | The knowledge is stored outside both tools |
Codex is explicit about what it reads, which is unusual
Most questions about agent memory run into a wall of vagueness: nobody quite knows what the tool retained, when, or why. Codex is a pleasant exception. Its documented behaviour is that it builds an instruction chain when it starts, once per run, and that it rebuilds that chain every time rather than caching it.
The chain is assembled in a fixed order. Global files come first, `~/.codex/AGENTS.override.md` then `~/.codex/AGENTS.md`. Then Codex walks from the Git root down to your current working directory, checking for an override file and then a standard file at each level. Everything found is concatenated from the root down and joined with blank lines.
That last detail carries the whole precedence model: files closer to where you are working appear **later** in the combined prompt, and later guidance overrides earlier guidance. There is no separate priority system. Position in the concatenation is the priority system.
Why session history is not persistent project memory
Given the above, the honest answer to "how do I give Codex memory" is that Codex does not have any to give. Nothing survives a session except what is written in files it will read again next time. Close the session and everything it worked out inside that session is gone, including the correction you gave it twenty minutes ago.
This is not a shortcoming to work around so much as a design to work with. A deterministic, file-driven context chain is auditable in a way that an opaque memory store is not: you can print exactly what Codex will see. The question just moves. It stops being *what does Codex remember* and becomes *what do the files say, and how do they get there*.
Answer one: write more into AGENTS.md
The obvious first move is to put more in the root file. It works, and for a small repository with a short list of conventions it is the correct answer, which is worth saying because the rest of this article is about cases where it stops being correct.
It decays in a predictable way. Every rule you add ships on every run, in every directory, regardless of what the task is. The file grows, and the rules that matter for the file in front of the model start competing with rules about parts of the codebase nobody is touching. Nothing announces this. Codex still reads the file and still sounds confident; the line that was load-bearing just gets less weight.
Answer two: nest AGENTS.md files per directory
This is the underused one, and it follows directly from the concatenation rule. An `AGENTS.md` in `services/billing/` is only picked up when you are working at or below that directory, and because it lands later in the chain it overrides the root file. That gives you real scoping with no tooling at all.
For a lot of teams this is the answer and they should stop here. The limits show up in three places. Everything in scope still ships in full, so a large per-directory file has the same dilution problem one level down. The files live in the repository, which means knowledge only travels at commit speed and only to people who pull. And the guidance is still prose: a constraint that must never be violated reads exactly like a stylistic preference, because a Markdown bullet has no way to say which is which.
The comparison between the file standard itself and a routed layer is worked through in [AGENTS.md vs Pathrule](/writing/agents-md-vs-pathrule-when-each-makes-sense). The short version is that they are complementary: keep a short `AGENTS.md` for repository-wide constants, and put the long tail somewhere that can scope it.
Answer three: supply the context from outside Codex
Because the instruction chain is rebuilt on every run, anything that can influence what Codex sees at startup effectively becomes its memory. That is the opening a context layer uses.
[Pathrule](/codex) attaches memories, rules and skills to repository paths and delivers the matching slice through the hook support Codex exposes, before the first tool call. The unit is the same one Codex already reasons in, a path, so the scoping model does not have to be learned twice. What changes is that a rule can now carry a scope, a priority and an enforcement level rather than being a sentence in a document, and that a strict rule can stop a matching change instead of describing why it should not happen.
The team dimension matters more than it first appears. Knowledge written by one person is available to the next teammate's Codex session without a commit, and the same entries drive other agents. If half your team is on Codex and half on Claude Code, that is one set of conventions rather than two files drifting apart. More on the general shape in [persistent memory for AI coding agents](/ai-agent-memory).
What to do first
Print the chain before you change anything. Knowing which files Codex actually picks up from where you normally work answers most confusion in one step, and it is common to find a file that is never in scope for the directory the work happens in.
Then split the root file. Move anything that is true of one area into an `AGENTS.md` in that area, and keep the root for things that are true everywhere. That single change usually shortens the root file enough to make it worth reading again.
Reach for an external layer at the point where the remaining problem is no longer about scoping but about **circulation and enforcement**: knowledge that has to reach teammates faster than a commit, constraints that need to hold rather than be suggested, or a second agent that would otherwise need its own copy of everything.