为托管深度代理添加记忆

托管深度代理为每个部署提供了持久的长期记忆：代理能够在不同对话线程和会话中记住每位用户的偏好和上下文，而您无需自行构建持久化层。记忆由 Context Hub 提供支持，代理可以在 /memories/user/ 路径下读取和更新文件。通过身份标识，记忆会根据操作者或租户进行重新挂载，使得调用方（触发代理运行的用户、服务账户或客户端）无法看到彼此的私有状态。

托管深度代理目前处于私有测试阶段，仅在LangSmith Cloud的美国区域提供。加入等待列表以申请访问权限。

记忆与相关状态的区别

下表区分了与记忆交互的四个概念：

概念	作用	重新部署后是否保留？	跨会话是否共享？
指令 / 技能	部署拥有的核心行为	是（从您的项目同步）	是（代理级别）
对话线程状态	对话连续性（检查点器）	是（由平台管理）	否（仅限单个线程）
长期记忆	Context Hub `/memories/user` 中的偏好和持久化笔记	是	根据身份范围而定
存储数据	工具的结构化数据 (`StoreBackend`)	是	根据存储命名空间而定

记忆不是您的系统提示词。编辑项目中的 instructions.md 和 skills/**，然后重新部署。部署会同步这些文件，但永远不会覆盖 Context Hub 中现有的 memories/** 文件。

代理可见的文件布局

代理在运行时会看到以下路径：

代理路径	Hub 来源	访问权限
`/instructions.md`	Hub `instructions.md`	只读
`/skills/**`	Hub `skills/**`	只读
`/memories/user/**`	一个重新挂载的 Hub 子集（例如 `memories/<actor>`）	读写
`/memories/org/**`	Hub `org-memory/**`（如果存在）	只读

记忆子集是 Context Hub memories/ 目录树下的一个子目录，属于一个范围：单个操作者 (memories/<actorId>)、一个租户 (memories/<tenantId>) 或共享代理 (memories/agent)。在运行时，一个子集会被重新挂载为 /memories/user/，因此代理在 /memories/ 下永远不会看到多用户的目录列表。

热记忆与冷记忆

运行时将一个有范围的 Hub 树挂载为 /memories/user/，并在每一轮对话中注入热记忆。这两个层级在加载时机上有所不同：

层级	路径	加载时机
热记忆	`/memories/user/AGENTS.md`	总是注入到系统提示词中
冷记忆	`/memories/user/` 下的其他文件（例如 `archive/…`）	通过 `read_file` / `write_file` 按需加载

保持热记忆专注于偏好、简短的游标和指向冷文件的指针。因为热记忆在每一轮对话中都会被注入系统提示词，所以它会增加每个请求的令牌数。将详细内容放在冷文件中，例如 /memories/user/archive/ 下的会议摘要、决策日志和完整的对话记录。在需要时从热记忆中链接它们。当创建一个新的记忆子集时，运行时会使用默认的记忆指令初始化 /memories/user/AGENTS.md。这些指令包含一个指导块，告诉代理在用户分享持久偏好时，对 /memories/user/AGENTS.md 调用 edit_file。编辑热记忆时，请勿删除该指导块。如果缺失，代理可能无法在不同对话线程中正确持久化偏好。

代理如何更新记忆

当用户分享一个持久偏好时，代理应在同一轮对话中，在声称稍后会记住之前，使用 edit_file 或 write_file 更新 /memories/user/AGENTS.md。如果写入失败，代理不应声称成功。它应该重试一次，或者告知用户持久化功能暂时不可用。要指示模型持久化记忆，请将以下内容添加到 instructions.md 中：

## 记忆

你在 `/memories/user/` 下拥有持久记忆。热记忆文件
`/memories/user/AGENTS.md` 每轮对话都会被加载。组织级事实（如果存在）
以只读形式存储在 `/memories/org/` 下。

当用户要求你记住一些持久信息时：

1. 对 `/memories/user/AGENTS.md` 调用 `edit_file`（如果是创建则调用 `write_file`）。
2. 确认你已将其存储在持久记忆中。

如果写入失败，不要声称你记住了它。重试一次，如果持久化仍然不可用，
则告知用户。

切勿在记忆中存储密钥、API 密钥、OAuth 令牌或密码。

请调整标题和措辞以适配您现有的 instructions.md 结构。此模板只是一个起点，并非固定格式。

写入成功后，对于同一调用方启动的新对话线程，应能从热记忆中回忆起该事实，而无需调用工具。这是跨会话持久化功能的产品验证标准。

按身份标识划分记忆范围

如果没有身份标识，所有调用方共享同一个代理记忆子集（Context Hub 中的 memories/agent，重新挂载为 /memories/user）。使用身份标识后，scoping.memory 决定哪个 Hub 子目录被重新挂载：

`scoping.memory`	重新挂载为 `/memories/user` 的 Hub 路径
`actor`（单租户）	`memories/<actorId>`
`actor`（多租户）	`memories/<tenantId>/<actorId>`
`tenant`	`memories/<tenantId>`
`agent`	`memories/agent`
`none`	`/memories/user/` 未挂载，且热记忆不会被注入

隔离性是强制实施的：一次运行只看到其重新挂载的树。同级的操作者或租户树是不可达的。像 private-assistant 和 internal-tool 这样的预设会将 memory 设置为 "actor"。service 预设使用共享的 agent 记忆。有关预设和入口的更多信息，请参阅身份标识。

from managed_deepagents import define_identity

identity = define_identity.preset("private-assistant")
# scoping.memory == "actor"

import { defineIdentity } from "managed-deepagents";

export const identity = defineIdentity.preset("private-assistant");
// scoping.memory === "actor"

当操作者或租户首次与代理交互时，运行时会自动创建他们的 /memories/user/AGENTS.md 文件。它会从项目定义的种子文件（如果存在）复制，否则回退到内置的默认模板。这确保代理从第一轮对话开始就拥有其记忆指令，而不是从一个空文件开始。

组织级记忆（只读）

可选的组织级全局事实存储在 Context Hub 的 org-memory/ 下，并挂载在 /memories/org。代理可以读取组织记忆；运行时会拒绝在 /memories/org/** 下的写入。由人类或组织工具来更新该树，而不是代理。有关更新 Context Hub 文件，请使用 Context Hub API 或 CLI。

本地开发

mda build 和 mda dev 会在 .mda/__contexthub__/ 维护一个本地的 Context Hub 模拟环境。这是您本地文件系统上的一个目录，用于模拟远程的 Context Hub，因此您可以在本地测试记忆行为而无需部署：

从项目同步 instructions.md 和 skills/**
当 memories/agent/AGENTS.md 和 org-memory/AGENTS.md 不存在时进行初始化
在重建过程中保留现有的记忆文件

操作者范围的本地运行会以与部署相同的方式，将 memories/<actorId>/ 重新挂载为 /memories/user。当您在项目中更新托管深度代理 SDK 时，请进行重建，以便 .mda/build/__runtime__ 能够获取新的运行时。运行时是在编译时复制的，因此 SDK 的更改在您重建之前不会生效。

禁用托管记忆

对于无状态代理或当您在外部管理持久化时，可以使用 disableMemory。在代理定义上设置 disableMemory / disable_memory 可跳过热注入和 /memories/user 记忆的连接。身份标识 scoping.memory: "none" 也会禁用挂载。

from managed_deepagents import define_deep_agent

agent = define_deep_agent(
    name="stateless-agent",
    model="openai:gpt-5.5",
    disable_memory=True,
)

import { defineDeepAgent } from "managed-deepagents";

export const agent = defineDeepAgent({
  name: "stateless-agent",
  model: "openai:gpt-5.5",
  disableMemory: true,
});

部署与 Context Hub

在执行 mda deploy 时，托管深度代理会将部署拥有的 instructions.md 和 skills/** 同步到 Context Hub 的代理仓库，并在需要时初始化代理记忆。现有的 memories/** 内容会被保留。同步和初始化行为与本地开发一致。有关部署生命周期，请参阅托管深度代理工作原理和 CLI 记忆说明。

测试与部署

使用 mda dev 在本地测试项目，然后使用 mda deploy 进行部署。在 LangSmith 中打开部署追踪，以检查模型调用、工具调用、错误和延迟情况。

故障排除

为什么代理忘记了我让它记住的事情？

如果代理声称记住了某事，但在新对话线程中该事实缺失，请检查代理的追踪记录，看是否有针对 /memories/user/AGENTS.md 的 edit_file 或 write_file 工具调用。确认调用成功，并且目标路径在 /memories/user/ 下。验证身份范围是否配置正确。对重新挂载子集之外的写入会被拒绝。

为什么我的上下文窗口快要填满了？

如果 /memories/user/AGENTS.md 的热记忆变得太大，它会消耗每个请求系统提示词的令牌。将详细内容移动到 /memories/user/archive/ 下的冷文件中，并在热记忆中仅保留偏好和指针。

为什么一个用户能看到另一个用户的记忆？

这是一个配置错误，而不是平台问题。请验证 scoping.memory 是否设置为 actor 或 tenant（而不是 agent）。检查身份标识声明是否存在，以及入口模式是否正确解析了调用方。检查追踪记录中的 runtime.identity 以确认解析出的操作者和租户 ID。更多信息，请参阅身份标识。

为什么种子模板覆盖了我的自定义内容？

运行时仅在文件不存在时，才会从种子模板创建 /memories/user/AGENTS.md。如果用户报告内容被覆盖，很可能是在首次访问该子集时文件不存在，因此运行时初始化了一个新的副本。部署永远不会覆盖现有的 memories/** 文件。

后续步骤

身份标识

使用 scoping.memory 按操作者或租户划分记忆。

工作原理

了解 Context Hub、对话线程和部署同步如何协同工作。

CLI 参考

查阅项目文件、disableMemory 和部署行为。

自定义工具

当工具需要调用方 ID 时，读取 runtime.identity。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Agent definition

Build and deploy

记忆与相关状态的区别

代理可见的文件布局

热记忆与冷记忆

代理如何更新记忆

按身份标识划分记忆范围

组织级记忆（只读）

本地开发

禁用托管记忆

部署与 Context Hub

测试与部署

故障排除

后续步骤

身份标识

工作原理

CLI 参考

自定义工具

​记忆与相关状态的区别

​代理可见的文件布局

​热记忆与冷记忆

​代理如何更新记忆

​按身份标识划分记忆范围

​组织级记忆（只读）

​本地开发

​禁用托管记忆

​部署与 Context Hub

​测试与部署

​故障排除

​后续步骤

身份标识

工作原理

CLI 参考

自定义工具

记忆与相关状态的区别

代理可见的文件布局

热记忆与冷记忆

代理如何更新记忆

按身份标识划分记忆范围

组织级记忆（只读）

本地开发

禁用托管记忆

部署与 Context Hub

测试与部署

故障排除

后续步骤