supermemory

Supermemory v5

Supermemory 存储文档、从中提取记忆，并提供三种内容：排名后的搜索结果、每个主题维护的个人资料，以及源文本块。每次调用都限定在一个 命名空间 中：用户 ID、项目 ID，或任何你想要隔离的边界。

本技能介绍 v5。旧版 v3 和 v4 API 已弃用，并将于 2026 年 12 月 31 日停用。如果你在代码库中看到 containerTag、customId、/v3/ 或 /v4/，说明它使用的是旧版 API；运行 npx supermemory@latest migrate 会启动一个编码 Agent 来升级代码。

本技能适用的版本

客户端	版本	安装
TypeScript SDK 和命令行工具	supermemory 5.x	npm i supermemory
Python SDK	supermemory 5.x	pip install -U supermemory
框架工具（Vercel AI SDK、OpenAI、Mastra、VoltAgent、Claude memory）	@supermemory/tools 3.x	npm i @supermemory/tools supermemory
Python 框架封装（supermemory-openai-sdk、supermemory-agent-framework、pipecat、livekit、cartesia）	仍使用旧版 API	建议在它们发布 v5 版本之前使用核心 Python SDK

核心模型

• 命名空间：隔离边界。每份文档只属于一个命名空间。切勿在同一请求中发送两个命名空间，也切勿根据文档 ID 推断范围。
• 文档：你添加的内容。可以是文本、URL 或文件。为文档设置稳定的 id，再次使用该 id 会向同一文档追加内容或与其进行差异比较，而不是创建新文档。可用于对话：一个会话 ID 对应一份文档。
• 记忆：从文档中提取的事实。你不能直接写入记忆；添加文档后，引擎会生成、更新记忆并为其创建版本。
• 个人资料：维护的命名空间主题概况，包括 static 事实、dynamic 近期上下文，以及可选的命名 buckets。
• 文本块：源文本的一部分。使用 searchMode: "chunks" 搜索原始内容，以实现经典 RAG。
• 处理：add 会返回 { id, status }，后续工作在后台继续进行。system.status 会跟踪提取和索引状态。system.dreamingStatus 会跟踪记忆形成过程，该过程可能在几分钟后才完成。使用默认设置 dreaming: "dynamic" 时，新命名空间可能在几分钟内显示零条记忆和空白个人资料。在快速入门、测试以及任何后续步骤会立即读取记忆的场景中，请使用 dreaming: "instant"。instant 每份文档会额外计费一次操作。

标准 API 接口

基础 URL：https://api.supermemory.ai。路由不带版本号；/v5 不是路径前缀。每个请求都需通过 Authorization: Bearer sm_... 进行身份验证。

方法和路径	用途
POST /ns/{namespace}/document	添加文本或 URL
POST /ns/{namespace}/document/batch	添加 1 到 600 个文档
POST /ns/{namespace}/document/file	上传文件（multipart）
GET /ns/{namespace}/document/{id}?include=chunks,memories	读取文档及其派生数据
PATCH /ns/{namespace}/document/{id}	更新内容或元数据
POST /ns/{namespace}/document/file/{id}, PATCH .../file/{id}	替换或部分更新文件文档
DELETE /ns/{namespace}/document with { "ids": [...] }	删除 1 到 100 个文档
POST /ns/{namespace}/search	搜索记忆、分块，或两者
POST /ns/{namespace}/profile	读取维护的用户画像
GET, PUT, DELETE /ns/{namespace}/profile/buckets	管理命名的用户画像分桶
POST /ns/{namespace}/list/{documents|chunks|memories}?page&limit&sort&order	分页列出数据，可在请求体中使用 filter
GET /ns/{namespace}/memories/{id}?include=related,documents	读取单条记忆及其历史记录
DELETE /ns/{namespace}/memories with { "ids": [...] }	忘记指定的记忆
DELETE /ns/{namespace}/memories/semantic with { "query", "dryRun" }	按含义查找记忆，并先预览结果
GET /namespaces, GET /ns/{namespace}, PATCH /ns/{namespace}, DELETE /ns/{namespace}?moveTo=	列出命名空间、管理设置、删除或迁移命名空间
GET /connectors, /ns/{namespace}/connectors...	OAuth 和配置连接器（Notion、Drive、网络爬虫、S3 等）
GET, PATCH /organization	组织级设置

参数的传递位置：GET 选项放在查询字符串中。POST、PATCH、PUT 选项放在 JSON 请求体中，文件上传则使用表单字段。列表分页参数放在查询字符串中。位置错误会返回 400。

SDK 快速入门

两个 SDK 都遵循同一条规则：先将 URL 值作为位置参数传入（先是命名空间，有 ID 时再传 ID），然后传入一个包含其他所有参数的对象。

import { Supermemory } from "supermemory"

const client = new Supermemory() // reads SUPERMEMORY_API_KEY

await client.add("user_alex", {
  content: "Alex prefers morning meetings and works in design.",
  id: "conv_2026_10_14",
  metadata: { source: "chat" },
  dreaming: "instant",
})

const { results } = await client.search("user_alex", { query: "when does Alex like to meet?", limit: 5 })
const { profile } = await client.profile("user_alex")

from supermemory import Supermemory

client = Supermemory()  # reads SUPERMEMORY_API_KEY

client.add("user_alex", content="Alex prefers morning meetings.", id="conv_2026_10_14", dreaming="instant")
response = client.search("user_alex", query="when does Alex like to meet?", limit=5)
profile = client.profile("user_alex")

方法对照表（Python 中相同，只是使用 snake_case）：

调用	端点
client.add(namespace, { content, id?, metadata?, supportingContext?, group?, date?, taskType?, dreaming? })	POST /ns/{ns}/document
client.search(namespace, { query, searchMode?, limit?, threshold?, filter?, include?, rerank?, rewriteQuery? })	POST /ns/{ns}/search
client.profile(namespace, { filter?, buckets? })	POST /ns/{ns}/profile
client.list(namespace, "documents" | "chunks" | "memories", { page?, limit?, sort?, order?, filter? })	POST /ns/{ns}/list/{type}
client.documents.get(namespace, id, { include? }), .update, .delete(namespace, { ids }), .batchAdd, .uploadFile, .replaceWithFile, .updateFile	/ns/{ns}/document...
client.memories.forget(namespace, { ids }), .forgetMatching(namespace, { query, dryRun })	/ns/{ns}/memories...
client.profiles.getBuckets, .setBuckets, .deleteBuckets	/ns/{ns}/profile/buckets
client.namespaces.list, .get, .update, .delete(namespace, { moveTo? })	/namespaces, /ns/{ns}
client.connectors.listAll, .list, .create, .get, .update, .delete, .sync	/connectors, /ns/{ns}/connectors...
client.organization.get, .update	/organization

搜索选项

选项	值	默认值	用途
searchMode	hybrid、memories、chunks	hybrid	memories 用于已学到的事实，chunks 用于对源文本进行 RAG，hybrid 在一个排序列表中同时提供两者
threshold	0 到 1	0.3	提高可提升精确率，降低可提升召回率
limit	整数	10
rerank	none、order、aggregate	none	order 重新排序，aggregate 合并重叠结果
rewriteQuery	布尔值	false	扩展含糊或对话式查询
include	{ documents, related, forgotten } 布尔值	全部为 false	附带源文档、相关记忆版本或已遗忘的记忆
filter	类型化表达式，见下文	无	元数据筛选

每个结果都包含 id、memory 或 chunk（有时两者都有）、similarity、metadata、isLatest、isInference、system 时间戳，以及在请求时返回的 included。请根据字段是否存在进行判断。

类型化筛选器

一个 filter 对象，由搜索、配置文件和列表共用。不使用 JSON 字符串。

filter: {
  operator: "and",
  operands: [
    { field: "source", operator: "eq", value: "slack" },
    { field: "priority", operator: "gte", value: 3 },
  ],
}

运算符：eq、neq、gt、gte、lt、lte、contains、notContains、arrayContains、arrayNotContains，以及带有 operands 的 and / or。字段名按字面处理：customer.plan 是一个键，而不是路径。最多支持五层嵌套，每个组最多包含 200 个操作数。

用法模式

聊天机器人或助手。 回答前：调用 profile(namespace) 获取长期事实，调用 search(namespace, { query: userMessage }) 搜索相关记忆。对话轮次结束后：调用 add(namespace, { content: turnText, id: sessionId })。重复使用同一个会话 ID，可将一次对话保存在同一份持续演进的文档中。

对知识库进行 RAG。 如果需要索引但不提取记忆，请使用 taskType: "superrag" 摄取内容。当答案需要引用来源时，使用 searchMode: "chunks" 和 include: { documents: true } 进行查询。

多租户。 为每位最终用户，或为每位用户与项目的组合创建一个命名空间（user_123、user_123_project_abc）。公司共享知识放在独立的命名空间中；通过第二次搜索读取，并按分数合并结果。

遗忘。 使用 memories.forgetMatching(namespace, { query, dryRun: true }) 预览，检查 matches[].id，然后调用 memories.forget(namespace, { ids })。使用 dryRun: false 重新运行语义请求时，可能会选出不同的集合。

等待处理完成。 轮询 documents.get(namespace, id)，直到 system.status === "done"。在 dreaming: "dynamic" 模式下，记忆形成可能会在几分钟后才完成；REST 读取会将其显示为 system.dreamingStatus，但 5.0.x SDK 类型目前尚未声明此字段。如果下一步要读取记忆或配置文件，请使用 dreaming: "instant" 摄取。

切勿输出

以下内容已过时或系虚构，在 v5 中会导致失败或产生误导：

• 任何位置都不要使用 containerTag、containerTags、container_tag。命名空间是 URL 路径或 SDK 的第一个参数。
• customId（现在是 id）、entityContext（现在是 supportingContext）、filterByMetadata（现在是 group）、documentDate（现在是 date）、q（现在是 query）、作为 JSON 字符串的 filters（现在是类型化的 filter）、searchMode: "documents"（现在是 "chunks"）、rerank: true（现在是 "order" 或 "aggregate"）。
• 包含 /v3/、/v4/ 或 /v5/ 的路径、/v1/search、GET /search。
• 请求头 x-api-key、x-supermemory-api-key、x-project-id、X-Workspace-Id。只能使用 Authorization: Bearer。
• SDK 方法 client.search.execute、client.search.memories、client.documents.list、client.memories.list、client.memories.add、client.memories.updateMemory、client.conversations.add、client.connections.*、client.settings.*、client.containerTags.*、client.profile({ containerTag, q })。
• 带查询条件的 profile 调用。Profile 会返回维护中的配置文件；请单独运行搜索以获取排序结果。
• 虚构选项：chunk_threshold、搜索时的 sort、include_content、include_full_docs、添加时的 isStatic。

集成

• @supermemory/tools 3.x：supermemoryTools(apiKey, { namespace }) 适用于 Vercel AI SDK，withSupermemory(model, { namespace, id }) 中间件适用于 AI SDK、OpenAI、Mastra 和 VoltAgent，createClaudeMemoryTool(apiKey, { namespace }) 适用于 Claude。从 @supermemory/tools/ai-sdk 等子路径导入。@supermemory/ai-sdk 已弃用。
• 命令行工具：npx supermemory 随 npm 包一起提供。可使用 supermemory add、search、profile、forget、docs、namespaces、connectors、migrate、setup、plugin。参见 supermemory-cli 技能。
• MCP：https://mcp.supermemory.ai 适用于 Claude、Cursor 和其他 MCP 客户端。
• 可自托管：supermemory local 可运行免费的单二进制文件服务；将 SDK 的 baseUrl 指向它即可。

参考文件

• references/quickstart.md：介绍两个 SDK 中的密钥、安装、首次添加、搜索和个人资料，以及如何等待处理完成。
• references/sdk-guide.md：介绍每个 SDK 方法的选项、响应、错误、重试和超时。
• references/api-reference.md：介绍每个 REST 端点的请求和响应格式，以及 cURL 示例。
• references/sdk-integrations.md：介绍 @supermemory/tools 和框架集成代码。
• references/use-cases.md：提供聊天机器人、任务助手、RAG、支持服务和多租户应用的完整示例。
• references/architecture.md：介绍文档如何转化为记忆、版本控制和检索。

最新权威资料：v5 API 参考、文档、v5 迁移指南以及 GitHub 上的 SDK README。