Codex CLI Memory: Give OpenAI Codex a Readable Project Brain

Codex CLI is becoming a serious coding partner, but the first problem most teams hit is memory. A great agent can refactor a subsystem, discover the weird deployment rule, and learn your preferred test command — then start the next session with none of that hard-won context unless you deliberately give it somewhere to write.

The right question is not “how do I make the context window bigger?” It is “where should durable engineering knowledge live?” For many teams, the answer should be files you can read, review, edit, back up, and self-host — not only embeddings hidden behind a retrieval API. That is the angle for Meshnote: agent-agnostic memory over MCP, stored as markdown wikis your agents maintain.

What the current top results cover

The pages ranking for “Codex CLI memory” are useful, but each leaves a gap. Basic Memory’s Codex guide focuses on adding persistent searchable context through MCP and on its memory:// workflow. OpenAI’s own Memories page explains that Codex can use /memories in an interactive session to decide whether the current task can use local memories or contribute future memories. Mem0’s Codex article explains the two native layers — AGENTS.md plus memories — and then positions Mem0 as an MCP memory layer with tools such as adding, searching, updating, and deleting memories.

What those pages mostly do not provide is an operational decision framework for engineering teams: what belongs in AGENTS.md, what belongs in native memories, what belongs in an MCP memory server, and how to keep that memory auditable. This post adds that missing layer, plus a concrete Codex MCP setup using a remote memory server.

The three memory layers in Codex CLI

Think of Codex memory as three layers with different jobs:

AGENTS.md: repository-scoped instructions. Put stable operating rules here: build commands, test commands, code style, package-manager constraints, and “never do X” warnings. It is versioned with the repo, so it should describe how work is done in that repo rather than personal preferences.
Native Codex memories: local remembered facts controlled through /memories. Use this for user-level preferences and lightweight recurring context. It is convenient, but it is not a shared, browsable project wiki.
MCP memory: an external tool surface that Codex can query and update. This is where shared project knowledge, decisions, runbooks, customer notes, and cross-tool agent memory can live.

If you already use Claude Code, the same pattern applies there too; see the Meshnote guide to Claude Code persistent memory. The point is to keep durable knowledge outside any single chat product so more than one agent can use it.

Working Codex CLI MCP setup for Meshnote

Codex CLI supports streamable HTTP MCP servers in ~/.codex/config.toml. You can either edit the TOML directly or use the built-in codex mcp add command. For hosted Meshnote, create an API key in Meshnote, store it in an environment variable, and point Codex at the MCP endpoint:

# macOS/Linux
export MESHNOTE_API_KEY='mnk_your_key_here'
codex mcp add meshnote \
  --url https://meshnote.io/mcp \
  --bearer-token-env-var MESHNOTE_API_KEY

On Windows, set the same environment variable in your shell before launching Codex. The resulting config is equivalent to:

[mcp_servers.meshnote]
url = "https://meshnote.io/mcp"
bearer_token_env_var = "MESHNOTE_API_KEY"

That is a real Codex CLI configuration shape: HTTP MCP servers use url, and authenticated servers can read the bearer token from bearer_token_env_var. The token is not written into the config file, which is exactly what you want for a developer workstation.

Once connected, tell Codex how to use memory in the repo’s AGENTS.md:

## Project memory
Use the meshnote MCP server for durable project memory.
Before architectural changes, search Meshnote for related decisions.
After a change that future agents should know about, update or create a wiki page.
Prefer concise pages with links to source files, commands, and decisions.

This instruction is intentionally boring. Good agent memory is not magic; it is a disciplined write path. If the agent only reads memory, it slowly goes stale. If it writes every thought, it becomes noise. The rule above tells Codex when a fact is worth preserving.

What should Codex write to memory?

Do not ask your agent to remember everything. Ask it to remember expensive-to-rediscover knowledge:

Architecture decisions and their trade-offs.
Non-obvious commands: migrations, generated clients, deployment checks, flaky test workarounds.
Integration constraints: OAuth redirect URLs, tenant boundaries, API-key handling, webhook gotchas.
Project vocabulary: domain terms, key entities, product positioning, customer-specific language.
Links between pages, for example [[Billing]], [[MCP auth]], and [[Production deploy]].

Readable markdown memory shines here because humans can audit it. A senior engineer can review a page and say “that deployment note is outdated” or “this belongs in the repo docs.” With vector-only memory, you often discover bad memory only after retrieval affects an answer.

Meshnote, Mem0, Zep, Letta, and native memory

Option	Best fit	Trade-off
Codex native memories	Personal preferences and local lightweight recall	Not a shared markdown knowledge base across agents.
Mem0	Teams that want an API-first memory layer with extraction and retrieval tools	Great category leader, but the memory is primarily operated through the service/API rather than a browsable wiki you own as files.
Zep	Conversational memory and graph-oriented user context for apps	Strong for product memory, less direct if your main need is repo-operational markdown maintained by coding agents.
Letta	Memory-first agents and research-backed memory architecture	Powerful if you are adopting the Letta agent stack; less agent-agnostic if you want one memory surface for Codex, Claude Code, and other MCP clients.
Meshnote	Readable, self-hostable project memory for coding agents over MCP	It optimizes for ownership and inspectability, not automatic benchmark claims or invisible personalization.

Recent memory research is also pushing in this direction. Letta’s 2025 LoCoMo write-up reported that a filesystem-style memory baseline scored 74.0% on the benchmark, a useful reminder that structure and accessibility can matter as much as fancy retrieval. That does not mean “files beat every memory system.” It means engineering teams should be skeptical of memory they cannot inspect.

A simple operating loop

Keep repo rules in AGENTS.md.
Connect Codex to an MCP memory server.
Start each substantial task by searching memory for related pages.
End each task by writing only durable discoveries.
Review memory pages in normal engineering hygiene, just like docs.

If you want Codex memory that survives sessions without disappearing into a black box, use a memory layer your team can open in an editor. Meshnote’s hosted plan is built for that workflow: Start syncing — $8/mo. For teams that need private infrastructure, choose Self-hosted for teams from $10/seat/month.