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

Install Ricord in Codex CLI

Two 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).
  • Node.js ≥ 18 with npm on your PATH.
  • A Ricord account — sign up if you don't have one.

Step 1 — Install the Ricord CLI

npm install -g ricord

Verify:

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

Step 2 — Set up Ricord

ricord setup

setup signs you in via the browser (API key lands in the OS keychain), scans your history for preferences, then auto-detects installed AI clients and wires each one. For Codex, it 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 3 — 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 4 — 30-second smoke test

Inside the Codex session, type:

Remember that this repo deploys to Cloud Run via deploy.sh.

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

Exit the session, start a new one, type:

How do I deploy this repo?

Codex calls ricord_recall and answers Cloud Run via deploy.sh. 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 Node.js inside a sandboxed dev container, run ricord setupfrom 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.

Optional: build a wiki for this repo

After a few sessions, run this from any repo root to generate a structured wiki from everything Ricord has learned:

ricord build

The result appears in the dashboard — one wiki page per entity your sessions have touched.

Same setup, other clients

ricord setupauto-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.