Skip to content

docs: revamp README with centered header and corrected recall/memory docs #118

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ishaanxgupta wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: revamp README with centered header and corrected recall/memory docs #118

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
daefccf
docs: revamp README with centered header, badges, and corrected recal…
ishaanxgupta Sep 3, 2026
2e5bc02
Update README.md
ishaanxgupta Sep 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
197 changes: 127 additions & 70 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,89 +1,128 @@
# Claude-Supermemory
<div align="center">

<img width="4000" height="2130" alt="image (6)" src="https://github.com/user-attachments/assets/07e63ac4-b67d-457b-9029-1dc5d860e920" />
# claude-supermemory

A Claude Code plugin that gives your AI persistent memory across sessions using [Supermemory](https://supermemory.ai).
Your agent remembers what you worked on - across sessions, across projects.
**Persistent memory for Claude Code, powered by [Supermemory](https://supermemory.ai)**

## Features
[![version](https://img.shields.io/github/package-json/v/supermemoryai/claude-supermemory/main?filename=plugin%2F.claude-plugin%2Fplugin.json&label=version&color=9C5C10)](https://github.com/supermemoryai/claude-supermemory)
[![license](https://img.shields.io/badge/license-MIT-9C5C10)](#license)

<img width="4000" height="2130" alt="claude-supermemory in action" src="https://github.com/user-attachments/assets/07e63ac4-b67d-457b-9029-1dc5d860e920" />

</div>

A Claude Code plugin that gives your agent persistent memory across sessions using
[Supermemory](https://supermemory.ai). Your agent remembers what you worked on, across
sessions and across projects.

<div align="center">

- **Team Memory** — Project knowledge shared across your team, separate from personal memories
- **Auto Capture** — Conversations saved when session ends
- **Project Config** — Per-repo settings, API keys, and container tags
[Install](#installation) · [Features](#features) · [How it works](#how-it-works) · [Shared containers](#shared-agents-memory) · [Configuration](#configuration) · [Commands](#commands) · [Privacy](#privacy)

</div>

---

## Installation

> **Requires Node.js 18+** on your PATH — the memory hooks run as Node scripts.
> **Requires Node.js 18+** on your PATH. The memory hooks run as Node scripts.

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

> **Already have the old `claude-supermemory` plugin installed?** It was renamed to `supermemory`, so it won't update in place. Migrate with:
>
> ```bash
> /plugin marketplace update supermemory-plugins
> /plugin install supermemory@supermemory-plugins
> ```
>
> Then, **only if you still have the old plugin**, remove it:
>
> ```bash
> /plugin uninstall claude-supermemory@supermemory-plugins
> ```

Set your API key (get one at [console.supermemory.ai](https://console.supermemory.ai)):
Set your API key (get one at [console.supermemory.ai](https://console.supermemory.ai)),
or just start a session and let browser login handle it:

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

## How It Works
<details>
<summary>Migrating from the old <code>claude-supermemory</code> plugin</summary>
<br>

That plugin was renamed to `supermemory`, so it won't update in place. Migrate with:

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

Then, only if you still have the old plugin installed, remove it:

```bash
/plugin uninstall claude-supermemory@supermemory-plugins
```

</details>

## Features

| | |
| --- | --- |
| 🧠 **Direct recall**<br>Every substantive prompt is searched against Supermemory by the hook itself before Claude sees it, and fresh matches are injected automatically. No permission prompt, no tool call spent. | 🔎 **Hosted MCP tools**<br>`search_memory`, `listSpaces`, `whoAmI`, and more are available through the same credentials as the hooks, auto-approved when read-only. |
| 💾 **Auto capture**<br>Conversations are saved automatically when a session ends. | 🏷️ **Team memory**<br>Project knowledge shared across your team, separate from personal memories, via `sm_scope` metadata. |
| 🧭 **Deep multi-container search**<br>The `context-gatherer` subagent fans out several searches across a project's containers and returns a synthesized brief. | ⚙️ **Project config**<br>Per-repo settings, API keys, and container tag overrides via `.claude/.supermemory-claude/config.json`. |
| 📟 **Live statusline**<br>An animated statusline (installed automatically, opt-out any time) shows recall and capture activity as it happens. | 👋 **Welcome-back notices**<br>Returning to a project after 6+ hours shows a one-line reminder of when you last worked here. |

- **Reasoned recall** — Before each turn, Claude decides whether recalling memory would actually help your current message, and only searches when it's worth it — every turn, once in a while, or not at all. The search runs automatically (no permission prompt), just like auto-capture. Searching only when needed also keeps more usage on your plan
- **supermemory-search** — Ask about past work or previous sessions, Claude searches your memories
- **supermemory-save** — Ask to save something important, Claude saves it for the team
## 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, installs the statusline on first run, and loads profile context plus a welcome-back notice. |
| 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, so it runs
on every substantive prompt instead of only when Claude chooses to spend 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.

### Shared Agents memory

Claude Code, Codex, and OpenCode use one container for a repository:
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>` stores automatic capture and every explicit save.
- `sm_scope` metadata keeps personal and project memories filterable inside that container.
```
repo_<project-name>__<remote-hash> stores automatic capture and every explicit save
sm_scope metadata keeping personal and project memories filterable
```

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. The agent plugins also read the previous `user_project_*`,
`repo_<project-name>`, `claudecode_project_*`, `codex_user_*`,
`codex_project_*`, `opencode_user_*`, and `opencode_project_*` containers, so
existing memories remain searchable without a migration. Set
`SUPERMEMORY_ISOLATE_WORKTREES=true` to use the worktree path instead of the
remote identity.

Explicit `repoContainerTag`/`projectContainerTag` overrides remain the canonical
write destination. Older personal/user overrides remain in the legacy read set.

## Commands
a local path identity. Set `SUPERMEMORY_ISOLATE_WORKTREES=true` to use the worktree
path instead of the remote identity.

| Command | Description |
| ------------------------------------ | ---------------------------------------- |
| `/supermemory:index` | Index codebase architecture and patterns |
| `/supermemory:project-config` | Configure project-level settings |
| `/supermemory:logout` | Clear saved credentials |
| `/supermemory:session` | Show clickable URL for the current session document in Supermemory |
| `/supermemory:status` | Show authentication status |
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**
### Environment variables

```bash
SUPERMEMORY_CC_API_KEY=sm_... # Required
SUPERMEMORY_DEBUG=true # Optional: enable debug logging
```
| 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` | Explicit project-container override, checked before the project config value. |
| `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`
### Global settings (`~/.supermemory-claude/settings.json`)

```json
{
Expand All @@ -95,18 +134,20 @@ SUPERMEMORY_DEBUG=true # Optional: enable debug logging
}
```

| Option | Description |
| ------------------- | --------------------------------------------- |
| `maxProfileItems` | Max memories in context (default: 5) |
| `recallDirective` | Override the built-in reasoned-recall instruction Claude is given |
| `signalExtraction` | Only capture important turns (default: false) |
| `signalKeywords` | Keywords that trigger capture |
| `signalTurnsBefore` | Context turns before signal (default: 3) |
| `includeTools` | Tools to explicitly capture |
| Option | Description |
| --- | --- |
| `maxProfileItems` | Max memories in context (default: 5). |
| `injectProfile` | Whether to fetch and inject the user profile (default: true). |
| `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`
### Project config (`.claude/.supermemory-claude/config.json`)

Per-repo overrides. Run `/supermemory:project-config` or create manually:
Per-repo overrides, created manually or via the settings your team shares:

```json
{
Expand All @@ -117,12 +158,22 @@ Per-repo overrides. Run `/supermemory:project-config` or create manually:
}
```

| Option | Description |
| ---------------------- | --------------------------- |
| `apiKey` | Project-specific API key |
| `baseUrl` | Supermemory API URL |
| `personalContainerTag` | Legacy personal container retained for reads |
| `repoContainerTag` | Override unified project container tag |
| Option | Description |
| --- | --- |
| `apiKey` | Project-specific API key. |
| `baseUrl` | Supermemory API URL. |
| `personalContainerTag` | Legacy personal container retained for reads. |
| `repoContainerTag` | Override the unified project container tag. |

## Commands

| Command | Description |
| --- | --- |
| `/supermemory:status` | Show authentication status, API and MCP reachability, and the active project container. |

Search and save no longer go through dedicated commands: recall happens automatically on
every prompt, deeper multi-container search runs through the `context-gatherer` agent or
the MCP tools directly, and saving happens automatically when a session ends.

## Privacy

Expand All @@ -132,3 +183,9 @@ For information about how Supermemory collects, uses, and retains data, see the
## License

MIT

---

<div align="center">
<sub>◪ is the supermemory mark. Whenever you see it (statusline, notices, Claude's answers), that information came from supermemory.</sub>
</div>
Loading