Codex Memories and AGENTS.md: Where to Keep Information and Rules
What you’ll learn
- The difference between preferences and cautions stored in Codex Memories and mandatory rules managed in a repository
- How to decide when to stop using or generating memories, or review their contents
- How to combine memory settings for individual threads with team instructions such as
AGENTS.md
The roles of Codex Memories and formal rules
Codex Memories provide a way to refer to information from past work in future tasks. When working repeatedly in the same repository—a place for managing code and documents together—they reduce the need to explain preferences and cautions every time.
Memories are intended for preferences and cautions that remain useful across tasks. Avoid keeping mandatory team rules or sensitive information solely in memory.
In this article, a “source of truth” means a document that a team maintains as its official reference. Treating memory as the source of truth makes it harder to establish who is responsible for updates and which information is still valid.
Choose where to store information based on who needs it and who is responsible for updating it. Memories support an individual’s work, repository instructions hold mandatory team rules, and temporary conversation context holds information needed only for the current task.
Using this distinction, this article explains what to keep in Memories, what to manage in the source of truth, and when to review memory.
Information suited to Memories
Memories are useful for information that lasts and would slow down work if it had to be explained repeatedly. Examples include writing preferences, recurring procedures, technologies in use, and problems encountered in the past.
Even the same information may belong in different places depending on whether it serves as a personal reference or a formal team rule.
| Information | Benefit of referring to it through Memories | Where to manage it formally |
|---|---|---|
| Personal writing preferences | Avoid explaining recurring preferences again; keep them separate from product specifications | Blog writing guidelines, when needed |
| Frequently used verification commands | Find the checks and commands needed at the start of a task more easily | AGENTS.md or shared team procedures (shared workflows) |
| Repository-specific cautions | Reduce the likelihood of repeating the same mistake | Shared team rules, if they must be followed consistently |
| Background to past decisions | Identify where to begin the next investigation | Documents managed in Git, if the information concerns specifications or design decisions |
The table classifies stored information by its intended use. This classification is specific to this article, rather than an official one from OpenAI. The official documentation describes how Codex saves useful information from past conversations as memories for future work.[1]
Information to avoid storing only in Memories
Do not manage information solely through Memories if losing it would cause problems, retaining an error would be dangerous, or it needs to apply consistently to everyone on a team.
Mandatory team rules
Rules such as “Run a production build only with explicit approval” or “Do not include fabricated sources in published articles” are safer when they are kept somewhere other than personal memory alone.
Record these rules in AGENTS.md, a file that gives Codex instructions for its work, or in shared rules. Add automatically checkable requirements to validation scripts as well. This lets everyone working on the repository refer to and verify the same rules.
Secrets and customer information
Work on the assumption that secrets and customer information should not be saved in Memories.
OpenAI’s official documentation explains that Codex removes secrets from the memories it generates. Even so, it advises inspecting the contents before sharing Codex home—the directory that stores settings and work state—or generated memory files.[1]
Avoid an approach that leaves sensitive information in memory on the assumption that it will be removed automatically.
Temporary hypotheses and workarounds
One-off hypotheses, unconfirmed findings, and workarounds that are valid only for today are also unsuitable for Memories. If they persist, Codex may start the next task with outdated assumptions.
Keep temporary investigation notes within the conversation for that task, separate from information intended for future work.
When to stop using or generating memories, and when to review them
Review memory handling when a project’s purpose or structure changes, incorrect recall recurs, or unnecessary information accumulates.
“Reset” here is an operational term that includes more than manually deleting memory files. It also includes stopping memory use or generation in a thread—an ongoing conversation—changing settings, or inspecting saved information to reduce reliance on unnecessary assumptions. Stopping memory use or generation is distinct from deleting memories that are already saved.
| Situation | Approach |
|---|---|
| Codex repeatedly uses outdated assumptions | Inspect the relevant memories. Record the correct rules in AGENTS.md or shared rules |
| The project structure changed substantially | Review memories that assume old directories, commands, or workflows |
| A thread involved extensive temporary research or external information | Configure that thread so it is not used to generate future memories |
| The work involved sensitive information | Stop memory generation. Inspect ~/.codex/memories/ before sharing related files |
| A personal caution became an established team rule | Reflect it in rules or checks managed in Git, a system for tracking changes |
| Codex’s suggestions conflict with current specifications | Prioritize official documentation and the repository’s current state over memory |
Memory can speed up the start of a task, but outdated assumptions can also make incorrect work proceed faster.
The purpose of a review is to ensure that Codex refers to information appropriate to the current specifications and task, rather than simply returning it to an initial state.
Memory settings for individual threads
Apps and CLIs that use Codex local memory offer controls for the current thread. The official documentation describes /memories controls in the ChatGPT desktop app and Codex TUI, the interactive terminal interface.[1]
You can choose:
- Whether the current thread uses existing memories
- Whether the current thread can be used to generate future memories
These choices apply to the individual thread and do not change global memory settings.[1]
These controls are an option when customer information, unpublished information, or authentication information should not carry into later work, or when temporary information imported through web search or MCP—a mechanism for connecting external tools and data to AI—should not be reused. Stopping memory use or generation is not the same as ensuring that the service does not retain information.
Investigations that test many incorrect hypotheses, or one-off checks with many decisions that should not carry over, are also occasions to reconsider whether a thread should be used to generate future memories.
The official settings include the following.[1][2]
| Setting | What it controls |
|---|---|
memories.generate_memories | Whether newly created threads are saved as input for memory generation |
memories.use_memories | Whether existing memories are referenced in subsequent work |
memories.disable_on_external_context | When true, excludes threads that use external information, such as MCP or web search, from memory generation |
memories.min_rate_limit_remaining_percent | The percentage of Codex usage allowance that must remain before memory generation starts |
Check memories.disable_on_external_context in particular if you want to exclude threads that use external information from memory generation.
The local memory described here is a different mechanism from memory in ChatGPT Web or ChatGPT Work. Check the settings for the product you are using.[1]
Handling automatically generated memory files
Codex stores memories under Codex home. The default Codex home is ~/.codex, and the main memory files are in ~/.codex/memories/.[1]
The official documentation describes these as files generated and updated by Codex. You can inspect them during troubleshooting or before sharing, but manual editing should not be the primary way to control memory.[1]
The following approach can help preserve formal records and rules.
| Information to manage | Primary method |
|---|---|
| Information needed only for the current task | Choose at the thread level whether to use memories or allow memory generation |
| Rules that must be followed consistently | Record them in AGENTS.md or shared rules |
| Changed specifications | Update repository documents and checks |
| Incorrect memories that keep being referenced | Inspect generated memories and review both the usage settings and the official reference |
Treating memory files like manually edited configuration files blurs the distinction between formal rules and automatically generated information. Memories are easier to manage as an aid that helps Codex recall past work.
Shared repository instructions and automatic checks
Keep shared commands, constraints, verification procedures, and responsibilities for each folder in AGENTS.md or shared rules managed in Git. AGENTS.md gives Codex the instructions it should consult first when working in that repository.
Add mechanically checkable requirements to review commands or CI, a mechanism for automatically running tests and checks through services such as GitHub Actions. Documents communicate the rules; automatic checks verify that they are followed.
Use Memories to refer to an individual’s working tendencies. Examples include “This user often treats Japanese documents as the official reference” and “This repository’s user prefers reviews focused on the changed areas.”
Once a tendency becomes a mandatory rule, reflect it in repository documents or checks. Avoid leaving it only in memory.
If important assumptions are also recorded in documents and checks, the necessary rules remain available when memory use stops or its contents are reviewed. Reducing dependence on memory can make Codex’s work more stable.
Summary: Personal Preferences in Memory, Mandatory Team Rules in Shared Documents
Codex Memories reduce the need to explain personal preferences and recurring cautions again. Manage mandatory team rules in AGENTS.md or shared documents, and work on the assumption that sensitive information and temporary hypotheses should not be retained in memory.
If you are unsure where information belongs, determine whether it is a personal preference, team instruction, sensitive information, or temporary context, and identify who needs it and who updates it. Review outdated assumptions against the current specifications. Before stopping memory use or generation, check the current settings for the product you use.
References
- OpenAI, Memories, ChatGPT Learn
- OpenAI, Configuration Reference, ChatGPT Learn
For details on the latest releases and updates, check the official website and documentation.