Codex Memory: How to Give OpenAI Codex Persistent Memory Across Sessions
< BlogGuides
October 19, 2026
Updated October 21, 2026
17 minutes read

Codex Memory: How to Give OpenAI Codex Persistent Memory Across Sessions

Codex memory is the hard part of using OpenAI's coding agent on real projects: the Codex CLI and Codex IDE agent reset between sessions, AGENTS.md is manually maintained and capped at 32 KiB by default with no notion of time, and nothing syncs across machines or tools. Engineers end up re-explaining the same repo, re-stating the same decisions, and losing context mid-task. This guide is for engineers using the Codex CLI or Codex IDE agent who want durable recall. It covers how Codex memory works today, how an MCP memory server extends it, and how to wire the Cognee MCP server into Codex as a worked example.

What does Codex memory need to work?

In practice, Codex memory is the combination of three layers that together let the agent carry context across sessions, machines, and tools. The first is AGENTS.md, a static instruction layer read at the start of every session, with a hierarchy from ~/.codex/AGENTS.md down to project-level files and a 32 KiB default cap (project_doc_max_bytes). The second is Codex Memories, a generated summary layer written in the background to ~/.codex/memories/ and enabled via memories = true under [features] in ~/.codex/config.toml. The third is an MCP memory server, configured under [mcp_servers.<name>] in the same config.toml, which provides durable cross-session, cross-machine, cross-tool recall. Any server that speaks the Model Context Protocol can fill this slot; a graph-based memory server exposes tools such as remember, recall, and forget that Codex calls like any other MCP tool.

How does Codex memory work today?

Codex ships with a two-layer model. AGENTS.md is a static instruction file read at the start of every run: Codex loads ~/.codex/AGENTS.md (or AGENTS.override.md) first, then walks from the project root down to the current directory, concatenating one file per directory until the combined size hits the 32 KiB default cap. Memories is a generated layer where Codex summarizes eligible prior sessions in the background and writes summaries, durable entries, and supporting evidence to ~/.codex/memories/. Memories are off by default and enabled with memories = true under [features] in config.toml; /memories inside a session controls whether the current chat can read existing memories or feed future ones. A minimum viable setup is AGENTS.md alone; a mature setup pairs AGENTS.md and Memories with an MCP memory server so recall survives sessions and syncs across machines.

What are the common problems with Codex memory?

Codex memory starts to break down the moment a project grows past a single developer on a single machine. The two native layers (AGENTS.md plus local Memories) reset between machines, cannot share context across tools, and have no concept of time. AGENTS.md is also manually maintained and capped at 32 KiB by default, so teams end up either hand-editing instruction files or re-explaining the repository every time a new session starts.

Where Codex memory breaks down

  • Cross-session resets. Codex ships with two native memory layers, but both are local to one machine and cannot share context across tools. Decisions made in one session do not carry into the next unless they are written back into AGENTS.md by hand or happen to survive background memory generation.
  • Cross-tool and cross-machine fragmentation. A developer using Codex CLI on a laptop, Codex in an IDE, and another agent such as Claude Code or Cursor ends up with three disconnected memories. There is no shared substrate, so architectural choices and task history live in silos.
  • AGENTS.md 32 KiB cap and manual upkeep. AGENTS.md files are the documented persistence mechanism for Codex CLI, with a hierarchy from ~/.codex/AGENTS.md down to project-level files, defaulting to a 32 KiB size cap. The file has to be curated by humans, and it fills up fast on any non-trivial codebase.
  • No time awareness. AGENTS.md has no concept of time, so stale guidance (an old library version, a deprecated service, a decision that was later reversed) sits next to current rules with no way to tell them apart.

Mitigation centers on moving durable context out of static files and into a shared MCP memory layer that every tool can read and write. A graph-based memory layer addresses the four failure modes directly: an MCP server gives Codex, Claude Code, and Cursor the same memory across machines; time-aware memory extracts events and timestamps so retrieval can be constrained to a particular period; recall returns facts together with their source references, so a developer can see which document, page, or paragraph a claim came from; and periodic graph maintenance prunes stale nodes and adds derived facts. Codex still needs to be told when to call memory tools, so those instructions belong in AGENTS.md or in the task prompt.

How should you design Codex memory?

Once Codex can reach an external memory server, the harder question is editorial: what gets remembered, when recall fires, and how stale knowledge is pruned. Tool choice matters less than those rules. Connecting an MCP memory server to Codex does not force Codex to read or write anything on its own; AGENTS.md or the task prompt has to tell the agent when to call remember, recall, or forget. Without that guidance, the server stays idle while Codex falls back to session-only context.

Must-have capabilities for Codex memory

  • Cross-session persistence. Memory must outlive a single Codex session so decisions, conventions, and prior fixes carry forward instead of being re-explained in every new chat.
  • Cross-tool sharing. The same memory store should be reachable from any MCP client, Codex, Claude Code, or Cursor, so an architectural note written in one agent is available to the next.
  • Source provenance. Every recalled fact should carry a pointer back to the document, page, or paragraph it came from, so Codex can cite the origin and engineers can audit what the agent is acting on.
  • Time-aware facts. Facts need ingestion timestamps and validity windows so that "what did we decide about auth last quarter?" returns the right version, not a superseded one.
  • Graph-structured retrieval. Pure top-k vector search returns loose snippets; a graph lets Codex traverse from an entity to its related functions, decisions, and owners before answering.

These five capabilities are the checklist to hold any backend against. Vector-only stores cover the first two; provenance, time awareness, and graph traversal are what separate a memory layer from a cache of chat snippets. The "How Cognee" section below shows how one graph-based server maps onto them.

How do you choose a memory backend for Codex?

Engineering teams adding persistent memory to Codex usually weigh three paths: a native plugin that drops into the CLI with minimal setup, a Codex MCP server that exposes a full memory tool set through ~/.codex/config.toml, or a hosted alternative managed outside the repo. The right choice depends on how much control the team needs over storage, how many developers share the memory layer, and whether compliance requires data to stay inside a specific account or region.

Selection criteria that matter most

Focus on criteria that affect day-to-day reliability: scalability of the underlying stores, open source versus hosted licensing, provenance of recalled facts, time awareness for questions scoped to a release window or sprint, deployment model (self-host, managed cloud, or BYOC), and cost predictability. Cognee, the worked example in this guide, is Apache-licensed and runs self-hosted with Docker or Kubernetes, air-gapped, inside a customer VPC, or as a managed cloud service, with pluggable backends such as Postgres/pgvector, Neo4j, Kuzu, Amazon Neptune, and LanceDB. Recall returns facts with their source references and time-aware events, which matters when Codex is asked why a decision was made.

Plugin vs MCP server for Codex

For most users, a memory plugin is the simpler path: it adds persistent memory with a few commands and no separate MCP server to run. The MCP setup is the right choice when a team wants the full tool set exposed to Codex, including graph-aware search, dataset management, and temporal queries, configured once in config.toml and shared across sessions. Codex also supports project-scoped .codex/config.toml files for trusted projects, so a team can check the MCP registration into the repo. Teams often start with the plugin to prove value, then move to MCP as workflows grow.

Deployment patterns by team size

A solo developer can run a hosted free tier (Cognee's includes 1M tokens and one workspace with no credit card required, with access to agentic integrations including Codex, Claude Code, Cursor, and MCP). A growing team can scale on a managed plan; as of October 2026 Cognee Cloud bills $1.00 per 1M tokens processed plus $5 per additional workspace per month. A regulated enterprise can run a BYOC plan inside its own AWS, Azure, GCP, or European provider account, keeping all memory data in the customer's VPC.

Alternative MCP memory backends

Mem0 is another MCP memory option for Codex and plugs into the same [mcp_servers.<name>] block in ~/.codex/config.toml that Codex uses for any MCP server. It is a reasonable choice for teams that want a hosted key-value style memory and do not need a graph plus vector index, source-level provenance, or time-aware recall. Teams that need those graph and temporal features, or a self-hosted and BYOC path, typically prefer a graph-based server such as Cognee; see Mem0 alternatives for a fuller comparison.

How to add persistent memory to Codex step by step

Adding persistent memory to Codex is a phased setup: pick an integration path, install or register it against ~/.codex/config.toml, connect to a memory backend, and tell the agent when to use memory. The steps below walk through both the Cognee memory plugin and the Cognee MCP server so a team can start with the lightest option and graduate to the full tool set when needed.

Wiring an MCP memory server into Codex

  1. Choose plugin or MCP server. For most users, the memory plugin is the simpler path: it adds persistent memory with a few commands and no separate MCP server to run. The MCP route is the right choice when a project needs the full tool set (remember, recall, forget) exposed to Codex and other MCP clients.

  2. Install the Cognee memory plugin. Enable the hooks feature, add the integrations marketplace, and install the plugin with these three commands:

This wires memory into Codex without running a standalone server.

  1. Alternatively, register the MCP server. Codex CLI supports MCP servers natively and reads them from ~/.codex/config.toml under [mcp_servers.<name>] blocks. For a Docker or HTTP deployment, run codex mcp add cognee --url http://localhost:8000/mcp. For a local source checkout, register a stdio command instead, for example:
  1. Authenticate against a backend. Point the plugin or MCP server at the hosted free tier (1M tokens and one workspace, no credit card), or at a self-hosted instance running via Docker, Kubernetes, air-gapped, or inside a customer VPC with pluggable stores such as Postgres/pgvector, Neo4j, Kuzu, LanceDB, Qdrant, or Redis.

  2. Tell Codex when to use memory in AGENTS.md. Connecting an MCP memory server does not force Codex to read or write memory. Add explicit instructions to AGENTS.md or the task prompt describing when the agent should call remember, recall, and forget, for example, recall before planning a change and remember after confirming a decision.

  3. Avoid duplicate memory generation. In ~/.codex/config.toml, set memories.disable_on_external_context = true (legacy alias memories.no_memories_if_mcp_or_web_search). When true, Codex keeps threads that use MCP tool calls, web search, or tool search out of its built-in memory generation, so the external server remains the single source of truth. The full list of memory keys is in the Codex configuration reference.

Best practices for Codex memory

Codex memory decays in value if nobody reviews, prunes, or standardizes what the agent remembers. Treat the memory layer like any other production system: keep instructions tight, let the graph self-maintain, carry provenance through to recall, and respect time. The practices below cover the controls that matter day to day when Codex is wired to an MCP memory server.

  • Keep AGENTS.md focused and under the 32 KiB cap. AGENTS.md is manually maintained, size-limited to 32 KiB by default, and has no concept of time, so reserve it for stable repo conventions and push durable, evolving knowledge into the MCP memory server. The agents.md convention is shared across coding agents, so the same file also guides tools other than Codex.
  • Let the memory layer prune stale nodes and reweight edges. A graph that refines itself after ingestion, pruning stale nodes, strengthening frequent connections, reweighting edges based on usage signals, and adding derived facts, keeps recall relevant as the codebase moves.
  • Preserve provenance so Codex answers cite source files. A memory server that records which document, page, and paragraph a fact came from, and returns those references with every recall, lets Codex show the file or decision log a suggestion is grounded in instead of asserting it blindly.
  • Use time-aware facts for anything that expires. Time-aware memory extracts events and timestamps so retrieval can be constrained to particular periods, which is how to keep API versions, deprecated endpoints, and migration deadlines from leaking into current answers.
  • Enable memories.disable_on_external_context when MCP is in use. When true, this key keeps threads that use MCP tool calls, web search, or tool search out of memory generation, which prevents duplicate memories once the external server is the system of record.

How Cognee Simplifies and Scales Codex Memory

Cognee gives Codex a knowledge-graph-plus-vector memory layer through a native MCP server, exposing remember, recall, forget, and improve as first-class operations that any MCP client (Codex, Claude Code, Cursor) can call. Under the hood, the ECL pipeline (extract, cognify, load) ingests repo files, extracts entities and relationships with an LLM, writes embeddings to the vector store and edges to the graph, and reprocesses only new or updated files. GRAPH_COMPLETION retrieval uses vector search as a hint, then traverses graph triplets to build structured context instead of returning plain top-k chunks. Memify refines the graph over time by pruning stale nodes, reweighting edges, and adding derived facts, while every recall ships with source provenance and time-aware facts so Codex knows which file, paragraph, and point in time a claim came from. Against the five must-have capabilities above, that covers cross-session persistence and cross-tool sharing through MCP, provenance and time-aware facts on ingestion, and graph-structured retrieval at query time.

Deployment is flexible: Cognee is Apache-2.0 and pip-installable, runs self-hosted on Docker or Kubernetes, air-gapped, or inside a customer VPC, and is also available as Cognee Cloud with a free tier of 1M tokens and one workspace with no credit card. Cognee Enterprise is BYOC inside the customer's AWS, Azure, GCP, or European provider account, so data stays in the customer's VPC. On the BEAM benchmark, Cognee reported 79% at the 100k-token context window (vs 73.4% SOTA) and 67% at the 10M-token context window (vs 64.1% SOTA), with token usage staying flat as data grows rather than scaling linearly like a stuffed-context approach. Full details are in the Cognee documentation and on GitHub.

Key takeaways

Codex offers two native memory layers, AGENTS.md instructions and locally generated Memories, but both are local to one machine and cannot share context across tools. Registering an MCP memory server in config.toml closes that persistence gap so Codex can store and recall project knowledge across sessions. A graph-plus-vector memory layer exposed through MCP with remember, recall, and forget tools adds provenance, time awareness, and structured retrieval on top. To get started with the worked example from this guide, create a workspace on the Cognee Cloud free tier (1M tokens, one workspace, no credit card), or self-host Cognee via pip or Docker under Apache-2.0.

Docs: Codex integration, MCP overview, MCP tools reference, Codex on Cognee Cloud.

FAQ

What is Codex memory and what does OpenAI Codex remember between sessions by default?

Codex memory has two native layers. AGENTS.md is a static instruction layer read at the start of every session, with a hierarchy spanning ~/.codex/AGENTS.md for global rules and project-level AGENTS.md files, capped at 32 KiB by default. Memories is a generated layer where Codex summarizes prior sessions in the background and writes them to ~/.codex/memories/, but it is off by default and must be enabled with memories = true under [features]. Both layers are local to one machine and cannot share context across tools, so cross-session recall requires an external memory backend.

How do I give OpenAI Codex persistent memory across sessions?

The durable path is to attach an MCP memory server to Codex. Codex ships with native Model Context Protocol support, so a server registered in config.toml becomes available as callable tools inside every session. A graph-based server exposes remember, recall and forget tools backed by a knowledge graph that stores decisions, code context and conversations and retrieves them mid-task. Because the graph lives outside Codex, context survives sessions, syncs across machines, and can be shared with other MCP clients such as Claude Code and Cursor.

Where is the Codex MCP configuration file and what does a memory server entry look like?

Codex stores MCP server settings in ~/.codex/config.toml under [mcp_servers.<name>] blocks, with an optional project-scoped .codex/config.toml for trusted projects. The fastest way to register a server against a Docker or HTTP deployment is the built-in command codex mcp add cognee --url http://localhost:8000/mcp, which writes the entry for you. For a local source run, you can instead define a stdio command block pointing at the MCP process. Once the entry exists, restart Codex and the remember, recall and forget tools appear automatically inside sessions.

What is the difference between AGENTS.md, Codex Memories, and an MCP memory server?

AGENTS.md is static: a human-maintained instruction file read at session start, size-limited to 32 KiB and with no concept of time. Codex Memories is generated: background summaries of past sessions written to ~/.codex/memories/, useful but local to one machine and opaque to other tools. An MCP memory server such as Cognee is durable graph memory: facts, code references and decisions are stored in a knowledge graph with vector index, time-stamped for temporal search, and queried on demand through MCP tools. The three layers complement each other rather than replace one another.

How much does Cognee cost as a Codex memory backend?

Cognee Cloud has a free workspace with 1M tokens and one workspace, no credit card required, and includes full access to agentic integrations including MCP, Claude Code, Codex and Cursor. Paid usage is billed as $1.00 per 1M tokens processed, plus $5 per additional workspace, as of October 2026. Teams that prefer to keep data in their own environment can self-host the open-source Cognee project under Apache-2.0, or run Enterprise BYOC. The same MCP server, remember and recall tools, and knowledge graph behavior apply across free, paid and self-hosted deployments.

Related reading

Codebase Memory: What It Is and How to Give AI Coding Agents Persistent Memory of Your Repository
Claude Code Memory: CLAUDE.md, Auto Memory & Persistent Memory
Cursor Memory: How It Works and How to Make It Persistent
Get started

Cognee is the fastest way to start building reliable Al agent memory.

Latest
What Are 500+ Companies Actually Building with AI Memory?
Meet the new cognee: smarter memory, lower costs, and control for your team
Coding Agent Findings Without Coordinates Are Just Hearsay