智能体记忆系统与知识库存储运行运维说明

本文基于V3.4，详细说明以下内容：

• 智能体记忆系统如何存储、读取、运行

• 知识库、Agent KB、扩展端本地数据分别放在哪里

• 如何调用相关接口

本文重点区分三类能力，避免概念混淆：

• Fusion 记忆系统

• Fusion 知识库

• Super Agent 内部 Agent KB 与扩展端本地存储

1. 总体结论

先给出最重要的结论：

• 当前版本中，记忆系统 与 Fusion 知识库 的主存储键值来自数据库中的设置项，除了 Embedding 缓存，还包括 knowledge + semantic 的异步快照归档、恢复预览、恢复前备份、失败记录与重试。

• 当前 Fusion 状态已补充 state.meta.revisions，会跟踪 global / memory / knowledge / search / publish 五类模块 revision，并在后台提供查询与展示。

• /admin/agent-memory 已展示治理预览、执行入口与最近治理记录；/admin/agent-archive 已展示 latest 完整性状态、单快照完整性校验、失败记录与重试。

• Super Agent 的上下文注入已开始统一到一类结构化项，每个上下文项都会附带基础 score 与 sourceTrace，并在响应 meta 中返回命中来源摘要，便于排障与后续排序治理。

• 即使没有配置云端，记忆、知识库、问答、扩展端对话仍然可以正常运行。

• 浏览器扩展端自己的设置、聊天记录、历史记录、本地流程等，默认保存在浏览器 chrome.storage.sync 和 chrome.storage.local，不依赖服务器数据库，也不依赖 S3/R2。

2. 系统分层

2.1 Fusion 记忆系统

Fusion 记忆系统是站点侧智能体的统一记忆容器，包含三层：

• episodic：对话/执行过程中的近期经验记忆

• semantic：较稳定的语义知识或压缩后的长期上下文

• skill：偏技能和动作模板类记忆

这三层统一挂在一个 Fusion 状态对象中。

2.2 Fusion 知识库

Fusion 知识库是后台可管理的知识条目系统，支持：

• 手动新增

• 检索

• 启停

• 删除

• 导入预览

• 批量确认入库

• 导出

• 学习反馈候选池自动吸收

它更像“结构化、可治理、可回溯”的长期知识层。

2.3 Agent KB

Agent KB 不是后 knowledge这套知识库本体，而是 Super Agent 的一套内置+自定义知识包，主要用于：

• 口语化指令

• 内部 API 速查

• 运维操作模板

• 执行 SOP

• 对话中自动附带相关条目

它分为两部分：

• 代码内置的 BUILTIN_KB

• 设置项里的自定义

2.4 扩展端本地存储

浏览器扩展有自己独立的一层本地存储，不直接等于服务端记忆系统。扩展端保存的是：

• 扩展设置

• 聊天历史

• 草稿

• 最近发布结果

• 工作流日志

• 后端动作日志

• 本地自定义工作流

这些数据默认存在浏览器本地。

3. 主存储位置

3.1 Fusion 状态主存储

当前 Fusion 状态统一存储在设置键：

• automation.agentFusion.state

该状态中包含：

• openclaw.memory.episodic

• openclaw.memory.semantic

• openclaw.memory.skill

• knowledge.items

• knowledge.templates

• knowledge.feedbackCandidates

• search

• publish

• skills

• context

也就是说，记忆系统与知识库并不是分散多张业务表，而是统一保存在一个 Fusion 状态对象里。

3.1.1 实际落库介质

持久化介质由当前运行时数据库决定：

• Mongo 模式：写入 Setting 文档

• SQL 模式：写入 settings 表

因此，当前主链路的“长期保存”依赖数据库，而不是对象存储。

3.1.2 主存储特点

优点：

• 读写入口统一

• 便于跨模块联动

• 后台页面实现简单

限制：

• 单一状态对象体积会增长

• 回滚粒度较粗

• 不天然等于归档/备份系统

3.1.3 当前版本治理元信息

当前 Fusion 状态除了业务数据本身，还会维护：

• meta.revisions.globalRevision

• meta.revisions.memoryRevision

• meta.revisions.knowledgeRevision

• meta.revisions.searchRevision

• meta.revisions.publishRevision

• meta.revisions.updatedAt

作用是：

• 给后台一个稳定的版本锚点

• 让归档 manifest 可以携带当前 revision

• 帮助区分“在线状态变更”和“只是对象存储是否可用”

当前 knowledge.revision 仍然保留，用于兼容知识库导入/导出与快照显示；同时会与 meta.revisions.knowledgeRevision 对齐。

3.2 Fusion 治理参数存储

记忆与知识库的一些治理参数不是放在 automation.agentFusion.state 内，而是独立设置键

默认治理值大致是：

• episodic 上限：60

• semantic 上限：220

• skill 上限：300

• 自动清理低分阈值：0.2

• 自动学习默认关闭

• 知识最小质量阈值：0.7

注意：

• 这些值决定“内存整理/治理策略”

• 但它们不代表“达到阈值就自动上传云端”

这两件事在当前代码里是分开的。

3.3 Agent KB 存储

Agent KB 有两部分来源：

3.3.1 内置 KB

内置条目直接写在代码中，属于随代码版本发布的知识集合。

特点：

• 不依赖数据库初始化

• 不依赖对象存储

• 更新需要改代码或发版

当前管理方式：

• 只读展示可在 agent-control的 Agent KB 管理块查看

• 内置条目不可直接删除或改写

• 若要基于内置条目继续维护，推荐“复制为自定义”后再保存

3.3.2 自定义 KB

自定义 Agent KB 存在设置项：

• ai.superAgent.agentKbItems

来源包括：

• 管理员手动配置

• 对话中的 <sa_commit kind="kb"> 自动沉淀

• 口语触发词入库

当前最小管理闭环已经包括：

• 列表

• 搜索

• 编辑 / 新增

• 查看内置条目并复制为自定义

• 删除自定义条目

• 落位建议（建议留在 Agent KB 或转到 /admin/knowledge）

• 一键转存到 Fusion 知识库

其中“转到知识库”不是额外对象存储，而是把内容写入：

• automation.agentFusion.state.knowledge.items

也就是说：

• Agent KB 自定义条目仍然保留在 ai.superAgent.agentKbItems

• 若执行“转存到 /admin/knowledge”，会额外在 Fusion 知识库生成或更新对应知识项

• 两者属于两套用途不同、但都落在数据库 settings 的在线层数据

为减少重复治理，当前自定义 Agent KB 条目还会额外记录迁移元信息：

• transferredAt

• transferredKnowledgeId

• transferredSignature

这些字段的作用是：

• 标记最近一次转存时间

• 记录已关联的 Fusion 知识项 ID

• 对标题 / 标签 / 正文做轻量签名，用于判断“内容未变化时跳过重复更新”

因此当前“转存”行为已经不是单纯复制，而是：

• 首次转存：在 knowledge新建知识项

• 再次转存：优先更新已关联知识项

• 若内容签名未变化：直接跳过写入，减少无效 revision 增长

Agent KB 当前检索也已从简单 token 命中升级为轻量排序检索，包含：

• 标题 / 标签 / 正文字段分权重

• 短语命中

• 覆盖率

• 顺序命中

• 字符级近似匹配

这意味着运行时附带 Agent KB 时，更容易命中“步骤 / 模板 / 接口速查 / 排障手册”类条目。

3.4 扩展端存储

扩展端的数据分两类：

3.4.1 chrome.storage.sync

主要用于跨浏览器同步的小体积配置：

• appSettings

其中包括：

• backendUrl

• token

• language

• role

• mcpPreset

• runtimeSkillMode

• runtimeMcpOverrides

这意味着：

• 扩展的基础配置是浏览器同步存储

• 它不进入服务端 Fusion 记忆

• 也不走 S3/R2

3.4.2 chrome.storage.local

主要用于本机本浏览器的大部分运行数据：

• history

• agentChatHistory.v1

• shuoshuoDraft.v1

• recentPublishResults

• latestPublishResult

• workflowRunLogs

• backendActionLogs

• customWorkflows

• agentClientId.v1

• 扩展主题/固定模板/面板偏好等本地状态

因此扩展端的“记忆感”更多来自浏览器本地缓存，而不是服务端统一记忆。

4. 运行链路

4.1 记忆是怎么写入的

当前记忆写入主要有两种方式。

4.1.1 后台管理写入

后台页面通过：

• memory.add

• memory.upsert

向fusion发起请求，把记忆写入 Fusion 状态中的对应层。

管理员可以指定：

• layer

• summary

• tags

• score

• scopeType

• scopeKey

• locale

• region

• role

• channel

4.1.2 对话自动写入

Super Agent 在正常对话结束后，会自动将问答片段写入 episodic 记忆。

常见写入来源：

• 流式回答完成后自动写入

• 非流式回答完成后自动写入

写入内容通常类似：

• Q: 用户问题

• A: 回答摘要

写入来源标识通常是：

• super-agent.chat

这意味着：

• 只要是走服务端 Super Agent 主链路的对话

• 并且满足写入条件

• 就会自动沉淀到 episodic

当前围绕 episodic 已补充的最小治理闭环：

• MemoryItem 新增最小治理元信息：updatedAt / hitCount / lastHitAt

• memory.governance.preview 可预览清理、去重、晋升候选

• memory.governance.run 可实际执行治理

当前治理逻辑主要覆盖：

• 低分且过期的 episodic 清理

• 同作用域下完全重复摘要的合并

• 高分、非强时效 episodic -> semantic 晋升

还未完成的部分：

• 默认仍未启用“系统级守护式定时治理”

• 已可通过自动化 workflow / scheduler 把 memory.governance.run 当作流程动作执行

• 更细粒度的 source / scope / channel 筛选

• 更完整的治理审计报表与聚合看板

• 更细参数的分规则预览与局部执行

4.2 记忆是怎么读取的

记忆读取不是“全量灌给模型”，而是带过滤条件的定向检索。

读取时会综合以下维度：

• scopeType

• scopeKey

• locale

• region

• role

• channel

Super Agent 会先把用户问题做一轮“意图扩写 + 同义词扩写 + Query Rewrite”，然后再查 scoped memory。

当前这一步已经抽到了 memory-intelligence.ts，主要包括：

• 识别只读问答 / 动作执行 / 高风险动作倾向

• 基于中文同义词组与英文触发词做查询变体扩写

• 针对 CJK 文本补充 2-gram / 3-gram 片段，提高短句与口语检索命中

• 对记忆摘要与标签做增强关键词打分，而不是单纯 includes

需要注意：

• 这仍然属于“增强关键词召回 + 规则打分”路线

• 它显著优于旧的纯字符串包含匹配

• 但它还不是独立向量库意义上的完整语义检索

主要目的：

• 保留同一用户/访客上下文

• 降低跨角色污染

• 减少不同渠道会话串味

补充：

• 当前 Super Agent 在真正喂给模型之前，会先把页面文章、站内相关文章、scoped memory、Fusion 检索结果、MCP 返回、Agent KB 命中统一整理成同一种上下文项结构

• 结构中至少包含：title / content / url / score / sourceTrace

• sourceTrace 当前会保留基础来源维度，例如 stage、sourceType、sourceLabel、scopeType/scopeKey、providerName、sourceId

• 当前统一排序层已抽到 context-ranking.ts，会先按 baseScore + stageWeight + queryOverlap + titleBoost + contentQuality + traceBonus 做首轮重排

• 返回给调用方时，会在 data.meta 中附带：

contextSourceSummary

• contextSources

• 这两项属于运行时诊断元信息，不会单独持久化进主存储，也不会作为云端快照主体

当前推荐理解是：

• episodic 更像“当前人当前会话域的近期上下文”

• semantic 更像“长期稳定语义”

• skill 更像“操作方法和模板”

4.3 知识库是怎么写入和读取的

Fusion 知识库主要通过 /api/admin/agent/fusion 的以下动作运转：

• knowledge.search

• knowledge.upsert

• knowledge.toggle

• knowledge.delete

• knowledge.import.preview

• knowledge.import.confirm

• knowledge.export

另外还有学习反馈流程：

• learning.feedback.submit

• learning.feedback.review

• learning.feedback.reopen

• learning.feedback.config.update

• learning.feedback.delete

知识库与记忆系统的区别是：

• 记忆更偏运行时上下文和经验片段

• 知识库更偏结构化、可审核、可复用知识资产

4.4 Agent KB 是怎么参与回答的

Agent KB 的附带条件与后台知识库不同。

当前逻辑里：

• 当请求方角色允许

• 且运行模式不是纯 search

• 系统会对 Agent KB 做一次命中检索

• 命中的条目会被当作“内部 API 知识库”上下文拼接给模型

因此 Agent KB 更像：

• 面向管理员/运营/作者的内部操作手册

• 针对执行型问答的近场知识

4.5 扩展端是怎么调用服务端智能体的

扩展端在“智能体”模式下，优先请求：

• super-agent

请求体中会带：

• question

• mode

• clientId

• 页面上下文

• 后端鉴权信息

扩展端的策略是：

• 有后端地址且 Token 可用时，优先走服务端

• 如果后端不可用、超时或被配置为本地模式，则回退到本地 MCP/本地命令执行

这套设计的好处是：

• 服务端记忆系统故障时，扩展不一定完全不可用

• 本地模式可以兜底基本的搜索、滚动、点击、页面结构分析

5.1 当前云端依赖的配置来源

• 智能体归档当前复用的是“附件 S3 配置”

• 不是单独一套 agent.s3.* 配置

这点非常重要，因为它代表：

• 如果附件云存储没开，记忆归档也默认不可用

• 如果附件云存储开了，智能体归档能力才有机会工作

5.2 当前已具备的云端能力

当前 memory-archiver.ts 提供了四类能力：

• archiveMemorySnapshot(data, type)

• loadLatestMemoryArchive(type)

• saveEmbeddingCache(slug, embedding)

• loadEmbeddingCache(slug)

另外当前主用的新归档闭环能力包括：

• createAgentArchiveSnapshot(...)

• listAgentArchiveSnapshots(...)

• previewAgentArchiveRestore(...)

• verifyAgentArchiveSnapshot(...)

• verifyLatestAgentArchiveSnapshots(...)

• 失败记录、重试与恢复前备份

这说明当前云端设计定位是：

• 记忆/知识快照归档

• Embedding 缓存

不是主数据库替代方案。

6. 如何调用

6.1 后台接口调用

记忆和知识库的统一管理入口是：

• /api/admin/agent/fusion

6.1.1 记忆相关动作

• memory.add

• memory.upsert

• memory.clear

• memory.clearByFilter

• memory.delete

• view=governance.revision

查询视图：

• view=memory.search

• view=memory.stats

6.1.2 知识库相关动作

• knowledge.search

• knowledge.upsert

• knowledge.toggle

• knowledge.delete

• knowledge.import.preview

• knowledge.import.confirm

• knowledge.export

• archive.snapshot.create

• archive.snapshot.previewRestore

• archive.snapshot.restore

• archive.snapshot.verify

• view=archive.snapshots

• view=archive.integrity.latest

• view=archive.failures

• archive.failure.retry

6.1.3 学习反馈相关动作

• learning.feedback.submit

• learning.feedback.review

• learning.feedback.reopen

• learning.feedback.config.update

• learning.feedback.delete

6.2 公共智能体调用

对外统一对话入口是：

• /api/ai/super-agent

常见用途：

• 站内悬浮对话

• 超级智能体页面

• 浏览器扩展

• 外部接入方

这个入口会在需要时：

• 注入 scoped memory

• 注入 Agent KB

• 注入 Fusion 上下文

• 注入页面上下文

• 将这些来源统一整理为带 score / sourceTrace 的上下文项

• 调用模型完成回答

• 回答后写回 episodic

6.3 扩展端调用

扩展端优先调用：

• /api/ai/super-agent

若以下情况出现：

• 未配置后端

• Token 不可用

• 外部网关不可运行

• 当前是 local 模式

• 后端超时

则会改走本地能力：

• 本地搜索

• 页面自动化命令

• 本地 MCP/Skill

这意味着扩展端不是硬绑定服务端，也不是硬绑定云端。

7.2 当前已经具备的降级行为

7.2.1 Embedding 缓存读取失败会回退

如果云端缓存读取失败：

• loadEmbeddingCache 会返回 null

• 系统会重新计算 embedding

因此不会因为缓存缺失而导致检索主流程中断。

7.2.2 Embedding 缓存写入失败不会阻断主流程

如果 saveEmbeddingCache 上传失败：

• 返回 false

• 但检索结果仍可继续返回

因此云端缓存更像性能优化，不是硬依赖。

7.2.3 未配置云端时直接跳过归档

如果附件 S3 配置没有启用：

• 归档函数直接返回空结果

• 不会强制报错阻断问答主链

7.3 推荐的运维原则

为了确保“启用云端后依然正常运行”，建议遵循以下原则。

原则 1：数据库仍然是主存储

不要把当前 S3/R2 理解成主数据库替代。

正确定位应是：

• DB：主状态

• S3/R2：归档与缓存

原则 2：云端失败不应阻断回答

所有云端调用都应保持以下模式：

• 读不到缓存就本地重算

• 写缓存失败就记录日志但不中断

• 归档失败只告警，不回滚主写入

原则 3：上云动作应放在异步或非关键路径

例如：

• 会话完成后异步归档

• 知识导入后异步快照

• 定时压缩后异步归档

不要把对象存储放在用户请求的同步强依赖链路上。

8. 扩展端相关补充说明

用户特别提到“包括扩展的”，这里单独补充。

8.1 扩展端不直接共享服务端记忆数据库

扩展端本地聊天记录：

• 保存在 chrome.storage.local

服务端智能体记忆：

• 保存在数据库设置项

二者关系是：

• 扩展调用服务端时，会触发服务端侧的 scoped memory 机制

• 扩展自己本地也保留一份聊天历史用于 UI 展示和快速恢复

所以扩展端是“本地体验层 + 服务端记忆增强层”的双层设计。

8.2 扩展端为什么能在云端故障时继续运行

因为扩展本身设计了后备路径：

• 有后端时走后端

• 后端不可用时尝试本地模式

因此即使：

• S3 不可用

• 服务端缓存失效

• 某些云端归档失败

扩展仍然可以执行：

• 本地搜索

• 本地浏览器自动化

• 基础页面理解

这也是“确保云端存储时依然正常运行”的关键保障之一。

9. 排障建议

9.1 记忆写入了但检索不到

优先检查：

• 是否写入了错误的 scopeType/scopeKey

• 是否缺失 role/channel 造成隔离不一致

• 查询时是否关闭了 includeGlobal

• 关键词是否过短

• 记忆是否被低分治理或压缩逻辑影响

9.2 知识库存在但回答没带上

优先检查：

• 是后台知识库还是 Agent KB

• 当前运行模式是否为 search

• 当前角色是否允许附带内部 KB

• 该条目是否命中搜索条件

9.3 云端配置了但看起来没上传

优先检查：

• attachment.s3.enabled 是否真的开启

• 是否只是开启了备份 S3，而没有开启附件 S3

• 当前是否真的命中了 Embedding 检索流程或 knowledge / semantic 归档触发点

• 当前是否调用了 archive.snapshot.create，或命中了 knowledge.import.confirm / learning.feedback.review / optimizeFusionContext()

• S3 连接测试是否通