> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Muse Code

> muse-supermemory — persistent memory for Meta Muse Code

[muse-supermemory](https://github.com/supermemoryai/muse-supermemory) is a native [Muse Code](https://dev.meta.ai/docs/muse-code) plugin that gives your agent persistent memory across sessions. Your agent remembers what you worked on — across sessions, across projects.

<Tip>
  **Prefer to keep everything on your machine?** This plugin works with [self-hosted Supermemory](/docs/self-hosting/overview) — run `npx supermemory local`, then set `baseUrl` in `.muse/supermemory.json` (Muse clears hook env, so `SUPERMEMORY_API_URL` may not reach the plugin) and use the API key printed on first boot.
</Tip>

## Install the Plugin

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

In a Muse session, open `/plugins` and install from the marketplace. Or from the CLI:

```bash theme={null}
export MUSE_EXPERIMENTAL_PLUGINS=1
muse plugins marketplace add supermemory https://github.com/supermemoryai/muse-supermemory
muse plugins install supermemory@supermemory
muse plugins approve supermemory
```

`approve` trusts the runtime capabilities (hooks + MCP). Without it, the plugin is installed but inert.

Local bundle (a clone of the repo):

```bash theme={null}
export MUSE_EXPERIMENTAL_PLUGINS=1
muse plugins install . --scope user
muse plugins approve supermemory
```

## Authenticate

Muse runs hooks with a **cleared environment**, so an exported API key in your shell does not reach them. Auth is file-based.

The first session opens a browser login and writes `~/.supermemory-muse/credentials.json`.

If you already logged in through the [Claude Code plugin](/docs/integrations/claude-code), that key is reused from `~/.supermemory-claude/credentials.json`.

Or write the file yourself with a key from [API Keys](https://console.supermemory.ai/keys):

```json theme={null}
{ "apiKey": "sm_..." }
```

Check the connection any time with `/supermemory:status`.

## How It Works

Two layers, same as the other coding plugins:

| Layer           | When               | What it does                                                                       |
| --------------- | ------------------ | ---------------------------------------------------------------------------------- |
| Session profile | `SessionStart`     | Injects up to 5 persistent profile facts and 5 recent memories for this repo       |
| Prompt recall   | `UserPromptSubmit` | Searches supermemory with the prompt, injects up to 5 new hits (similarity ≥ 0.55) |
| Auto-approve    | `PreToolUse`       | Allows read-only supermemory MCP tools without a permission prompt                 |
| Auto-capture    | `Stop`             | Saves new user prompts and assistant messages from Muse's `session.jsonl`          |
| MCP tools       | on demand          | Search, save, list, and manage memories explicitly                                 |

Recalled lines are marked `◪`. When the model uses one, it keeps that mark and says "from supermemory" — never "from memory".

Slash commands and very short prompts skip recall. Timeouts fail open so a slow network never blocks the turn.

### Memory scope

Container tags match [Claude Code](/docs/integrations/claude-code):

```text theme={null}
repo_<project_name>__<project_id>
```

The project ID is a hash of the git remote (or the resolved local path if there isn't one). The same repo in Muse and Claude Code shares memory. Override with `repoContainerTag` in project config.

## Commands

| Command               | Description                                   |
| --------------------- | --------------------------------------------- |
| `/supermemory:index`  | Index codebase architecture and patterns      |
| `/supermemory:status` | Auth, container tag, API and MCP reachability |
| `/supermemory:logout` | Clear saved Muse credentials                  |

A bundled skill also tells the agent when to search vs save on its own.

## Configuration

### Global settings

`~/.supermemory-muse/settings.json`

```json theme={null}
{
  "maxProfileItems": 5,
  "debug": false
}
```

| Option            | Description                                              |
| ----------------- | -------------------------------------------------------- |
| `maxProfileItems` | Max profile facts injected at session start (default: 5) |
| `debug`           | Log hook activity to stderr                              |
| `recallDirective` | Replace prompt-recall injection with a fixed instruction |

### Project config

Per-repo overrides in `.muse/supermemory.json`. A Claude Code config at `.claude/.supermemory-claude/config.json` is also read, so one repo keeps one container tag across tools.

```json theme={null}
{
  "apiKey": "sm_...",
  "baseUrl": "https://api.supermemory.ai",
  "repoContainerTag": "my-team-project"
}
```

| Option             | Description                                 |
| ------------------ | ------------------------------------------- |
| `apiKey`           | Project-specific API key                    |
| `baseUrl`          | Supermemory API URL (use for self-hosted)   |
| `repoContainerTag` | Override the auto-derived project container |

Add the project file to `.gitignore` if it contains an API key.

## Next Steps

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="https://mintcdn.com/supermemory/ZK-HtfuFp7hNJbwr/images/github-icon.svg?fit=max&auto=format&n=ZK-HtfuFp7hNJbwr&q=85&s=f5554e90fe5f39e734c00fcf946da30b" href="https://github.com/supermemoryai/muse-supermemory" width="16" height="16" data-path="images/github-icon.svg">
    Source code, issues, and detailed README.
  </Card>

  <Card title="Claude Code Plugin" icon="https://mintcdn.com/supermemory/sv4TYl2Rdl7-erX8/images/claude-code-icon.svg?fit=max&auto=format&n=sv4TYl2Rdl7-erX8&q=85&s=53efdccf3116a20e180e728f342024ad" href="/docs/integrations/claude-code" width="66" height="52" data-path="images/claude-code-icon.svg">
    The same memory in Claude Code.
  </Card>
</CardGroup>