Claude-Supermemory
PluginSupermemory's official Claude Code plugin: hooks save memories automatically when a session ends and recall them on demand, giving persistent memory across sessions and projects, with shared project memory for teams. Needs a Supermemory API key and Node.js 18+.
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 toolssearch_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_<project-name>__<remote-hash> 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
Automatic capture sends new conversation content to Supermemory, including tool
content when configured. Before saving, an offline filter replaces common
credential-shaped values (provider tokens, credential assignments, private keys,
Bearer tokens, and URL credentials) with explicit [REDACTED:…] markers while
keeping surrounding context. It cannot detect every secret. Existing stored
memories and local transcripts are not rewritten; explicit MCP tool calls and
recall queries are not filtered by this capture-only protection.
For information about how Supermemory collects, uses, and retains data, see the Supermemory Privacy Policy.
License
MIT
関連リソース
Beads
PluginGraph-based task tracking and memory for coding agents: a dependency graph replaces Markdown plans, agents claim ready work with bd ready and keep context across sessions. The plugin injects workflow instructions through hooks. Requires the bd CLI.
gastownhall/beads27.9k
Planning with Files
PluginManus-style file-based planning: writes the plan, findings and progress to three Markdown files and injects them into context each turn via hooks, so the agent resumes from the current phase after /clear, compaction or a crash. Supports Claude Code, Codex and many other agents.
OthmanAdi/planning-with-files27.5k
ECC
PluginA complete harness for coding agents: dozens of subagents, nearly 300 skills, hooks, rules, memory and continuous learning, plus the AgentShield security scanner. Built mainly for Claude Code, with Codex support.
affaan-m/ECC281k
Claude-Mem
PluginPersistent memory across sessions: hooks record tool calls and generate semantic summaries, then inject relevant context into new sessions, with history search and a web viewer. The hosted memory service needs sign-in, or use your own Anthropic plan or model key.
thedotmack/claude-mem101k
CLAUDE.md Management
PluginAudits whether CLAUDE.md matches the current codebase and scores its quality, and /revise-claude-md writes lessons from the current session back into project memory. Official Anthropic plugin.
anthropics/claude-plugins-official40.1k
Context Mode
PluginProcesses large tool outputs in a sandbox and returns only the results to context; logs session events in SQLite with FTS5 so work continues after context compaction. Supports Claude Code, Codex and a dozen other clients. ELv2 licensed.
mksglu/context-mode30.1k