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 是可選的審閱依據，可協助確認但不會被系統逐字驗證；未附時卡片會提示使用者儲存前確認。不得提案 SQL 或查詢執行態內容。單次查詢步驟的 pitfalls 應記入 Query Step Ledger（[[QUERY_STEP]]），不進知識庫。頻控：每則使用者訊息（整次 Agent 回覆 stream）最多 2 條成功入隊、3 次工具呼叫（含失敗）；每對話最多 5 條 pending agent 提案（Apply 或 Dismiss 後釋放額度）。入隊失敗（如內容衛生、去重或頻控）在聊天中與一般 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 首次啟動：Setup Mode 與 Agent Preferences

首次啟動時須先選擇協作路徑（Setup Mode Choice）：Built-in Agent (BYOK) 或 External Agent (MCP)。選 Built-in 後，在尚無 User Knowledge 檔且聊天記錄為空時，會自動彈出 Agent Preferences（可 Save / Skip）。流程為：Setup Mode Choice → Agent Preferences（Built-in only，可 Skip）→ Open AI Settings（Built-in）或 Agent Integration（External）→ 首次聊天。

External 路徑不彈 Agent Preferences；改由 Agent Integration 複製 connection kit 與 onboarding prompt 完成 first-run。

可設定四項（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。