Persistent Memory for Codex

What Codex keeps, and what it drops

Codex starts every session with a lot of context: the repository, the diff, your AGENTS.md. That's a genuinely strong starting position, and it's why the gap is easy to miss. The gap is that nothing Codex learns during a run goes anywhere.

Available next session?	What
Yes	The code, the tests, the git history, your `AGENTS.md` instructions
No	Why a design was chosen over the alternative that looks equally good in the code
No	The root cause behind a fix, as opposed to the fix itself
No	The three approaches already tried and ruled out
No	The staging-only constraint discovered at 2am last month
No	Where the previous session stopped and what it intended to do next

Every row in the "No" column is knowledge that was expensive to acquire and is invisible in the code. That's precisely the set worth persisting.

Why not just put it in AGENTS.md?

Because AGENTS.md is loaded in full, every run. That's exactly what you want for instructions — deterministic, always present, no retrieval step to get wrong — and exactly what you don't want for a knowledge base. A file that must stay short cannot also hold two years of accumulated findings.

The split that works: AGENTS.md holds how to behave in this repo. A memory server holds what has been learned about this project, searched on demand so only the relevant few notes ever enter context. The same argument applies to CLAUDE.md, worked through in detail.

Connecting Codex to a memory server

Knownbase is a remote MCP memory server: one URL, nothing to install.

{
  "mcpServers": {
    "knownbase": {
      "url": "https://knownbase.dev/mcp"
    }
  }
}

If your Codex build handles OAuth for remote MCP servers, that's the whole configuration — it will open a browser to sign in and let you pick a workspace. If it only supports static config, generate an API key in Settings → Workspace & MCP and add a header instead:

{
  "mcpServers": {
    "knownbase": {
      "url": "https://knownbase.dev/mcp",
      "headers": {
        "Authorization": "Bearer kb_YOUR_KEY_HERE"
      }
    }
  }
}

Step-by-step, including how to scope a key to a single project, is on the Codex integration page.

Telling Codex when to use it

The tools being available isn't the same as the agent using them well. Add this to AGENTS.md:

## Project memory

Persistent project memory is available via the `knownbase` MCP server.

Before starting a task, `search_notes` for decisions, constraints and
prior debugging findings about the area you're touching.

After the task, `upsert_note` anything durable that isn't visible in
the code: a decision and its reasoning, a root cause, a constraint,
an approach that was tried and rejected, or a handoff if you're
stopping mid-task.

Do not store code, transcripts, or unconfirmed speculation.

A worked example

Codex is asked to speed up a nightly export job. It profiles, finds the bottleneck is the upstream API's per-page rate limit rather than anything local, and confirms that parallelising requests trips a 429 that the provider applies per account rather than per connection. The final change is a modest one: bigger pages, same serial loop.

Without memory, the next agent to look at that job sees a serial loop over an API and does the obvious thing — parallelise it. It works in dev, where volume is low, and fails in production. The same afternoon gets spent twice.

With memory, Codex writes it down before finishing:

upsert_note({
  project: "reporting",
  title: "Export job cannot be parallelised — provider rate limit is per account",
  tags: ["constraint", "rejected-approach", "exports"],
  status: "active",
  body: "Nightly export is bounded by the provider's rate limit, not by our\n" +
        "processing. The limit is per ACCOUNT, so concurrent requests trip 429\n" +
        "regardless of connection count. Tried and rejected: worker pool,\n" +
        "connection-per-shard. What worked: max page size, serial loop.\n" +
        "See src/exports/nightly.js:140."
})

Next session, whichever agent picks it up finds that in one search and doesn't repeat the afternoon.

Sharing memory with Claude Code and Cursor

Because the store is outside every tool, it isn't Codex's memory — it's the project's. Point Claude Code at the same workspace and it reads the same notes:

claude mcp add --transport http knownbase https://knownbase.dev/mcp

This turns out to matter more than expected in practice, because people use different agents for different work — one for large refactors, another for quick fixes, a third inside the editor. Without shared memory, each one is permanently new to the project. More on sharing context between Claude Code and Codex.

Keep reading

FAQ

Does Codex remember anything between sessions?

It reads your repository and your AGENTS.md every time, so instructions and code carry over. What doesn't carry over is what a session worked out: the reason an approach was abandoned, the actual cause of a failure, the constraint discovered in staging. That lives in the conversation and ends with it.

How do I give Codex persistent memory?

Connect it to an MCP memory server. Add the Knownbase endpoint to your Codex MCP configuration, authenticate with OAuth or a bearer key, and Codex gains search_notes, get_note and upsert_note. From then on it can write findings and read them back in later sessions.

Can Codex read notes that Claude Code wrote?

Yes, if both point at the same workspace. That's the main reason to keep memory outside either tool: a constraint Claude Code discovered on Monday is retrievable by Codex on Thursday, with no copying and no re-explaining.

Is AGENTS.md enough?

For rules, it's the right tool — a short, explicit set of instructions the agent reads every run. It's the wrong tool for accumulated knowledge, because it's loaded in full every time and therefore has to stay short, while project knowledge only ever grows. Use AGENTS.md for how to behave and a memory server for what has been learned.

What should Codex actually save?

Decisions and the reasoning behind them, root causes rather than patches, approaches that were tried and rejected, environment and deployment constraints, and end-of-session handoffs. Not code (that's git's job), not transcripts, and not unconfirmed speculation.

Does this need anything installed?

No. It's a remote MCP server, so it's a URL plus authentication. Nothing runs on your machine, which also means it works identically from a different machine or a web client.

Give Codex project memory it can share

One MCP endpoint, readable by Codex, Claude Code, Cursor and your teammates' agents. Free plan, no card required.

Create free workspace