Skip to main content
All install guides
Install guide~60s total

Install Ricord in Codex CLI

Three commands and an in-terminal smoke test. Persistent memory wired into OpenAI's Codex CLI in 60 seconds — survives across sessions and across the Codex sandbox.

Prerequisites

  • OpenAI Codex CLI installed (codex --version works).
  • bun on your PATH (install Bun if you don't have it).
  • A Ricord account — sign up if you don't have one.

Step 1 — Install the Ricord CLI

bun add -g ricord

Verify:

ricord --version
# → ricord vX.Y.Z

Step 2 — Log in

ricord login

Sign in via the browser tab. API key lands in the OS keychain.

Step 3 — Wire into Codex

ricord install

For Codex, this appends to ~/.codex/config.toml. Codex uses TOML, not JSON — the block looks like:

[mcp_servers.ricord]
command = "ricord"
args = ["mcp"]

Existing [mcp_servers.*] tables in the config are left untouched. Verify the block landed:

grep -A2 "mcp_servers.ricord" ~/.codex/config.toml

Step 4 — Start a fresh Codex session

Codex reads config.toml at startup. If you have an active codex session running, exit it and start a new one:

codex

Step 5 — 30-second smoke test

Inside the Codex session, type:

Remember that we use Bun, not npm, for this project.

Codex calls ricord_save. You'll see the tool call inline.

Exit the session, start a new one, type:

Which package manager does this project use?

Codex calls ricord_recall and answers Bun. Install is good.

Working inside the Codex sandbox

Codex runs your sessions in a sandbox with restricted network and filesystem access. Ricord's MCP server runs outsidethe sandbox (it's a separate process spawned by Codex itself), so memory writes and reads aren't blocked by sandbox network restrictions — even when the sandbox blocks the agent's outbound HTTP.

One thing the sandbox does affect: the Ricord CLI in your shell needs to be on a PATH the host can reach, not just a path that exists inside the sandbox. If you installed bun inside a sandboxed dev container, run ricord installfrom your host shell, not from inside the container.

What to expect over the next week

  • Day 1: Codex saves and recalls across codex sessions when you ask explicitly.
  • Day 3: Codex calls ricord_get_context at session start — pulls in what it learned in previous runs without you re-explaining the repo.
  • Day 7: Open the dashboard — wiki pages per repo, with the architectural decisions and deploy commands Codex helped you figure out.

Replace your improvised CONTEXT.md

Codex doesn't ship a built-in memory convention (no CLAUDE.md, no .cursorrules). Many Codex users land on an improvised CONTEXT.md or AGENT.md in their repo root. Once Ricord is wired in, you can stop maintaining that file — auto-extraction from your conversations replaces the curation. Keep the file for stable architectural context if you like, or delete it. Either works. More on this →

Troubleshooting

Codex doesn't use the tools. Some sandbox profiles disable MCP entirely. Check ~/.codex/config.toml for a [sandbox] section that might be restricting tools. Loosen the profile or run Codex outside the sandbox for the smoke test.

Tools loaded but recall is empty. Background indexing runs every ~10 minutes. If still empty after an hour, run ricord usage to verify the account is healthy.

TOML parse errors after install. Run cat ~/.codex/config.toml and look for a duplicate [mcp_servers.ricord] section. If the file was already non-empty with other servers and ricord install appended a second table with the same name, delete the duplicate by hand.

Same install, other clients

ricord installauto-detects Claude Desktop, Claude Code, and Cursor if they're on the machine. Memory follows you across all four MCP clients — switch tools mid-debugging, the wiki and recall stay consistent.