> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory-vorflux-slack-workspace-override-consent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Codex

> codex-supermemory — persistent memory for OpenAI Codex CLI

[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 theme={null}
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 theme={null}
    echo 'export SUPERMEMORY_CODEX_API_KEY="sm_..."' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Tab>

  <Tab title="macOS / Linux (bash)">
    ```bash theme={null}
    echo 'export SUPERMEMORY_CODEX_API_KEY="sm_..."' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    [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 theme={null}
{
  "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 theme={null}
npx codex-supermemory status
```

## Uninstall

```bash theme={null}
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 theme={null}
{
  "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 theme={null}
export SUPERMEMORY_DEBUG=true
tail -f ~/.codex-supermemory.log
```

## Next Steps

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="https://mintlify.s3.us-west-1.amazonaws.com/supermemory-vorflux-slack-workspace-override-consent/docs/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>