Skip to main content
Use the universal installer first. It can configure this target for hosted cloud or local Docker Convex and creates config backups before writing.

​
Agent Instructions

Copy and paste this directly into Codex:
Codex Desktop shares ~/.codex/config.toml with the Codex CLI, so this install also configures the desktop app. You can equivalently run --targets codex-desktop. Restart Codex Desktop (or open Settings → MCP → Reload) to pick up the server.
For native Windows PowerShell, use:
For local data storage, add --backend local in Bash or -Backend local in PowerShell. See Local-First Setup. Codex can connect to Memory Crystal so it remembers project facts, rules, and past work instead of acting like every run is the first run.

​
What this means in practice

Codex CLI uses the current MCP path. The repo supports both:
  • a Codex-specific installer
  • direct MCP registration

​
How it actually works

Important repo surfaces:
  • apps/web/public/install-codex-mcp.sh
  • packages/mcp-server/README.md
  • .env.example
The installer handles:
  • detecting the Codex CLI
  • obtaining or validating the API key
  • wiring Codex config for the Memory Crystal MCP endpoint

​
Universal installer path

The recommended first install path is the universal installer:
Use it when you want Memory Crystal to detect Codex CLI, ask before changing config, and offer cloud or local-first backend mode. The dedicated commands below remain useful for single-client installs and compatibility.

​
Commands / examples

Installer:
Direct registration:

​
Tool-use guidance

For repo work, call recall-style tools with repoSlug or projectId when possible. Use crystal_preflight before config writes, deletes, external sends, and deploys. Use crystal_query_knowledge_base for named manuals, voice guides, transcripts, runbooks, or imported repo docs, and use crystal_search_messages only for exact prior wording.

​
Uninstall

For purge behavior and safety notes, see the uninstall guide.

​
Common mistakes

  • mixing the older deprecated package instructions into the current Codex flow
  • assuming Codex config and Claude config are identical
  • documenting hosted and local MCP URLs as if they were interchangeable without context
  • omitting repo scope and letting unrelated project memories consume context

​
Source of truth

Primary files behind this page:
  • apps/web/public/install-codex-mcp.sh
  • packages/mcp-server/README.md
  • .env.example