codex-supermemory
Persistent memory for OpenAI Codex CLI — powered by Supermemory
Codex forgets every session. codex-supermemory wires Supermemory into Codex CLI's
hooks system so your coding agent remembers your stack, preferences, prior decisions,
and the lessons learned across every project — automatically.
Features
- 🧠 Automatic recall — relevant memories are injected for substantive prompts via
the
UserPromptSubmithook, with visible recall counts and a 3-second network cap. - 🔎 Hosted MCP tools — deeper search and explicit memory operations use
mcp.supermemory.aithrough the same credentials as the hooks. - 💾 Automatic capture — completed turns are saved in the background via the
Stophook. - 🏷️ Shared Agents scoping — Codex, Claude Code, and OpenCode use one collision-safe repository container.
- 🏷️ Personal + project routing —
sm_scopemetadata keeps automatic/personal memories distinguishable from explicit project knowledge in the shared container. - Entity-aware extraction - the shared container uses one coding-agent context covering durable preferences and project/codebase facts.
- 🔒 Privacy-aware — anything wrapped in
<private>...</private>is redacted before being sent to Supermemory. - ⚡ Zero-config install — one command sets up
~/.codex/config.tomland~/.codex/hooks.jsonfor you. - 🪶 No runtime deps in hooks — the hook scripts are pre-bundled with esbuild for fast cold starts.
- 🔧 Focused status skill —
$supermemory-statuschecks authentication and connectivity; memory operations come from MCP instead of separate command skills. - ◪ Persistent CLI mark — compatible Codex terminals keep a quiet Supermemory badge at the bottom of the TUI, while hook notices report live recall and save activity.
Quick start
-
Install the hooks:
npx codex-supermemory install -
Start Codex CLI. On your first prompt, a browser window will open to authenticate with Supermemory automatically.
Alternatively, set
export SUPERMEMORY_CODEX_API_KEY="sm_..."in your shell profile. -
That's it — memory is active.
How it works
Codex CLI supports hooks and MCP servers. codex-supermemory registers four hooks:
| Hook | Event | What it does |
|---|---|---|
recall | UserPromptSubmit | Searches Supermemory directly, injects fresh relevant memories, and prints ◪ supermemory · recalled …. |
recall-approve | PreToolUse | Prints the MCP search query and auto-allows read-only Supermemory tools. |
flush | Stop | Captures completed turns in the background. |
session-start | SessionStart | Loads persistent and recent profile context for the session. |
Prompt recall and automatic capture call the Supermemory API directly. Deeper model-initiated search, add, list, and forget operations go through the hosted MCP server.
The installer:
- Registers the
supermemoryMCP server in~/.codex/config.toml - Registers the hooks in
~/.codex/hooks.json - Copies pre-bundled hook scripts to
~/.codex/supermemory/ - Installs only the
supermemory-statusskill to~/.codex/skills/ - Installs a static custom TUI badge to
~/.codex/pets/supermemory/
The installer selects the badge only when no Codex pet preference already exists. Terminals
without a supported inline-image protocol may not render it; recall and capture continue to work.
Use Codex's /pet picker to disable or change the persistent badge.
The hooks are tolerant: if Supermemory is unreachable, the API key is missing, or anything else fails, they exit cleanly without breaking your Codex session.
Shared Agents containers
Codex, Claude Code, and OpenCode use one container for a repository:
repo_<project-name>__<remote-hash>stores automatic capture and every explicit save.sm_scopemetadata preserves optional personal/project filtering.
The hash comes from the normalized Git remote, so clones share memory while
same-named repositories do not collide. Repositories without a remote fall back to
a local path identity. Codex also reads the previous user_project_*,
repo_<project-name>, codex_user_*, codex_project_*,
claudecode_project_*, opencode_user_*, and opencode_project_*
containers, so existing memories remain searchable without duplicating or
migrating them. Set SUPERMEMORY_ISOLATE_WORKTREES=true to use the worktree
path instead of the remote identity.
Explicit projectContainerTag/repoContainerTag overrides remain the canonical
write destination. Older user/personal overrides remain in the legacy read set.
Configuration
Environment variables
| Variable | Purpose |
|---|---|
SUPERMEMORY_CODEX_API_KEY | Your Supermemory API key (browser auth is preferred). |
SUPERMEMORY_API_URL | Override the Supermemory API base URL (takes precedence over config). |
SUPERMEMORY_DEBUG | Set to any truthy value to enable debug logging to ~/.codex-supermemory.log. |
~/.codex/supermemory.json (optional)
Drop this file in to override defaults:
| Key | Type | Default | Description |
|---|---|---|---|
apiKey | string | — | API key (env var takes precedence, browser auth is preferred). |
baseUrl | string | https://api.supermemory.ai | Supermemory API base URL (SUPERMEMORY_API_URL/SUPERMEMORY_BASE_URL env vars take precedence). |
similarityThreshold | number | 0.6 | Minimum similarity score for retrieved memories. |
maxMemories | number | 5 | Max memories injected per prompt. |
maxProfileItems | number | 5 | Max profile items considered from each persistent/recent section. |
injectProfile | boolean | true | Whether to fetch and inject the user profile. |
containerTagPrefix | string | "codex" | Legacy prefix retained when reading containers created by older versions. |
userContainerTag | string | auto | Legacy personal container retained for backward-compatible reads. |
projectContainerTag | string | auto (per-repo) | Explicit unified project-container override, also honored by Claude Code. |
filterPrompt | string | (sensible) | Filter prompt used by Supermemory's stateful filter. |
debug | boolean | false | Enable debug logging. |
recallMode | "direct" | "off" | "advisory" | "direct" | Directly retrieve relevant memory, disable prompt recall, or inject an advisory directive. |
recallDirective | string | (sensible) | Context injected when recallMode is "advisory". |
autoRecallEveryPrompt | boolean | — | Deprecated compatibility key; true maps to direct and false maps to off. |
autoSaveEveryTurns | number | 3 | Deprecated compatibility setting; completed turns are captured by Stop. |
signalExtraction | boolean | false | Enable signal-based filtering (only capture turns with keywords like "prefer", "decided"). |
signalKeywords | string[] | (defaults) | Keywords that trigger signal extraction. |
signalTurnsBefore | number | 3 | Include N turns before a signal for context. |
Project tags combine the sanitized repository name with a normalized Git-remote hash. Linked worktrees and clones of the same remote therefore share one container; same-named repositories with different remotes do not collide. Without a remote, the Git common directory is used as the fallback identity.
Entity context
Codex sends one shared coding-agent entityContext whenever it saves memories. It
covers durable preferences, workflows, architecture, conventions, setup, decisions,
and implementation lessons without one save type overwriting another container-level
context.
Signal extraction (optional)
When signalExtraction is enabled, only conversation turns containing signal keywords
(like "prefer", "decided", "remember", "bug", "fix") are captured. This reduces noise
but may miss some context. Disabled by default — all turns are captured.
Commands
npx codex-supermemory install # set up hooks + MCP + status skill
npx codex-supermemory uninstall # remove hooks + config (keeps your memories)
npx codex-supermemory status # show current install statusStatus
Run $supermemory-status inside Codex to check the saved credential, API reachability,
active project container, and account details. Browser authentication is automatic on
SessionStart; there is no separate login skill.
Privacy
Anything wrapped in <private>...</private> is replaced with [REDACTED] before
being sent to Supermemory. Use this for secrets, tokens, or anything you'd rather
not have stored.
License
MIT