随着开发者在 Cloudflare 上构建日益复杂的 代理，他们面临的最大挑战之一是在正确的时间将正确的信息放入上下文中。模型生成结果的质量直接与其运行的上下文质量相关，但即使上下文窗口大小增长到超过一百万（1M）个 token，上下文腐烂 仍然是一个未解决的问题。两种糟糕的选择之间会出现自然的张力：将所有内容保留在上下文中并观察质量下降，或者激进地修剪并冒着丢失代理稍后所需信息的风险。
今天，我们宣布 Agent Memory 的私有测试版，这是一种托管服务，可从代理对话中提取信息，并在需要时提供这些信息，而不会填满上下文窗口。
它为 AI 代理提供了持久记忆，使其能够记住重要内容，忘记无关内容，并随着时间的推移变得更智能。在这篇文章中，我们将解释它的工作原理——以及它能帮助你构建什么。
代理记忆的现状
代理记忆是 AI 基础设施中发展最快的领域之一，新的开源库、托管服务和研究原型几乎每周都会推出。这些产品在存储内容、检索方式以及设计目标代理类型方面差异很大。像 LongMemEval、LoCoMo 和 BEAM 这样的基准测试提供了有用的同类比较，但它们也容易构建出针对特定评估 过拟合 并在生产中崩溃的系统。
现有产品在架构上也存在差异。有些是托管服务，在后台处理提取和检索；有些是自托管框架，你需要自己运行记忆管道。有些提供受限的、专用 API，将记忆逻辑排除在代理的主上下文之外；有些则让模型直接访问数据库或文件系统，并自行设计查询，将 token 消耗在存储和检索策略上，而不是实际任务上。有些试图将所有内容塞进上下文窗口，如果需要则在多个代理之间分区，而有些则使用检索仅呈现相关内容。
Agent Memory 是一种托管服务，具有固执的 API 和基于检索的架构。我们仔细考虑了替代方案，并相信这种组合是大多数生产工作负载的正确默认选择。更严格的摄取和检索管道优于让代理直接访问文件系统。除了改善成本和性能外，它们还为生产中所需的复杂推理任务（如时间逻辑、替代和指令遵循）提供了更好的基础。我们可能会在未来为编程查询公开数据，但我们预计这对边缘情况有用，而不是常见情况。
我们构建 Agent Memory 是因为我们在平台上看到的工作负载暴露了现有方法未能完全解决的差距。针对真实代码库和生产系统运行数周或数月的代理需要随着增长而保持有用的记忆——而不仅仅是在可能完全适合较新模型上下文窗口的干净基准数据集上表现良好的记忆。
它们需要快速摄取。它们需要不阻塞对话的检索。而且它们需要在保持每次查询成本合理的模型上运行。
Agent Memory 将记忆存储在配置文件中，通过名称进行寻址。配置文件提供多种操作：摄取对话、记住特定内容、回忆所需信息、列出记忆或遗忘特定记忆。摄取是批量路径，通常在框架压缩上下文时调用。记住用于模型当场存储重要信息。回忆运行完整的检索流程并返回综合答案。
export default {
async fetch(request: Request, env: Env): Promise<Response> {
// 获取一个配置文件——跨会话、代理和用户共享的隔离内存存储
const profile = await env.MEMORY.getProfile("my-project");
// 摄取——从对话中提取记忆（通常在压缩时调用）
await profile.ingest([
{ role: "user", content: "使用 React 和 TypeScript 设置项目。" },
{ role: "assistant", content: "已完成。为 Workers 搭建了一个 React + TS 项目。" },
{ role: "user", content: "使用 pnpm，而不是 npm。并且默认使用暗色模式。" },
{ role: "assistant", content: "收到——使用 pnpm 并默认暗色模式。" },
], { sessionId: "session-001" });
// 记住——显式存储单条记忆（模型直接使用工具）
const memory = await profile.remember({
content: "4月10日事件后，API 速率限制已提高至每个区域每秒 10,000 次请求。",
sessionId: "session-001",
});
// 回忆——检索记忆并获取综合答案
const results = await profile.recall("用户偏好哪个包管理器？");
console.log(results.result); // "用户偏好 pnpm 而非 npm。"
return Response.json({ ok: true });
},
};
Agent Memory 可通过任何 Cloudflare Worker 的绑定进行访问。对于在 Workers 之外运行的 agent，也可以按照与其他 Cloudflare 开发者平台 API 相同的模式，通过 REST API 进行访问。如果你正在使用 Cloudflare Agents SDK 构建，Agent Memory 服务可以无缝集成，作为 Sessions API 的 memory 部分 中处理压缩、记忆和搜索记忆的参考实现。
你可以用它构建什么
Agent Memory 旨在适用于多种 agent 架构：
单个 agent 的记忆。 无论你是使用 Claude Code 或 OpenCode 等编码 agent（有人类参与循环），使用 OpenClaw 或 Hermes 等自托管 agent 框架代表你行动，还是连接 Anthropic 的托管 agent 等托管服务，Agent Memory 都可以作为持久记忆层，无需对 agent 的核心循环进行任何更改。
自定义 agent 框架的记忆。 许多团队正在构建自己的 agent 基础设施，包括在无人参与循环的情况下自主运行的后台 agent。Ramp Inspect 是一个公开示例；Stripe 和 Spotify 也描述了类似的系统。这些框架也可以受益于为其 agent 提供跨会话持久化并在重启后仍然存在的记忆。
跨 agent、人员和工具共享的记忆。 一个记忆配置文件不必属于单个 agent。一个工程师团队可以共享一个记忆配置文件，使得一个人编码 agent 学到的知识对所有人都可用：编码规范、架构决策、目前存在于人们头脑中或在上下文被修剪时丢失的隐性知识。一个代码审查机器人和一个编码 agent 可以共享记忆，使得审查反馈影响未来的代码生成。你的 agent 积累的知识不再短暂，而是成为持久的团队资产。
虽然搜索是记忆的一个组成部分，但 agent 搜索和 agent 记忆解决的是不同的问题。AI Search 是我们用于在非结构化和结构化文件中查找结果的原始工具；Agent Memory 用于上下文回忆。Agent Memory 中的数据不以文件形式存在；它源自会话。一个 agent 可以同时使用两者，并且它们被设计为协同工作。
随着 agent 变得越来越强大，越来越深入地嵌入业务流程，它们积累的记忆变得真正有价值——不仅是作为操作状态，而且是作为需要实际工作才能建立的机构知识。我们听到客户越来越担心将该资产与单一供应商绑定意味着什么，这是合理的。agent 学得越多，如果记忆无法随之迁移，转换成本就越高。
Agent Memory 是一项托管服务，但你的数据属于你。每个记忆都可以导出，我们致力于确保你的 agent 在 Cloudflare 上积累的知识可以在你的需求变化时随你离开。我们认为赢得长期信任的正确方式是让离开变得容易，并持续构建足够好的东西，让你不想离开。
要理解上述 API 背后发生了什么，有助于分解 agent 如何管理上下文。一个 agent 有三个组件：
一个 框架，驱动对模型的重复调用，促进工具调用，并管理状态。
一个 模型，接收上下文并返回补全。
状态，包括当前上下文窗口以及上下文之外的信息：对话历史、文件、数据库、记忆。
代理上下文生命周期中的关键时刻是压缩，此时框架决定缩短上下文以保持在模型限制内或避免上下文腐烂。如今，大多数代理会永久丢弃信息。Agent Memory 在压缩时保留知识，而不是丢失它。
Agent Memory 通过两种方式融入此生命周期：
压缩时的批量摄取。 当框架压缩上下文时，它将对话发送到 Agent Memory 进行摄取。摄取从消息历史中提取事实、事件、指令和任务，与现有记忆去重，并将其存储为记忆以供将来检索。
模型的直接工具使用。 模型获得直接与记忆交互的工具，包括回忆（搜索记忆以获取特定信息）的能力。模型还可以记住（基于重要内容显式存储记忆）、忘记（将记忆标记为不再重要或真实）和列出（查看存储了哪些记忆）。这些是轻量级操作，不需要模型设计查询或管理存储。主代理绝不应在存储策略上消耗上下文。它看到的工具表面被刻意限制，以便记忆不影响实际任务。
当对话到达进行摄取时，它经过一个多阶段流水线，提取、验证、分类和存储记忆。
第一步是确定性 ID 生成。每条消息获得一个内容寻址 ID——会话 ID、角色和内容的 SHA-256 哈希，截断为 128 位。如果同一对话被摄取两次，每条消息解析为相同的 ID，使重新摄取具有幂等性。
接下来，提取器并行运行两遍。完整遍将消息分块为大约 10K 字符，重叠两条消息，并同时处理最多四个块。每个块获得一个结构化转录，包含角色标签、相对日期解析为绝对日期（"昨天"变为"2026-04-14"）以及用于来源溯源的索引。对于较长的对话（9 条以上消息），详细遍与完整遍并行运行，使用重叠窗口，专门关注提取具体值，如名称、价格、版本号和实体属性，这些是宽泛提取容易遗漏的。然后合并两个结果集。
下一步是根据源转录验证每个提取的记忆。验证器运行八项检查，涵盖实体身份、对象身份、位置上下文、时间准确性、组织上下文、完整性、关系上下文以及推断的事实是否确实得到对话支持。每个项目相应通过、修正或丢弃。
然后，流水线将每个验证后的记忆分类为四种类型之一。
事实代表当前为真的、原子性的、稳定的知识，如"项目使用 GraphQL"或"用户偏好暗色模式。"
事件捕获在特定时间发生的事情，如部署或决策。
指令描述如何做某事，例如程序、工作流程、操作手册。
任务跟踪当前正在处理的工作，并且设计为临时性的。
事实和指令都有键。每个事实和指令都会获得一个标准化的主题键，当新记忆与现有记忆具有相同键时，旧记忆会被取代而非删除。这会创建一个版本链，其中包含从旧记忆指向新记忆的前向指针。任务被完全排除在向量索引之外以保持其精简，但通过全文搜索仍然可以发现。
最后，所有内容都使用 INSERT OR IGNORE 写入存储，以便内容寻址的重复项被静默跳过。在向测试框架返回响应后，后台向量化异步运行。嵌入文本将分类期间生成的 3-5 个搜索查询前置到记忆内容本身，弥合了记忆写入方式（声明式：“用户偏好深色模式”）与搜索方式（疑问式：“用户想要什么主题？”）之间的差距。被取代的记忆的向量与新插入操作并行删除。
当智能体搜索记忆时，查询会经过一个独立的检索管道。在开发过程中，我们发现没有单一的检索方法对所有查询都最佳，因此我们并行运行多种方法并融合结果。
第一阶段并发运行查询分析和嵌入。查询分析器生成排序后的主题键、带同义词的全文搜索词以及 HyDE（假设文档嵌入），即一个以问题答案形式表述的声明性语句。此阶段直接嵌入原始查询，两个嵌入都用于下游。
在下一阶段，五个检索通道并行运行。使用 Porter 词干提取 的全文搜索处理关键词精确性，适用于你知道确切术语但不知道周围上下文的查询。精确事实键查找返回查询直接映射到已知主题键的结果。原始消息搜索通过全文搜索直接查询存储的对话消息，用于未分类的对话片段，这些片段作为安全网，捕捉提取管道可能泛化掉的确切细节。直接向量搜索使用嵌入查询查找语义相似的记忆。HyDE 向量搜索查找与答案外观相似的记忆，这通常会呈现直接嵌入遗漏的结果——特别是对于问题和答案使用不同词汇的抽象或多跳查询。
在第三阶段也是最后阶段，来自所有五个检索通道的结果使用倒数排名融合（RRF）合并，每个结果根据其在给定通道中的排名获得加权分数。事实键匹配获得最高权重，因为精确主题匹配是最强的信号。全文搜索、HyDE 向量和直接向量根据信号强度分别加权。最后，原始消息匹配也以低权重包含在内，作为识别提取管道可能遗漏的候选结果的安全网。平局按时间先后打破，较新的结果排名更高。
然后，管道将最佳候选传递给合成模型，该模型生成对原始搜索查询的自然语言答案。某些特定查询类型会得到特殊处理。例如，时间计算通过正则表达式和算术确定性地处理，而不是由 LLM 处理。结果作为预计算事实注入到合成提示中。模型在日期计算等方面不可靠，所以我们不要求它们执行此操作。
我们的初始 Agent Memory 原型很轻量，包含基本的提取管道、向量存储和简单检索。它足以演示概念，但不足以发布。
因此，我们将其放入一个由智能体驱动的循环中并不断迭代。循环如下：运行基准测试，分析差距所在，提出解决方案，由人工审查提案以选择泛化而非过拟合的策略，让智能体进行更改，重复。
这种方法效果不错，但有一个特定挑战。LLM 是随机的，即使温度设置为零也是如此。这导致不同运行的结果存在差异，意味着我们必须对多次运行取平均值（对于大型基准测试耗时较长），并依赖趋势分析与原始分数来理解实际有效的内容。在此过程中，我们必须谨慎防止以不能真正改善产品通用性的方式过拟合基准测试。
随着时间的推移，我们达到了基准分数随每次迭代持续提升的状态，并拥有了一个在现实世界中可行的通用架构。我们特意针对多个基准测试（包括 LoCoMo、LongMemEval 和 BEAM）进行测试，以从不同角度推动系统发展。
我们在 Cloudflare 上构建 Cloudflare，Agent Memory 也不例外。现有强大且易于组合的原语使我们能够在周末交付第一个原型，并在不到一个月内构建出功能完备、生产化的内部版本 Agent Memory。除了交付速度，Cloudflare 还是构建此类服务的理想场所，原因如下。
在底层，Agent Memory 是一个协调多个系统的 Cloudflare Worker：
- Durable Object：存储原始消息和分类记忆
- Vectorize：提供嵌入记忆的向量搜索
- Workers AI：运行 LLM 和嵌入模型
每个记忆上下文映射到其自己的 Durable Object 实例和 Vectorize 索引，从而在上下文之间完全隔离数据。这也使我们能够轻松应对更高需求进行扩展。
通过 Durable Objects 实现计算隔离。 每个记忆配置文件拥有自己的 Durable Object (DO)，带有 SQLite 支持的存储，在无需任何基础设施开销的情况下提供租户间的强隔离。DO 处理 FTS 索引、替代链和事务性写入。DO 的 getByName() 寻址意味着来自任何地方的任何请求都可以通过名称到达正确的记忆配置文件，并确保敏感记忆与其他租户强隔离。
跨栈存储。 记忆内容存储在 SQLite 支持的 DO 中。向量存储在 Vectorize 中。未来，快照和导出将存储到 R2 以实现经济高效的长期存储。每个原语针对其工作负载专门构建，我们无需将所有内容强制放入单一形状或数据库中。
使用 Workers AI 进行本地模型推理。 整个提取、分类和合成管道运行在部署于 Cloudflare 网络上的 Workers AI 模型上。所有 AI 调用都传递一个路由到记忆配置文件名称的会话亲和性标头，因此重复请求会命中同一后端以获得提示缓存优势。
模型选择中的一个有趣发现是：更大、更强的模型并不总是更好。我们目前默认使用 Llama 4 Scout（17B，16专家MoE）进行提取、验证、分类和查询分析，使用 Nemotron 3（120B MoE，12B活跃参数）进行合成。Scout 高效处理结构化分类任务，而 Nemotron 更大的推理能力提升了自然语言回答的质量。合成器是唯一一个增加参数数量始终有助于解决问题的阶段。对于其他所有任务，较小的模型在成本、质量和延迟之间达到了更优的平衡点。
我们在 Cloudflare 内部的工作流程中运行 Agent Memory，既作为试验场，也作为下一步构建思路的来源。
编码代理记忆。 我们使用一个内部 OpenCode 插件，将 Agent Memory 接入开发循环。Agent Memory 提供了会话内和跨会话的过去压缩记忆。一个不那么明显的好处是团队内的共享记忆：通过共享配置文件，代理知道你的团队成员已经学到了什么，这意味着它可以停止询问已经回答过的问题，并停止犯已经纠正过的错误。
代理代码审查。 我们将 Agent Memory 连接到内部的代理代码审查器。可以说，它学会的最有用的事情就是保持安静。审查器现在记得某个评论在过去的审查中不相关，某个特定模式被标记过，而作者出于合理原因选择保留它。随着时间的推移，审查变得不那么嘈杂，而不仅仅是更智能。
聊天机器人。 我们还将记忆接入了一个内部聊天机器人，它摄取消息历史，然后潜伏并记住发送的新消息。这样，当有人提问时，机器人可以根据之前的对话来回答。
我们还有一系列额外的用例，计划在完善和改进服务后，在不久的将来内部推出。
我们正在内部持续测试和完善 Agent Memory，改进提取管道，调整检索质量，并扩展后台处理能力。类似于人脑在睡眠期间通过重放和加强连接来巩固记忆，我们看到了异步改进记忆存储的机会，目前正在实施和测试各种策略以实现这一目标。
我们计划很快公开发布 Agent Memory。如果你正在 Cloudflare 上构建代理并希望提前体验，联系我们加入候补名单。
如果你想深入了解架构、分享你的构建内容，或跟随我们进一步开发，请加入 Cloudflare Discord 或在 Cloudflare Community 中发起讨论。我们正在积极关注这两个平台，并对生产环境中代理工作负载的实际表现感兴趣。