Give Codex Permanent Memory
Codex forgets everything between sessions. AgentBay fixes that — MCP connection plus a memory protocol that tells Codex when to recall and store.
Local-first option: if you only need memory inside Codex on one machine, run pip install agentbay and use the SDK directly — no signup, no API key, fully offline. Skip the MCP setup below entirely and call AgentBay() from a small Python helper Codex can shell out to. Switch to MCP when you want shared cloud memory or teams.
One command sets up everything: MCP server, memory instructions, and connection verification.
export AGENTBAY_API_KEY="ab_live_YOUR_KEY_HERE" curl -sSL https://www.aiagentsbay.com/install-codex.sh | bash
This installer:
- Adds the AgentBay MCP server to
~/.codex/config.toml(HTTP transport) - Creates
~/.codex/instructions.mdwith the memory protocol - Verifies the HTTP connection to AgentBay
- Falls back to stdio config guidance if HTTP is blocked
After install: start a new Codex session, then tell Codex:
Register as an AgentBay agent, store a test memory, and read it back.
No API key yet? Create a free account (1,000 memories, 10,000 API calls/month, no credit card).
- Go to aiagentsbay.com/register and create a free account
- Open Dashboard → API Keys
- Click Create API Key — copy the
ab_live_...key
# Add to ~/.zshrc (Mac) or ~/.bashrc (Linux): export AGENTBAY_API_KEY="ab_live_YOUR_KEY_HERE" # Then reload: source ~/.zshrc # or: source ~/.bashrc
Make sure the variable is set in the same environment that launches Codex. If you use stdio transport (step 3, Option C), you can set the key directly in the MCP config instead.
Option A: CLI one-liner (fastest)
codex mcp add agentbay \ --url https://www.aiagentsbay.com/api/mcp \ --bearer-token-env-var AGENTBAY_API_KEY
Option B: Edit ~/.codex/config.toml
[mcp_servers.agentbay] url = "https://www.aiagentsbay.com/api/mcp" bearer_token_env_var = "AGENTBAY_API_KEY"
Option C: stdio (if HTTP is blocked)
Stores your API key in plaintext in config.toml. Only use this if HTTP transport is blocked.
[mcp_servers.agentbay] command = "/bin/sh" args = ["-c", 'exec npx -y aiagentsbay-mcp@latest --api-key "$AGENTBAY_API_KEY"'] [mcp_servers.agentbay.env] AGENTBAY_API_KEY = "ab_live_YOUR_KEY_HERE"
The MCP server gives Codex the ability to use memory. This file tells Codex it should — recalling context at session start and storing learnings after work.
Create ~/.codex/instructions.md (global) or AGENTS.md (per-project):
# AgentBay Memory You have AgentBay connected via MCP for persistent memory across sessions. ## On every session: 1. At session start, call agentbay_agent_memory_query with a search relevant to the current task to recall prior context. 2. Work on the task. 3. After meaningful work, call agentbay_agent_memory_record to store what you learned. ## What to store (type="PATTERN", "PITFALL", "DECISION", or "ARCHITECTURE"): - Patterns: "This codebase uses X for Y" - Pitfalls: "Do not do X because Y breaks" - Decisions: "We chose X over Y because Z" - Architecture: "Service A talks to B via C" ## What NOT to store: - Raw code (it is in git) - Temporary debugging state - Secrets or credentials ## For team/project context: Use agentbay_memory_store and agentbay_memory_recall with a projectId to share knowledge across agents and team members. Agent memory (agentbay_agent_memory_*) is private to you.
A versioned copy of this template is available at packages/codex-plugin/AGENTS.md.template.
Start a new Codex session (MCP servers load at startup), then:
# 1. Check MCP is registered: codex mcp list # → Should show "agentbay" # 2. In a Codex session, tell it: Register as an AgentBay agent, store a test memory, and read it back. # Codex should call: # agentbay_agent_register → links your API key # agentbay_agent_memory_record → stores the test memory # agentbay_agent_memory_query → reads it back
Codex requires approval for write operations
Interactive sessions: Codex prompts you to approve state-changing MCP calls (store, register, forget). Approve when asked. Read-only calls (recall, whoami) work without approval.
codex exec / non-interactive: Write calls may be silently cancelled. Use codex --full-auto to allow all tool calls, or run write operations in an interactive session first.
Private agent memory
agentbay_agent_memory_record and agentbay_agent_memory_query — memories tied to your agent, not visible to others.
Shared project memory
agentbay_memory_store and agentbay_memory_recall with a projectId — shared across team members and agents.
4-strategy search
Alias + tag + full-text + vector search with RRF fusion. Finds the right memory whether you search by name, keyword, or concept.
Self-maintaining
Confidence decay, compaction, dedup. Old unused memories fade. Frequently verified ones stay strong.
Tool count varies by transport and package version. See all integrations for the full tool list.
MCP tools not appearing?
MCP servers load at session start — you must start a new Codex session after adding the config. Run codex mcp list to verify.
"user cancelled MCP tool call" on writes?
Interactive: Approve state-changing calls when prompted.
codex exec: Write calls may be silently cancelled. Use codex --full-auto or run write operations in an interactive session first.
"No agent linked to this API key"?
Call agentbay_agent_register once to link your API key. Only needed once per key.
AGENTBAY_API_KEY not found?
Verify with echo $AGENTBAY_API_KEY in the same terminal that runs Codex. If empty, add the export to your shell profile and source it.
Sandbox blocks network?
Use stdio transport (step 3, Option C). The npm package runs locally and proxies to the cloud.
Codex not using memory automatically?
Check that ~/.codex/instructions.md exists and contains the AgentBay memory protocol (step 4). Without it, Codex has the MCP tools but won't use them unless you ask explicitly.
Works with other AI agents too
Same setup pattern. Use project memory to share context across agents.