OpenAI Codex

codex-supermemory — persistent memory for OpenAI Codex CLI

This integration requires the Supermemory Pro plan. Upgrade here.

codex-supermemory wires Supermemory into the OpenAI Codex CLI 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.

Get Your API Key

Create a Supermemory API key from the API Keys page, then export it in your shell profile:

macOS / Linux (zsh)

echo 'export SUPERMEMORY_CODEX_API_KEY="sm_..."' >> ~/.zshrc
source ~/.zshrc

macOS / Linux (bash)

echo 'export SUPERMEMORY_CODEX_API_KEY="sm_..."' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell)

[System.Environment]::SetEnvironmentVariable("SUPERMEMORY_CODEX_API_KEY", "sm_...", "User")

Restart your terminal after running this.

Install the Plugin

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:

Tag	Format	Description
User	codex_user_{sha256}	Memories shared across all your projects
Project	codex_project_{sha256}	Memories scoped to the current working directory

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

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

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:

{
  "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:

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

Next Steps

GitHub Repository

Source code, issues, and detailed README.

Claude Code Plugin

Memory plugin for Claude Code.