OpenAI Codex
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 immediately available in Claude Code, Cursor, Claude Desktop, or any other MCP client.
Codex comes in two forms, and both connect to Basic Memory:
- Codex app — the agent inside ChatGPT (or the Codex desktop app)
- Codex CLI — the terminal-based coding agent
Each one can connect to either a local Basic Memory (running on your machine) or Basic Memory Cloud (remote MCP). Pick the combination that fits your workflow.
Codex app
The Codex app talks to MCP servers over HTTP, so you give it a URL.
Connect to Basic Memory Cloud (remote MCP)
Get your MCP endpoint
Your Basic Memory Cloud URL is:
https://cloud.basicmemory.com/mcp
Add it in Codex
In the Codex app, open Settings → Connectors → Custom MCP (the exact label may be "MCP Servers" or "Developer → MCP" depending on your version) and add:
- Name: Basic Memory
- Server URL:
https://cloud.basicmemory.com/mcp
Authenticate
Sign in to authorize Codex. Basic Memory Cloud uses OAuth — when prompted, complete the sign-in flow in your browser.
Enable in conversations
Turn on the Basic Memory connector for the conversation, and Codex can read, write, and search your notes.
Connect to a local Basic Memory (local MCP)
To point the app at a Basic Memory running on your own machine, start a local HTTP MCP server, then add its URL to Codex:
Start a local server
basic-memory mcp --transport streamable-http --port 8000
This exposes Basic Memory at http://localhost:8000/mcp.
Add it in Codex
In Codex's MCP/connector settings, add:
- Name: Basic Memory (local)
- Server URL:
http://localhost:8000/mcp
basic-memory mcp process running while you use Codex. For most app users, the Cloud setup is simpler.Codex CLI
The Codex CLI can spawn local MCP servers as subprocesses or connect to a remote MCP endpoint via its config file.
Local MCP
Add Basic Memory as a local 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
codex mcp list
You should see basic-memory listed with the command bash -c uvx basic-memory mcp.
Video walkthrough
Remote MCP (Basic Memory Cloud)
Get an API key
Create one in the web app under Settings → API Keys. See the API Keys guide for details.
Export it
Add the key to your shell profile (~/.zshrc or ~/.bashrc):
export BASIC_MEMORY_API_KEY=<your-api-key>
Reload your shell:
source ~/.zshrc
Configure ~/.codex/config.toml
[mcp_servers.basic-memory]
url = "https://cloud.basicmemory.com/mcp"
bearer_token_env_var = "BASIC_MEMORY_API_KEY"
The 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 when 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 CLI 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"
Codex app can't reach a local server — Confirm basic-memory mcp --transport streamable-http is still running and the port matches the URL you gave Codex. Apps can't spawn subprocesses, so the server has to be live.
Cloud authentication errors — For the CLI, make sure BASIC_MEMORY_API_KEY is exported in the shell Codex was launched from. For the app, remove and re-add the connector to redo the OAuth flow.
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.
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.
App or CLI — which should I use?
They're complementary. Many people use the CLI with local MCP while coding, and the app with cloud MCP for planning or review on another device. Both read the same knowledge base.
Local or remote MCP?
- Local keeps everything on your machine — best for personal projects and when you don't want anything in the cloud.
- Remote (Basic Memory Cloud) means your notes are reachable from any device and any client, with no local processes to manage. Required for the app unless you're willing to run a local HTTP server.