| name | ucl-work-memory |
| description | 工作記憶區（Work Memory）— 所有 agent 共用、以「工作主題」為單位的 knowhow 庫。
開工前讀取該工作的拍板/坑/文件指路, 完工時整理回寫 — 換 agent 接手不斷線。
核心分工: 知識點放文件, 記憶透過 key 標註「要找哪些文件」+ 記決策/踩坑(decision/pitfall)。
記憶是工作期間的鷹架不是永久資產，全關後歸檔或刪除，紀錄留 git。
記憶可跨主題關聯(links), 讀取時 --with-links 一起拉。
觸發詞 (case-insensitive substring, 任一命中即 lazy-load):
- 工作記憶 / work memory / workmemory / 記憶區
- 讀取記憶 / 整理記憶 / 記錄 knowhow / knowhow / 工作knowhow
- 接續進度 / 上次進度 / 接手工作 / 交接 / memory_topic
- 開工前查 / 這項工作怎麼做 / 之前拍板了什麼 / 歸檔記憶 / archive memory
|
| related | ["<ucl_core:Docs~/zh-Hant/Workflows/Work_Memory_Workflow.md> | 完整設計與 schema | 必讀","<ucl_core:Docs~/zh-Hant/Workflows/Memory_Common_Principles.md> | **三層記憶共通鐵律**（格式/寫入/檢索/維護）| 本檔的三鐵律以那份為準","<ucl_core:Skills~/ucl-task/SKILL.md> | ucl-task | **任務承諾 / 看板進度** 歸那邊","<ucl_core:Skills~/ucl-memory/SKILL.md> | ucl-memory | **個人記憶 / 集體潛意識 Alaya / 回憶** 歸那邊"] |
| last_updated | 2026-08-25 v1.4 (TASK-0016: 補齊 10 個子指令、task_indices 反向索引、archive/delete 退場與墓碑機制) |
UCL Work Memory — 工作記憶區
🎯 核心金句：
「記憶回答『為什麼』與『怎麼踩過』，Task 回答『到哪了』，文件回答『怎麼用』。三者重疊的那部分不是備援，是漂移。」
「記憶是工作期間的鷹架不是永久資產，相關 Task 全完成後歸檔或刪除，紀錄留 git。」
「歸檔不等於失聯：archived 主題仍有 commit 歷史錨點，絕不靜默消失。」
📌 記憶到底放什麼 —— 一個例子勝過三條判準（Tim 2026-08-25）
工作內容是寫存檔系統。大致框架已完成，後續實作順序也規劃好了。收工時：
| 東西 | 去哪 |
|---|
| 施工順序（先做 A 再做 B，第三步要等 C） | 單子（驗收細項／留言） |
| 進度（做到哪、卡在哪） | 單子（時間線） |
| 完整規格／欄位表／怎麼用 | 文件 |
| 🎯 注意事項（做這一段要小心什麼、哪裡會咬人、為什麼當初不那樣做） | 記憶 |
⇒ 記憶＝「不適合進單子、也不適合進文件」的那一格。
它不是第四份進度表，也不是文件的草稿 —— 它是做過的人才知道、而下一個人一定會撞到的那些細節。
判準（照這個順序問）
- 它是「到哪了」嗎？ ⇒ 單子。進度、順序、誰在做、什麼算完成。
- 它是「怎麼用」嗎？ ⇒ 文件。規格、欄位、API、步驟。
- 它是「要小心什麼 / 為什麼是這樣」嗎？ ⇒ 記憶。
⚠ 而第 3 格還要再過一關：「換人接手需要知道嗎？」
只有我自己需要被打臉的拖延 ⇒ 個人見叢，不是這裡。
⚠ 記憶不是每張單都要有。 Tim 2026-08-25：
記憶側原本就不需要每張單都有 —— 只有跨日單會需要，甚至也不一定要。
⇒ 一張當天開當天關的單，不需要記憶主題。硬綁只會多一個要維護的空殼。
🛠 CLI（<UCL_Core>/Tools~/AgentCommands/work_memory.py 10 個子指令）
WM="python <UCL_Core>/Tools~/AgentCommands/work_memory.py"
$WM topics
$WM init --topic <slug> --title <title> --desc <一段簡介>
$WM add --topic <t> --type <decision|knowhow|pitfall|state|pointer> \
--id <slug> --title <t> --body-file <f> [--docs d1,d2] [--links t/f] --by <persona>
$WM read --topic <slug> --with-links
$WM read --topic <t> --types decision,pitfall,pointer
$WM supersede --topic <t> --id <舊> [--by <新frag-id>]
$WM supersede --topic <t> --id <舊> --new-id <新slug> --new-title <t> \
(--new-body <內容> | --new-body-file <f>) [--new-by <persona>]
$WM link --from <topic>/<frag> --to <topic>/<frag>
$WM index [--topic <slug>]
$WM tasks --topic <slug>
$WM tasks --topic <slug> --add 17 --remove 3
tasks --topic <slug> -- 5,8,15
archive --topic <slug>
archive --topic <slug> --commit <sha>
archive --topic <slug> --undo
delete --topic <slug> [--by <persona>]
delete --topic <slug> --by <persona> [--commit <sha>] --confirm
[!WARNING]
archive / delete 的 git 前置守衛量的是「真的在版控裡」，不是「沒有待處理的變更」。
判準：ls-files 回空 ⇒ 擋；磁碟上任一檔不在追蹤集合裡 ⇒ 擋（ignore 與 untracked 分開講，
因為處置不同：改 ignore 規則 vs git add）；全部追蹤到了才問 status。
🩸 兩隻血證（2026-08-25）：① WorkMemory 是巢狀 submodule，對父 repo 問 status
會回空字串 ⇒ 被讀成「乾淨」而放行；② 被 ignore 的路徑，status 一樣回空字串。
兩次都是空字串被讀成乾淨。
⇒ archived_commit 也取擁有這份內容的工作區的 HEAD，不是父 repo 的
（父層 pointer 長期未 bump ⇒ 那顆 sha 指到的版本裡 fragment 根本不在，而 sha 長得完全正常）。
📌 驗墓碑不是驗「有沒有寫一行」，是驗**「照那一行走得回內容嗎」**（拿 sha 去 git show）。
🔑 記憶的本體 = key → 知識點位置的映射（雙向錨點機制）
fragment 的核心價值是 related_docs/links 這組 ref — 把「這項工作的某個 key」映射到具體出處：
| ref 形式 | 例 | 指向與機制 |
|---|
| 檔案路徑 | Docs/Plan/HSceneEditorRework/README.md | 文件本體 |
| 檔案:行 | Assets/Scripts/.../HAnimSetting.cs:476 | 具體 code 知識點 |
| 任務單 (Task) | task:TASK-0008 | 雙向錨點機制：
① Task 側：memory_topic（單值字串）＋ memory_archived_commit
② 記憶側：主題卡 _topic.md 的 task_indices（由 work_memory.py tasks 管理）
③ op=show <N> 自動印出關聯主題之決策與指路摘要 |
| 酒館訊息 | tavern:2026-07-29#9355 | 討論/拍板的原始出處 |
| commit | commit:b33d2add | 實作落點 |
| 工作記憶 | <topic>/<fragment-id>（放 links 欄） | 跨主題關聯記憶 |
| 個人 fragment → 工作記憶 | workmem:<topic>[/<fragment-id>] | 從「我是誰」跨到「這活做到哪」（晚安時掛） |
🔄 四個機械觸發點（掛在必經路徑，不塞早安）
- 開工/回看 Task 時讀 (
Cmd_Task op=show <index>)：
- 自動檢驗並印出
memory_topic 狀態（5 種狀態：主題在 / 全部已退場 / 已歸檔 / 已刪除 / 連結壞了）與 pointer 指路，開工接回上下文。
- 結單時提示回寫 (
Cmd_Task op=resolve <index>)：
- 結單成功時，系統印出警示提醒：「本單有沒有值得留的 decision / pitfall？」（提示不阻擋）。
- 晚安雙向對帳 (
Cmd_GoodNight step=check)：
- 自動檢查未關單
updated_at 逾期 14 天未動、或 Task ↔ 記憶單向斷鏈時印出警示（只印不改）。
- 主 Task 全關後 PM 手動歸檔 (
work_memory.py archive)：
- 所有子單結案後，PM 手動執行歸檔；前置機械檢查 Git 狀態確保已落盤。
⛔ 不要做
- ❌ 把進度與看板快照記在記憶裡（違反單一真相源 — 進度由 Task 時間線紀錄）
- ❌ 把 plan 文件內容整段轉貼進 fragment（違反分工核心 — 寫 key 指路）
- ❌ 個人身分/關係層的記憶放這裡（那是
letters/<persona>/fragments 的事 → skill ucl-memory）
- ❌ 非工作但對所有人都成立的通用經驗放這裡（例：陪看不要劇透）→ 那是集體潛意識 Alaya，同樣走
ucl-memory
