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

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

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

<Tip>
**Prefer to keep everything on your machine?** This plugin works with [self-hosted Supermemory](/self-hosting/overview) — run `npx supermemory local`, then `export SUPERMEMORY_API_URL="http://localhost:6767"` (or set `baseUrl` in `~/.codex/supermemory.json`) and use the API key printed on first boot.
</Tip>

## Install the Plugin

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

This command:

- Copies hook and skill scripts to `~/.codex/supermemory/`
- Enables `codex_hooks` in `~/.codex/config.toml`
- Registers `UserPromptSubmit` (recall) and `Stop` (flush) hooks in `~/.codex/hooks.json`
- Installs explicit memory skills under `~/.codex/skills/`

Restart Codex CLI after installing.

## Authenticate

**Browser auth is preferred.** Start Codex CLI — on your first prompt a browser window opens to authenticate with Supermemory.

Alternatively:

- Use `$supermemory-login` / `/supermemory-login` inside Codex
- Or set an API key from [API Keys](https://console.supermemory.ai/keys):

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

## How It Works

Once installed, the plugin runs on every Codex session:

| Hook | Event | What it does |
|------|-------|--------------|
| `recall` | `UserPromptSubmit` | Captures new turns (every N prompts), searches Supermemory, injects memories + profile as `additionalContext` |
| `flush` | `Stop` | Captures any remaining turns at session end so nothing is lost |

- **Incremental capture** — Memories are saved every N turns (default: 3) so mid-session context is available for later prompts in the same session.
- **Privacy** — Content wrapped in `<private>...</private>` is redacted before storage.

### Memory Scopes

| Tag | Derived from | Description |
|-----|-------------|-------------|
| User | `git config user.email` (hashed) | Preferences and workflows across projects |
| Project | Git common directory (hashed) | Repo-scoped knowledge (worktrees share by default) |

Override tags in `~/.codex/supermemory.json` if needed:

```json
{
  "userContainerTag": "my-custom-user-tag",
  "projectContainerTag": "my-custom-project-tag"
}
```

Set `SUPERMEMORY_ISOLATE_WORKTREES=true` to keep each worktree isolated.

## Explicit Memory Skills

| Skill | Description |
|-------|-------------|
| `supermemory-search` | Search memories by natural-language query |
| `supermemory-save` | Save important project knowledge |
| `supermemory-forget` | Remove outdated or incorrect memories |
| `supermemory-profile` | Show remembered profile facts |
| `supermemory-status` | Check connection, hooks, config, and skills |
| `supermemory-login` | Re-authenticate with Supermemory |
| `supermemory-logout` | Remove saved local credentials |

Example prompts:

```
> 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.
> Is Supermemory connected?
```

## Verify Installation

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

## Uninstall

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

This removes hook registrations and skill scripts. Your existing memories in Supermemory are preserved.

## Configuration

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

```json
{
  "apiKey": "sm_...",
  "baseUrl": "https://api.supermemory.ai",
  "similarityThreshold": 0.6,
  "maxMemories": 5,
  "maxProfileItems": 5,
  "injectProfile": true,
  "containerTagPrefix": "codex",
  "autoSaveEveryTurns": 3,
  "signalExtraction": false,
  "debug": false
}
```

| Option | Default | Description |
|--------|---------|-------------|
| `apiKey` | — | API key (env / browser auth preferred) |
| `baseUrl` | `https://api.supermemory.ai` | API base URL (`SUPERMEMORY_API_URL` overrides) |
| `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 auto-generated container tags |
| `autoSaveEveryTurns` | `3` | Save memories every N turns |
| `signalExtraction` | `false` | Only capture turns with signal keywords |
| `debug` | `false` | Write debug logs to `~/.codex-supermemory.log` |

## Logging

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

## Next Steps

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="/images/github-icon.svg" 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>