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 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)
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.

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

Supermemory MCP

Plugins

Install the Plugin

Authenticate

How It Works

Memory Scopes

Explicit Memory Skills

Verify Installation

Uninstall

Configuration

Logging

Next Steps

GitHub Repository

Claude Code Plugin

​Install the Plugin

​Authenticate

​How It Works

​Memory Scopes

​Explicit Memory Skills

​Verify Installation

​Uninstall

​Configuration

​Logging

​Next Steps

GitHub Repository

Claude Code Plugin

Install the Plugin

Authenticate

How It Works

Memory Scopes

Explicit Memory Skills

Verify Installation

Uninstall

Configuration

Logging

Next Steps