OpenAI Codex

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.

Prefer to keep everything on your machine? This plugin works with self-hosted Supermemory — 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.

Get Your API Key

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

macOS / Linux (zsh)
macOS / Linux (bash)
Windows (PowerShell)

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

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

[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, supermemory-forget, and supermemory-status 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:

{
  "userContainerTag": "my-custom-user-tag",
  "projectContainerTag": "my-custom-project-tag"
}

Explicit Memory Skills

The installer includes four 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
`supermemory-status`	Check Supermemory connection, hook, config, and skill status

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.
> Is Supermemory connected?

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, supermemory-status)
  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

Get Your API Key

Install the Plugin

How It Works

Memory Scopes

Explicit Memory Skills

Verify Installation

Uninstall

Configuration

Logging

Next Steps

GitHub Repository

Claude Code Plugin

​Get Your API Key

​Install the Plugin

​How It Works

​Memory Scopes

​Explicit Memory Skills

​Verify Installation

​Uninstall

​Configuration

​Logging

​Next Steps

GitHub Repository

Claude Code Plugin

Get Your API Key

Install the Plugin

How It Works

Memory Scopes

Explicit Memory Skills

Verify Installation

Uninstall

Configuration

Logging

Next Steps