supermemory/apps/docs/integrations/codex.mdx

---
title: "OpenAI Codex"
sidebarTitle: "OpenAI Codex"
description: "codex-supermemory — persistent memory for OpenAI Codex CLI"
icon: "terminal"
---

<Warning>
This integration requires the **Supermemory Pro plan**. [Upgrade here](https://console.supermemory.ai/billing).
</Warning>

[codex-supermemory](https://github.com/supermemoryai/codex-supermemory) wires Supermemory into the [OpenAI Codex CLI](https://github.com/openai/codex) via hooks and an MCP server. Your agent gets **two layers of memory**:

- **Implicit** (hooks) — automatically recalls context before each prompt and captures conversations after each session.
- **Explicit** (MCP tools) — lets you or the agent save, search, and manage memories on demand.

## Get Your API Key

Create a Supermemory API key from the [API Keys](https://console.supermemory.ai/keys) page, then export it in your shell profile:

<Tabs>
  <Tab title="macOS / Linux (zsh)">
    ```bash
    echo 'export SUPERMEMORY_CODEX_API_KEY="sm_..."' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Tab>
  <Tab title="macOS / Linux (bash)">
    ```bash
    echo 'export SUPERMEMORY_CODEX_API_KEY="sm_..."' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Tab>
  <Tab title="Windows (PowerShell)">
    ```powershell
    [System.Environment]::SetEnvironmentVariable("SUPERMEMORY_CODEX_API_KEY", "sm_...", "User")
    ```
    Restart your terminal after running this.
  </Tab>
</Tabs>

## Install the Plugin

```bash
npx codex-supermemory@latest install
```

This command:
- Copies hook scripts and the MCP server to `~/.codex/supermemory/`
- Enables `codex_hooks = true` in `~/.codex/config.toml`
- Registers `UserPromptSubmit` (recall) and `Stop` (capture) hooks in `~/.codex/hooks.json`
- Registers the `supermemory` MCP server in `~/.codex/config.toml`

Restart Codex CLI after installing.

## How It Works

Once installed, the plugin runs automatically on every Codex session:

- **Recall** — Before each prompt, relevant memories and your user profile are fetched from Supermemory and injected as additional context.
- **Capture** — After each session ends, the conversation transcript is ingested into Supermemory, scoped to the current project and user.
- **Privacy** — Content wrapped in `<private>...</private>` tags is redacted before storage.

### Memory Scopes

Memories are tagged with two container tags per session:

| Tag | Format | Description |
|-----|--------|-------------|
| User | `codex_user_{sha256}` | Memories shared across all your projects |
| Project | `codex_project_{sha256}` | Memories scoped to the current working directory |

## Explicit Memory Tools (MCP)

The installer registers a local stdio MCP server that runs alongside Codex — no separate login needed. It uses the same `SUPERMEMORY_CODEX_API_KEY` as the hooks.

Three tools are available directly in your Codex session:

| Tool | Description |
|------|-------------|
| `memory` | Save a new memory (`mode: "add"`) or forget one by ID (`mode: "forget"`) |
| `recall` | Search memories by natural-language query |
| `listProjects` | List recent memories in the current project or user scope |

Examples:
```
> Remember that this project uses Vitest for unit tests and Playwright for E2E.
> What do you remember about our database schema?
> Forget the memory about the old API endpoint.
```

Verify the MCP server is registered:
```bash
codex mcp list
```

## Verify Installation

```bash
npx codex-supermemory status
```

Expected output when everything is configured:

```
codex-supermemory status:

  API key:       ✓ set (SUPERMEMORY_CODEX_API_KEY)
  Hook scripts:  ✓ installed at ~/.codex/supermemory
  hooks.json:    ✓ registered
  config.toml:   ✓ codex_hooks enabled
  MCP server:    ✓ registered

All good! Memory is active.
```

## Uninstall

```bash
npx codex-supermemory uninstall
```

This removes the hook scripts and MCP server from `~/.codex/supermemory/`, the hook registrations from `~/.codex/hooks.json`, and disables `codex_hooks` and the MCP server entry in `~/.codex/config.toml`. Your existing memories in Supermemory are preserved.

## Configuration

Create `~/.codex/supermemory.json` to override defaults:

```json
{
  "apiKey": "sm_...",
  "similarityThreshold": 0.6,
  "maxMemories": 5,
  "maxProfileItems": 5,
  "injectProfile": true,
  "containerTagPrefix": "codex",
  "debug": false
}
```

| Option | Default | Description |
|--------|---------|-------------|
| `apiKey` | — | API key (overrides env var) |
| `similarityThreshold` | `0.6` | Minimum match score for recall (0–1) |
| `maxMemories` | `5` | Max memories injected per prompt |
| `maxProfileItems` | `5` | Max profile facts injected per prompt |
| `injectProfile` | `true` | Include user profile in context |
| `containerTagPrefix` | `"codex"` | Prefix for container tags |
| `debug` | `false` | Write debug logs to `~/.codex-supermemory.log` |


## Logging

Enable debug logging to trace hook activity:

```bash
export SUPERMEMORY_DEBUG=true
tail -f ~/.codex-supermemory.log
```

## Next Steps

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/supermemoryai/codex-supermemory">
    Source code, issues, and detailed README.
  </Card>

  <Card title="Claude Code Plugin" icon="code" href="/integrations/claude-code">
    Memory plugin for Claude Code.
  </Card>
</CardGroup>