Supermemory Skills

---
name: supermemory
description: Build with the Supermemory v5 API and SDKs (TypeScript `supermemory` 5.x, Python `supermemory` 5.x, `@supermemory/tools` 3.x). Use when an application needs persistent memory across sessions, per-user personalization, a maintained user profile, or semantic search over documents. Covers the namespace-scoped endpoints, exact SDK call shapes, search and ingestion options, typed filters, and the legacy names that must not be emitted.
---

# Supermemory v5

Supermemory stores documents, extracts memories from them, and serves three things back: ranked search results, a maintained profile per subject, and the source chunks. Every call is scoped to one **namespace**: a user id, a project id, or any boundary you want isolated.

This skill documents **v5**. The legacy v3 and v4 API is deprecated and shuts down on December 31, 2026. If you see `containerTag`, `customId`, `/v3/`, or `/v4/` in a codebase, it is on the legacy API; `npx supermemory@latest migrate` launches a coding agent that upgrades it.

## Versions this skill matches

| Client | Version | Install |
| --- | --- | --- |
| TypeScript SDK and CLI | `supermemory` 5.x | `npm i supermemory` |
| Python SDK | `supermemory` 5.x | `pip install -U supermemory` |
| Framework tools (Vercel AI SDK, OpenAI, Mastra, VoltAgent, Claude memory) | `@supermemory/tools` 3.x | `npm i @supermemory/tools supermemory` |
| Python framework wrappers (`supermemory-openai-sdk`, `supermemory-agent-framework`, pipecat, livekit, cartesia) | still on the legacy API | prefer the core Python SDK until they ship a v5 release |

## Core model

- **Namespace**: the isolation boundary. One document lives in exactly one namespace. Never send two namespaces in one request and never infer scope from a document id.
- **Document**: what you add. Text, a URL, or a file. Give it a stable `id` and repeating that `id` appends or diffs into the same document instead of creating a new one. Use it for conversations: one session id, one document.
- **Memory**: a fact extracted from documents. You never write memories directly; you add documents and the engine forms, updates, and versions them.
- **Profile**: the maintained picture of a namespace's subject. `static` facts, `dynamic` recent context, and optional named `buckets`.
- **Chunk**: a piece of source text. Search with `searchMode: "chunks"` for classic RAG over the raw content.
- **Processing**: `add` returns `{ id, status }` and work continues in the background. `system.status` tracks extraction and indexing. `system.dreamingStatus` tracks memory formation and can finish minutes later. With the default `dreaming: "dynamic"`, a new namespace can show zero memories and an empty profile for several minutes. Use `dreaming: "instant"` in quickstarts, tests, and anywhere the next step reads memories right away. `instant` bills one extra operation per document.

## Canonical API surface