MemoryCustodian

1) 安裝 MemoryCustodian（選擇與您的代理/工作流程匹配的路徑）: 選擇一種安裝方法：\n- 要求您的編碼代理從儲存庫安裝技能：https://github.com/waittim/MemoryCustodian\n- Codex（本地市場）：從結帳處運行 `codex plugin marketplace add .`，然後運行 `codex plugin add memory-custodian@memory-custodian-dev`。\n- Claude Code（插件）：對於本地測試，運行 `claude --plugin-dir .`，或使用 `./install.sh claude` 安裝到個人技能。\n- Gemini 風格的代理：使用 `./install.sh gemini` 或 `gemini skills link ./skills/memory-custodian` 安裝。\n- CLI/源碼結帳：透過 `scripts/memory-custodian ...` 從儲存庫運行，或使用 `python3 -m pip install -e .` 可編輯安裝以獲取 `memory-custodian` 命令。

2) 在專案中初始化 MemoryCustodian（每個儲存庫一次）: 為每個目標專案運行一次初始化：\n- 如果作為控制台腳本安裝：`memory-custodian init --project-root /path/to/project --agent all`\n- 從源碼結帳：`scripts/memory-custodian init --project-root /path/to/project --agent all`\n使用 `--agent codex`、`--agent claude`、`--agent gemini` 或 `--agent all` 生成您的代理讀取的精簡引導文件。

3) 了解初始化創建了什麼（記憶體所在位置）: 初始化在 `docs/memory/` 下創建預設的持久性記憶體集：\n- `manifest.md`（路由要載入的內容）\n- `brief.md`（當前專案形狀）\n- `decisions.md`（關鍵決策）\n- `constraints.md`（硬性要求）\n- `do-not-use.md`（被拒絕的路徑/墓碑）\n- `inbox.md`（暫存區）\n平台引導文件（例如 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`）保持精簡，並將代理指向 `docs/memory/`。

4) 在依賴之前策劃生成的簡報: 在 `init` 之後，`brief.md` 以帶有 TODO 的腳手架開始。在將記憶體視為準備就緒之前，從權威的專案來源（README、程式碼、文件）填充它。使用 `memory-custodian status --project-root /path/to/project`（或 `scripts/memory-custodian status ...`）查看簡報是否仍未策劃；`status` 和 `check` 會報告未策劃的簡報。

5) 為任務載入正確的記憶體（清單優先讀取）: 代理的預期工作流程是：\n1) 讀取 `docs/memory/manifest.md`。\n2) 讀取 `docs/memory/brief.md`。\n3) 僅載入清單中標記為與當前任務相關的文件。\n對於手動檢查，生成一個上下文包：\n- `memory-custodian read --project-root /path/to/project --task planning`\n- `memory-custodian read --project-root /path/to/project --task implementation`\n- `memory-custodian read --project-root /path/to/project --task artifact`

6) 當某些內容應在當前聊天中保留時，添加持久性記憶體: 使用 CLI 記錄決策/限制/偏好/被拒絕的方法：\n- `memory-custodian add "We chose manifest-first loading." --type decision`\n- `memory-custodian add "Persist sync retry backoff." --type decision --area sync --reason "Keep retries bounded across launches."`\n保持決策條目簡短（該工具強制執行令牌指南，並拒絕過長的寫入，除非您明確允許長條目）。

7) 僅在相關時啟用可選記憶體模組: 可選模組（例如規則、配置文件、區域）是選擇加入的，除非由清單啟用和路由，否則不會載入。根據需要啟用它們：\n- `memory-custodian enable preferences`\n- `memory-custodian enable rules/output`\n- `memory-custodian enable profile/git`\n- `memory-custodian enable area/frontend`\n啟用永遠不會覆蓋現有的模組文件。

8) 使用「do-not-use」來保留被拒絕的方法並避免回歸: 當您有意拒絕某種方法（例如儲存後端或架構）時，請將其記錄在 `docs/memory/do-not-use.md` 中（透過編輯或適當的添加/遺忘工作流程），這樣未來的會話就不會重新提出它。

9) 定期檢查健康狀況和協議兼容性: 運行確定性驗證以確保結構、預算和協議元數據正確：\n- `memory-custodian check --project-root /path/to/project`\n使用 `memory-custodian status` 快速概覽並檢測未策劃的簡報。

10) 壓縮和維護記憶體（預覽優先，安全變異）: 使用維護命令保持記憶體小巧和最新：\n- `memory-custodian compact --project-root /path/to/project`\n壓縮受到保護且預覽優先；僅在審查計劃後才應用更改。收件箱壓縮是保守的（例如，精確重複的頂級項目符號單元刪除和墓碑過濾），並期望代理/人類將語義提升到決策/限制中。

11) 安全地忘記過時的資訊（預覽優先）: 使用預覽優先的遺忘功能刪除或編輯過時的主題：\n- 預覽：`memory-custodian forget "old deployment note" --mode soft --project-root /path/to/project`\n- 審查後應用：`memory-custodian forget "old deployment note" --mode soft --apply --project-root /path/to/project`\n廣泛匹配需要明確確認（例如 `--allow-broad-match`）。某些情況需要手動重寫；該工具將拒絕不安全的整體刪除。

12) 需要時修復或替換現有設置: 如果文件丟失或元數據需要更新而無需覆蓋策劃的內容：\n- 修復：`memory-custodian init --project-root /path/to/project --repair`\n如果您有意進行完全替換，請使用預覽優先替換，並僅在正確時應用：\n- `memory-custodian init --project-root /path/to/project --replace-existing`\n- 然後僅在列出的文件應替換時添加 `--apply`。

13) 當工具更新時，遷移協議/專案記憶體版本: 當 `check` 報告舊的或丟失的協議元數據時，離線遷移專案清單：\n- 預覽：`memory-custodian migrate --project-root /path/to/project`\n- 審查後應用：`memory-custodian migrate --apply --project-root /path/to/project`

14) 在 Windows 上與源碼結帳使用正確的調用: 在 Windows 上，安裝控制台命令並使用 `memory-custodian ...`。在任何平台上的儲存庫結帳中，您可以將 `scripts/memory-custodian ...` 作為包裝器運行。