v1.1.0 to v1.1.0

---

name: memory-hygiene

description: |

Manual memory tiering — classify Hot/Warm/Cold, review candidates, and migrate MEMORY.md index + memory files. Use when the session-start advisory fires, MEMORY.md Hot grows past 15 entries, or you want a periodic cleanup. Trigger "memory-hygiene", "整理記憶", "memory 降級", "/memory-hygiene", "decay scan", "tier memory".

記憶要整理：MEMORY.md 的 Hot 區長太長、session 開場的提醒跳出來、或想定期清一次。

例如「整理記憶」「memory 降級」「decay scan」。

不用於：寫一則新記憶（那直接寫）、找一則舊記憶（那直接讀）。

metadata:

triggers: |

- "memory-hygiene"

- "/memory-hygiene"

- "整理記憶"

- "memory 降級"

- "memory 清理"

- "decay scan"

- "tier memory"

- "memory tier"

version: 1.1.0

requires:

- skill: driving-work-to-done

why: 「哪張單卡住了」這一題本支明文不答，交給它的 spine-loop-state.sh next；沒有它的話那一段是一個指不到任何地方的轉介

scope: universal

---

# Memory Hygiene

`memory-hygiene` 是 manual memory tiering：檢查 Hot / Warm / Cold，產生 demotion

candidate，並在使用者確認後搬移 memory files 與更新 index。

## Contract

這是 memory maintenance skill，不是一般 task planning。Scan / dry-run 只讀；apply 會寫

workspace memory，因此必須先有本 session 的 dry-run 結果與使用者明確確認。

## Mode Routing

| User says | Mode | Reference |

|---|---|---|

| `/memory-hygiene`, `memory-hygiene`, default | scan | `memory-hygiene-scan-flow.md` |

| `dry-run`, `full report`, `看看所有分類` | dry-run | `memory-hygiene-scan-flow.md` |

| `apply`, `搬檔`, `執行`, `migrate` | apply | `memory-hygiene-apply-flow.md` |

| `retire`, `退休`, `清掉做完的`, `過期的 memory` | retire | 見〈退休〉 |

## 退休：記進度的 memory，在它記的工作收斂之後就走

```bash

python3 .claude/skills/memory-hygiene/scripts/memory-hygiene-tiering.py retire \

--memory-dir {memory_dir} # 預覽，什麼都不動

python3 .claude/skills/memory-hygiene/scripts/memory-hygiene-tiering.py retire \

--memory-dir {memory_dir} --execute # 真的搬

```

**分層不是退休。** Hot → Warm 只是換一個資料夾躺著，索引還是指得到它。退休問的是另一

個問題：這份東西記的工作還活著嗎。`type: project` 記的是「現在做到哪」，那件工作收斂之後

它就不再是任何人的下一步了。

判定的依據是**那張單自己的狀態**（`{單}/.spine/loop-state.json` 的 `status`），不是誰記得

要來清——這一層已經有兩個手動退休到一半就停下來的資料夾。單號從 `snapshot_of` 或檔名取，

**不掃內文**：一份 handoff 會順帶提到十幾張單，拿內文去判會把還在用的錨點記錄，判成某張

早就收斂的單的殘骸。

四件事不退休，而且每一種都會被數出來印在報告上：`type` 不是 `project` 的、`pinned: true`

的（那是人的判斷，機械規則不得蓋過它）、單還在進行的、以及**找不到那張單容器的**。最後

那一種特別重要：把查不到當成做完了，退休掉的就是還在用的東西。

退休 ＝ 搬進 `archive/` 並從索引上拿掉，**不刪檔**。搬的時候會一併把指向它的連結、以及

它自己的相對連結重新算過——換了目錄，相對路徑的起點就換了，兩邊都會變成死指標。

## Reference Loading

| Situation | Load |

|---|---|

| Any run | `polaris-project-dir.md`, `feedback-memory-procedures.md` |

| Scan / dry-run | `memory-hygiene-scan-flow.md` |

| Apply | `memory-hygiene-apply-flow.md` |

| 要寫一份 memory（不是維護它） | `memory-write-contract.md` |

`memory-write-contract.md` 講的是**寫入端**：檔案放哪個資料夾、指標寫進哪一份索引、Hot 的

軟上限、以及 `pinned` / `topic` 兩個分層欄位。它以前住在使用者機器上的常駐指示檔裡，那個

`scripts/` 底下。

Classification rules live in `.claude/skills/memory-hygiene/scripts/memory-hygiene-tiering.py` and

`_template/rule-examples/feedback-and-memory.md` Memory Tiering.

Plan artifact authority lives in `bash .claude/skills/memory-hygiene/scripts/validate-memory-hygiene-plan.sh`。

`apply` 不應直接吃任意 JSON；必須先通過 plan validator。

## Hard Rules

- Apply requires prior dry-run in the same session.

- Do not hard-code user-specific memory paths; resolve active workspace memory dir.

- Do not auto-move pinned memories.

- 不刪除 Cold memories；archive 是 historical context。

- Routine migrations 不建立 feedback memory。

- If apply finds anomalies, record at most one framework-experience memory.

- Canonical apply chain is `dry-run --json | validate-memory-hygiene-plan.sh | apply`；不要手動改 plan JSON 後直接餵 apply。

- DP-213 起 apply 一定把 Hot 收斂到 ≤ 15（`MEMORY_HOT_CAPACITY` env 可覆寫）：超量者依

確定性 ranking 自動降 Warm，pinned + graduated_to 永遠不被擠出，migration log 列出

`overflowed-hot-capacity` 降級檔名。chain 在含 nested_frontmatter 的 plan 也能跑通；

validator 把 nested_frontmatter 移到 warnings，apply 內部 normalize 是唯一 enforcement

path，不需要 `POLARIS_MEMORY_HYGIENE_APPLY=1` bypass。

## Completion

Return mode, memory dir, Hot/Warm/Cold counts when available, candidate summary, apply status,

files moved, migration log path, and any anomalies.