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.

Core Components Required for Codex Memory to Work at Scale

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. 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.] in the same config.toml, which provides durable cross-session, cross-machine, cross-tool recall. Cognee is an open-source MCP memory server backed by a knowledge graph and vector index that Codex can call through remember, recall, and forget tools.

How Codex Memory Works in Modern Coding Agents

Codex ships with a two-layer model: AGENTS.md, a static instruction file read at the start of every session (with a global ~/.codex/AGENTS.md and project-level files, defaulting to a 32 KiB cap), and Memories, a generated layer where Codex summarizes prior sessions in the background and writes them to ~/.codex/memories/. Memories are off by default and enabled with memories = true under [features] in config.toml. A minimum viable setup is AGENTS.md alone; a mature setup pairs AGENTS.md and Memories with an MCP memory server such as Cognee so recall survives sessions and syncs across machines.

Common Challenges Teams Face 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 in-session context) 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.

Key Challenges and Failure Modes When Scaling Codex Memory

• Cross-session resets. Codex ships with two native memory layers, but both reset between machines 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.
• 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. Cognee 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 memify refines the graph after ingestion by pruning stale nodes, reweighting edges based on usage, and adding 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 to Define a Winning Strategy for 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 a Scalable Codex Memory Strategy

• 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.

Cognee aligns with each of these. Its MCP server exposes remember, recall, and forget as first-class tools reachable from Codex, Claude Code, and Cursor. GRAPH_COMPLETION uses vector search as a hint to locate relevant triplets and then traverses the graph to assemble structured context. Provenance and time-aware facts are preserved on ingestion and returned alongside recall results, and memify prunes stale nodes, reweights edges by usage, and adds derived facts as the graph grows.

How to Choose the Right 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 is Apache-licensed and runs self-hosted with Docker or Kubernetes, air-gapped, inside a customer VPC, or as managed Cognee Cloud, 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 Tradeoffs for Codex

For most users, the Cognee 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 Cognee's full tool set exposed to Codex, including graph-aware search, dataset management, and temporal queries, configured once in config.toml and shared across sessions. 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 Cognee Cloud's free tier, which includes 1M tokens and one workspace with no credit card required and full access to agentic integrations including Codex, Claude Code, Cursor, and MCP. A growing team can scale on Cognee Cloud at $1.00 per 1M tokens processed plus $5 per additional workspace per month. A regulated enterprise can run the BYOC Enterprise 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.] 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 Cognee.

Step-by-Step Guide to Adding Persistent Memory to Codex

Adding persistent memory to Codex is a phased setup: pick an integration path, install or register it against ~/.codex/config.toml, connect to a Cognee 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 Cognee Memory Into Codex

1. Choose plugin or MCP server. For most users, the Cognee 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 Cognee's 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:

   codex features enable hooks
   codex plugin marketplace add topoteretes/cognee-integrations --ref main
   codex plugin add cognee@cognee
   
   This wires memory into Codex without running a standalone server.

3. **Alternatively, register the Cognee 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:
   toml
   [mcp_servers.cognee]
   command = "uv"
   args = ["--directory", "/path/to/cognee-mcp", "run", "cognee"]

4. Authenticate against a Cognee backend. Point the plugin or MCP server at Cognee Cloud using the free tier (1M tokens and one workspace, no credit card, full access to agentic integrations including Codex), or at a self-hosted Cognee 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.

5. 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.

6. 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 Cognee remains the single source of truth.

Best Practices for Operating Codex Memory Long Term

Codex memory decays in value if nobody reviews, prunes, or standardizes what the agent remembers. As a practitioner of durable AI memory, Cognee recommends treating 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.
• Let Cognee memify prune stale nodes and reweight edges. Memify refines the graph after ingestion by pruning stale nodes, strengthening frequent connections, reweighting edges based on usage signals, and adding derived facts, which keeps recall relevant as the codebase moves.
• Preserve provenance so Codex answers cite source files. Cognee preserves which document, page, and paragraph a fact came from and returns those references with every recall, so Codex can 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. In the Codex configuration reference, memories.disable_on_external_context (legacy alias memories.no_memories_if_mcp_or_web_search), when true, keeps threads that use MCP tool calls, web search, or tool search out of memory generation, which prevents duplicate memories once Cognee 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.

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 Codex-style stuffed-context approach. Full details are at Cognee.

Key Takeaways and How to Get Started

Codex offers two native memory layers, AGENTS.md instructions and in-session Memories, but both reset between machines 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. Cognee adds a graph-plus-vector memory layer exposed through an MCP server with remember, recall, and forget tools that Codex can call directly. To get started, 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.

Related guides

• Claude Code Memory: CLAUDE.md, Auto Memory, and Persistent Memory Across Sessions
• MCP Memory: What It Is and How to Give Any MCP Client Persistent Memory
• Hermes Agent Memory: How It Works and How to Improve It
• Best MCP Memory Servers for AI Coding Assistants

Frequently Asked Questions

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 reset between machines 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. Cognee is the worked example: the Cognee MCP server exposes remember, recall and forget tools backed by a Cognee knowledge graph, which 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 Cognee entry look like?+

Codex stores MCP server settings in ~/.codex/config.toml under [mcp_servers.] blocks. The fastest way to register Cognee 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 Cognee MCP process. Once the entry exists, restart Codex and the Cognee remember, recall and forget tools appear automatically inside sessions, ready to query the underlying knowledge graph.

What is the difference between AGENTS.md, Codex Memories, and a Cognee 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. A Cognee MCP memory server 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. 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.