> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory-claude-naughty-bhaskara-7bc56a.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 after each 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>

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

## Install the Plugin

```bash theme={null}
npx codex-supermemory@latest install
```

This command:

* Copies hook and skill scripts to `~/.codex/supermemory/`
* Enables `codex_hooks = true` in `~/.codex/config.toml`
* Registers `UserPromptSubmit` (recall) and `Stop` (capture) hooks in `~/.codex/hooks.json`
* Installs `supermemory-search`, `supermemory-save`, and `supermemory-forget` skills to `~/.codex/skills/`

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, auto-derived from your environment:

| Tag     | Derived from                       | Description                              |
| ------- | ---------------------------------- | ---------------------------------------- |
| User    | `git config user.email` (hashed)   | Memories shared across all your projects |
| Project | Current working directory (hashed) | Memories scoped to the current repo      |

Tags are generated automatically — no configuration needed. You can override them in `~/.codex/supermemory.json` if needed:

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

## Explicit Memory Skills

The installer includes three skills that Codex auto-discovers from `~/.codex/skills/`. They use the same `SUPERMEMORY_CODEX_API_KEY` as the hooks — no separate login needed.

| Skill                | Description                                    |
| -------------------- | ---------------------------------------------- |
| `supermemory-search` | Search your memories by natural-language query |
| `supermemory-save`   | Save important project knowledge to memory     |
| `supermemory-forget` | Remove outdated or incorrect memories          |

These skills let you interact with memory explicitly — for example:

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

```bash theme={null}
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 (implicit memory)
  Skills:        ✓ installed (supermemory-search, supermemory-save, supermemory-forget)
  config.toml:   ✓ exists

All good! Memory is active.
```

## Uninstall

```bash theme={null}
npx codex-supermemory uninstall
```

This removes the hook registrations and skill scripts from `~/.codex/supermemory/`, removes skill directories from `~/.codex/skills/`, and disables `codex_hooks` in `~/.codex/config.toml`. Your existing memories in Supermemory are preserved.

## Configuration

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

```json theme={null}
{
  "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 theme={null}
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>