Supermemory 深度拆解：从文档摄入到画像注入，记忆何时真正生效？

Memory Agent 深度拆解 · 第 8 / 8 篇。查看系列目录。

一段对话上传成功，文档状态也变成 done。你马上读取用户画像，却没看到刚刚更新的偏好。

这种现象不一定说明数据丢了。Supermemory 的公开协议将文档索引与后续记忆形成分成不同阶段。理解这件事，才能知道“处理完成”究竟完成了什么。

这篇文章同时看两层：官方文档公开的服务行为，以及仓库里能直接检查的 SDK 上下文处理代码。核心服务内部实现没有被本文完整审计，不能把文档说明当作全部源码证明。

资料截点为 2026 年 9 月 22 日，仓库固定到 57b430b5b6a19，未执行本地或云端测试。

1. 一份输入，可能形成三种输出

Supermemory 接收的 document 是原始输入，可以来自聊天、文件或其他资料。处理之后，需要区分 document chunks、memories 与 profile。固定版本文档：处理流程

片段保留检索原始材料的入口；记忆表达从材料中提取的事实及其联系；画像则提供一个较紧凑、经常使用的背景。

比如一次对话包含“请叫我阿林”和“正在排查支付回调”。称呼适合较稳定的背景，正在处理的任务适合近期状态，具体回调日志则更适合按问题检索。

这三个层次使用频率不同，更新方式也不必相同。应用不能只盯着上传文档这一项状态，就推断其他层已经同步完成。

2. done 为什么不一定等于图记忆就绪？

公开文档将文档路径分为 queued、extracting、chunking、embedding、indexing、done 等阶段。done 表示文档片段路径可搜索，但图事实的提取和组织还涉及 dreaming。

默认 dynamic 模式会将相关材料组合起来形成记忆，因此后续工作可能延续到文档 done 之后。instant 则针对当前文档单独、尽快执行相应记忆处理，文档也提示其操作成本不同。固定版本文档：Dreaming

可以用两条进度线理解：

文档线：接收 → 解析 → 分块 → 索引 → 文档可查
记忆线：整理相关材料 → 提取与关联 → 图记忆与画像逐步更新

这是对公开协议的概念归纳，不是已验证的内部调度图。

对接时，我会先确定需求：下一步要查原始片段，还是必须看到新偏好？两者的等待条件不同。若业务必须读到刚写入的记忆，需要明确验证对应模式和完成信号，而不是固定 sleep 两秒碰碰运气。

3. updates、extends、derives 分别意味着什么？

官方图记忆说明将关系分成三种方向：新事实更新旧状态，补充事实扩展已有信息，或者从已有材料形成推导。固定版本文档：图记忆

“现在负责支付项目”可以替代旧岗位状态；“主要处理跨境支付”是补充；“可能关注国际结算”则是推论。

把三者分开非常必要。推论对个性化可能有用，但不能换个措辞就升级成“用户亲口确认过”。

如果用它做长期助理，我会让高影响的推断有可复核入口，尤其在信息会影响后续操作时。记忆的强大不只在于能联系起来，还在于保留“这条联系到底是什么性质”。

图服务自动维护关系，也不等于应用可以把任意业务约束交给它。订单状态、权限授予等事实，仍应由相应的可信系统记录决定。

4. 为什么画像不能完全被语义搜索替代？

用户要求“以后用中文回答”，几周后问一个英文错误码。这个问题与语言偏好未必语义接近，但偏好仍然应该影响回答。

画像解决的正是这种“与当前问题不相似，却长期相关”的背景。官方区分 static 与 dynamic 内容，也支持进一步组织画像；它们与按问题寻找细节的 search 互补。固定版本文档：用户画像

公开 SDK 的 convertProfileToMarkdown() 把静态与动态部分分别格式化，再由模板组织成可以进入提示的记忆文本。源码：提示构造

画像的工程目标应是让关键背景稳定可用，而不是把用户所有信息都常驻。越常驻的内容，越值得压缩、确认和及时纠正，因为它会影响大量后续回答。

5. 注入上下文时，一个小问题会越来越大

接入记忆中间件时，最简单的办法是把结果追加到 system prompt。

第一轮追加一份，第二轮再追加一份。经过工具调用循环和多轮聊天，同一批记忆可能越积越多，旧偏好也被重复保留。

Supermemory 公开代码为自有记忆块设置了明确边界，提供 strip、wrap 和 replace 等函数：先移除中间件先前拥有的块，再插入本次内容，同时保留调用方原来的指令。源码：memory-context

这使上下文更新有了明确的所有权：中间件可以替换自己管理的区域，业务提示仍由调用方管理。

它也会转义检索文本中仿冒自身标签的内容，避免材料轻易闭合或嵌套中间件的边界。但标签转义不是完整的提示注入防御，readonly 字样也不是模型执行层的强制权限。取回的内容仍然需要当作数据处理。

6. 缓存命中了，为什么还可能用到旧记忆？

公开工具包有一个 LRU 记忆缓存，目的包括在工具循环中减少重复请求。其 key 由 containerTag、threadId、模式和规范化后的消息文本组成，基础类还提供 clear 等操作。源码：MemoryCache

值得注意的是，基础 key 没有天然包含“记忆版本号”。它能否跨轮保持正确，取决于调用方的实例生命周期和清理策略。

所以不能只看注释写着 per-turn，就断言任何集成都绝不会复用旧结果。应沿具体 wrapper 检查何时创建缓存、何时清理，以及新记忆写入后会不会重新获取。

这是一项代码审阅问题，不是本文已经复现的缓存故障。一个很直接的测试是：连续两轮提同样的问题，在中间更新画像，观察第二轮实际使用的上下文。

7. containerTag 与 metadata 的职责不同

官方多租户文档将 containerTag 用作隔离范围，将 metadata 用作范围内的分类与筛选，并说明可通过受限凭据约束可访问的容器。固定版本文档：多租户

映射到产品里，前者可能对应用户或组织，后者表达工单状态、材料来源等属性。

如果后端持有高权限密钥，就仍应从可信登录身份推导 containerTag，不能直接信任客户端传入的标签。隔离机制需要被正确调用，才能形成实际授权边界。

同样，一个命名上带冒号的标签，不自动证明应用已经实现完整的组织层级权限。具体权限继承与共享规则需要依照产品接口和自己的租户模型来定义。

8. Local 与 Enterprise，要比较实际组成

当前官方文档已经介绍本地运行，不能继续笼统地说它只能用云服务。Local 与 Enterprise 在认证、团队控制、连接器、模型选择、可观测性和规模上存在差异。固定版本文档：Local 与 Enterprise

文档将 Local 描述为开源、本地单机形态；本文实际检查的是公共仓库中的文档与接入代码，没有完成本地核心引擎的构建复现或分发物审计。因此不能从 SDK 可读，直接推出全部生产内部实现都已核验。

API 兼容也不意味着记忆质量与成本完全一致。自带模型与托管专用模型的抽取效果，应在相同样本上测，而不是凭接口名称判断。

9. 一次完整验收应该穿过哪些边界？

我会记录同一条偏好从上传到文档可查、图记忆可查、画像更新，再到模型实际输入的全过程。

随后修改偏好、重复相同问题，检查缓存和注入块是否同步更新。删除时，也要检查文档、派生记忆、画像和应用缓存的实际行为。

Supermemory 的启发，是把记忆从存储服务扩展成一整套应用接入体验。越接近“一次调用就能用”，接入者越需要知道每个阶段的保证是什么。

记忆真正生效的时刻，是正确的信息进入了当前任务，而不只是上传接口返回成功。

系列阅读

返回系列目录与全景总览。

上一篇：MemOS 深度拆解。