claude-supermemory
Persistent memory for Claude Code, powered by Supermemory
Conceptual overview. Some command names in the image predate the current plugin; see Commands for what's available now.
A Claude Code plugin that gives your agent persistent memory across sessions using Supermemory. Your agent remembers what you worked on, across sessions and across projects.
Install · Features · How it works · Shared containers · Configuration · Commands · Privacy
Installation
Requires Node.js 18+ on your PATH. The memory hooks run as Node scripts.
/plugin marketplace add supermemoryai/claude-supermemory
/plugin install supermemory
Set your API key (get one at console.supermemory.ai), or just start a session and let browser login handle it:
export SUPERMEMORY_CC_API_KEY="sm_..."
Migrating from the old claude-supermemory plugin
That plugin was renamed to supermemory, so it won't update in place. Migrate with:
/plugin marketplace update supermemory-plugins
/plugin install supermemory@supermemory-plugins
Then, only if you still have the old plugin installed, remove it:
/plugin uninstall claude-supermemory@supermemory-plugins
Features
| 🧠 Direct recall | |
| When authenticated, the hook searches substantive prompts before Claude sees them and injects fresh matches. No permission prompt or MCP tool call. | 🔎 Hosted MCP tools |
search_memory, listSpaces, whoAmI, and more are available through the same credentials as the hooks, auto-approved when read-only. |
|
| 💾 Auto capture | |
| At the end of a session, the Stop hook saves new conversation content in the background. It asks Supermemory to retain durable context rather than transient Git state. | 🏷️ Shared repo memory |
Automatic captures use the repository container shared with Codex and OpenCode and carry sm_scope: personal metadata. |
|
| 🧭 Deep multi-container search | |
The context-gatherer subagent fans out several searches across a project's containers and returns a synthesized brief. |
⚙️ Project config |
Per-repo settings, API keys, and container tag overrides via .claude/.supermemory-claude/config.json. |
|
| 🗂️ Codebase index | |
/supermemory:index saves architecture, conventions, and how to run into this project's container. |
👋 Session context |
| Loads profile facts at session start and shows a welcome-back notice when you return to a project after 6+ hours. |
- Recall strip — On Claude Code 2.1.287+ in the terminal, press the changing memory headline above the prompt to browse the full returned facts one at a time
On Claude Code 2.1.250, local marketplace install/update and the SessionStart and UserPromptSubmit command hooks were verified, but claude plugin validate rejects the recall mod's classic.SessionStart event. The strip is not available on that version; other older versions and install sources have not been verified.
How it works
Claude Code supports hooks and MCP servers. supermemory registers four hooks, in lifecycle order:
SessionStart → UserPromptSubmit → PreToolUse → Stop
| Step | Hook | Event | What it does |
|---|---|---|---|
| 1 | session-start |
SessionStart |
Bootstraps auth and loads profile context plus a welcome-back notice. It does not install a statusline; an old auto-installed one is removed. |
| 2 | recall-directive |
UserPromptSubmit |
Searches Supermemory directly with the prompt and injects fresh matches, deduplicated within the session. |
| 3 | recall-approve |
PreToolUse |
Auto-allows read-only Supermemory MCP tools; writes still ask for permission. |
| 4 | capture |
Stop |
Saves the completed conversation delta in the background. |
By default, recall is performed by the hook itself, not delegated to the model. It searches
substantive prompts when authenticated, without waiting for Claude to choose a tool call.
Setting recallDirective switches to advisory mode: the hook stops searching and instead
tells Claude when it should decide to search on its own.
The hooks are tolerant: if Supermemory is unreachable, the API key is missing, or anything else fails, they exit cleanly without breaking your Claude Code session. A capture that fails is reported the next time a session starts.
Shared Agents memory
Claude Code, Codex, and OpenCode all generate the same container tag for a given repository, so new memories are shared:
repo___ default container for capture and MCP memory tools
sm_scope: personal metadata on automatic captures
The hash is derived 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. Set SUPERMEMORY_ISOLATE_WORKTREES=true to use the worktree
path instead of the remote identity.
Unlike Codex, this plugin does not read older per-tool legacy containers
(codex_user_*, opencode_project_*, and similar); it only ever uses the single
unified tag above, generated fresh or overridden via repoContainerTag /
SUPERMEMORY_REPO_TAG.
Configuration
Environment variables
| Variable | Purpose |
|---|---|
SUPERMEMORY_CC_API_KEY |
Your Supermemory API key (browser auth is preferred). |
SUPERMEMORY_API_URL |
Override the Supermemory API base URL. |
SUPERMEMORY_MCP_URL |
Override the hosted MCP endpoint (default https://mcp.supermemory.ai/mcp). |
SUPERMEMORY_AUTH_URL |
Override the browser-auth base URL. |
SUPERMEMORY_REPO_TAG |
Project-container override, used only when project config has no repoContainerTag. |
SUPERMEMORY_ISOLATE_WORKTREES |
Set to true to key the project container on the worktree path instead of the Git remote. |
SUPERMEMORY_DEBUG |
Set to true to enable debug logging. |
Global settings (~/.supermemory-claude/settings.json)
{
"maxProfileItems": 5,
"signalExtraction": true,
"signalKeywords": ["remember", "architecture", "decision", "bug", "fix"],
"signalTurnsBefore": 3,
"includeTools": ["Edit", "Write"]
}
| Option | Description |
|---|---|
maxProfileItems |
Max memories in context (default: 5). |
recallDirective |
Set to switch prompt recall from direct hook search to an advisory instruction Claude reasons over. |
signalExtraction |
Only capture important turns (default: false). |
signalKeywords |
Keywords that trigger capture. |
signalTurnsBefore |
Context turns before signal (default: 3). |
includeTools |
Tool calls to explicitly capture. |
debug |
Enable debug logging (default: false). |
Project config (.claude/.supermemory-claude/config.json)
Per-repo overrides, created manually or via the settings your team shares:
{
"apiKey": "sm_...",
"baseUrl": "https://api.supermemory.ai",
"repoContainerTag": "my-team-project",
"signalExtraction": true
}
| Option | Description |
|---|---|
apiKey |
Project-specific API key. |
baseUrl |
Supermemory API URL. |
repoContainerTag |
Override the unified project container tag. Checked before SUPERMEMORY_REPO_TAG. |
Commands
| Command | Description |
|---|---|
/supermemory:index |
Index this repo's architecture, conventions, and how to run into the project container. |
/supermemory:status |
Show authentication status, API and MCP reachability, and the active project container. |
Search does not have its own command. With a key, the prompt hook searches
substantive prompts. For deeper history, use the context-gatherer agent or
the MCP tools. /supermemory:index saves codebase structure. For a one-off
save, ask Claude to use the add_memory MCP tool. Without containerTag,
the proxy defaults it to this repository's container; pass a different tag
to select another space. Conversation turns are saved when a session ends.
Privacy
For information about how Supermemory collects, uses, and retains data, see the Supermemory Privacy Policy.
License
MIT
◪ is the supermemory mark. Whenever you see it (the recall strip, notices, or Claude's answers), that information came from supermemory.