Documentation Index
Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
Use this file to discover all available pages before exploring further.
文件记忆是 Xpert 的内置文件型长期记忆能力。它把可长期复用的用户偏好、项目状态、反馈修正和参考资料保存为 Markdown 文件，让智能体可以在后续会话中检索、读取和补充这些记忆。
Dreaming 是文件记忆的后台整理能力。它会基于现有记忆、使用信号和会话证据运行一个专门的 Dreamer 智能体，对记忆文件进行整理，并生成可追踪的运行记录和报告。
适用场景
- 保存跨会话仍然有效的用户偏好、长期事实和个性化信息。
- 沉淀项目背景、阶段性结论、业务规则和可复用上下文。
- 记录用户对回答的反馈、纠错和后续修正。
- 需要让管理员直接查看、编辑和审计智能体记忆内容。
记忆类型
文件记忆按用途分为四类，每个 Xpert 拥有独立的记忆空间。
| 类型 | 用途 |
|---|
user | 用户偏好、用户档案、长期有效的个性化信息 |
feedback | 用户反馈、纠错、对答案风格或业务口径的修正 |
project | 项目状态、业务背景、阶段性决策、任务上下文 |
reference | 可复用资料、规则说明、流程说明、标准口径 |
文件结构
文件记忆以一个 Xpert 为单位组织。常见结构如下：
MEMORY.md
user/
feedback/
project/
reference/
.dream/
MEMORY.md 是记忆索引，用于快速浏览和召回候选记忆。user/、feedback/、project/、reference/ 保存具体记忆主题文件。.dream/ 保存 Dreaming 运行状态、运行记录、信号和评分缓存，默认不是前台记忆正文。
每个主题文件是带 frontmatter 的 Markdown。frontmatter 中包含记忆 ID、类型、状态、标题、摘要、标签、来源、更新时间和 usage 使用统计。正文部分保存可供智能体阅读的具体内容。
智能体如何使用文件记忆
启用 Xpert 文件记忆中间件后，智能体会获得以下记忆工具：
| 工具 | 作用 |
|---|
memory_search | 按自然语言问题搜索相关记忆，可限制记忆类型和返回数量 |
memory_get | 读取指定记忆的完整内容，支持使用 memoryId、relativePath 或 canonicalRef |
memory_write | 写入或更新一条长期有效的文件记忆 |
memory_search 或 memory_get。
文件记忆是辅助上下文，不会覆盖用户当前输入。若当前用户输入与记忆冲突，智能体应优先遵循当前输入，并在必要时说明记忆可能已过期。
自动召回配置
文件记忆中间件支持自动召回相关记忆，并把选中的内容注入到本轮模型上下文中。
| 配置项 | 说明 |
|---|
| 召回模式 | 当前支持 hybrid_async，系统会异步准备索引、摘要和候选记忆 |
| 召回选择模型 | 用于从候选记忆中选择最相关内容的模型 |
| 选择模型超时 | 选择模型的最长等待时间 |
| 最大选择数量 | 单轮最多选入多少条详细记忆 |
| 摘要数量 | 单轮提供给模型的摘要数量上限 |
| 单轮最大详情字节 | 单轮可注入的详细记忆内容上限 |
| 单会话最大详情字节 | 一个会话内详细记忆内容的累计上限 |
usage 统计和 .dream/scorecards/index.json 评分缓存。
自动写回
如果一轮对话中没有显式调用 memory_write，系统会在对话结束后触发自动写回流程。自动写回会读取最近对话内容，判断其中是否存在值得长期保存的信息。
| 配置项 | 说明 |
|---|
| 写回模型 | 用于判断是否需要新增、更新或归档记忆的模型 |
| 等待策略 | never_wait 表示不等待后台写回；soft_drain 表示短暂等待后台任务完成 |
| 软等待时长 | soft_drain 模式下最多等待的毫秒数 |
| 写回提示词 | 用于指导模型如何判断长期记忆价值 |
文件记忆管理页面
进入数字专家的记忆页面后，选择“文件”即可管理文件记忆。
页面左侧是文件工作区，可查看 MEMORY.md、四类记忆目录和具体主题文件。支持打开、编辑、保存、上传和删除文件。
手动编辑记忆文件时建议保持以下规则：
MEMORY.md 保持为简洁索引，不在索引中写入大段正文。- 主题文件放入正确类型目录。
- frontmatter 中的
type、scopeId、status、title 和 summary 保持有效。
- 归档内容使用
status: archived，避免直接删除仍有价值的记忆。
Dreaming 配置
文件记忆页面顶部提供 Dreaming 配置。
| 字段 | 说明 |
|---|
| 记忆整理智能体 | 选择负责整理文件记忆的 Dreamer Xpert |
| 记忆整理智能体 Key | 指定 Dreamer Xpert 内部用于执行整理任务的 Agent key，默认通常为 FileMemoryDreamer |
| 打开 Dreamer | 跳转到所选 Dreamer Xpert 的智能体配置页面 |
| 启用 Dream gate | 开启后，系统会根据 gate 条件判断本次 Dream 是否需要真正执行 |
| 最小间隔 | 距离上次有效 Dream 运行至少经过多少分钟 |
| 新记忆数 | 上次有效 Dream 之后至少出现多少条新增或更新记忆 |
| 会话数 | 上次有效 Dream 之后至少出现多少个相关会话 |
运行 Dream
点击“Dream”按钮会创建一次手动 Dream 运行。系统会立即返回运行 ID，并在后台继续执行。
Dream 运行会完成以下工作：
- 创建运行记录。
- 获取当前 Xpert 的 Dream 锁，避免同一个 Xpert 同时运行多个 Dream。
- 评估 Dream gate 条件；不满足时标记为
skipped。
- 准备 evidence 文件，包括记忆清单、信号、评分缓存、会话片段和 instructions。
- 运行配置的 Dreamer Xpert。
- 校验整理后的记忆文件和
MEMORY.md。
- 生成 Dream report、validation、changed files 和
DREAMS.md 记录。
Dream 运行状态
| 状态 | 说明 |
|---|
queued | 已创建运行，等待后台处理 |
running | 正在执行 |
succeeded | 执行成功，校验未发现问题 |
partial | 执行完成，但校验发现需要处理的问题 |
failed | 执行失败 |
cancelled | 运行被取消 |
skipped | gate 条件未满足，跳过本次 Dream |
查看 Dream 结果
文件记忆页面右侧展示 Dream runs 列表。选择某次运行后，可查看：
- 运行状态、开始时间、结束时间、变更文件数和问题数。
- gate 判断结果、新增或更新记忆数、相关会话数和跳过原因。
- preflight 报告。
- Dream report，包括整理摘要、变更文件和未解决冲突。
- validation 校验结果。
- 运行 artifacts，包括
status.json、request.json、evidence/、gate.json、dream-report.json、validation.json 和 changed-files.json。
当运行状态为 partial 时，建议优先查看 validation 和 unresolved conflicts，根据提示修复 frontmatter、索引链接或重复标题等问题。
当前校验规则
Dreaming 完成后，系统会对记忆文件执行结构校验。当前已覆盖：
- 主题文件 frontmatter 的 Xpert scope 是否匹配当前 Xpert。
- 是否存在重复标题。
- 是否存在无法解析的主题文件。
MEMORY.md 链接是否指向有效记忆路径。MEMORY.md 是否引用不存在、重复或已归档的主题文件。MEMORY.md 是否出现过长索引项或疑似正文内容。
校验通过时运行状态为 succeeded；存在问题时运行状态为 partial，并在页面中展示需要处理的问题。
相关接口
文件记忆页面使用以下接口：
| 接口 | 说明 |
|---|
GET /xpert/:id/memory/files | 获取文件记忆目录 |
GET /xpert/:id/memory/file | 读取指定文件 |
PUT /xpert/:id/memory/file | 保存指定文件 |
POST /xpert/:id/memory/file/upload | 上传文件到记忆目录 |
DELETE /xpert/:id/memory/file | 删除指定文件 |
POST /xpert/:id/memory/dream | 手动触发 Dream |
GET /xpert/:id/memory/dream/config | 获取 Dreaming 配置 |
PUT /xpert/:id/memory/dream/config | 保存 Dreaming 配置 |
GET /xpert/:id/memory/dream/runs | 获取 Dream runs 列表 |
GET /xpert/:id/memory/dream/runs/:runId | 获取单次 Dream 详情 |
POST /xpert/:id/memory/dream/runs/:runId/cancel | 取消尚未开始的 Dream |
使用建议
- 把稳定、可复用的信息写入文件记忆，避免保存临时闲聊。
- 主题文件保持单一主题，标题和摘要尽量清晰。
- 批量导入或多轮对话后，可以手动运行 Dream 进行整理。
- Dream report 出现冲突时，先修复 validation 中列出的问题，再继续运行下一次 Dream。
- 对关键业务口径建议优先保存到
reference 或 project 类型，方便后续检索和审计。
