Codex Memory: How to Add Persistent Memory to Codex CLI

Disclosure: Membase is our product. Codex’s built-in memory works well for many solo projects, and we say where. Codex features were checked against OpenAI’s Codex documentation in November 2026.

Quick answer

Codex has two kinds of built-in memory:

• AGENTS.md: instructions you write. Codex loads them at the start of every session.
• Memories: notes Codex generates from your past threads, stored in ~/.codex/memories/. They are off by default.

Codex still forgets in four places: on your other machines, for your teammates, in your other AI tools, and once your AGENTS.md files pass the 32 KiB limit. To fix that, add a memory layer that lives outside one machine. With Membase it takes one command:

npx add-mcp 'https://api.app.membase.com/mcp-http'

In this guide: Does Codex remember past conversations? · AGENTS.md · Codex Memories · Why Codex forgets · What forgetting looks like · Your options · Add persistent memory with Membase · FAQ

Does Codex remember past conversations?

Not by default.

Inside one session, Codex remembers everything in its context window. You can reopen an earlier session with codex resume, but a new session doesn’t see it. With Memories off, a new session starts from AGENTS.md, your repo and your prompt.

So memory in Codex means files: the ones you write (AGENTS.md) and, if you turn them on, the ones Codex writes (Memories).

AGENTS.md: memory you write

AGENTS.md is a Markdown file of instructions. Codex reads it before it starts work.

It can live at several levels:

How it loads:

• Codex reads the global file first, then walks from the project root down to your current folder.
• In each folder it checks AGENTS.override.md, then AGENTS.md, and uses at most one file per folder.
• It stops adding files once their combined size reaches 32 KiB. Raise the limit with project_doc_max_bytes in ~/.codex/config.toml, or split instructions across folders.

Other coding agents read AGENTS.md too, so one well-kept file can guide Codex, Cursor and Claude Code (which can import it with @AGENTS.md).

Good for: stable rules. Build and test commands, coding style, review rules.

Not good for: decisions you make while working. Codex won’t add them to AGENTS.md unless you ask.

Codex Memories: memory Codex writes

Memories let Codex carry useful context from earlier threads into future work: your preferences, recurring workflows and lessons from past tasks.

How it works:

• Turn it on in the Codex app settings, or add this to ~/.codex/config.toml:

  [features]
  memories = true
  

• Codex turns useful context from eligible past threads into local files under ~/.codex/memories/. It skips active or short-lived sessions and redacts secrets.

• Type /memories in a session to choose whether that thread can use existing memories or be used to create new ones.

• Treat the files as generated state. You can read them, but OpenAI doesn’t recommend editing them by hand.

• At launch, Memories aren’t available in the European Economic Area, the United Kingdom or Switzerland.

Rules that must always apply belong in AGENTS.md, not in Memories.

Why Codex forgets

Codex’s built-ins are designed for one developer, on one machine, in one tool. Outside that, they forget:

1. On your other machines. Memories live in ~/.codex on the machine that wrote them. A second laptop, a server or a cloud sandbox starts with nothing but what’s committed in AGENTS.md.
2. For your teammates. Memories are per user. A teammate’s Codex doesn’t know what yours learned last week.
3. In your other AI tools. Claude Code, Cursor and ChatGPT keep their own memory. A decision made in Codex doesn’t reach them.
4. Past the size limit. Codex stops loading AGENTS.md files once they add up to 32 KiB. Files further down the tree are left out.

And if Memories are off, which is the default, a decision you didn’t write into AGENTS.md is simply gone next session.

What forgetting looks like

On Monday, you and Codex agree that list endpoints use cursor-based pagination and never offset. The old endpoints still use offset.

Nothing is broken. The memory just isn’t where the work is.

Your options for longer-lasting Codex memory

Add persistent memory with Membase

Membase is a memory layer for AI agents. It keeps one memory outside any single machine or tool, so Codex can save what matters and bring it back in the next session, wherever you work.

What it does differently:

• Recalls on every prompt, automatically. With the Codex hooks, relevant memory is added at session start and to every message you send. Codex doesn’t have to decide to look.
• Never blocks you. Recall waits up to 10 seconds; if Membase is slow, Codex moves on and the results arrive with your next prompt.
• Saves in the background. Your sessions are saved without slowing Codex down.
• One memory, everywhere. The same Memory works on every machine and in Claude Code, Gemini CLI and Cursor. Give each teammate’s agent its own key scoped to that Memory, and revoke it any time.
• Every answer has a source. Each search result points back to the session or document it came from.
• Hosted or local. Use the hosted service, or keep memory on your own machine with local mode.
• Fewer tokens. Membase’s engine scores 93.1% on LoCoMo while using up to 11x fewer tokens than the full history (our own numbers; see the method).

Set it up in 2 minutes:

1. Sign up at app.membase.com, open Connect > Developer keys and create a key. Create a Memory named after your repo.

2. Add Membase to Codex:

   export MEMBASE_API_KEY=mbk_your_key
   codex mcp add membase --url https://api.app.membase.com/mcp-http --bearer-token-env-var MEMBASE_API_KEY
   

   Run codex mcp list to check the connection.

3. For automatic recall on every prompt, install the Codex hooks: follow Membase Use Case 01. The same installer works for Claude Code and Gemini CLI. Codex hooks don’t currently run on Windows; there, use the MCP connection on its own.

4. Test it: decide something specific, quit, open a new session and ask about it without mentioning it.

Tip: add one line to your AGENTS.md, such as “Before starting a task, search Membase for past decisions about this code.” Codex then checks memory even without the hooks.

Use it alongside AGENTS.md and Memories

You don’t have to choose. Each layer has its job:

Common mistakes

• Putting everything in AGENTS.md. Past 32 KiB, files stop loading. Keep rules there and let memory hold the rest.
• Expecting Memories to be on. They’re off by default. Turn them on, or decisions won’t carry over.
• Editing ~/.codex/memories/ by hand. It’s generated state. Put rules you want to control in AGENTS.md.
• One memory for every repo. Create one Memory per repository so projects don’t mix.

Quick links

• Membase web app: create a key and a Memory
• Membase Use Case 01: install the hooks for Codex, Claude Code and Gemini CLI
• How to Add Persistent Memory to Claude Code
• MCP server: https://api.app.membase.com/mcp-http
• Membase docs

Membase is in beta and free during the beta.