# Supermemory — how to use (mcp.ai)

Connect your Supermemory account and use 11 tools for artificial intelligence straight from your AI agent. Connect with your own API key. Supermemory is a memory and context API for ingesting, organizing, searching, and recalling information across applications.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_supermemory?ms=1787291460000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `supermemory_add_document`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/supermemory`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/supermemory/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/supermemory/add/document` — Ingest text or a public URL as a Supermemory document and return its document ID and initial processing status.
  - body: { content: string, dreaming?: string, metadata?: object, custom_id?: string, task_type?: string, container_tag?: string, entity_context?: string, filter_by_metadata?: object }
- `POST https://api.mcp.ai/api/supermemory/add/documents` — Add 1 to 600 documents in one request, with explicit per-document metadata and processing options. HTTP 200 may contain partial failures; callers must inspect failed, success, and every result rather 
  - body: { dreaming?: string, documents: object[] }
- `POST https://api.mcp.ai/api/supermemory/delete/document` — Permanently delete one document by ID. This does not remove the document's container-tag settings record.
  - body: { document_id: string }
- `POST https://api.mcp.ai/api/supermemory/get/account/status` — Return the connected Supermemory organization's plan, credit balance, high-level usage, and reset date.
- `POST https://api.mcp.ai/api/supermemory/get/document` — Get one document's content, metadata, source details, and processing status by document ID.
  - body: { document_id: string }
- `POST https://api.mcp.ai/api/supermemory/get/document/chunks` — Return the ordered extracted chunks for one processed document.
  - body: { document_id: string }
- `POST https://api.mcp.ai/api/supermemory/get/profile` — Retrieve the static, dynamic, or bucketed profile learned for one container tag, optionally with matching search results.
  - body: { query?: string, buckets?: string[], filters?: object, include?: string[], threshold?: number, container_tag: string }
- `POST https://api.mcp.ai/api/supermemory/list/documents` — List documents, optionally filtered by containers, metadata, or filepath, one page at a time.
  - body: { sort?: string, limit?: integer, order?: string, filters?: object, filepath?: string, next_cursor?: string, container_tags?: string[], include_content?: boolean }
- `POST https://api.mcp.ai/api/supermemory/list/memories` — List extracted memory entries for one or more container tags, one page at a time.
  - body: { sort?: string, limit?: integer, order?: string, filters?: object, next_cursor?: string, container_tags: string[] }
- `POST https://api.mcp.ai/api/supermemory/search/context` — Semantically search Supermemory memories, document chunks, or both, with optional container and metadata filters.
  - body: { limit?: integer, query: string, rerank?: boolean, filters?: object, include?: object, aggregate?: boolean, threshold?: number, search_mode?: string, rewrite_query?: boolean, container_tags?: string[] }
- `POST https://api.mcp.ai/api/supermemory/update/document` — Update the content, metadata, container, or processing configuration of one existing document. When metadata is supplied, it completely replaces the document's metadata, so omitted metadata keys are r
  - body: { content?: string, metadata?: object, custom_id?: string, task_type?: string, document_id: string, container_tag?: string, filter_by_metadata?: object }

## Example prompts
- "What can I do in Supermemory?"
- "Show me a summary of my Supermemory account"

## More
- Page: https://mcp.ai/supermemory
- Agent spec (llms.txt): https://mcp.ai/supermemory/llms.txt
- Postman collection: https://mcp.ai/supermemory/postman.json