# claude-supermemory: persistent memory for Claude Code, with a team container per repo

> The supermemory plugin for Claude Code captures sessions and recalls them on demand, keyed to a Git remote hash so teammates share one memory container. Here is how the install works, what the config controls, and where it stops being the right tool.

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

- Repository: https://github.com/supermemoryai/claude-supermemory
- Website: https://supermemory.ai/docs/integrations/claude-code
- Stars: 2,771 · Forks: 172
- Language: HTML
- License: not declared
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/supermemoryai-claude-supermemory

## What claude-supermemory solves, and for whom

Claude Code starts each session without the previous one. That is fine for a one-off script and painful for a repository you have been working in for weeks, where the useful context is the decision you made three sessions ago and the reason a file is structured the way it is. claude-supermemory is a Claude Code plugin that stores conversation material in Supermemory and pulls it back when a new message makes recall worthwhile. The README describes the goal plainly: your agent remembers what you worked on, across sessions and across projects.

The audience is narrower than "anyone using Claude Code". The plugin assumes a Supermemory account, since you need an API key from console.supermemory.ai. It assumes Node.js 18 or newer on your PATH, because the memory hooks run as Node scripts. And the team-memory feature assumes a Git remote on the repository you care about, which is the mechanism that lets two clones of the same project land in the same memory container. A solo developer on a throwaway directory gets capture and recall, but not the shared part.

## Reasoned recall and the container scheme behind shared memory

The README describes recall as reasoned rather than automatic on every turn. Before each turn, Claude decides whether searching memory would help the current message and only searches when it judges that it would, with the search running without a permission prompt. The README also notes the usage angle: searching only when needed keeps more usage on your plan. That is a design trade-off worth naming. A model deciding whether to look is cheaper than looking every time, but it also means the memory layer is only as good as that judgement call, and a turn where the model decides not to search will not surface a memory that existed.

The storage side is more concrete. Claude Code, Codex, and OpenCode share one container per repository, named repo_<project-name>__<remote-hash>. Automatic capture and every explicit save go there, and an sm_scope metadata field keeps personal and project memories filterable inside the same container. The hash comes from the normalized Git remote, so clones of one repository share memory while two different repositories with the same name do not collide. Repositories with no remote fall back to a local path identity, which means the same directory on two machines produces two containers. The plugin also reads a list of older container names (user_project_*, repo_<project-name>, claudecode_project_*, codex_user_*, codex_project_*, opencode_user_*, opencode_project_*), so existing memories stay searchable without a migration step. Setting SUPERMEMORY_ISOLATE_WORKTREES=true switches the identity to the worktree path instead of the remote, which is the escape hatch for parallel worktrees that should not share context.

## Installing the plugin and running a first index

Installation goes through the Claude Code plugin marketplace. The README requires Node.js 18 or newer on your PATH before any of this, since the hooks are Node scripts.

```bash
/plugin marketplace add supermemoryai/claude-supermemory
/plugin install supermemory
```

After the install, set the API key in your environment. The key comes from console.supermemory.ai and the README shows the sm_ prefix.

```bash
export SUPERMEMORY_CC_API_KEY="sm_..."
```

If you already had the older plugin under the name claude-supermemory, note that it was renamed to supermemory and will not update in place. The README gives the migration path, and it includes removing the old plugin only if it is still installed.

```bash
/plugin marketplace update supermemory-plugins
/plugin install supermemory@supermemory-plugins
/plugin uninstall claude-supermemory@supermemory-plugins
```

A reasonable first real use is indexing the current repository so later sessions have architecture context to recall. The command is /supermemory:index, described in the README as indexing codebase architecture and patterns. Run /supermemory:status first to confirm authentication, and /supermemory:session to get a clickable URL for the current session document in Supermemory, which is the quickest way to see that writes are actually landing.

## Global settings and per-repo config, and what they do not cover

Two configuration layers exist. Global settings live at ~/.supermemory-claude/settings.json, and the README shows a sample with maxProfileItems, signalExtraction, signalKeywords, signalTurnsBefore, and includeTools.

```json
{
  "maxProfileItems": 5,
  "signalExtraction": true,
  "signalKeywords": ["remember", "architecture", "decision", "bug", "fix"],
  "signalTurnsBefore": 3,
  "includeTools": ["Edit", "Write"]
}
```

maxProfileItems caps how many memories enter context and defaults to 5. signalExtraction defaults to false, which means capture is broad until you turn it on; when enabled, only turns matching signalKeywords or the includeTools list are captured, with signalTurnsBefore supplying context turns ahead of the signal. recallDirective is the unusual one: it lets you override the built-in instruction that tells Claude how to reason about recall. That is a real lever if the default judgement misfires on your workload, but it also means you are now maintaining a prompt, and the README does not document what the built-in text says.

Per-repo overrides go in .claude/.supermemory-claude/config.json, which you can create with /supermemory:project-config or by hand. It accepts apiKey, baseUrl, personalContainerTag, and repoContainerTag. The README states that explicit repoContainerTag or projectContainerTag overrides remain the canonical write destination, so an override changes where new memories are written, not just where they are read. The README does not document a rollback procedure for memories already stored, and it does not list a delete or purge command among the plugin commands.

## Where this is the wrong tool

The clearest boundary is data residency. The plugin sends conversation content to Supermemory's API at api.supermemory.ai by default, and the README's privacy section does not describe a local-only mode; it points at the Supermemory privacy policy for how data is collected, used, and retained. If your repository is under a policy that forbids conversation transcripts leaving your network, this plugin is not the tool, regardless of how well the recall works. The README does not document a self-hosted endpoint, though baseUrl is configurable per repository, so the question of whether a self-hosted deployment exists is answered by Supermemory's own documentation, not by this repository.

Second, the container identity depends on a Git remote. Repositories without one fall back to a local path identity, so the same project checked out at two paths produces two separate memory stores. That is a quiet failure: recall simply returns less than you expect, with no error. Third, the whole recall path depends on the model deciding to search. There is no documented way to force a search on every turn short of overriding recallDirective. Fourth, the project is small and its release history is thin: the only release listed is v0.0.2 from 2026-02-09, while the last push to the repository was on 2026-09-17. The README does not document a versioning or compatibility policy for the plugin.

## How it differs from Claude-mem and from a plain CLAUDE.md

The obvious alternative is Claude-mem, which people compare it against directly. The difference in approach is where memory lives and who can read it. claude-supermemory writes to a hosted Supermemory account and organizes memories into containers keyed by the normalized Git remote, with an sm_scope field separating personal from project entries inside one container. That structure is what makes team sharing work: a teammate cloning the same remote reads the same container. A file-based approach such as a CLAUDE.md or a local notes directory keeps everything in the repository, which means it travels with the code, needs no API key, and cannot leak through a third-party service. It also means nothing is captured automatically, the file grows until someone prunes it, and there is no search step that decides what is relevant.

The interop detail is worth noting because it cuts against the usual plugin-lock-in story. The README states that Claude Code, Codex, and OpenCode use one container per repository and that the plugin reads the older container names from all three, so switching between those agents does not orphan what you already stored. That is a deliberate choice, and it is the strongest argument in the README for this project over a single-agent memory file.

## Conclusion

Adopt it if your work happens in Claude Code and you want session context to survive across restarts without building your own store. Skip it if you cannot send conversation data to a hosted API, or if you need a documented rollback path: the README covers installation and migration, not removal of stored memories. Before installing, confirm Node.js 18 or newer is on your PATH, since the hooks are Node scripts, and check whether your repository has a Git remote, because containers without one are keyed by local path instead of a shared remote hash.

## FAQ

### How does Supermemory AI work with the claude-supermemory plugin?

The plugin stores automatic capture and explicit saves in a Supermemory container named repo_<project-name>__<remote-hash>, derived from the normalized Git remote. Before each turn, Claude decides whether a memory search would help and searches only when it judges that it would.

### Can Supermemory AI be self-hosted?

The README does not document a self-hosted deployment. It exposes a baseUrl setting in the per-repo config file, but the default points at https://api.supermemory.ai and the privacy section refers readers to the Supermemory privacy policy.

### Which memory plugin is best for Claude Code?

The README does not compare itself to other memory plugins, so it gives no basis for that ranking. It does state that Claude Code, Codex, and OpenCode share one container per repository, which is the interoperability claim it makes for itself.

## Sources

- [Issues](https://github.com/supermemoryai/claude-supermemory/issues)
- [Project website](https://supermemory.ai/docs/integrations/claude-code)
- [README](https://github.com/supermemoryai/claude-supermemory/blob/main/README.md)
- [Releases](https://github.com/supermemoryai/claude-supermemory/releases)
- [supermemoryai/claude-supermemory on GitHub](https://github.com/supermemoryai/claude-supermemory)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/supermemoryai-claude-supermemory