AgentKit Studio
任务指南

绑定知识库与 Memory

绑定云端知识库、选择本地或云记忆来源、配置召回与写入,让 Agent 跨会话记住事实。

知识库与 Memory 是两件事:知识库是只读检索,Memory 是可写的长期记忆。两者都在 Agent 表单的「绑定能力」和「策略与确认」两步里配置。

前置条件

  • 已经连接云端控制面。没连上时,平台资源下拉里只有「请先连接云端」。
  • 云端的知识库与记忆库实例已创建,并且当前账号有访问权限。
  • 本地记忆(DSH Native 的本地记忆)不需要云端绑定,但只在 Star Harness 运行时可用。

操作步骤

绑定知识库

打开 智能体 → 选中目标 Agent → 编辑 → 绑定能力 步骤 → 滚到平台资源区块 → 知识库 下拉 → 选一个知识库。

绑定后的配置是固定的,不能手改:

字段值
retrieval.modetool(只读检索,通过工具调用触发)
retrieval.topK5
retrieval.maxChars16000
requiredtrue(由代码固定,不可关)

只有可用的实例能被选中:资源被停用或从云端消失时,platformBinding 直接抛 PLATFORM_RESOURCE_UNAVAILABLE,不会写入一个指向空资源的绑定。

知识库每类只能绑一个。 再选一个会替换掉前一个。

界面位置

「绑定能力」步骤的平台资源区块,知识库下拉已选中一个实例。

绑定记忆库

同一个平台资源区块里,记忆库 下拉 → 选一个记忆库实例。

记忆库的配置比知识库简单:只有 binding,没有 retrieval。它决定 memory.providerRef 是否走云:

是否绑定记忆库记忆来源providerRef
否本地记忆local-default
是云记忆库binding://platform-memory-instance

失效的资源会阻塞保存

如果之前绑定的资源在云端被删除了,下拉里会出现一条灰色选项「(当前不可用,请重新选择)」, 并显示红色提示「检测到已失效的平台资源」。必须重新选择或清空后才能保存。

打开跨会话记忆

切到策略与确认步骤 → 记忆 小节 → 打开跨会话记忆。

关闭时不要跳过这一节:关闭只是把 memory.enabled 设为 false,不会改变已有的 provider、scopes、recall、write、rollout 配置。重新打开会回到原来的设置。

选择记忆来源

打开后出现记忆设置面板。第一行是来源二选一:

来源何时出现说明
本地记忆运行时是 Star Harness 且不是编辑云端 Agent自带本地记忆,无需绑定云记忆库
云记忆库所有非云端编辑路径绑定云端记忆库,由 AICP 召回与写入

选本地记忆时会自动剔除已绑定的记忆库实例,避免留下悬空引用。选云记忆库但还没绑定记忆库时,保存会被拦下并提示「启用云记忆前,请在「绑定能力」步骤选择记忆库。」

界面位置

「记忆设置」面板的来源二选一控件与后续字段。

配置本地召回(仅本地记忆)

字段默认范围说明
本地召回开启开关关闭后不再自动召回已有事实
召回最大 token16000–100000注入上下文的召回预算
召回条数81–64最多返回几条
最低相似度0.450–1,步长 0.05低于该分数不返回

召回是词项覆盖率,不是语义相关度

本地召回的置信度按词项覆盖率计算。它对「同义词换一种说法」不敏感,对「关键词完全没出现」必然漏召回。 需要语义检索时用云记忆库。

recall.enabled 与 memory.enabled 相互独立:可以关掉写入但保留召回。

配置记忆写入

记忆写入方式三选一:

取值界面文案行为
off不提取记忆候选完全不提取。仅本地记忆路径提供该选项
explicit_only仅在我明确要求时记住只有你明确说「记住这个」才写入
candidate每轮完成后提取可用记忆每轮结束自动提取候选

新建 Agent 默认 explicit_only,编辑已有 Agent 默认 candidate。

两个刷新点(默认都开启):

开关时机
压缩前刷新在上下文压缩前提取记忆候选
轮次后刷新在本轮完成后提取当前用户消息中的候选

使用模型自动提炼记忆(默认关闭):按累计的新对话提炼长期事实与偏好,会产生额外模型用量。打开后可以设置累计用户字符数(默认 64,范围 1–100000)。

自动提炼有调用上限

每个任务最多调用 5 次模型。窗口太短时只会累计,不发起模型调用,也不推进游标。 运行与子任务面板可以查看状态和额外用量。

记忆写入开关(rollout)三选一,默认 shadow:

取值界面文案行为
off关闭写入不写入记忆库,已写入的事实仍可召回
shadow仅评估(shadow)只评估候选策略,不写入记忆库
enabled实际写入真正写入,请确认后再开启

shadow 不会写任何东西

默认值就是 shadow。想让 Agent 真的记住事实,必须显式改成 enabled。 这也是「明明开了记忆但它什么都不记得」的最常见原因。

保存并验证

点创建 Agent 或保存 Agent。回到策略与确认步骤,确认摘要里的记忆一行显示正确的来源:

  • 本地记忆 或 云记忆库 —— 记忆已启用。
  • 未启用 —— memory.enabled 为 false。

保存后发两条消息验证:第一条说一个事实并要求记住,第二条在新会话里问这个事实。

云端 Agent 的差异

编辑来源为 agentengine-server 或 agentengine-managed-runtime 的 Agent 时,行为不同:

项目云端 Agent
绑定能力步骤只保存知识库、记忆库、Skill Center 三类云端 ComponentConfig
模型、MCP、本地 Skill、Tool由 AgentEngine Runtime 自身管理,界面不提供
跨会话记忆开关禁用,并提示「云端 Agent 的记忆由 AgentEngine Server 管理记忆库绑定」
记忆写入方式只有 explicit_only 与 candidate,没有 off
保存语义调用 AgentEngine UpdateAgent;已有会话继续用旧快照,新运行用新绑定

成功后的样子

  • 平台资源区块的知识库、记忆库下拉都显示已选中的实例名称。
  • 确认配置摘要的记忆行不是「未启用」。
  • 第二个会话里问第一个会话说过的事实,Agent 能复述出来——这是记忆真的生效的唯一判据。
  • 问一个知识库里存在、但模型不可能自己知道的问题,Agent 会发起检索工具调用再回答。

常见错误

错误码原因处理
PLATFORM_RESOURCE_UNAVAILABLE选中的实例已被停用或从云端消失重新选择;失效项会显示为灰色「当前不可用」
INVALID_RESOURCE_KIND资源类型不在 knowledge-base / memory-instance / skill-space 里用界面下拉选择,不要手写类型
MANAGED_RESOURCE_INVALID资源引用不符合 agentengine.resources/v1(id 匹配 ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$,region 匹配 ^[a-z0-9][a-z0-9-]{0,63}$)从下拉重新选择,不要手写 ID
MANAGED_RESOURCE_MEMORY_UNBOUND记忆已启用但没绑定记忆库实例回到「绑定能力」选择记忆库,或把来源改为本地记忆
MEMORY_BINDING_SKIPPED记忆绑定被跳过(资源不可用)检查记忆库实例是否存在、是否有权限
MEMORY_SERVICE_UNAVAILABLE记忆服务不可达检查云端连接与控制面地址
MEMORY_WRITE_FAILED写入记忆失败检查 rollout 是否为 shadow;shadow 不写入
MEMORY_WRITE_AUTHORITY_LOST写入期间授权失效重新发起会话
MEMORY_RECALL_SKIPPED召回被跳过检查本地召回是否关闭、运行时是否为 Star Harness
MEMORY_DURABLE_WRITER_UNAVAILABLE持久化写入器不可用重启 Host 后重试
MEMORY_PARTITION_MISMATCH记忆分区与当前用户或 Agent 不匹配确认没有跨账号复用记忆库
MEMORY_OUTCOME_UNKNOWN / MEMORY_RESPONSE_UNKNOWN写入结果未确认不要盲目重试;先查看运行记录
MANAGED_RESOURCE_ACCESS_REVOKED资源访问授权被收回重新授权后重新保存
MANAGED_RESOURCE_SERVER_UNAVAILABLEAgentEngine 控制面不可达检查网络与控制面地址
启用云记忆前,请在「绑定能力」步骤选择记忆库。来源选了云记忆库但没有实例二选一:绑定记忆库,或改回本地记忆

相关参考

你想知道去哪里
资源与绑定资源与绑定
托管运行时生命周期托管运行时
记忆配置的内存模型src/client/state/agent-memory-config.mjs
托管资源契约src/managed-resource-contract.mjs
平台资源选择器src/client/pages/platform-resource-picker.mjs
权限与审批审批与权限策略
记忆相关的 21 个错误码错误码

本页导航