Agents, skills and MCP

This page is for building with Supermemory using coding agents: scaffolding a project, following the real API, and searching product docs. It is not the consumer Memory MCP (give Claude/Cursor long-term memory about you). That is a separate product surface — see Supermemory MCP.

Path	How	For
CLI	`npx supermemory`	Setup, smoke tests, agent-driven integration
Skill	`npx skills add … --skill supermemory`	Teach the agent the real API surface
Docs MCP	`https://supermemory.ai/docs/mcp`	Search these docs while the agent codes

CLI

Agents (and humans) can set things up from the terminal easily using our CLI

npx supermemory

Useful for coding agents:

npx supermemory setup              # detect project, launch/print integration flow
npx supermemory setup --prompt     # print integration prompt only
npx supermemory setup --json       # machine-readable output
npx supermemory help --json        # agent-readable command catalog
npx supermemory help --all

Also available for smoke tests against your key: add, search, profile, docs, tags, config, whoami. Auth via first-run credentials or SUPERMEMORY_API_KEY.

npx supermemory add "User prefers TypeScript" --tag user_123
npx supermemory search "language preference" --tag user_123
npx supermemory profile --tag user_123

Skill

Install the official skill so the agent uses the real endpoints, auth, and containerTag rules instead of hallucinating APIs:

npx skills add https://github.com/supermemoryai/skills --skill supermemory

Source: github.com/supermemoryai/skills.

Best combo for coding agents: skill + docs MCP + npx supermemory setup.

Docs MCP

Remote MCP that lets the agent search Supermemory documentation while it implements an integration. Server URL:

https://supermemory.ai/docs/mcp

Setup by client

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "supermemory-docs": {
      "url": "https://supermemory.ai/docs/mcp"
    }
  }
}

claude mcp add --transport http supermemory-docs https://supermemory.ai/docs/mcp

Or project .mcp.json:

{
  "mcpServers": {
    "supermemory-docs": {
      "type": "http",
      "url": "https://supermemory.ai/docs/mcp"
    }
  }
}

codex mcp add supermemory-docs --url https://supermemory.ai/docs/mcp

Or ~/.codex/config.toml:

[mcp_servers.supermemory-docs]
url = "https://supermemory.ai/docs/mcp"

{
  "mcp": {
    "supermemory-docs": {
      "type": "remote",
      "url": "https://supermemory.ai/docs/mcp",
      "enabled": true
    }
  }
}

Add to .vscode/mcp.json:

{
  "servers": {
    "supermemory-docs": {
      "type": "http",
      "url": "https://supermemory.ai/docs/mcp"
    }
  }
}

{
  "mcpServers": {
    "supermemory-docs": {
      "url": "https://supermemory.ai/docs/mcp"
    }
  }
}

Stdio-only clients can proxy:

{
  "mcpServers": {
    "supermemory-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://supermemory.ai/docs/mcp"]
    }
  }
}

Starter prompt (docs + setup)

You are integrating Supermemory into my app.

- Use the supermemory-docs MCP (or https://supermemory.ai/docs/llms.txt) before inventing endpoints.
- Prefer `npx supermemory setup` / the supermemory skill for correct auth, containerTag, and SDK usage.
- Canonical writes: POST /v3/documents · search: POST /v4/search · profile: POST /v4/profile
- Auth: Authorization: Bearer $SUPERMEMORY_API_KEY only
- Always scope with containerTag (singular) on write and search
- For demos use dreaming: "instant" when memories must be ready right after status done

Integrate prompt (optional)

If the skill is not installed, paste a fuller prompt so the agent asks the right product questions:

Copy full integration prompt

You are integrating Supermemory into my application. Supermemory provides user memory, semantic search, and automatic knowledge extraction for AI applications.

Note: You can always reference the documentation by using the **supermemory-docs MCP** or content on **supermemory.ai/docs**. Prefer `npx supermemory setup` / `npx supermemory help --json` when scaffolding.

CANONICAL API SURFACE (use these, nothing else):

- Auth header: `Authorization: Bearer $SUPERMEMORY_API_KEY` — the only supported auth header
- Write content:     POST https://api.supermemory.ai/v3/documents
- Search:            POST https://api.supermemory.ai/v4/search
- Profile + search:  POST https://api.supermemory.ai/v4/profile
- Settings:          PATCH https://api.supermemory.ai/v3/settings
- Scoping:           `containerTag` (singular string) in the JSON body — never in a header
- SDK:               `client.add()`, `client.search()`, `client.profile()`

DO NOT USE — deprecated, undocumented, or fabricated:

- Endpoints:  /v1/anything, /v3/memories, /v3/search   (use /v3/documents and /v4/search)
- Headers:    x-supermemory-api-key, x-api-key, x-sm-user-id (for API auth)
- Body keys:  containerTags (plural) on writes as the only scope, userId, spaces
- Mixing:     `rerank` and `rewriteQuery` on /v4/search only — never on /v3/search

SCOPING IS LOAD-BEARING. Every write and every search MUST include `containerTag`.

Prefer for tutorials:
- Ingest conversations with customId + dreaming: "instant" when you need memories immediately
- Wait until document status is done before search
- search with searchMode: "documents" for RAG, search (+ relatedMemories) for the graph, profile for always-on context

STEP 1: Ask what I'm building, integration style (AI SDK / OpenAI / Direct SDK / API), data model (user/org/both), profiles yes/no.
STEP 2: Install supermemory (npm/pip), set SUPERMEMORY_API_KEY from https://console.supermemory.ai
STEP 3: Generate complete working code.

DOCS: https://supermemory.ai/docs

Memory MCP (different product)

Want your assistant to remember you across chats (save/recall/profile in Claude, Cursor, etc.)? That is the Memory MCP, not the docs MCP: → Supermemory MCP

Next steps

Quickstart

Conversation + document ingest, RAG, graph, profile, harness.

Memory MCP

Persistent memory for assistants — separate from docs setup.

Plugins

Claude Code, OpenClaw, Codex, Hermes, and more.

AI SDK

withSupermemory and memory tools in app code.

Getting Started

Concepts

Using supermemory

Deployment

Other resources

Migration Guides

CLI

Skill

Docs MCP

Setup by client

Starter prompt (docs + setup)

Integrate prompt (optional)

Memory MCP (different product)

Next steps

Quickstart

Memory MCP

Plugins

AI SDK

​CLI

​Skill

​Docs MCP

​Setup by client

​Starter prompt (docs + setup)

​Integrate prompt (optional)

​Memory MCP (different product)

​Next steps

Quickstart

Memory MCP

Plugins

AI SDK

CLI

Skill

Docs MCP

Setup by client

Starter prompt (docs + setup)

Integrate prompt (optional)

Memory MCP (different product)

Next steps