Skip to content

5.codex.md

Latest commit

 

History

History
233 lines (170 loc) · 7.49 KB

5.codex.md

File metadata and controls

233 lines (170 loc) · 7.49 KB
title Add Memory to OpenAI Codex — Persistent Development Context
description Add persistent memory to OpenAI Codex with Basic Memory. Keep development context, decisions, and code knowledge across every coding session.

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.

Why Add Memory to Codex?

Codex is a powerful coding agent, but it starts fresh every time. Basic Memory gives it persistent context:

  • Decisions that stick — Architecture choices, API designs, and coding patterns are remembered automatically
  • No more re-explaining — Pick up where you left off with full project context intact
  • Cross-tool knowledge — Notes created in Codex are available in Claude Code, Cursor, or any MCP client
  • Your files, your control — Everything stored as plain Markdown you can read, edit, and version control

Setup

Video Tutorial

Watch this quick guide to get started with Basic Memory and OpenAI Codex:

<iframe style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border-radius: 0.5rem;" src="https://www.youtube.com/embed/BfISDQ0p-UM" title="Basic Memory + OpenAI Codex Setup Guide" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen ></iframe>

Configure Codex

Basic Memory works with Codex through MCP. Install it with:

codex mcp add basic-memory bash -c "uvx basic-memory mcp"

::tip If you want to use a specific Basic Memory project, modify the command like so:

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-memory then codex 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.

Frequently Asked Questions

Does Codex have persistent memory?

OpenAI Codex doesn't retain memory between sessions by default. Basic Memory adds persistent, searchable context through MCP integration, so Codex can access your full project knowledge every time.

How do I add memory to Codex?

Run codex mcp add basic-memory bash -c "uvx basic-memory mcp" to configure Basic Memory as an MCP server. See the setup guide above for detailed instructions.

Can I share notes between Codex and other AI tools?

Yes! Basic Memory uses a universal knowledge format. Notes created in Codex are immediately available in Claude Code, Cursor, Claude Desktop, or any MCP-compatible client.

::note Basic Memory also works with: Claude Code · Cursor · Claude Desktop · VS Code · Obsidian ::

Next Steps

:::card-group ::card

title: Project Documentation icon: i-lucide-folder-kanban to: /how-to/project-documentation

Learn how to document your development projects. ::

::card

title: Research & Learning icon: i-lucide-graduation-cap to: /how-to/research-learning

Build knowledge from your coding sessions. ::

::card

title: CLI Reference icon: i-lucide-terminal to: /reference/cli-reference

Master Basic Memory command line tools. ::

::card

title: Knowledge Format icon: i-lucide-file-text to: /concepts/knowledge-format

Structure effective development documentation. :: :::