Add Memory to OpenAI Codex — Persistent Development Context
OpenAI Codex is a powerful coding agent, but it starts fresh every time. Basic Memory gives it persistent context through MCP — architecture decisions, API designs, and project knowledge carry over between sessions. Notes created in Codex are available in Claude Code, Cursor, or any MCP client.
Local Setup
Video Tutorial
Configure Codex
Install Basic Memory as an MCP server:
codex mcp add basic-memory bash -c "uvx basic-memory mcp"
--project flag:codex mcp add basic-memory bash -c "uvx basic-memory mcp --project your-project-name"
Verify the installation:
codex mcp list
You should see basic-memory listed with the command bash -c uvx basic-memory mcp.
Codex CLI (Cloud)
The Codex CLI also supports MCP via a config file, which is how you connect to Basic Memory Cloud.
Get an API Key
Create one in the web app under Settings > API Keys. See the API Keys guide for details.
Add it to your shell profile (~/.zshrc or ~/.bashrc):
export BASIC_MEMORY_API_KEY=<your-api-key>
Reload your shell:
source ~/.zshrc
Configure config.toml
Add the Basic Memory server to ~/.codex/config.toml:
[mcp_servers.basic-memory]
url = "https://cloud.basicmemory.com/mcp"
bearer_token_env_var = "BASIC_MEMORY_API_KEY"
Codex CLI will now connect to Basic Memory Cloud using your API key for authentication.
Try It
Once configured, try these prompts to see Basic Memory in action:
"Create a note about our authentication strategy for the API"
Codex creates a structured note with technical details and rationale, saved to your knowledge base.
"Search my notes for everything related to database migrations"
Codex uses semantic search to find relevant notes across your projects — even if they don't contain the exact words.
"What decisions have we made about the API design? Check my notes."
Codex loads context from your knowledge base and gives answers grounded in your actual project history.
For the full list of tools Codex can use, see the MCP Tools Reference.
Troubleshooting
Codex can't find Basic Memory -- Verify it's installed (basic-memory --version), check MCP config (codex mcp list), and reinstall if needed:
codex mcp remove basic-memory
codex mcp add basic-memory bash -c "uvx basic-memory mcp"
Context not loading from memory:// URLs -- Confirm the note exists in your current project, check the URL syntax (memory://folder/note), and verify sync status with basic-memory status.
Notes not updating -- Check file permissions in the knowledge base directory and look at ~/.basic-memory for error logs.
FAQ
Does Codex have persistent memory?
Not by default. Basic Memory adds persistent, searchable context through MCP, so Codex can access your full project knowledge every session.
Can I share notes between Codex and other AI tools?
Yes. Basic Memory uses plain Markdown files as the source of truth. Notes created in Codex are immediately available in Claude Code, Cursor, Claude Desktop, or any MCP client.
How is the Codex CLI setup different from local?
The codex mcp add command runs Basic Memory locally via uvx. The config.toml approach connects to Basic Memory Cloud with an API key -- useful when you want cloud-hosted memory without a local install.