mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-05-19 07:42:43 +00:00
75e7b7d34a
Adds apps/docs/integrations/codex.mdx with installation, configuration, and usage docs for the codex-supermemory plugin. Also registers the page in docs.json under the Plugins tab alongside openclaw, claude-code, and opencode.
141 lines
4.1 KiB
Text
141 lines
4.1 KiB
Text
---
|
||
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 its hooks system. Your agent automatically recalls relevant context before each prompt and captures the conversation after each session — no slash commands required.
|
||
|
||
## 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 to `~/.codex/supermemory/`
|
||
- Enables `codex_hooks = true` in `~/.codex/config.toml`
|
||
- Registers `UserPromptSubmit` (recall) and `Stop` (capture) hooks in `~/.codex/hooks.json`
|
||
|
||
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 |
|
||
|
||
## 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: ✓ exists
|
||
|
||
All good! Memory is active.
|
||
```
|
||
|
||
## Uninstall
|
||
|
||
```bash
|
||
npx codex-supermemory uninstall
|
||
```
|
||
|
||
This removes the hook registrations from `~/.codex/hooks.json` and disables `codex_hooks` 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>
|