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 into every prompt via the UserPromptSubmit hook.
• 💾 Automatic capture — conversations are stored incrementally (every N turns) and at session end via the Stop hook.
• 🏷️ Project + user scoping — memories are tagged per-project and per-user so context never leaks across repos.
• 🔒 Privacy-aware — anything wrapped in <private>...</private> is redacted before being sent to Supermemory.
• ⚡ Zero-config install — one command sets up ~/.codex/config.toml and ~/.codex/hooks.json for you.
• 🪶 No runtime deps in hooks — the hook scripts are pre-bundled with esbuild for fast cold starts.
• 🔧 Fallback skills — explicit /supermemory-search, /supermemory-save, and /supermemory-forget commands available when hooks don't cover your use case.

Quick start

1. Install the hooks:

   npx codex-supermemory install

2. Start Codex CLI. On your first prompt, a browser window will open to authenticate with Supermemory automatically.

   Alternatively, authenticate manually:

   • Use $supermemory-login inside Codex
   • Or set export SUPERMEMORY_CODEX_API_KEY="sm_..." in your shell profile

3. That's it — memory is active.

How it works

Codex CLI supports a hooks system that lets external scripts run at specific lifecycle events. codex-supermemory registers two hooks:

Hook	Event	What it does
recall	UserPromptSubmit	Captures new turns (every N prompts), then searches Supermemory for relevant memories and your profile, injecting them into the prompt as additionalContext.
flush	Stop	Captures any remaining turns at session end so the final conversation turns are never lost.

Incremental capture: Memories are saved every N turns (default: 3) during the session. This means memories from earlier in your session are immediately available for recall in the same session. The flush hook ensures any trailing turns are captured when the session ends.

The installer:

• Enables the codex_hooks feature flag in ~/.codex/config.toml
• Registers the hooks in ~/.codex/hooks.json
• Copies pre-bundled hook scripts to ~/.codex/supermemory/
• Installs skills to ~/.codex/skills/

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.

Configuration

Environment variables

Variable	Purpose
SUPERMEMORY_CODEX_API_KEY	Your Supermemory API key (browser auth is preferred).
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).
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.
injectProfile	boolean	true	Whether to fetch and inject the user profile.
containerTagPrefix	string	"codex"	Prefix for auto-generated container tags.
userContainerTag	string	auto	Override the user container tag.
projectContainerTag	string	auto (per-cwd)	Override the project container tag.
filterPrompt	string	(sensible)	Filter prompt used by Supermemory's stateful filter.
debug	boolean	false	Enable debug logging.
autoSaveEveryTurns	number	3	Save memories every N turns (incremental capture).
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.

User and project tags are auto-derived from your git config user.email and the current working directory (both hashed) when not explicitly set.

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 + config + skills
npx codex-supermemory uninstall   # remove hooks + config (keeps your memories)
npx codex-supermemory status      # show current install status

Skills (fallback commands)

These Codex skills are available as explicit commands when you need more control:

Skill	Usage	Description
/supermemory-search	/supermemory-search <query>	Search memories manually.
/supermemory-save	/supermemory-save <content>	Save a specific memory explicitly.
/supermemory-forget	/supermemory-forget <content>	Remove a memory.
/supermemory-login	/supermemory-login	Re-authenticate with Supermemory.

Skills are fallback commands — the hooks handle most use cases automatically.

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