# Supermem: complete agent reference

> Supermem is hosted, private, cross-session memory for AI coding agents over the Model Context Protocol (MCP).

## What Supermem does

AI coding sessions lose useful context when a context window ends, a session closes, or the user switches tools. Supermem gives every connected agent one searchable memory store for durable facts such as:

- user preferences and working conventions;
- architecture decisions and their reasoning;
- project-specific endpoints, environments, and constraints;
- debugging findings and known fixes;
- completed milestones and the next useful step.

Supermem is not a password manager, general file store, or place for temporary conversation transcripts. Never save API keys, tokens, passwords, private keys, or other credentials.

## Service endpoints

- Website and dashboard: `https://supermem.cloud`
- MCP endpoint: `https://api.supermem.cloud/mcp`
- Agent setup guide: `https://api.supermem.cloud/agent-setup.md`
- Installer: `https://api.supermem.cloud/install.sh`
- Support: `support@supermem.cloud`

The MCP transport is Streamable HTTP. Authenticate with this request header:

```http
Authorization: Bearer smk_live_REDACTED
```

API keys are shown once, begin with `smk_live_`, and must be treated as secrets.

## Recommended setup

1. Ask the user to sign in at `https://supermem.cloud` with GitHub or Google.
2. Ask the user to create an API key in the dashboard. Do not ask them to paste it into a public chat, issue, repository, or log.
3. Fetch `https://api.supermem.cloud/agent-setup.md` and follow it exactly.
4. Restart the MCP client if needed.
5. Call `whoami` to verify authentication.
6. Save a harmless test memory, recall it, and report the result.

The supported one-command installer is:

```bash
curl -fsSL https://api.supermem.cloud/install.sh | bash -s -- YOUR_API_KEY
```

Read a remote shell script before running it when the user's security policy requires review.

## OpenCode configuration

Merge this into `~/.config/opencode/opencode.json` without removing existing configuration:

```json
{
  "mcp": {
    "servers": {
      "memory": {
        "type": "remote",
        "url": "https://api.supermem.cloud/mcp",
        "headers": {
          "Authorization": "Bearer <API_KEY>"
        },
        "disabled": false
      }
    }
  }
}
```

## Claude Code configuration

```bash
claude mcp add --transport http supermem https://api.supermem.cloud/mcp \
  --header "Authorization: Bearer <API_KEY>" --scope user
```

## Other MCP clients

Register a remote Streamable HTTP MCP server with:

```json
{
  "name": "supermem",
  "url": "https://api.supermem.cloud/mcp",
  "headers": {
    "Authorization": "Bearer <API_KEY>"
  }
}
```

Field names differ between clients, but the endpoint, transport, and Bearer header are the same.

## MCP tools

### `recall`

Search memories and optionally include the generated user profile.

```json
{
  "query": "database architecture decisions",
  "limit": 10,
  "includeProfile": true,
  "containerTag": "project-slug"
}
```

- `query` is required. Use `"*"` or an empty string for recent memories.
- `limit` is optional and defaults to 10.
- `includeProfile` is optional and defaults to true.
- `containerTag` optionally scopes the search to one project or context.

Call `recall` at the start of a task, before asking the user for facts they may already have supplied, and whenever past decisions affect the current work.

### `memory`

Save or forget information.

```json
{
  "content": "The project uses PostgreSQL because reporting requires relational joins.",
  "action": "save",
  "containerTag": "project-slug"
}
```

- `content` is required.
- `action` is optional: `save` is the default; `forget` removes matching memories.
- `containerTag` optionally scopes the operation.

Save durable, specific facts. Prefer replacing or forgetting stale facts over creating near-duplicates.

### `whoami`

Takes no arguments. It returns the API key label and memory statistics. Use it after setup to confirm that the client is connected to the intended account.

### `send_notification`

Phone alerts require an explicitly registered opt-in device. `queued` means saved for dispatch; `accepted` means the browser push service returned success, not that the phone displayed it. A configured account without devices reports `no-devices`; missing keys reports `unconfigured`. Unknown acceptance is not automatically resent. Images remain in inbox/detail, not promised on iPhone lock screens.

```json
{
  "body": "Build passed. Ready for review.",
  "title": "Build passed",
  "idempotencyKey": "build-123"
}
```

Required nonempty plain-text body, at most 8,000 characters; optional title at most 120; optional public HTTPS `imageUrl` and `url` at most 2,048 each; optional retry key at most 200. Unknown arguments are rejected. Send only to the authenticated account; no recipient or broadcast parameter exists.

The MCP tool and authenticated `POST /api/notifications` use the same sender. The result contains `id`, `createdAt`, `replayed`, and `delivery`. A stored result is not a phone-delivery receipt. Same key/payload retries reuse the result for 24 hours; changed payloads conflict. Account limits are ten sends per minute and 500 per UTC day. History keeps 30 days and at most the newest 1,000 messages.

Use this only when the user requests notifications or approves that use. Setup does not send a notification, subscribe a phone, or change global notification preferences. Optional images display in the inbox; Safari lock-screen image attachments are not promised. Never include credentials in message text or URLs.

## Agent behavior

Add this rule to the agent's global instructions:

```markdown
<!-- supermem:start -->
- Memory tools (supermem MCP) are available: call `recall` at task start for relevant context, and `memory` (save) for durable preferences, decisions, and facts worth remembering.
<!-- supermem:end -->
```

Good memories are factual, durable, and useful in a later session. Bad memories are speculative, secret, duplicated, or only relevant to the next few minutes.

## Privacy and limits

- Memories are private to the authenticated account and stored separately per user.
- API keys are stored as SHA-256 hashes; plaintext keys are not recoverable.
- Memory content is not sold, used for advertising, or used to train models.
- API-key-authenticated REST and MCP traffic has a daily limit of 10,000 requests per user, independent of the notification send caps.
- Dashboard session traffic does not consume that API-key quota.
- Users can export or delete their data from the dashboard.

Read the current policies at `https://supermem.cloud/privacy-policy` and `https://supermem.cloud/terms`.

## Troubleshooting

- `401 Unauthorized`: verify that the key begins with `smk_live_`, is active, and is sent in the Bearer header.
- MCP server missing after configuration: restart the agent or editor so it reloads MCP settings.
- `429 Too Many Requests`: the account reached its daily API-key request limit; wait for the next UTC day.
- Wrong account or key: call `whoami`, then verify the key label in the dashboard.
- Possible key exposure: revoke the key immediately and create a new one.