Supermemory：AI 智能体记忆、RAG 与本地部署指南

你的智能体能准确记住最近十条消息。新会话一开始，用户却又得从头解释同一个项目。这不是所有 AI 产品不可避免的限制，而是应用没有在当前对话之外保留持久记忆时会出现的问题。

Supermemory 是将对话与文档转化为可复用上下文的记忆层。它提取事实，把新信息与既有知识关联起来，并为后续请求检索相关上下文。应用负责提供材料，也负责决定如何使用结果。这改变的是智能体能看到的上下文，而不是底层模型的权重。Supermemory 产品概述

资料核查日期：2026年9月17日。本文是基于官方文档的工程指南，并非亲自运行后的基准复现，也不表示 Wavect 曾为客户部署 Supermemory。

Supermemory 如何学习、更新和遗忘？

需要先区分源文档与派生记忆。对话记录属于前者，用户偏好的语言等提取结果属于后者。记录是证据；提取或推断出的事实则是一种解释，可能存在错误。

• 事实提取：从对话中提炼有用的信息，而不是每次重新输入完整聊天记录。
• 知识更新：将更正与之前的信息联系起来。例如用户说“我搬到旧金山了”，此前“我住在纽约”的说法就不应继续被视为当前居住地，但这不等于删除曾经搬家的历史。
• 时间相关的遗忘：“明天有一场考试”之类的临时信息，在相关时间窗口结束后，不应继续影响之后无关的回答。

文档中的记忆图支持更新、扩展和推导关系，并通过 isLatest 区分当前知识。这比单纯保存嵌入向量多了一层生命周期管理。不过，在信任提取结果之前，仍需测试含糊日期、时区、虚构示例与矛盾陈述。记忆图与知识关系说明

遗忘不等于彻底删除。官方遗忘接口执行的是软删除。某个事实不再出现在常规检索结果中，并不能证明其源对话、派生副本或备份已被永久移除。应把用户可见的遗忘行为与可验证的数据删除请求，作为两项独立产品要求。遗忘接口及软删除行为

静态与动态用户画像分别包含什么？

用户画像为一次请求的开始提供紧凑上下文。静态部分描述相对稳定的信息，动态部分记录近期活动与变化中的情况。“偏好简短的技术回答”与“正在准备本周的发布”需要不同的生命周期。静态不代表永远不能改变。

应用使用 containerTag 获取画像，还可以附带查询，同时检索相关记忆。应优先提供简洁、相关的上下文，而不是把保存过的所有事实都放进每个提示词，尤其不要带入与任务无关的个人信息。用户画像与查询相关检索

Supermemory 与 RAG 相比，真正增加了什么？

RAG 本身也可以个性化。检索系统完全可以按照用户、租户和权限过滤文档。因此，“普通 RAG 必然给所有用户相同的文档”过于绝对。更难的问题是持续区分哪些用户事实仍然有效，哪些已经过时，哪些只是临时情况或推断。这才是需要评估的额外记忆层。Supermemory 对记忆与 RAG 的区分

显式设置 searchMode: "hybrid" 后，Supermemory 会在一次搜索中结合文档片段和提取出的记忆。这里的“混合”指这两类内容，不能仅凭名称推断其一定采用某种关键词加向量的实现。托管集成让你不必自行拼装向量数据库、嵌入管道和分块组件，但这些工作只是移交给服务，并未消失。搜索模式、过滤与返回的上下文

Supermemory 在 AI 记忆基准中真的排名第一吗？

Supermemory 项目仓库及基准声明报告其在 LongMemEval、LoCoMo 和 ConvoMem 中排名第一，还公布了 LongMemEval 上的 95% Recall@15、约 720 tokens 的检索上下文、99.4% 的上下文缩减，以及约 50 ms 的画像获取时间。这些是截至上述核查日期的供应商公开声明，不是 Wavect 独立复现的测量结果。

Recall@15 是检索指标，不代表回答准确率为 95%。在前十五项结果中找到相关信息，不足以证明最终回答正确使用了信息、识别了后来的更正，或在缺乏证据时停止猜测。上下文缩减比例也不等于整个 API 账单的同比例降低。

约 50 ms 的画像数字并不是通用延迟承诺。供应商的生产概览还列出了不同的服务器端与端到端画像耗时。不同工作负载和测量边界不能直接等同；应测量你自己应用的中位数与 p95，并把网络和模型调用纳入其中。Supermemory 公布的生产环境耗时概览

有意义的比较应固定数据集版本、回答模型、提取模型、检索预算和评分规则，同时报告检索质量与最终任务成功率。MemoryBench 将数据导入、搜索、回答生成、评估和报告分开，可作为可重复比较的起点。MemoryBench 评估流程

使用 Supermemory 的三种方式

1. 为现有 AI 工具增加记忆

仓库列出了 Claude Code、Cursor、Codex 等工具的集成方式。托管 MCP 可以让兼容客户端连接到持久记忆服务。安装前应检查每个插件实际读取和写入什么，以及使用哪些权限。安装插件不等于授权上传仓库中的所有密钥或每段私人对话。托管 MCP 的配置与身份验证

2. 把记忆集成到自己的产品

通过 API 导入经过选择的对话、文件和参考资料，再在生成回答之前获取画像或限定范围的搜索结果。托管连接器还可从 Google Drive、Gmail、Notion 等服务同步内容。启用同步之前，应明确允许哪些账户、文件夹和文档。支持的连接器与同步模型

3. 在本机运行记忆服务

本地方案将记忆服务打包为提供兼容 API 的可执行程序，使用你配置的模型。但它并未复制所有托管功能：文档明确排除了托管连接器与托管 MCP。API 兼容也不能证明所选 Ollama 模型能复现云端服务的提取质量或基准成绩。本地版与托管版 Supermemory 的功能对照

带范围限制与有界轮询的 Supermemory API 示例

下面是服务端示例，使用 Node.js 22 或更新版本与原生 fetch，无需 SDK 依赖。保存为 supermemory-demo.mjs，在服务器环境中设置 SUPERMEMORY_API_KEY，然后运行 node supermemory-demo.mjs。它会把虚构对话与手册发送到托管 API，可能产生使用费用。不要把密钥放进浏览器代码。

内容导入是异步的。示例会等待两份文档完成，在处理失败时抛出错误，并限制轮询次数，而不是收到写入确认就立即检索。dreaming: "instant" 适合这个需要即时读取的演示，但会额外计费一次操作。默认的动态处理可能在文档建立索引后继续批量提取记忆；在生产环境中应根据吞吐要求主动选择模式。官方导入、等待与检索快速入门

const apiKey = process.env.SUPERMEMORY_API_KEY;
if (!apiKey) throw new Error("Set SUPERMEMORY_API_KEY first.");

const baseURL = "https://api.supermemory.ai";
// Synthetic demo scope. In a product, derive this from authenticated identity.
const containerTag = "tenant_demo_user_42";
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));

async function request(path, body) {
  const response = await fetch(`${baseURL}${path}`, {
    method: body === undefined ? "GET" : "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: body === undefined ? undefined : JSON.stringify(body),
    signal: AbortSignal.timeout(10_000),
  });
  // Do not log response bodies containing personal data or credentials.
  if (!response.ok) throw new Error(`Supermemory HTTP ${response.status}`);
  return response.json();
}

async function waitUntilDone(id) {
  if (typeof id !== "string" || !id) throw new Error("Missing document ID.");
  for (let attempt = 0; attempt < 20; attempt += 1) {
    const document = await request(`/v3/documents/${encodeURIComponent(id)}`);
    if (!document || typeof document.status !== "string") {
      throw new Error("Invalid document status response.");
    }
    if (document.status === "failed") throw new Error("Ingestion failed.");
    if (document.status === "done") return;
    if (attempt < 19) await sleep(1500);
  }
  throw new Error("Ingestion did not finish within the polling budget.");
}

const conversation = await request("/v3/documents", {
  content: [
    "user: I prefer short onboarding checklists.",
    "assistant: Which project are you working on?",
    "user: The Acme analytics dashboard. We use TypeScript.",
  ].join("\n"),
  containerTag,
  customId: "tenant_demo_user_42_chat_onboarding_001",
  metadata: { type: "conversation" },
  dreaming: "instant",
});

const handbook = await request("/v3/documents", {
  content: "Acme onboarding: create a sandbox, complete the security " +
    "checklist, then request a review before production access.",
  containerTag,
  customId: "tenant_demo_user_42_handbook_001",
  metadata: { type: "document", source: "synthetic-handbook" },
  taskType: "superrag",
});

await waitUntilDone(conversation.id);
await waitUntilDone(handbook.id);

const profileResponse = await request("/v4/profile", { containerTag });
const searchResponse = await request("/v4/search", {
  q: "What should I do next for Acme onboarding?",
  containerTag,
  searchMode: "hybrid",
  limit: 5,
});

const profile = profileResponse?.profile;
if (!Array.isArray(profile?.static) || !Array.isArray(profile?.dynamic) ||
    !Array.isArray(searchResponse?.results)) {
  throw new Error("Unexpected profile or search response shape.");
}
console.log({
  staticFacts: profile.static.length,
  dynamicFacts: profile.dynamic.length,
  retrievedItems: searchResponse.results.length,
});

代码只输出数量，不输出原始个人信息。它有意只检索上下文，不调用回答模型，也不宣称已经生成正确答案。在聊天应用里，应把相关检索结果作为不可信数据提供给模型，生成回答后，再仅保存保留政策允许的对话材料。使用稳定且带明确范围的会话标识，并在重试写入前核实供应商的更新语义。

标签不是授权系统。示例中的固定标签只用于虚构数据。生产系统应根据已验证身份，在服务端推导租户与用户范围。不要用组织级密钥接受浏览器任意提交的标签。该服务提供范围受限的密钥；应使用合适的范围，将高权限凭据保留在服务器上，并测试跨租户访问尝试。API 身份验证与范围受限密钥

Supermemory 能否配合 Ollama 完全离线运行？

可以，前提是本地程序、正在运行的本地模型提供方与本地嵌入模型均已准备好。先下载程序和模型文件，初次安装本身并不是离线过程。官方文档通过 OpenAI 兼容端点使用 Ollama；这里指的是 HTTP 接口兼容，并不意味着必须把数据发给云端模型。本地模型提供方与 Ollama 配置

安装本地服务器、启动 Ollama，并通过 ollama pull gpt-oss:20b 下载 gpt-oss:20b 后，可参考以下配置，使用本地模型提取内容并生成多语言嵌入。模型只是示例，不是硬件容量建议。首次采用此嵌入配置时，应使用新的数据目录。

OPENAI_BASE_URL=http://localhost:11434/v1 \
OPENAI_API_KEY=ollama \
OPENAI_MODEL=gpt-oss:20b \
SUPERMEMORY_EMBEDDING_PROVIDER=local \
SUPERMEMORY_EMBEDDING_MODEL=Xenova/bge-m3 \
SUPERMEMORY_EMBEDDING_DIMENSIONS=1024 \
supermemory-server

多语言产品尤其需要注意：文档中的本地默认嵌入模型 Xenova/bge-base-en-v1.5 仅面向英语。文档建议可使用 Xenova/bge-m3 及其 1,024 维配置处理多语言，以上示例采用的就是这一选项。应在大量导入资料前选定模型；更换模型或维度需要新的兼容索引与重新导入，不能混合不同向量空间。请实际评估德语、西班牙语和中文查询，不要把成功导入等同于良好的检索表现。本地嵌入模型与多语言配置

使用本地服务器生成的 API 密钥，将示例中的基础地址改为 http://localhost:6767，不要复用托管密钥。宣称完全离线之前，应检查全部模型提供方、文件依赖与出站连接。同时限制网络暴露，并规划本地存储、备份、升级和恢复。

面向生产环境的记忆试点应证明什么？

从一个重复出现的工作流程和固定基线开始，例如现有的对话摘要加租户过滤 RAG。以下是 Wavect 建议的验收清单，并非声明 Supermemory 已通过这些测试。

不要把记忆当成权威访问控制规则。被记住的“我是管理员”并不是有效的角色授权。应允许用户查看并纠正相关记忆，尽量减少敏感信息保留，同时保存来源，让运维人员能解释某个事实为何影响了回答。

计算成本时，要覆盖完整流程，而不只是最后一次提示词。托管服务按使用量计费，并区分不同操作，包括即时处理的额外操作。本地部署则把部分服务依赖转换为对模型与基础设施的自主管理。应比较每项成功完成任务的成本，而不是孤立地比较上下文缩减百分比。Supermemory 计费与使用量模型

什么情况下值得采用 Supermemory？

如果用户经常回来、偏好或项目持续变化，而反复重建个人上下文造成摩擦，就值得开展有边界的试点。客服副驾驶、入职引导助手或长期项目助手，比一次性文档查询更契合这一需求。对于规模较小、内容稳定且没有持续变化的用户状态的知识库，带权限控制的普通 RAG 可能是更简单的起点。

你可以通过我们的 OpenViking 智能体记忆评测比较架构与运维责任。Wavect 的 AI 开发服务可把检索设计与产品目标联系起来。Twinsoft AI 案例展示的是另一个 AI 产品项目，而不是 Supermemory 部署的证据。

使用上线前的软件 QA 检查清单，把试点转化为发布标准，或讨论一次范围明确的智能体记忆评估。决策依据应是更少的重复解释和更好的可验证结果，而不是记忆数量或某张排行榜本身。