supermemory

[!info] 知识库定位 这是一篇 工具评估 / 使用笔记，重点回答”它值不值得用、怎么用、什么时候不用”。 底层概念链接到 related_concepts；真实项目落地链接到 used_in_projects。

一句话：AI 的记忆层 API，让 AI 应用拥有跨对话的长期记忆能力，在 LongMemEval、LoCoMo、ConvoMem 三大基准测试中排名第一。

为什么需要它

传统 AI 应用在每次对话后都会”失忆”——用户昨天说的偏好、上周讨论的项目、上个月的决策，全部丢失。开发者要么自己搭建复杂的向量数据库 + Embedding 管道，要么用 RAG 但效果有限（RAG 只做语义相似度搜索，不理解时间维度和用户状态变化）。Supermemory 提供了一个开箱即用的记忆 API，自动从对话中提取事实、构建用户画像、处理知识更新和矛盾、遗忘过期信息，在正确的时间提供正确的上下文。

核心优势

• 三大基准测试 #1：LongMemEval 81.6%、LoCoMo、ConvoMem 均排名第一，有硬数据支撑
• Memory ≠ RAG：理解时间维度——“我刚搬到上海”会自动覆盖”我住在北京”，RAG 做不到这点
• 一体化上下文栈：记忆 + RAG + 用户画像 + 连接器 + 文件处理，一个 API 搞定
• 自动遗忘机制：临时性事实（“我明天有考试”）过期后自动遗忘，噪音不会变成永久记忆
• 用户画像 API：一次调用 ~50ms，获取静态事实 + 动态上下文，直接注入 system prompt

性能表现

官方有公开 benchmark 数据，且提供了开源基准测试框架 MemoryBench：

快速上手

安装

# Python
pip install supermemory

# TypeScript/Node.js
npm install supermemory

# 设置 API Key（在 console.supermemory.ai 免费获取）
export SUPERMEMORY_API_KEY="YOUR_API_KEY"

最小示例（Python）

from supermemory import Supermemory

client = Supermemory()
USER_ID = "user_123"

# 对话内容
conversation = [
    {"role": "user", "content": "我喜欢 Python，讨厌 Java"},
    {"role": "user", "content": "推荐一门编程语言？"}
]

# 获取用户画像 + 相关记忆
profile = client.profile(
    container_tag=USER_ID,
    q=conversation[-1]["content"]
)

# 拼接上下文
context = f"""
静态画像: {''.join(profile.profile.static)}
动态画像: {''.join(profile.profile.dynamic)}
相关记忆: {''.join(r.get("memory", "") for r in profile.search_results.results)}
"""

# 注入到 LLM 的 system prompt
messages = [
    {"role": "system", "content": f"用户上下文:\n{context}"},
    *conversation
]

# 存储对话供未来使用
client.add(
    content="\n".join(f"{m['role']}: {m['content']}" for m in conversation),
    container_tag=USER_ID
)

配置要点

1. container_tag：用户/会话隔离标签，类似多租户的 namespace
2. threshold：搜索结果相关性阈值（0-1），如 threshold=0.7 过滤低相关结果
3. Connectors：配置 Google Drive/Gmail/Notion/GitHub 等外部数据源自动同步
4. Projects：项目标签，分离工作/个人/不同客户的上下文

适用场景

适合：

• AI 助手/聊天机器人需要记住用户偏好和历史
• 编程 Agent 需要跨会话记住项目上下文（已内置 Claude Code/Cursor 插件）
• 个性化推荐系统需要理解用户长期行为变化
• 客服系统需要追踪用户问题历史和解决状态
• 知识管理工作流（个人第二大脑）

不适合：

• 纯文档检索场景（只需要 RAG，不需要用户记忆）
• 对延迟极度敏感的实时系统（虽然 <300ms，但仍是网络调用）
• 需要完全离线/本地运行的场景（依赖 Supermemory 云服务）
• 简单的单轮问答应用（记忆的价值在于多轮/跨会话）

已知坑 & 注意事项

[!warning] 云服务依赖 核心记忆引擎是云服务，不是纯本地运行。虽然 SDK 是开源的，但数据存储和处理在 Supermemory 云端。

• API Key 必需：即使自托管也需要注册获取 key
• 定价模型：按 token 计费，高频使用需要预估成本
• 数据主权：用户对话数据会上传到 Supermemory 服务器，敏感场景需评估合规性
• Breaking Changes：v3 API 是当前版本，文档中仍有 v2 迁移相关内容，注意版本匹配

竞品对比

选择建议：

• 选 supermemory：需要开箱即用的完整记忆方案，重视 benchmark 性能，接受云服务
• 选 Mem0：需要本地部署 + 知识图谱能力，对数据主权要求高
• 选 Zep：需要时序知识图谱，适合合规审计等需要”双时态”的场景
• 选 OMEGA/Letta：需要完全本地、零外部依赖的方案

生态 & 社区

• 维护状态：非常活跃，1645+ commits，持续更新中
• 文档质量：好，有完整的 Quickstart、API Reference、Concepts 文档、Cookbook
• 周边生态：
  • MCP Server（Claude Desktop/Cursor/Windsurf/VS Code）
  • Vercel AI SDK 集成
  • LangChain/LangGraph 集成
  • OpenAI Agents SDK 集成
  • Mastra/Agno/n8n 集成
• 社区活跃度：有 Discord 社区，GitHub Issues 响应及时

引入评估

结论：推荐 — 如果你在构建需要长期记忆的 AI 应用，supermemory 是目前性能最好、上手最简单的方案。三大 benchmark #1 的成绩不是吹的，单 API 集成的设计也很务实。唯一需要考虑的是云服务依赖和数据主权问题。

推荐引入版本：latest（npm: supermemory，pypi: supermemory）

相关链接

前置知识：RAG · 向量数据库 · Embedding向量 竞品：Mem0 · Zep 使用场景：AI Agent · 个性化推荐 · 知识管理 底层概念：记忆引擎 · 用户画像 · 时序知识图谱

• 官方文档
• Quickstart
• Changelog
• GitHub
• Console
• Memory vs RAG 概念解析

个人备注

{留白，供后续补充实际使用心得}