> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory-capy-add-llmstxt-summary-and.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

> Persistent memory for the OpenAI Codex CLI with the codex-supermemory plugin.

[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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    echo 'export SUPERMEMORY_CODEX_API_KEY="sm_..."' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Tab>

  <Tab title="macOS / Linux (bash)">
    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    echo 'export SUPERMEMORY_CODEX_API_KEY="sm_..."' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    [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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npx codex-supermemory status
```

## Uninstall

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
export SUPERMEMORY_DEBUG=true
tail -f ~/.codex-supermemory.log
```

## Next steps

<CardGroup cols={2}>
  <Card title="GitHub repository" icon="https://mintcdn.com/supermemory-capy-add-llmstxt-summary-and/RZUchfWXNk8FOiN_/images/github-icon.svg?fit=max&auto=format&n=RZUchfWXNk8FOiN_&q=85&s=997e915bbbc7ec5808a4cced93759dbc" href="https://github.com/supermemoryai/codex-supermemory" width="16" height="16" data-path="images/github-icon.svg">
    Source code, issues, and detailed README.
  </Card>

  <Card title="Cursor plugin" icon="https://mintcdn.com/supermemory-capy-add-llmstxt-summary-and/RZUchfWXNk8FOiN_/images/cursor-logo.svg?fit=max&auto=format&n=RZUchfWXNk8FOiN_&q=85&s=19113ff7ed218f8ac503f4891850e18d" href="/integrations/cursor" width="512" height="512" data-path="images/cursor-logo.svg">
    Memory for your Cursor chats.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.