Skip to main content
Claude Code + Supermemory supermemory is a Claude Code plugin that gives your AI persistent memory across sessions. Your agent remembers what you worked on — across sessions, across projects.
Prefer to keep everything on your machine? This plugin works with self-hosted Supermemory — run npx supermemory local, then set baseUrl in project config (or point your install at your local API) and use the API key printed on first boot.

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:

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 recallDirective to 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: personal metadata.
  • 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 the context-gatherer agent.
  • 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.