--- title: "Agents, skills and MCP" description: "Set up coding agents to integrate Supermemory with the CLI, the skill and the docs MCP." sidebarTitle: "Agents, skills and MCP" icon: "/icons/hugeicons/robotic.svg" --- This page is for **building with Supermemory** using coding agents: scaffolding a project, following the real API, and searching product docs. This is not the consumer memory MCP that gives Claude or Cursor long-term memory about you. That is a separate product: [Supermemory MCP](/supermemory-mcp/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 ```bash npx supermemory ``` Useful for coding agents: ```bash 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 npx supermemory migrate # move a v3/v4 project to v5 with your agent ``` Also available for smoke tests against your key: `add`, `search`, `profile`, `docs`, `namespaces`, `config`, `whoami`. Auth via first-run credentials or `SUPERMEMORY_API_KEY`. ```bash npx supermemory add "User prefers TypeScript" --namespace user_123 npx supermemory search "language preference" --namespace user_123 npx supermemory profile --namespace user_123 ``` ## Skill Install the official skill so the agent uses the real endpoints, auth, and `namespace` rules instead of hallucinating APIs: ```bash npx skills add https://github.com/supermemoryai/skills --skill supermemory ``` Source: [github.com/supermemoryai/skills](https://github.com/supermemoryai/skills). For coding agents, use all three together: the skill, the docs MCP and `npx supermemory setup`. ## Docs MCP Remote MCP that lets the agent **search Supermemory documentation** while it implements an integration. Server URL: ```text https://supermemory.ai/docs/mcp ``` ### Setup by client Add to `~/.cursor/mcp.json`: ```json { "mcpServers": { "supermemory-docs": { "url": "https://supermemory.ai/docs/mcp" } } } ``` ```bash claude mcp add --transport http supermemory-docs https://supermemory.ai/docs/mcp ``` Or project `.mcp.json`: ```json { "mcpServers": { "supermemory-docs": { "type": "http", "url": "https://supermemory.ai/docs/mcp" } } } ``` ```bash codex mcp add supermemory-docs --url https://supermemory.ai/docs/mcp ``` Or `~/.codex/config.toml`: ```toml [mcp_servers.supermemory-docs] url = "https://supermemory.ai/docs/mcp" ``` ```json { "mcp": { "supermemory-docs": { "type": "remote", "url": "https://supermemory.ai/docs/mcp", "enabled": true } } } ``` Add to `.vscode/mcp.json`: ```json { "servers": { "supermemory-docs": { "type": "http", "url": "https://supermemory.ai/docs/mcp" } } } ``` ```json { "mcpServers": { "supermemory-docs": { "url": "https://supermemory.ai/docs/mcp" } } } ``` Stdio-only clients can proxy: ```json { "mcpServers": { "supermemory-docs": { "command": "npx", "args": ["-y", "mcp-remote", "https://supermemory.ai/docs/mcp"] } } } ``` ### Starter prompt (docs + setup) ```text 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, namespace, and SDK usage. - Canonical writes: POST /ns/{namespace}/document · search: POST /ns/{namespace}/search · profile: POST /ns/{namespace}/profile - Auth: Authorization: Bearer $SUPERMEMORY_API_KEY only - Always scope with one namespace in the URL path on write and search; there is no namespace field in the body - SDK: import { Supermemory } from "supermemory"; version 5 or later; the namespace is the first argument: client.add(namespace, { content }), client.search(namespace, { query }) - For demos use dreaming: "instant" when memories must be ready right after status done - Already on Supermemory v3/v4? Run `npx supermemory@latest migrate` instead of rewriting calls by hand ``` ### Integrate prompt (optional) If the skill is not installed, paste a fuller prompt so the agent asks the right product questions: ```` 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/ns/{namespace}/document - Search: POST https://api.supermemory.ai/ns/{namespace}/search - Profile: POST https://api.supermemory.ai/ns/{namespace}/profile - Org settings: PATCH https://api.supermemory.ai/organization - Scoping: one `namespace` in the URL path — never in the body or a header - SDK: `import { Supermemory } from "supermemory"`; `supermemory.add(namespace, { content, id?, metadata? })`, `supermemory.search(namespace, { query })`, `supermemory.profile(namespace)` DO NOT USE — deprecated, undocumented, or fabricated: - Endpoints: /v1/anything, /v3/documents, /v3/search, /v4/search, /v4/profile, /v4/memories (use /ns/{namespace}/...) - Headers: x-supermemory-api-key, x-api-key, x-sm-user-id (for API auth) - Body keys: containerTag, containerTags, customId (use `id`), entityContext (use `supportingContext`), filterByMetadata (use `group`), documentDate (use `date`), q (use `query`), filters (use `filter`), userId, spaces - SDK: `client.add({ containerTag })`, `client.search.execute`, `client.memories.*`, `client.profile({ q })` SCOPING IS LOAD-BEARING. Every write and every search MUST name one namespace in the path. Prefer for tutorials: - Ingest conversations with a stable `id` + dreaming: "instant" when you need memories immediately - Wait until document system.status is done before search - search with searchMode: "chunks" for RAG, searchMode: "memories" (+ include.related) 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](/supermemory-mcp/mcp) ## Next steps Conversation + document ingest, RAG, graph, profile, harness. Persistent memory for assistants — separate from docs setup. Claude Code, OpenClaw, Codex, Hermes, and more. withSupermemory and memory tools in app code.