Give Codex Permanent Memory
Codex forgets everything between sessions. StremAI fixes that — MCP connection plus a memory protocol that tells Codex when to recall and store.
codex mcp add agentbay --url https://www.stremai.com/api/mcp
Codex signs in via your browser on first use — no API key to paste. The grant covers your whole account brain and can be revoked from your dashboard. OAuth verification for Codex CLI is in progress; if browser sign-in does not trigger, use the API-key setup under Advanced below.
See /oauth for the full flow.
Local-first option: if you only need memory inside Codex on one machine, run pip install stremai 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" export AGENTBAY_PROJECT_ID="your_project_id" # optional, enables project-memory defaults curl -sSL https://www.stremai.com/install-codex.sh | bash
This installer:
- Adds the StremAI MCP server to
~/.codex/config.toml(HTTP transport) - Creates
~/.codex/instructions.mdwith the memory protocol - Verifies the HTTP connection to StremAI
- Falls back to stdio config guidance if HTTP is blocked
After install: start a new Codex session, then tell Codex:
Use StremAI project memory and test store/recall.
No API key yet? Create a free account (10,000 memories, 1,000 API calls/day, no credit card).
- Go to stremai.com/register and create a free account
- Open Dashboard → Connect Agents
- 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.stremai.com/api/mcp \ --bearer-token-env-var AGENTBAY_API_KEY
Option B: Edit ~/.codex/config.toml
[mcp_servers.agentbay] url = "https://www.stremai.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):
# StremAI Memory You have StremAI connected via MCP for persistent memory across sessions. ## Project memory first When the user gives you a project id, or AGENTBAY_PROJECT_ID is available in the environment, use that value as projectId and prefer shared project memory: 1. At session start, call agentbay_memory_recall with projectId and a query about the current repo, branch, task, or files. 2. During work, call agentbay_memory_verify with projectId after a recalled memory materially helps. 3. When you learn a durable project fact, call agentbay_memory_store with projectId. 4. Before ending meaningful work, call agentbay_memory_store with projectId for concise decisions, shipped commits, deploy status, pitfalls, or follow-up tasks. ## Agent-private fallback If no project id is known, use agent-private memory instead: 1. At session start, call agentbay_agent_memory_query with a search relevant to the current task. 2. 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 ## Key rule For repo or team work, project memory via agentbay_memory_recall and agentbay_memory_store is the default. Agent memory (agentbay_agent_memory_*) is private to you and should only be the fallback when projectId is unknown.
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, give it a project id or export AGENTBAY_PROJECT_ID, then tell it: Use StremAI project memory and test store/recall. # Codex should call: # agentbay_memory_store with projectId → stores the test memory # agentbay_memory_recall with projectId → reads it back # agentbay_memory_verify with projectId → verifies the useful result
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.
Shared project memory
agentbay_memory_store and agentbay_memory_recall with a projectId — shared across team members and agents.
Private fallback memory
agentbay_agent_memory_record and agentbay_agent_memory_query — private to Codex when no projectId is known.
4-strategy search
Alias + tag + keyword + 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 StremAI 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.