
Install the plugin
Requires Node.js 18+ on your PATH — the memory hooks run as Node scripts.
Migrating from the old
claude-supermemory plugin name? It was renamed to supermemory and will not update in place:Authenticate
Start a Claude Code session and the plugin opens a browser login, then saves the key to~/.supermemory-claude/credentials.json.
Or create a Supermemory API key from the API Keys page in the console and add it to your shell profile:
- macOS / Linux (zsh)
- macOS / Linux (bash)
- Windows (PowerShell)
How it works
Once installed, the plugin runs automatically:- Session context — At session start, profile facts for this project are loaded into context.
- Direct recall — Before Claude sees each substantive prompt, the hook searches Supermemory and injects fresh matches. Set
recallDirectiveto switch to advisory mode, where Claude decides when to search. - Auto-capture — After each Claude response (the Stop hook), conversation content added since the last save is captured in the background.
- Shared repo memory — Captures go to one repository container shared with the Codex, OpenCode, and Cursor plugins, tagged with
sm_scope: personalmetadata. - MCP tools — The hosted Supermemory MCP tools (
search_memory,add_memory, and more) use the same credentials. They follow your Claude Code permission settings, so Claude asks before using one unless you’ve allowed it. For deeper history, Claude can also use thecontext-gathereragent. - Skipped sessions — Print-mode runs (
claude -p), GitHub Action runs, and turns that relay a background subagent’s result make no Supermemory calls by default. Conductor and Vibe Kanban sessions are treated as interactive.
Commands
Configuration
Environment variables
Global settings
Create~/.supermemory-claude/settings.json:
Each of the last five options can also be set with an environment variable,
SUPERMEMORY_CAPTURE_SUBAGENTS, SUPERMEMORY_CAPTURE_HEADLESS, SUPERMEMORY_CAPTURE_ORCHESTRATED, SUPERMEMORY_DEDUPE_OPENING_PROMPT or SUPERMEMORY_DEDUPE_RECALL_QUERIES. Set it to true or false; it takes priority over settings.json.
Project config
Per-repo overrides in.claude/.supermemory-claude/config.json. Create the file manually:
API key precedence is
SUPERMEMORY_CC_API_KEY, project apiKey, then ~/.supermemory-claude/credentials.json.
Next steps
GitHub repository
Source code, issues, and detailed README.
Cursor plugin
Memory for your Cursor chats.