OpenAI Codex
OpenAI Codex provides native support for Basic Memory through the Model Context Protocol (MCP), enabling persistent context across development sessions and building comprehensive coding knowledge.
Setup
Video Tutorial
Watch this quick guide to get started with Basic Memory and OpenAI Codex:
Configure Codex
Basic Memory works with Codex through MCP. Install it with:
codex mcp add basic-memory bash -c "uvx basic-memory mcp"
codex mcp add basic-memory bash -c "uvx basic-memory mcp --project your-project-name"
Verify Installation
Check that Basic Memory is configured correctly:
codex mcp list
You should see basic-memory listed with the command bash -c uvx basic-memory mcp --project main.
Codex CLI
The Codex CLI supports MCP servers via configuration file. This is useful for connecting to Basic Memory Cloud.
Prerequisites
Create an API key in the web app under Settings → API Keys. See the API Keys guide for detailed instructions.
Configure Environment
Add your API key to your shell profile (~/.zshrc or ~/.bashrc):
# Basic Memory API key
export BASIC_MEMORY_API_KEY=<your-api-key>
Reload your shell:
source ~/.zshrc
Configure Codex CLI
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.
Quick Start
Once configured, you can immediately start using Basic Memory in your development workflow:
You: "Create a note about our authentication strategy for the API"
Codex: I'll document the authentication strategy we discussed...
[Creates structured note with technical details and rationale]
You: "Switch to my personal coding project"
Codex: [Changes context to personal project knowledge base]
MCP Integration Benefits
Codex's native MCP support provides:
- Automatic tool access - No manual setup required
- Project-aware context - Maintains separate knowledge bases per project
- Real-time sync - Changes are immediately available
- Persistent memory - Context survives between sessions
- Structured knowledge - Uses Basic Memory's semantic format
Available Tools
Through MCP, Codex can access all Basic Memory functionality:
- write_note - Create and update documentation
- read_note - Access existing knowledge and context
- search_notes - Find relevant information across projects
- edit_note - Update documentation incrementally
- recent_activity - Check what you've been working on
- project management - Switch between different knowledge bases
- build_context - Load conversation context from memory:// URLs
Integration with Development
Project Context
Basic Memory maintains separate knowledge bases for different projects:
You: "Switch to my work project"
Codex: [Loads work project context and knowledge]
You: "Based on our API design notes, what's the next step?"
Codex: [References existing documentation to provide contextual guidance]
Troubleshooting
Common Issues
Codex can't access Basic Memory
Solutions:
- Verify Basic Memory is installed:
basic-memory --version - Check MCP server configuration:
codex mcp list - Reinstall if needed:
codex mcp remove basic-memorythencodex mcp add basic-memory bash -c "uvx basic-memory mcp --project main"
Context not loading from memory:// URLs
Solutions:
- Confirm files exist in current project
- Check memory:// URL syntax (e.g.,
memory://folder/note) - Verify sync is working:
basic-memory status
Notes not updating
Solutions:
- Check file permissions in knowledge base directory
- Check ~/.basic-memory for logs containing error messages
- Report error messages to the Basic Memory team
Performance Tips
- Multiple projects: Use separate Basic Memory projects for different codebases
- Organized structure: Keep consistent folder organization across projects
- Regular cleanup: Archive old projects to maintain performance
Alternative Usage
If MCP isn't working, you can still use Basic Memory:
- CLI Integration — Use Basic Memory CLI tools from your terminal
- File Editing — Edit Basic Memory notes directly and sync manually
- Manual Context — Copy content from Basic Memory into conversations
- Parallel Usage — Use Claude Desktop or other MCP clients alongside Codex. With Basic Memory they can see the same notes and share context.