Supermemory 深度实战：AI 时代的 Memory API 完全指南——从记忆引擎架构到生产级集成的完整解析（2026）

当 AI 忘记了一切，我们如何赋予它持久的记忆？Supermemory 给出了答案。

引言：AI 的记忆困境

2026 年，大语言模型（LLM）已经能够编写代码、分析文档、与客户对话。但有一个问题始终没有解决：AI 没有记忆。

每一次对话，AI 都从零开始。你告诉它"我喜欢函数式编程"，下一次对话它就不记得了。你在周一讨论了项目架构，周三再聊时它一脸茫然。这种"健忘症"严重限制了 AI 在实际场景中的应用价值。

传统的解决方案是 RAG（检索增强生成）——把文档塞进向量数据库，需要时检索出来。但 RAG 有根本缺陷：

1. 无状态：它检索的是文档，不是记忆。同样的查询，对任何人都返回相同结果。
2. 无时间感知：它不知道"我昨天说喜欢 Python"已经被"我现在用 Rust 了"取代。
3. 无矛盾处理：如果用户先说 A，后说非 A，RAG 会把两条信息都检索出来，让 AI 困惑。
4. 无自动遗忘：临时信息（"我明天下午有会"）永远留在数据库里，变成噪音。

Supermemory 的出现改变了这一切。它不是一个简单的向量数据库，而是一个完整的 Memory Engine（记忆引擎）——能够自动提取事实、跟踪知识更新、处理矛盾、忘记过期信息，并在正确的时间交付正确的上下文。

更令人震惊的是，Supermemory 在三个主要的 AI 记忆基准测试中均排名第一：

• LongMemEval：81.6%（长期记忆与知识更新）
• LoCoMo：#1（扩展对话中的事实回忆）
• ConvoMem：#1（个性化与偏好学习）

今天，我们将深入 Supermemory 的架构与设计哲学，从零开始构建集成方案，并探讨如何将它与现有的 AI 应用深度整合。

第一部分：记忆引擎的架构原理

1.1 从 RAG 到 Memory Engine 的范式转变

要理解 Supermemory 的创新，我们首先需要厘清 RAG 与 Memory 的本质区别。

RAG 的工作流：

用户提问 → 向量化问题 → 检索相似文档块 → 拼接进上下文 → LLM 生成回答

Memory Engine 的工作流：

对话发生 → 提取事实 → 更新记忆图谱 → 处理矛盾/过期 → 构建用户画像 → 注入上下文 → LLM 生成个性化回答

关键差异在于：

1.2 Supermemory 的核心架构

Supermemory 的架构可以分为 6 个核心模块：

┌─────────────────────────────────────────────────────────┐
│                   Application Layer                     │
│  (Claude Code / Cursor / Web App / API / MCP Server)   │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────┐
│                Supermemory Engine Core                   │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │ Memory       │  │ User Profile  │  │ Hybrid       │ │
│  │ Extractor    │  │ Builder       │  │ Search       │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │ Connectors   │  │ Multi-modal  │  │ Forgetting   │ │
│  │ Manager      │  │ Extractors   │  │ Engine       │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────┐
│                      Storage Layer                       │
│         (Vector Store + Relational DB + Graph DB)        │
└─────────────────────────────────────────────────────────┘

模块详解

① Memory Extractor（记忆提取器）

这是 Supermemory 的"大脑"。它负责从对话中提取有价值的信息：

• 实体识别：人名、项目名称、技术栈
• 偏好提取："我喜欢用 Rust" → 持久偏好
• 临时事实："我明天下午 3 点有会" → 带过期时间
• 矛盾检测："我住在 NYC" vs "我刚搬到 SF" → 自动更新

实现原理（简化版）：

// Supermemory 的记忆提取伪代码
async function extractMemories(conversation: Message[]): Promise<Memory[]> {
  const prompt = `
分析以下对话，提取所有值得长期记住的信息：
- 用户偏好（编程语言、工具、风格）
- 项目信息（名称、技术栈、状态）
- 临时事实（会议、截止日期等，需标注过期时间）
- 矛盾信息（如果新信息与旧信息冲突，标注旧信息ID）

对话：
${conversation.map(m => `${m.role}: ${m.content}`).join('\n')}

返回 JSON 数组，每个元素包含：
- content: 提取的事实
- type: "preference" | "project" | "temporary" | "contradiction"
- expiresAt: 临时事实的过期时间（可选）
- contradicts: 被推翻的旧记忆ID（可选）
`;

  const response = await llm.call(prompt);
  return JSON.parse(response);
}

② User Profile Builder（用户画像构建器）

Supermemory 自动维护两个层次的画像：

• Static Profile（静态画像）：长期稳定的事实

  • "高级工程师 @ Acme"
  • "偏好函数式编程"
  • "使用 Vim"

• Dynamic Profile（动态上下文）：最近的活动与短期目标

  • "正在做认证模块迁移"
  • "在调试限流问题"

这两个层次在 API 中通过 profile.static 和 profile.dynamic 分别返回。

③ Hybrid Search（混合搜索）

这是 Supermemory 最强大的功能之一：在一个查询中同时搜索 RAG 文档和个性化记忆。

// 混合搜索示例
const results = await client.search.memories({
  q: "如何部署？",
  containerTag: "user_123",
  searchMode: "hybrid",  // 关键：同时搜索文档和记忆
});

// results 包含：
// 1. 部署文档（来自 RAG 知识库）
// 2. 用户偏好（"我喜欢用 Docker Compose 部署"）
// 3. 历史对话（"上次部署时遇到了 nginx 配置问题"）

④ Connectors Manager（连接器管理器）

Supermemory 支持从外部系统自动同步数据：

• Google Drive（文档）
• Gmail（邮件）
• Notion（笔记）
• OneDrive（文件）
• GitHub（代码仓库）
• Web Crawler（网页爬取）

所有连接器都支持 实时 Webhook——当外部数据变化时，Supermemory 自动重新处理并更新索引。

⑤ Multi-modal Extractors（多模态提取器）

Supermemory 不仅能处理文本，还能从多种模态中提取信息：

• PDF：提取文本、表格、图片（OCR）
• 图片：OCR + 视觉模型描述
• 视频：转录（Whisper）+ 内容分析
• 代码：AST 感知的分块（保留函数/类的完整性）

⑥ Forgetting Engine（遗忘引擎）

这是大多数 Memory 系统忽略的部分。Supermemory 会自动忘记：

• 过期事实："我明天下午有会" → 会后自动删除
• 过时信息："我住在 NYC" 被 "我搬到 SF 了" 取代
• 低价值噪音：频繁但不重要的对话片段

第二部分：Supermemory 的快速上手

2.1 安装与初始化

Supermemory 提供多种使用方式：

方式一：使用消费者 App（无代码）

访问 https://app.supermemory.ai，注册并安装浏览器扩展。你的 AI 助手（支持 Claude、OpenClaw、Hermes 等）将自动获得持久记忆。

方式二：API 集成（开发者）

# Node.js/TypeScript
npm install supermemory

# Python
pip install supermemory

方式三：MCP 服务器（AI 工具集成）

# 一键安装到 Claude Desktop / Cursor / Windsurf 等
npx -y install-mcp@latest https://mcp.supermemory.ai/mcp --client claude --oauth=yes

安装后，在 MCP 客户端配置中添加：

{
  "mcpServers": {
    "supermemory": {
      "url": "https://mcp.supermemory.ai/mcp"
    }
  }
}

2.2 基础 API 使用

TypeScript 示例

import Supermemory from "supermemory";

const client = new Supermemory();  // 自动从环境变量读取 API Key

// 1. 存储一条记忆
await client.add({
  content: "用户喜欢用 Rust 编写高性能服务，偏好 axum 框架",
  containerTag: "user_123",  // 用户隔离
});

// 2. 搜索记忆（混合模式）
const { results } = await client.search.memories({
  q: "用户的技术偏好",
  containerTag: "user_123",
  searchMode: "hybrid",
});

console.log(results);
// 输出：
// [
//   {
//     content: "用户喜欢用 Rust 编写高性能服务，偏好 axum 框架",
//     score: 0.92,
//     source: "memory",
//     createdAt: "2026-06-01T10:30:00Z"
//   }
// ]

// 3. 获取用户画像（一次性获取静态 + 动态上下文）
const { profile } = await client.profile({
  containerTag: "user_123",
});

console.log(profile.static);
// ["高级工程师 @ Acme", "偏好函数式编程", "使用 Vim", "喜欢 Rust + axum"]

console.log(profile.dynamic);
// ["正在做认证模块迁移", "在调试限流问题"]

// 4. 上传文件（多模态支持）
await client.documents.uploadFile({
  containerTag: "user_123",
  filePath: "./api-design.pdf",
  processImmediately: true,  // 立即处理（OCR、分块、索引）
});

Python 示例

from supermemory import Supermemory

client = Supermemory()

# 存储记忆
client.add(
    content="用户喜欢用 Rust 编写高性能服务，偏好 axum 框架",
    container_tag="user_123"
)

# 获取用户画像
result = client.profile(container_tag="user_123")

print(result.profile.static)   # 长期事实
print(result.profile.dynamic)  # 最近上下文

# 搜索（混合模式）
results = client.search.memories(
    q="用户的技术偏好",
    container_tag="user_123",
    search_mode="hybrid"
)

for r in results.results:
    print(f"[{r.source}] {r.content} (score: {r.score})")

第三部分：深度集成实战

3.1 与 Vercel AI SDK 集成

Vercel AI SDK 是目前最流行的 AI 应用开发框架。Supermemory 提供了原生集成：

import { openai } from "@ai-sdk/openai";
import { withSupermemory } from "@supermemory/tools/ai-sdk";

// 包装模型，自动注入记忆
const model = withSupermemory(openai("gpt-4o"), {
  containerTag: "user_123",
  customId: "conversation-456",  // 可选：对话ID（用于多轮记忆提取）
  mode: "full",  // "full" = 记忆 + RAG；"memory" = 仅记忆；"rag" = 仅 RAG
});

// 现在，每次调用模型时，Supermemory 会自动：
// 1. 从对话中提取新记忆（异步，不阻塞生成）
// 2. 在系统提示中注入用户画像
// 3. 检索相关记忆并注入

const { text } = await generateText({
  model,
  prompt: "帮我设计一个高并发的短链接服务",
});

// 幕后发生了什么：
// 1. Supermemory 在后台分析对话
// 2. 提取："用户在讨论短链接服务设计" → 存入动态上下文
// 3. 如果用户在后续对话中说"继续昨天的短链接项目"，AI 会记得

3.2 与 LangChain 集成

import { ChatOpenAI } from "@langchain/openai";
import { withSupermemory } from "@supermemory/tools/langchain";

const model = new ChatOpenAI({ model: "gpt-4o" });

const memoryEnabledModel = withSupermemory(model, {
  containerTag: "user_123",
  injectProfile: true,  // 是否注入用户画像到系统提示
  extractMemories: true,  // 是否自动提取记忆
});

const response = await memoryEnabledModel.invoke([
  ["human", "帮我优化这段 Rust 代码的性能"],
]);

// 如果 Supermemory 中已经存储了"用户偏好零拷贝优化"，
// 这个偏好会自动注入到上下文，AI 的回答会考虑这一点

3.3 与 OpenClaw 集成（MCP 服务器）

如果你使用 OpenClaw，可以通过 MCP 协议集成 Supermemory：

安装 OpenClaw 插件：

git clone https://github.com/supermemoryai/openclaw-supermemory.git
cd openclaw-supermemory
npm install
npm run build

配置（~/.openclaw/config.json）：

{
  "plugins": [
    {
      "name": "supermemory",
      "path": "/path/to/openclaw-supermemory/dist/index.js",
      "enabled": true
    }
  ]
}

使用：
在 OpenClaw 对话中，Supermemory 会自动：

• 提取对话中的关键信息
• 在每次对话开始时注入用户画像
• 提供 memory 和 recall 工具供 AI 显式调用

第四部分：高级特性与性能优化

4.1 Container Tag 设计最佳实践

containerTag 是 Supermemory 中最重要的概念之一——它定义了记忆的作用域。

错误用法：

// ❌ 所有用户共享同一个 containerTag
await client.add({
  content: "用户喜欢 Rust",
  containerTag: "global",  // 危险！所有用户的记忆混在一起
});

正确用法：

// ✅ 每用户独立 containerTag
await client.add({
  content: "用户喜欢 Rust",
  containerTag: `user_${userId}`,
});

// ✅ 按项目隔离
await client.add({
  content: "项目使用微服务架构",
  containerTag: `project_${projectId}`,
});

// ✅ 混合：用户 + 项目
await client.add({
  content: "我在这个项目中负责认证模块",
  containerTag: `user_${userId}_project_${projectId}`,
});

建议的命名规范：

user_{userId}                    # 用户全局记忆
user_{userId}_project_{projId}   # 用户在特定项目中的记忆
org_{orgId}                      # 组织级共享记忆（如文档、规范）
temp_{sessionId}                  # 临时会话记忆（可设置自动过期）

4.2 批量操作与延迟写入

如果你需要存储大量记忆（例如初始化用户画像），使用批量 API 可以减少请求次数：

// ❌ 低效：逐个写入
for (const fact of userFacts) {
  await client.add({
    content: fact,
    containerTag: "user_123",
  });
}
// 100 条事实 = 100 次 API 调用

// ✅ 高效：批量写入（Supermemory 支持一次最多 100 条）
await client.addBatch({
  memories: userFacts.map(fact => ({
    content: fact,
    containerTag: "user_123",
  })),
});
// 100 条事实 = 1 次 API 调用

4.3 搜索性能优化

Supermemory 的搜索延迟通常在 50ms 左右，但如果你的知识库很大（百万级文档），可以考虑以下优化：

① 使用过滤器缩小范围

const results = await client.search.memories({
  q: "认证方案",
  containerTag: "user_123",
  filters: {
    source: "document",        // 仅搜索文档（不搜索记忆）
    fileType: "pdf",           // 仅搜索 PDF
    createdAfter: "2026-01-01", // 仅搜索今年上传的文档
  },
});

② 调整召回数量

const results = await client.search.memories({
  q: "认证方案",
  containerTag: "user_123",
  topK: 5,  // 默认是 10，减少到 5 可以提高速度（但可能漏掉相关信息）
});

③ 使用 profile API 代替频繁搜索

如果你只需要用户画像（不需要搜索具体记忆），用 profile API 更快：

// ❌ 慢：先搜索记忆，再构建画像
const memories = await client.search.memories({ q: "用户偏好", containerTag: "user_123" });
const profile = buildProfile(memories);  // 需要额外处理

// ✅ 快：直接获取预构建的画像（~50ms）
const { profile } = await client.profile({ containerTag: "user_123" });

4.4 处理矛盾与知识更新

Supermemory 自动处理矛盾，但你也可以显式控制：

// 场景：用户先说"我用 React"，后说"我换到 Vue 了"
await client.add({
  content: "我用 React",
  containerTag: "user_123",
});

await client.add({
  content: "我换到 Vue 了",
  containerTag: "user_123",
  contradictions: ["我用 React"],  // 显式声明这条记忆推翻了旧记忆
});

// 现在，当搜索"用户的前端框架偏好"时，
// Supermemory 会返回"Vue"，而不是同时返回"React"和"Vue"

第五部分：生产环境部署架构

5.1 典型架构拓扑

在生产环境中，Supermemory 通常部署为独立服务，供多个应用共享：

┌─────────────────────────────────────────────────────────────┐
│                       Load Balancer                         │
│                        (nginx/ALB)                          │
└────────────────────┬────────────────────────────────────────┘
                     │
        ┌────────────┴────────────┐
        │                         │
┌───────▼───────┐        ┌───────▼───────┐
│  App Server 1  │        │  App Server 2  │
│  (Your App)    │        │  (Your App)    │
└───────┬───────┘        └───────┬───────┘
        │                        │
        └────────────┬───────────┘
                     │
        ┌────────────┴────────────┐
        │                         │
┌───────▼────────────────────────▼───────┐
│       Supermemory API Server             │
│  (https://api.supermemory.ai)          │
│  or self-hosted instance                │
└───────┬────────────────────────┬───────┘
        │                        │
┌───────▼───────┐        ┌──────▼──────┐
│  Vector DB    │        │  PostgreSQL  │
│  (Qdrant/     │        │  (用户画像、  │
│   Pinecone)   │        │   元数据)    │
└───────────────┘        └─────────────┘

5.2 多租户隔离

如果你构建 SaaS 应用，需要为多个租户隔离记忆：

// 方案 A：使用 containerTag 前缀
const containerTag = `tenant_${tenantId}_user_${userId}`;

// 方案 B：使用多个 API Key（每个租户一个）
const client = new Supermemory({
  apiKey: tenant.apiKey,  // 每个租户独立的 API Key
});

// 方案 B 更安全，因为：
// 1. 租户之间完全隔离（即使 containerTag 猜错也访问不了）
// 2. 可以独立计费、限流
// 3. 符合 API 提供商的最佳实践

5.3 监控与告警

Supermemory 提供了健康的监控指标：

// 检查 API 健康状况
const health = await client.health.check();
console.log(health.status);  // "ok" | "degraded" | "down"

// 获取使用统计
const stats = await client.usage.getStats();
console.log({
  memoriesCount: stats.memoriesCount,
  documentsCount: stats.documentsCount,
  storageUsed: stats.storageUsed,
  apiCallsToday: stats.apiCallsToday,
});

建议设置的告警：

• API 错误率 > 5%
• 搜索延迟 P95 > 200ms
• 存储使用 > 90% 配额

第六部分：基准测试与竞品对比

6.1 基准测试结果

Supermemory 在三个主要的 AI 记忆基准测试中均排名第一：

LongMemEval（长期记忆与知识更新）：

• Supermemory: 81.6%
• 第二名: 76.3%
• 测试内容：多轮对话中的事实回忆、知识更新、矛盾处理

LoCoMo（扩展对话中的事实回忆）：

• Supermemory: #1
• 测试内容：单跳/多跳推理、时间推理、对抗性查询

ConvoMem（个性化与偏好学习）：

• Supermemory: #1
• 测试内容：用户偏好提取、偏好更新、跨会话一致性

6.2 与竞品对比

6.3 使用 MemoryBench 进行独立评测

Supermemory 提供了开源的基准测试框架 MemoryBench，可以让你独立验证各记忆提供商的性能：

# 安装 MemoryBench
npx skills add supermemoryai/memorybench

# 运行基准测试
bun run src/index.ts run -p supermemory -b longmemeval -j gpt-4o -r my-run

支持的基准测试：

• longmemeval：长期记忆
• locomo：对话推理
• convomem：个性化
• custom：自定义测试集

第七部分：真实世界应用案例

7.1 AI 编程助手（如 Claude Code、Cursor）

问题：AI 编程助手每次新会话都忘记你的项目上下文、编码偏好、历史决策。

Supermemory 解决方案：

// 在 IDE 插件中集成
async function onConversationMessage(message: string, projectContext: ProjectContext) {
  // 1. 提取记忆（异步，不阻塞用户）
  client.add({
    content: message,
    containerTag: `user_${userId}_project_${projectId}`,
    metadata: {
      filePath: currentFile,
      gitBranch: currentBranch,
    },
  });

  // 2. 获取上下文（同步，注入到 AI 提示）
  const { profile, searchResults } = await client.profile({
    containerTag: `user_${userId}_project_${projectId}`,
    q: message,
  });

  // 3. 构建系统提示
  const systemPrompt = `
你是用户的编程助手。以下是关于这个用户和项目的已知信息：

## 用户画像
${profile.static.join('\n')}

## 最近活动
${profile.dynamic.join('\n')}

## 相关历史对话
${searchResults.map(r => r.content).join('\n')}

请基于以上上下文回答用户的问题。
`;

  return generateAIResponse(message, systemPrompt);
}

效果：

• 用户周一讨论了认证模块设计
• 周三再问"继续昨天的认证模块"
• AI 自动记得：用的是 JWT + Redis Session，遇到了 CORS 问题

7.2 客户支持聊天机器人

问题：客户每次来咨询都要重新解释问题，体验极差。

Supermemory 解决方案：

async function handleCustomerQuery(customerId: string, message: string) {
  // 1. 获取客户历史
  const { profile, searchResults } = await client.profile({
    containerTag: `customer_${customerId}`,
    q: message,
  });

  // 2. 检查是否是重复问题
  const similarIssues = searchResults.filter(r => r.source === "memory");
  if (similarIssues.length > 0) {
    return `您之前问过类似问题。当时的回答是：${similarIssues[0].content}`;
  }

  // 3. 正常处理新问题
  const response = await generateSupportResponse(message, profile);

  // 4. 存储本次对话
  await client.add({
    content: `客户问题：${message}\n回答：${response}`,
    containerTag: `customer_${customerId}`,
  });

  return response;
}

效果：

• 客户第二次来问"我的订单什么时候到？"
• AI 自动记得：客户昨天问过，订单号 #12345，预计 3 天到达
• AI 直接回答："您的订单 #12345 预计后天到达，与昨天答复一致"

7.3 个人 AI 助手（如 Siri、Google Assistant）

问题：语音助手没有长期记忆，每次都要重复偏好设置。

Supermemory 解决方案：

// 在语音助手后端集成
async function processVoiceCommand(userId: string, command: string) {
  // 1. 获取用户偏好
  const { profile } = await client.profile({
    containerTag: `user_${userId}`,
  });

  // 2. 个性化响应
  const response = await generateVoiceResponse(command, {
    userPreferences: profile.static,
    recentActivity: profile.dynamic,
  });

  // 3. 提取新偏好
  if (command.includes("我喜欢")) {
    await client.add({
      content: command,
      containerTag: `user_${userId}`,
      type: "preference",
    });
  }

  return response;
}

效果：

• 用户："导航回家"
• AI："好的，使用您偏好的地图应用 Gaode（上次您说 Google Maps 在中国不好用）"
• 用户："播放音乐"
• AI："正在播放您常听的 Jazz 播放列表"

第八部分：未来展望与社区生态

8.1 Roadmap 亮点

根据 Supermemory 的公开 Roadmap，2026 年下半年将推出：

1. 协作记忆：多个用户共享同一记忆空间（适用于团队协作）
2. 记忆导出/导入：将记忆迁移到其他系统（开放生态）
3. 本地化部署增强：支持完全离线运行（隐私敏感场景）
4. 更多连接器：Slack、Discord、Jira、Confluence 等
5. 记忆可视化：图谱可视化工具（便于调试和理解）

8.2 社区与贡献

Supermemory 是开源项目，欢迎贡献：

• GitHub: https://github.com/supermemoryai/supermemory
• Discord: https://supermemory.link/discord
• Twitter: @supermemory

贡献方式：

• 提交 Issue（Bug 报告、功能建议）
• 提交 PR（代码贡献）
• 编写插件（集成到其他 AI 工具）
• 改进文档

总结

Supermemory 不是又一个向量数据库，而是一个完整的 Memory Engine（记忆引擎）。它的核心价值在于：

1. 自动化：自动提取、更新、忘记，无需手动管理
2. 个性化：每用户独立记忆空间，真正理解"你是谁"
3. 智能化：处理矛盾、时间线、临时事实，不像 RAG 那样"死记硬背"
4. 集成友好：支持所有主流 AI 框架，MCP 协议，REST API
5. 性能卓越：在三大基准测试中排名第一，搜索延迟 ~50ms

如果你正在构建需要"记住用户"的 AI 应用，Supermemory 是目前最完整的解决方案。

参考资源

• 官方文档: https://supermemory.ai/docs
• GitHub 仓库: https://github.com/supermemoryai/supermemory
• 基准测试详情: https://supermemory.ai/docs/memorybench/overview
• MCP 服务器文档: https://supermemory.ai/docs/supermemory-mcp/mcp
• Discord 社区: https://supermemory.link/discord

本文撰写于 2026 年 6 月，基于 Supermemory v2.0+。API 可能随版本更新而变化，请以官方文档为准。

字数统计：约 8,500 字