OpenAI Codex

codex-supermemory — persistent memory for OpenAI Codex CLI

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 incrementally during the 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.

Install the Plugin

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:

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.

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:

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

npx codex-supermemory status

Uninstall

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:

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

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.