Codex memory: AGENTS.md, local memories and external context

Does Codex have memory between sessions?

Codex has three relevant layers. AGENTS.md files are instructions Codex reads before doing work, so the same repository rules apply at the start of a new session. Local Codex memories are an opt-in feature that turns useful context from eligible prior chats into memory files on the same machine. The current chat and session context is the working state for the task in front of you.

Those layers are not interchangeable. AGENTS.md is reviewable guidance that should always apply. Local memories are a helpful recall layer generated in the background and stored under the Codex home directory. Neither is a shared, multi-tenant memory API that synchronizes decisions across teammates, repositories and other coding tools.

How does Codex discover AGENTS.md files?

Codex builds an instruction chain when it starts. At the global level it reads `AGENTS.override.md` in the Codex home directory if that file exists; otherwise it reads `AGENTS.md`. At the project level it starts at the project root, walks down to the current working directory and checks each directory for an override file, then the normal file, then configured fallback names. Codex includes at most one instruction file per directory.

The merge order is root first, then nested directories. Because files closer to the current directory appear later in the combined prompt, they can override earlier guidance. An empty file is skipped, and the combined instruction chain stops at `project_doc_max_bytes`, which defaults to 32 KiB. AGENTS.md should hold stable repository rules, not a transcript of every decision.

How do local Codex memories work?

Local Codex memories are off by default. In the ChatGPT desktop app they are enabled under Settings > Personalization, and in a local Codex client they can be enabled with `[features] memories = true` in `config.toml`. The `/memories` command in an interactive session controls whether the current chat can use existing memories and whether it can contribute to future ones. Chat-level choices do not change the global setting.

When enabled, Codex can turn useful context from eligible prior chats into local memory files. It skips active or short-lived sessions, redacts secrets from generated memory fields and updates memories in the background after a chat has been idle. Generation can also be skipped when the remaining rate-limit percentage is below the configured threshold, so recall is not guaranteed to be immediate.

The local store lives under the Codex home directory. A fresh profile uses `$CODEX_HOME/memories_v2/` by default, while an existing `$CODEX_HOME/memories/` store continues to be used unless the version is set explicitly. Treat these files as generated state: inspect them when troubleshooting, but do not make hand-editing them your primary control surface.

Can Codex use MCP for persistent memory?

Codex can connect to Model Context Protocol servers for tools and information. A memory MCP server can expose operations such as remember, search and forget, which lets Codex retrieve durable context from a service outside the local Codex home directory. MCP is a transport and tool contract; it does not decide what should be stored, merged, retained or deleted.

A production memory server must authenticate the connection, resolve the user and repository from trusted application context and enforce tenant and project scopes before returning records. A tenant identifier supplied by the model is not an authorization boundary. If the integration uses the AI Memory API instead of MCP, apply the same scopes and token budget.

What are the limits of Codex memory?

The local memory store belongs to one Codex home directory on one machine. It is not a team-wide, cross-repository or cross-product memory service, and it does not automatically synchronize with Cursor, Claude Code or another Codex installation. Generated summaries can also be incomplete, stale or simply irrelevant to the task in front of the agent.

AGENTS.md has its own limits. The instruction chain is capped by `project_doc_max_bytes`, nested files can contradict each other, and prompt-level guidance is not enforced configuration. A model can miss or misapply an instruction. Keep behavior that must be guaranteed in permissions, hooks, CI checks and tests rather than in remembered text.

• Local memories do not synchronize across machines or teammates.
• Memory generation is delayed and can be skipped near a rate limit.
• Generated summaries are not an authoritative system of record.
• AGENTS.md is capped at 32 KiB by default and can contain conflicts.
• Local memory does not provide tenant isolation across products.
• Deleting a local store does not delete copies held by other tools.
• Secrets should never be stored in AGENTS.md or memory files.
• Recall does not replace reading the current code and configuration.

How do you add durable memory to Codex?

Separate stable instructions from changing memory. Keep repository policy, build commands and architecture boundaries in AGENTS.md. Store accepted decisions, review feedback, failed approaches and repository facts that change over time in an authenticated memory service. Before a task, retrieve a small set of records scoped to the repository and current user; after review or merge, write the decision that changed the code.

A useful memory record includes the fact, the scope, the source (pull request, commit or review), the timestamp and a validity state. When a later review changes the decision, supersede the old record instead of adding a second contradictory fact. When a branch or repository is closed, delete the task memory that should not follow the team.

memory.add(
    text="The payments module owns idempotency keys; do not generate them in the handler.",
    user_id="dana",
    agent_id="codex",
    metadata={
        "tenant": "acme",
        "repo": "checkout-service",
        "source": "pr-4821-review",
        "kind": "convention",
    },
)

context = memory.search(
    query="idempotency keys payments handler",
    user_id="dana",
    filters={"tenant": "acme", "repo": "checkout-service"},
    limit=5,
)

What workflow makes Codex memory reliable?

Treat the repository as the source of truth and memory as a reviewed supplement. The agent should reread the code, configuration and tests before changing behavior. A remembered decision explains why the code looks the way it does; it does not override what the current branch actually contains.

• Before the task: load the repository AGENTS.md chain and retrieve decisions related to the files being changed.
• During the task: keep branch-specific state in the session, not in permanent memory.
• After review: write the feedback that changed the code, with the pull request and reason.
• After merge: supersede any convention the review replaced.
• On branch close: delete task memories that are not durable lessons.
• On repository archive: export and delete repository-scoped memory.

How do you test Codex memory?

Test instructions and memories separately. Start a fresh Codex session in a repository with a known AGENTS.md rule and ask Codex to list the instruction sources it loaded. Change the rule, start another session and confirm the old guidance is gone. Repeat with a nested override and a second repository.

For local memories, enable the feature on one machine, complete an eligible chat, wait for background generation and then start a new chat with `/memories` enabled. Confirm that the expected context is recalled, then disable memories for a chat and confirm it is not used. Test that a fresh Codex home directory does not inherit the previous store.

What is the recommended Codex memory architecture?

Use AGENTS.md for the rules that must apply to every run, and keep those files short, specific and reviewed like code. Use local Codex memories as a personal recall layer when they help, but do not treat them as team policy or an auditable record. Add a scoped external memory service when decisions, review feedback and repository context must survive across tools, machines and teammates.