> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorycrystal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI

> Connect Memory Crystal to Codex CLI and understand both the installer path and direct MCP registration.

## Recommended: universal installer

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:

```text theme={"system"}
Install Memory Crystal for Codex CLI. Run the official installer command for this machine, follow the auth/backend prompts, and do not manually edit Codex config unless the installer fails and asks for a manual fallback. After installation, run `codex mcp list` when available or restart Codex CLI and confirm Memory Crystal tools are available.

macOS/Linux/WSL:
curl -fsSL https://memorycrystal.ai/crystal | bash -s -- --targets codex-cli

Windows PowerShell:
iwr https://memorycrystal.ai/install.ps1 -OutFile install.ps1; .\install.ps1 -Targets codex-cli
```

<Note>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.</Note>

```bash theme={"system"}
curl -fsSL https://memorycrystal.ai/crystal | bash -s -- --targets codex-cli
```

For native Windows PowerShell, use:

```powershell theme={"system"}
iwr https://memorycrystal.ai/install.ps1 -OutFile install.ps1
.\install.ps1 -Targets codex-cli
```

For local data storage, add `--backend local` in Bash or `-Backend local` in PowerShell. See [Local-First Setup](/configuration/local-first).

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:

```bash theme={"system"}
curl -fsSL https://memorycrystal.ai/crystal | bash
```

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:

```bash theme={"system"}
curl -fsSL https://memorycrystal.ai/install-codex-mcp.sh | bash
```

Direct registration:

```bash theme={"system"}
codex mcp add memory-crystal --url http://localhost:3100/mcp
```

## 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

```bash theme={"system"}
curl -fsSL https://memorycrystal.ai/uninstall-codex-mcp.sh | bash
```

For purge behavior and safety notes, see the [uninstall guide](/help/uninstall).

## 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`