为AI Agent构建可扩展记忆层：Supermemory的Memory API与混合检索架构实践

AI Agent 的 "失忆" 问题一直是制约其智能化的关键瓶颈。当前大多数 Agent 在每次对话结束后便丢失上下文，无法形成持续的用户认知。Supermemory 作为在 LongMemEval、LoCoMo、ConvoMem 三大记忆基准测试中均排名第一的解决方案，提供了一套完整的 Memory API 与混合检索架构，为开发者构建可扩展的长期记忆层提供了工程化路径。

记忆与 RAG 的本质区别

传统 RAG 系统仅提供文档片段的语义检索，对所有用户返回相同结果，缺乏时序演化和个性化能力。而 Supermemory 的核心设计理念是 "记忆不是 RAG"—— 它提取并追踪关于用户的事实随时间的变化，能够理解 "我刚搬到旧金山" 取代 "我住在纽约" 的语义更新。

这种差异体现在架构层面：RAG 是状态无关的文档检索，Memory 是状态相关的知识图谱。Supermemory 通过将两者结合，在单次查询中同时返回知识库文档和用户个性化上下文，实现了真正的上下文感知。

图内存模型：三层关系构建知识演化

Supermemory 的底层采用图内存结构，新记忆与现有记忆通过三种关系类型自动关联：

UPDATE 关系处理信息变更。当用户从 "在 Google 担任软件工程师" 变为 "在 Stripe 担任产品经理" 时，系统通过 UPDATE 关系标记最新状态，同时保留历史轨迹。查询时优先返回isLatest标记的记忆，但历史版本仍可通过特定查询获取。

EXTENDS 关系实现信息丰富。当补充 "专注于支付基础设施并领导 5 人团队" 时，该记忆通过 EXTENDS 关联到职位记忆，两者同时有效，为检索提供更丰富的上下文。

DERIVES 关系支持推理推断。系统从 "是 Stripe 的 PM" 和 "经常讨论支付 API 与欺诈检测" 推断出 "可能负责 Stripe 核心支付产品"， surfaced 用户未明确陈述的洞察。

这种图结构使记忆具备天然的演化能力，无需人工定义关系或清理过期数据。

Memory API 设计：极简抽象与灵活作用域

Supermemory 的 API 设计遵循 "一次调用，完整上下文" 的原则。核心接口包括：

// 存储记忆
await client.add({
  content: "用户偏好TypeScript和函数式编程",
  containerTag: "user_123",  // 作用域隔离
});

// 获取用户档案+相关记忆
const { profile, searchResults } = await client.profile({
  containerTag: "user_123",
  q: "用户的编程风格偏好是什么？",
});
// profile.static → ["热爱TypeScript", "偏好函数式模式"]
// profile.dynamic → ["正在进行API集成工作"]

containerTag参数是设计关键，它支持按用户、项目、组织等多维度隔离记忆上下文。企业场景下可为不同客户创建独立容器，个人应用则可区分工作与生活场景。

用户档案采用双池设计：static池存储长期稳定的事实（职位、偏好、技能），dynamic池存储近期活动（正在进行的项目、临时状态）。这种分离使 Agent 既能掌握用户本质特征，又能感知当前上下文，单次调用约 50ms 即可完成检索。

混合检索模式：向量 + 图的协同查询

Supermemory 提供三种搜索模式，开发者可按场景选择：

Hybrid 模式（默认） 同时检索文档知识库和用户记忆，适用于需要结合通用知识与个人上下文的场景。例如询问 "如何部署" 时，既返回部署文档（RAG）又包含用户的部署偏好（Memory）。

Memories 模式 仅搜索用户记忆，适用于纯个性化查询。Documents 模式 则专注于知识库文档检索，支持元数据过滤和上下文分块。

混合检索的实现依赖于统一的语义索引层。系统对输入内容进行智能分块，构建语义理解图谱，在查询时通过向量相似度与图遍历的结合，精确定位最相关的上下文片段。

自动记忆管理：遗忘与矛盾处理

长期记忆系统必须解决信息过时和矛盾问题。Supermemory 实现了三层自动管理机制：

时间遗忘：临时性事实（"明天有考试"、"今天下午 3 点与 Alex 开会"）在时间点过后自动失效，避免记忆膨胀。

矛盾解决：当新事实与旧记忆冲突时，UPDATE 关系确保检索返回最新信息，同时保留历史版本供追溯。

噪声过滤：闲聊内容不会转化为永久记忆，系统通过内容重要性评估自动筛选。

记忆类型也被自动区分：Facts（事实）持续存在直至被更新，Preferences（偏好）随重复强化，Episodes（事件）随时间衰减除非具有显著意义。

工程集成：从 MCP 到框架适配

Supermemory 提供多层次的集成方案。对于终端用户，MCP（Model Context Protocol）服务器支持一键接入 Claude Desktop、Cursor、Windsurf 等主流客户端，安装命令如下：

npx -y install-mcp@latest https://mcp.supermemory.ai/mcp --client claude --oauth=yes

对于开发者，官方提供 Vercel AI SDK、LangChain、LangGraph、OpenAI Agents SDK、Mastra 等框架的适配器，实现 "零配置" 接入。以 Vercel AI SDK 为例：

import { withSupermemory } from "@supermemory/tools/ai-sdk";
const model = withSupermemory(openai("gpt-4o"), { 
  containerTag: "user_123",
  customId: "conv-1" 
});

可落地参数清单

基于 Supermemory 的设计，构建 AI Agent 记忆层时可参考以下参数配置：

维度	推荐配置	说明
作用域隔离	`containerTag`按用户 + 项目组合	支持多租户与场景分离
搜索模式	默认`hybrid`，个性化场景切`memories`	平衡知识广度与个性化深度
档案注入	每次对话开始时调用`profile`	约 50ms 开销，提升上下文感知
记忆类型	依赖自动分类，关键偏好手动标记	减少人工标注成本
内容分块	使用 AST 感知分块（代码）/ 语义分块（文档）	多模态内容自动处理
过期策略	依赖自动遗忘，关键临时信息显式标注时间	避免手动清理

总结

Supermemory 通过图内存模型、三层关系类型、混合检索架构和自动记忆管理，为 AI Agent 提供了一套生产级的 Memory API 解决方案。其核心设计哲学 ——"记忆不是 RAG"—— 指引开发者从文档检索思维转向知识演化思维。

对于正在构建 AI Agent 的开发者，建议从containerTag作用域设计和profile档案注入入手，逐步引入混合检索与自动遗忘机制。记忆层的完善将显著提升 Agent 的连续对话能力与用户个性化体验。

资料来源

Supermemory GitHub 仓库: https://github.com/supermemoryai/supermemory
Supermemory 官方文档: https://supermemory.ai/docs
Supermemory 图内存概念文档: https://supermemory.ai/docs/concepts/graph-memory

ai-systems

内容声明：本文无广告投放、无付费植入。

如有事实性问题，欢迎发送勘误至 i@hotdrydog.com。