Agent Memory（知識庫）

15. Agent Memory（知识库）

在 Agent Memory 启用的前提下，AI 能从对话中产生可重复使用的业务知识建议（术语、商业规则、分析偏好、领域背景等）。新建议会先进入目前工作区的 Queued Knowledge 伫列，经你核准并合并至 User 或 Project 知识后，才会在后续对话中注入模型。你不需要每次开新对话都重复同一段背景说明——但若关闭记忆总开关，则不会背景萃取、也不会注入；若仅关闭 Automatic suggestions，则停止对话后背景萃取，已核准知识仍会注入，Agent 仍可 propose_knowledge。

15.1 知识建议如何产生

当 Enabled（总开关）为打开、Automatic suggestions 为打开、且已设置可用的 LLM（API Key 等）时，每次与 AI 的对话在正常结束后，系统会在背景非阻塞地：

1. 萃取：LLM 仅从最近一轮对话中的 user 讯息（默认最近 8 条）辨识可复用的知识片段；一键触发的 System instruction（HTML Report、Resolve Comments、Execute Plan 等）不参与萃取。每条建议须附 evidence_quote（你原话的引述），后端会校验引述必须出现在上述 user 讯息中，否则丢弃。建议含 Type：rule（约束、偏好、流程）或 info（定义、背景、事实）。有聚焦项目时，系统会优先建议 project 层并预填项目 ID（来自当次对话 context，必要时 fallback session）。
2. 去重：与已核准知识、伫列中 pending、以及（project 层）同项目知识档比对；语意重复则略过；若为更新表述可带 supersedes 取代旧 pending 项。
3. 入伫列：通过校验与去重的项目写入目前工作区的 Queued Knowledge（JSON 伫列，未核准前不写入正式的 User / Project Markdown 知识档）。被动萃取每轮对话最多入队 3 条。
4. Agent 主动提案：分析中 Agent 可呼叫 propose_knowledge 将口径/字段陷阱等跨对话可重用规则送入同一伫列（来源标示 Agent proposed）。同样须 Apply 后才注入；未核准前不会改变 Agent 行为。需可验证的 evidence_quote（来自近期 user 或 tool 输出，或写入类 tool 参数如 add_report 报告正文）；不得提案 SQL 或查询执行态内容。单次查询步骤的 pitfalls 应记入 Query Step Ledger（[[QUERY_STEP]]），不进知识库。频控：每则用户讯息（整次 Agent 回复 stream）最多 2 条成功入队、3 次工具呼叫（含失败）；每对话最多 5 条 pending agent 提案（Apply 或 Dismiss 后释放额度）。入队失败（如 evidence 校验未过）在聊天中与一般 tool 相同折叠显示，不会出现审批卡片；仅成功入队才显示 Agent proposed knowledge 审批卡。主动提案只受 Enabled 控制，不受 Automatic suggestions 影响。

若 Enabled 为关闭或 LLM 未设置，则不会执行被动萃取或 Agent 提案入队。若仅 Automatic suggestions 关闭（Enabled 仍开），则不跑对话后背景萃取，但已核准知识仍注入，且 Agent 仍可提案入队。旧版 use_knowledge_extraction_queue 会在加载设置时自动与 Enabled 同步，不是独立的用户开关。

15.2 知识如何被使用（注入 Agent）

• 仅有已合并至知识库文件的内容（全域 User Knowledge 及各项目的 Project Knowledge）会在 AI 回复时注入系统提示词。核准后的知识档采 ## Rules / ## Info 两区（旧版四区或 ## Notes 会在读取时自动迁移）；目前 Rules 与 Info 全文一并注入（非仅 Rules）。
• Queued Knowledge 里待核准的项目不会进入模型上下文。
• Enabled 关闭时：不背景萃取、不注入、不允许受控写入与 Agent 提案，Agent 行为等同没有记忆库。
• 仅 Automatic suggestions 关闭时：不背景萃取；已核准知识仍注入，手动编辑与伫列 Apply／Dismiss 仍可用。

15.3 打开对话框与 Enabled 开关

点击标题列右上角的灯泡图标（Lightbulb），即可打开 Agent Memory 管理对话框。

• 当记忆功能打开且目前工作区的伫列中有待处理项目时，灯泡右上会显示红点提示（关闭记忆时不显示红点）。
• 对话框标题列下方设有 Enabled 切换：关闭时主内容区会以半透明层遮蔽并显示英文说明（大意为记忆已关、不注入且暂停背景萃取与 Agent 提案；需重新打开才可继续编辑与使用）。开关需切回打开才可编辑与处理伫列。
• 其下另有 Automatic suggestions 切换（仅在 Enabled 打开时可改）：关闭后不会在对话结束后跑背景萃取；不会删除或停用已核准知识。关闭 Enabled 时此开关会停用但仍显示你先前的偏好，重新打开 Enabled 后会恢复。

对话框顶部有两个标签页：Agent Memory（编辑知识库）与 Queued Knowledge (n)（n 为目前待核准笔数）。

15.3.1 首次启动：Agent Preferences

在首次完成 LLM 连接设置（API Key 等）且磁碟上尚无 User Knowledge 档时，会自动弹出 Agent Preferences 对话框（欢迎影片关闭或 hot-update 跳过影片后）。流程为：Onboarding 影片（可跳过）→ 设置 API Key → Agent Preferences（可 Skip）→ 首次聊天。

可设置四项（UI 为英文）：

• Save preferences：将选项写入 user_knowledge.md 的 ## Rules（每项一条英文规则，供 Agent 注入）。
• Skip for now、或按 X / Esc：仍会建立空的 User Knowledge 范本档（Rules 为 (none yet)），之后可在灯泡图标的 Agent Memory 编辑。
• 点击对话框外侧遮罩不会关闭；须明确 Save / Skip / X / Esc。
• 若 Agent Memory 总开关为关闭，仍可先保存偏好至知识档；打开 Enabled 后下一轮对话才会注入。
• 仅在尚无 User Knowledge 档时自动弹出一次；之后请在 Agent Memory 手动编辑。

项目知识档：自本版起，新建项目时会自动建立该项目的 project_knowledge.md 范本（## Rules / ## Info）。升级前已存在的旧项目不会自动补档，首次写入或 Reorganize 时仍会按需建立。

15.4 Agent Memory 标签页（编辑区与 Library status）

Agent Memory 标签页呈现三栏式版面：

• 左侧（文件列表）：顶部固定 User Knowledge（Global）；其下为各项目的 Project Knowledge 列表。目前聚焦的项目列右侧显示绿色 Eye 图标。
• 中央：Markdown 编辑器，查看与编辑目前选定之知识档内容。
• 右侧（Library status）：显示统计与操作区（见下表）。

Last updated 下方会依目前打开的文件（User / Project）显示 Reorganize 字数阈值说明：User 未达 2,500 字、Project 未达 5,000 字时，重组仅产出顶格条列；达阈值后才允许「短目录标题 + 缩排子条」（父行为查询用标签，事实写在子条）。若未达阈值但档内已有缩排子条，会提示 Reorganize 将扁平化。编辑未 Save 时统计以磁碟为准，并提示 Counts update after Save。此阈值与 Characters 的注入上限（6,000 / 20,000）不同。

待核准笔数仅显示于顶部 Queued Knowledge (n) 标签页标题。下方有 Save、Reorganize（见 §15.6）。

15.5 Queued Knowledge 标签页

Agent proposed 入队成功后，右侧 AI 对话中会出现知识提案卡片（显示建议内容、evidence、可选 rationale），可直接 User / Project / Dismiss 审批——不会像 ask_user 那样暂停 Agent；对话可继续。亦可稍后在 Queued Knowledge 标签页处理同一笔。

• 卡片状态会保留：套用或略过后，卡片会显示 Applied / Dismissed；重启应用或重新打开对话后仍会同步伫列状态，不会再出现可重复点击的按钮。
• Project 默认目标：有聚焦项目时，卡片上的 Project 会默认套用到该项目（而非项目列表第一个）。
• 套用后去哪看：User 写入全域 User Knowledge；Project 写入该项目的 Project Knowledge（须在 Agent Memory 左侧选择对应项目）。成功时会以英文 toast 提示写入位置。
• Queued 列表行为：Queued Knowledge 标签页仅显示 pending 项目；套用成功后该笔会从列表消失——属正常行为，不代表知识遗失。
• 勿重复套用：已 Dismiss 或已套用的项目，再次点击不会重写知识档；系统会提示 Already dismissed 或 Already saved，请到对应的 User / Project 知识档查看。
• 与 Agent Memory 同步：在卡片或 Queued 标签页套用后，若 Agent Memory 窗口已打开，伫列与编辑区会自动刷新；Project 套用时会切换至目标项目。

在 Queued Knowledge 中逐笔查看建议的文字与建议层级（user / project）。列表会标示来源：Chat extraction（对话结束后被动萃取）或 Agent proposed（分析中 Agent 主动提案）。选中一笔时，右侧会显示：

• Source：Chat extraction / Agent proposed。
• Agent rationale（若有）：Agent 供审核的简短说明，不注入模型。
• Evidence：所依据的可验证引述（user 原话或 tool 输出片段；升级前旧数据可能显示 No evidence (pre-migration item)）。
• Knowledge：建议并入知识库的内容摘要。
• Type：rule 或 info。
• Suggested project：建议的项目 ID；聚焦项目对话下多数会自动预填；若仍无效或缺失，列表会以琥珀色 Pick project 标示。

对选定项目可：

• User：将该建议套用到全域 User Knowledge（合并至对应章节）。
• Project：套用到项目知识。若该笔标示 Pick project 或未指定有效项目，系统会弹出 Pick project 对话框，请你选择目标项目后再套用。
• Dismiss：略过该笔，不写入知识档。

亦提供 Process all (by LLM recommend) 等批次处理；需手动选项目的项目（Pick project）会被跳过，需逐笔套用。介面上可能标示快捷键：1 User / 2 Project / 3 Dismiss（以及 ↑ / ↓ 切换列）。

15.6 Save、Reorganize 与内容验证

15.7 注意事项

• User Knowledge 为单一 Markdown 档（如 user_knowledge.md）；Project Knowledge 为各项目目录内之文件。皆可直接在 Agent Memory 标签页手动编辑。
• 知识萃取需有效 LLM 设置且 Enabled 为开；否则略过萃取，其余功能不受影响。
• 伫列项目在套用前不会出现在模型上下文中。
• 知识建议必须能追溯至你的原话（evidence_quote）；无法对应 user 讯息的建议不会入队，避免 AI 自行捏造业务规则。
• User 与 Project 知识皆可在 Agent Memory 标签页手动 Reorganize（开哪个档就整理哪个）。
• Reorganize 前会备份 .bak，若结果不满意可自磁碟还原参考。
• 知识内容保留你的原始语言。
• 注入与 Mode 一致（见 Library status Mode）：flat（User 未达 2,500 字、Project 未达 5,000 字）时全文注入；catalog（达阈值）时默认注入目录索引，Agent 可呼叫 expand_knowledge_catalog 加载完整条目。
• 达 catalog 字数但尚未整理成目录（全顶格、无父+子结构）时，新对话首次向 Agent 发送讯息前，系统可能自动执行一次 Reorganize（介面会显示「Reorganizing Agent Memory before injection…」）；同一对话内不会重复执行。若曾失败，新开对话可再试一次。打开 Agent Memory 编辑器且有未保存变更时，请先 Save，以免自动 Reorganize 覆写磁碟上旧内容（与手动 Reorganize 相同风险）。

设计说明： Agent Memory 治理全流程见 可治理的 Agent Memory。