Star 历史趋势
数据来源: GitHub API · 生成自 Stargazers.cn
README.md

claude-supermemory

Persistent memory for Claude Code, powered by Supermemory

version license

Conceptual overview of Claude Code and 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.


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, subject to your Claude Code permissions.
💾 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

StepHookEventWhat it does
1session-startSessionStartBootstraps auth and loads profile context plus a welcome-back notice. It does not install a statusline; an old auto-installed one is removed.
2recall-directiveUserPromptSubmitSearches Supermemory directly with the prompt and injects fresh matches, deduplicated within the session.
3recall-approvePreToolUseDisplays read-only Supermemory activity without approving calls or changing their input.
4captureStopSaves 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.

Directory review and permissions

MCP tool calls follow your Claude Code permission rules. The PreToolUse hook only displays recall activity and records search counts; it does not approve calls or change their input. The index and status commands do not grant blanket shell access. Direct recall and capture still run as the lifecycle hooks you enabled when installing the plugin.

The MCP declaration passes https://mcp.supermemory.ai/mcp literally to the bundled proxy as its default endpoint. The proxy uses that argument for the standard hosted configuration, shares the hooks' authentication, and supplies the current repository's default container. Existing SUPERMEMORY_MCP_URL, custom API backend settings, API keys, stored credentials, and OAuth refresh remain supported. Running the proxy without the argument retains its previous endpoint resolution.

The optional recall-strip mod observes classic.SessionStart and classic.UserPromptSubmit. It calls next(e) with the original event, reads returned memory facts for its terminal display, and returns the same result object. It does not replace the first user message, edit permission settings, register agents, or alter tool inputs. Its ui.render hook adds the expandable recall strip above the terminal prompt. The Directory's static policy check may still require a reviewer to confirm this pass-through behavior.

The credential-related review holds require review of the existing Supermemory sign-in flow, not a replacement of users' keys. Credentials are used for the configured Supermemory API and MCP endpoints. No new user_config credential flow is introduced by this change. Directory acceptance and publisher ownership must be confirmed in the submission portal; local validation is not approval.

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. Linked worktrees (git worktree add, Conductor, Claude Squad, claude --worktree) resolve to the main checkout's identity, with or without a remote. 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 identity above, overridden via the project namespace setting or the compatible repoContainerTag / SUPERMEMORY_REPO_TAG settings.

Which sessions are remembered

By default the hooks make no Supermemory calls (no profile, no prompt recall, no capture) for sessions nobody is typing into. They decide this only from signals Claude Code sets:

SessionSignalOpt back in
Background subagent results relayed to the main sessionthe <task-notification> turn (origin.kind: "task-notification" in the transcript; scheduled fires and inbox messages still count as yours)captureSubagents: true / SUPERMEMORY_CAPTURE_SUBAGENTS=true
claude -p and GitHub Action runsCLAUDE_CODE_ENTRYPOINT is claude-code-github-action, or sdk-cli while that Claude Code process is itself in print mode (CLAUDE_CODE_SESSION_ATTENDED=0, or -p / --print / --output-format on older builds)captureHeadless: true / SUPERMEMORY_CAPTURE_HEADLESS=true

Subagents never run these hooks: Claude Code fires only SubagentStart and SubagentStop inside them, so their work reaches memory only through the main session. Claude Code's own helper prompts (session titles, prompt suggestions, the auto mode classifier) never run these hooks either.

An interactive claude that merely inherited CLAUDE_CODE_ENTRYPOINT=sdk-cli (for example one started from a shell a claude -p run spawned) stays on. Agent SDK apps (sdk-ts, sdk-py), including editors such as Zed that drive Claude Code over ACP, are treated as interactive and keep recall and capture. To keep an SDK app out of memory, run it without this plugin: leave "user" out of the SDK's settingSources, or disable the plugin for that app.

Sessions started by Conductor or Vibe Kanban (CONDUCTOR_WORKSPACE_PATH, CONDUCTOR_SESSION_ID or VK_WORKSPACE_ID set) are real user work and stay on even though they run through claude -p; set captureOrchestrated: false or SUPERMEMORY_CAPTURE_ORCHESTRATED=false to turn them off. Crystal sets no such variable, so its claude -p sessions count as headless.

For swarms that replay one task across many sessions, two local indexes in ~/.supermemory-claude (hashes only) cut repeats:

  • Opening prompt: a session whose opening prompt (at least 200 characters) was already captured from this machine for the same container in the last 24 hours saves the session with a one-line [opening prompt already captured from this machine: <hash>] marker in place of the prompt. Opt out with dedupeOpeningPrompt: false / SUPERMEMORY_DEDUPE_OPENING_PROMPT=false.
  • Recall query: when the exact same query (whitespace-normalized) was recalled successfully by another session for the same container in the last 10 minutes, the hook re-serves that result from recall-cache.json instead of calling the API. A failed or timed-out search is never cached. Opt out with dedupeRecallQueries: false / SUPERMEMORY_DEDUPE_RECALL_QUERIES=false.

Configuration

Environment variables

VariablePurpose
SUPERMEMORY_CC_API_KEYYour Supermemory API key (browser auth is preferred).
SUPERMEMORY_API_URLOverride the Supermemory REST base URL; custom URLs default to legacy compatibility.
SUPERMEMORY_MCP_URLOverride the hosted MCP endpoint (default https://mcp.supermemory.ai/mcp).
SUPERMEMORY_AUTH_URLOverride the browser-auth base URL.
SUPERMEMORY_REPO_TAGProject-scope override; used when no project scope setting is set.
SUPERMEMORY_ISOLATE_WORKTREESSet to true to key the project container on the worktree path instead of the Git remote.
SUPERMEMORY_DEBUGSet to true to enable debug logging.
SUPERMEMORY_CAPTURE_SUBAGENTStrue/1/yes/on or false/0/no/off; overrides captureSubagents.
SUPERMEMORY_CAPTURE_HEADLESStrue/1/yes/on or false/0/no/off; overrides captureHeadless.
SUPERMEMORY_CAPTURE_ORCHESTRATEDtrue/1/yes/on or false/0/no/off; overrides captureOrchestrated.
SUPERMEMORY_DEDUPE_OPENING_PROMPTtrue/1/yes/on or false/0/no/off; overrides dedupeOpeningPrompt.
SUPERMEMORY_DEDUPE_RECALL_QUERIEStrue/1/yes/on or false/0/no/off; overrides dedupeRecallQueries.

Global settings (~/.supermemory-claude/settings.json)

{
  "maxProfileItems": 5,
  "signalExtraction": true,
  "signalKeywords": ["remember", "architecture", "decision", "bug", "fix"],
  "signalTurnsBefore": 3,
  "includeTools": ["Edit", "Write"]
}
OptionDescription
maxProfileItemsMax memories in context (default: 5).
recallDirectiveSet to switch prompt recall from direct hook search to an advisory instruction Claude reasons over.
signalExtractionOnly capture important turns (default: false).
signalKeywordsKeywords that trigger capture.
signalTurnsBeforeContext turns before signal (default: 3).
includeToolsTool calls to explicitly capture.
debugEnable debug logging (default: false).
captureSubagentsRecall and capture for relayed background-subagent results (default: false).
captureHeadlessRecall and capture for claude -p and GitHub Action runs (default: false).
captureOrchestratedRecall and capture for Conductor and Vibe Kanban sessions (default: true).
dedupeOpeningPromptReplace an opening prompt of 200+ characters captured from this machine in the last 24 hours with a marker (default: true).
dedupeRecallQueriesRe-serve the cached result of the same query another session recalled in the last 10 minutes (default: true).

Project config (.claude/.supermemory-claude/config.json)

Per-repo overrides, created manually or via the settings your team shares:

API key precedence is SUPERMEMORY_CC_API_KEY, project apiKey, then ~/.supermemory-claude/credentials.json.

{
  "apiKey": "sm_...",
  "baseUrl": "https://api.supermemory.ai",
  "namespace": "my-team-project",
  "signalExtraction": true
}
OptionDescription
apiKeyProject-specific API key.
baseUrlSupermemory API URL.
namespaceCanonical project scope, preserving the exact old container-tag value.
repoContainerTagOverride the unified project container tag. Checked before SUPERMEMORY_REPO_TAG.

Advanced self-hosted compatibility

Hosted Supermemory uses v5 without a version choice. Existing custom REST URLs default to legacy, keeping v3 writes and v4 profiles for self-hosted servers older than 0.0.9. After upgrading the server, explicitly set SUPERMEMORY_API_VERSION=v5 or project apiVersion: "v5". The environment setting takes precedence; legacy is also an explicit rollback option for a server that still supports v3/v4. Invalid values fail closed for memory operations. There is no automatic version fallback after a failed request and no fallback to the hosted API. REST, MCP, and browser-auth URLs remain separate.

Scope precedence is project namespace, project repoContainerTag, SUPERMEMORY_REPO_TAG, then the generated identity. Keep an existing override's exact value when renaming its setting: changing the value selects another space, not a data migration. V5 scopes allow 1–100 letters, digits, underscores, hyphens, or colons; invalid scopes are rejected before any request without rewriting config or capture cursors.

Hosted Supermemory applies the same rule to legacy endpoints, so a scope with a dot, slash, or space must be renamed; the new value starts a new memory space. A self-hosted server that still accepts such a scope through v3/v4 can keep it with SUPERMEMORY_API_VERSION=legacy or project apiVersion: "legacy". There is no automatic switch or failed-write retry across protocols.

Commands

CommandDescription
/supermemory:indexIndex this repo's architecture, conventions, and how to run into the project container.
/supermemory:statusShow 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

Development runtime

Marketplace installations need only Node 18 or later, not npm install. plugin/hooks/vendor/supermemory.cjs is the committed runtime bundle built from the exact official SDK and esbuild versions in package-lock.json. Maintainers reproduce it with npm ci && npm run build:sdk; CI rejects a stale bundle. The SDK's Apache-2.0 license is included alongside the generated bundle.


◪ is the supermemory mark. Whenever you see it (the recall strip, notices, or Claude's answers), that information came from supermemory.

关于 About

Enable Claude Code to learn in real-time, update it's knowledge, and grow with you, using supermemory.

语言 Languages

JavaScript54.2%
HTML43.6%
TypeScript2.2%

提交活跃度 Commit Activity

代码提交热力图
过去 52 周的开发活跃度
242
Total Commits
峰值: 32次/周
Less
More

核心贡献者 Contributors