{"slug":"memory-lint","title":"memory-lint","summary":"Use when the user wants to lint a Claude Code memory directory (~/.claude/memory or custom path) for index inconsistency, broken cross-links, stale project state, duplicate / conflicting feedback rules, naming violations, frontmatter gaps, and oversized files. Phase 1 is a read-o","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-18T13:26:55.82157Z","repo":{"url":"https://github.com/KerberosClaw/kc_ai_skills","stars":79,"forks":14,"license":"MIT","updatedAt":"2026-09-23T08:52:42Z"},"bodyHtml":"
\n

name: memory-lint\ndescription: \"Use when the user wants to lint a Claude Code memory directory (~/.claude/memory or custom path) for index inconsistency, broken cross-links, stale project state, duplicate / conflicting feedback rules, naming violations, frontmatter gaps, and oversized files. Phase 1 is a read-only scan and report. Phase 2 applies fixes only for findings the user explicitly picks. Phase 3 verifies with an independent process and rolls back if it fails.\"\nversion: 0.3.0\nstatus: mvp\ntriggers:

\n\n
\n

memory-lint — Memory 品質健檢

\n
Phase 1  唯讀掃描 ──► 報告（預設只做這段，不動任何檔案）\n                        │  user 逐條拍板要修哪些\nPhase 2  執行修正 ──► commit（開工前先記回退點）\n                        │  改完全部提交 = 凍結\nPhase 3  獨立複驗 ──► 過 → 收工\u3000／\u3000不過 → 回退到 Phase 2 前\n
\n

\uD83D\uDD34 收到 lint 觸發詞的預設動作是出報告。 user 必須明確點名要修哪幾條\n（或明說「全部修掉」）才准進 Phase 2。Phase 1 期間不准順手合併、順手刪、順手歸檔。

\n

跟 llm-wiki-lint 差異：本 skill 針對 memory 目錄（prefix-based 平鋪結構）；\nllm-wiki-lint 針對 Karpathy LLM Wiki repo（wiki/ + raw/ + SCHEMA.md 三層）。

\n
\n

Phase 1 — 唯讀掃描

\n

Step 1: 找到 memory 目錄

\n

依序嘗試，命中第一個就用：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
順序來源
1$ARGUMENTS 第一個位置參數
2環境變數 $CLAUDE_MEMORY_DIR
3settings.json 的 autoMemoryDirectory
4~/.claude/memory/
5都找不到 → 停止，告訴 user「偵測不到 memory 目錄」，不要瞎猜
\n

第 3 條要看當前設定目錄（多帳號並存時 $CLAUDE_CONFIG_DIR 會指到別處）：

\n
CFG=\"${CLAUDE_CONFIG_DIR:-$HOME/.claude}\"\nMEMORY_PATH=$(jq -r '.autoMemoryDirectory // empty' \"$CFG/settings.json\" | envsubst)\n
\n

Step 2: 跑機械掃描

\n
# <skill_dir> = 本 SKILL.md 所在的目錄；掃描標的由參數帶入，\n# 所以在哪個工作目錄呼叫都不影響結果\npython3 <skill_dir>/scripts/scan.py \"$MEMORY_PATH\"\n
\n

只用標準函式庫、唯讀、輸出 JSON。目標目錄由參數帶入，所以在哪個工作目錄呼叫都一樣。\n沒有 MEMORY.md 會回 {\"fatal\": ...} 並以 exit 1 結束。

\n

腳本已經處理掉幾個會讓檢查靜默失效的坑，不要自己在對話裡改寫成 shell 一行流：

\n\n

輸出欄位：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
欄位意義
layout單層（只有 MEMORY.md）／兩層（MEMORY.md 只留路由、細目在 index_*.md）
index_declared_missingMEMORY.md 指到但磁碟上沒有的子索引
index_orphaned磁碟上有、但沒人指向的孤立子索引
orphan / missing有檔沒被索引／索引指向不存在的檔
frontmatter缺 name／description（只認頂層）或 type（頂層或 metadata.type）
wiki_broken / wiki_external[[...]] 解析不到的／指向子目錄或外部的
oversize超過 300 行的檔（行數語意同 wc -l）
prefixes / no_prefix命名前綴分布與例外
\n

\uD83D\uDD34 兩層結構下若只拿 MEMORY.md 當索引來源，會把整庫誤判成 orphan。 腳本已處理，\n但若你另外手寫檢查，這是最容易踩的一個。

\n

Step 3: 判讀（這段才是本 skill 的價值）

\n

腳本只給事實，嚴重度與去留由你判斷。判斷前先讀 MEMORY.md 與相關索引的說明文字，\n很多「異常」其實是既定決策。

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
嚴重度收什麼
\uD83D\uDD34 Error結構壞了：index_declared_missing、orphan、missing、frontmatter 缺漏、真正的斷鏈、兩條規則直接互打
\uD83D\uDFE1 Warning沒壞但該看：index_orphaned、過期 dashboard、oversize、命名例外、疑似結束未歸檔
\uD83D\uDD35 Info啟發式：語意相近可能重複、description 與索引描述不符、同一計數寫在多處
\n

不確定就降一級。推測與語意相似一律不得標 Error。

\n

這些不是缺陷，別報

\n\n

這些要另外用眼睛看（腳本測不出來）

\n\n

Step 4: 出報告

\n

繁體中文（語言跟 memory 對齊）。每個 finding 必須有具體檔名 ＋ 行為描述 ＋\n建議動作（Error 必附）。結尾主動問要不要進 Phase 2，並建議優先序：\n一行就能修的（斷鏈、索引缺漏）→ 每個 session 都會載入的檔 → 大型重構。

\n
\n

Phase 2 — 執行修正（需明確授權）

\n

開工前四項，缺一不進

\n

1. 判斷是不是 git repo。 Step 1 只要求有 MEMORY.md，而預設的 ~/.claude/memory/\n常常不是 repo。整套回退機制不能預設 git 存在。

\n
# \uD83D\uDD34 要比對 top-level 是不是它自己，不能只問「這裡有沒有 git」——\n#    rev-parse --git-dir 會往上找父層 repo，memory 目錄只要剛好放在某個 repo 底下\n#    就會被誤判成 git 模式，接著把 memory 的改動提交進那個不相干的 repo\ntop=$(git -C \"$MEMORY_PATH\" rev-parse --show-toplevel 2>/dev/null)\n[ -n \"$top\" ] && [ \"$top\" = \"$(cd \"$MEMORY_PATH\" && pwd -P)\" ] && echo git || echo 非git\n
\n

2. 依上一步建立回退點：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
情況回退點回退方式
git repogit -C \"$MEMORY_PATH\" log --oneline -1 的 commit hash，寫進回報git -C \"$MEMORY_PATH\" revert 或退回該 commit
非 git見下方備份指令（放在 memory 目錄外，免得被自己掃到）見下方回復指令
\n
# 建備份：碰撞就停，不要覆蓋既有備份\nBAK=\"$MEMORY_PATH.bak.$(date +%Y%m%d-%H%M%S)\"\n[ -e \"$BAK\" ] && { echo \"備份路徑已存在，停止\"; exit 1; }\ncp -R \"$MEMORY_PATH\" \"$BAK\" && echo \"回退點：$BAK\"\n\n# 回復：一定要用 --delete，否則 Phase 2 新增的檔案不會被移除\nrsync -a --delete \"$BAK/\" \"$MEMORY_PATH/\"\ndiff -rq \"$BAK\" \"$MEMORY_PATH\" && echo \"回復完成且內容一致\"\n
\n

\uD83D\uDD34 「把備份複製回去」不等於回復。 單純覆蓋複製移不掉 Phase 2 新增的檔案，\n回復後會是舊檔與新檔的混合體，而且看起來像成功了。一定要用 rsync --delete\n（或等效做法）並用 diff -rq 驗過。

\n

3. 確認工作區乾淨（git 情況）：有未提交的改動先問 user。

\n

4. 把 Phase 3 的驗證管道先定下來並試跑一次。 三件事都要做完才算過：

\n
    \n
  1. 寫下你打算在 Phase 3 用的那一行完整指令（含唯讀旗標與標的目錄），記進回報。
    2. \n
  2. 用那一行實際發一次最小的唯讀請求（例如請它回報某個檔案的行數），確認拿得到回應。
    3. \n
  3. 拿不到回應就停下來問 user，讓他選：換一個管道、接受「只做自檢、不做外部複驗」，\n或不要進 Phase 2。user 選了「只做自檢」也可以繼續，但要在最終回報裡明講\n這次沒有外部複驗。
    4. \n
\n

\uD83D\uDD34 只看執行檔在不在是不夠的。 裝了但沒登入、設定壞掉，command -v 一樣會過，\n然後你會在 Phase 2 已經改完並提交之後才撞到 —— 正好是這道閘門要防的狀態。

\n

\uD83D\uDD34 本 skill 不指定用哪一套工具。 只要求它是獨立行程、可唯讀執行、\n可把標的目錄寫死。至於是哪一套 CLI agent，由執行者依環境決定並記錄下來。

\n

動手紀律

\n

\uD83D\uDD34 所有 git 指令一律帶 -C \"$MEMORY_PATH\"。 裸的 git add / git commit / git status\n會作用在呼叫端的專案上（子行程裡的 cd 不會改變父行程的工作目錄），\n結果是把別人的檔案提交掉，而 memory 的改動還躺在那裡沒進版控。

\n

\uD83D\uDD34 Edit / Write 可能被背景 session 的隔離守衛擋住。 memory 目錄常伴隨一個\n「Edit/Write 後自動 commit」的 hook，而用 Bash 改檔不會觸發那個 hook。\n被擋時的正解：用 Bash 寫檔，最後手動 git -C \"$MEMORY_PATH\" add -A && git -C \"$MEMORY_PATH\" commit，\n改完 git -C \"$MEMORY_PATH\" status -s 確認乾淨才算數。

\n

\uD83D\uDD34 git push 要另外問過，不含在 Phase 2 的授權範圍。 user 同意的是「修這幾條」，\n不是「把 memory 發佈到遠端」。memory 內容通常私密，而推送在多數託管服務上不可逆\n（就算之後刪掉，中間狀態可能已被同步或快取）。commit 完停手，明確問一句再動。\n例外：該目錄若本來就掛著自動推送的 hook，那是既有行為 —— 但仍要在回報裡講明。

\n

\uD83D\uDD34 不要在 memory 目錄內開 worktree。 若該目錄的 hook 跑的是 git add -A，\nworktree 會被當成 gitlink 提交進版控。

\n

\uD83D\uDD34 「規則漂移」類發現一律先逐檔讀過再決定。 例如「這幾個檔依規則不該存在」——\n這種規則幾乎都留有例外（文件查不到、跨 session 才需要知道的操作性事實）。\n報告階段只能標「待判斷」、禁止寫「建議刪除」；Phase 2 也禁止照單無腦刪。

\n

\uD83D\uDD34 改名要連帶處理入站引用，[[...]] 與 markdown 連結都要掃，含 archive/ 底下的。

\n

收尾

\n

重跑一次 scan.py，全綠才進 Phase 3。自檢就不過的東西不要浪費一次外部複驗。

\n

\uD83D\uDD34 「全綠」不是「JSON 完全是空的」。 已經跟 user 確認過、決定不處理的項目\n（刻意的外部連結、刻意超長的 canonical 檔、刻意不合併的規則群組）會一直留在輸出裡。\n定義是：輸出裡每一條剩餘項目，都在你這輪明確記錄下來的「已接受例外」清單上。\n把那份清單寫進回報，Phase 3 的 brief 也要附上，否則外部驗證者會把它們當成新缺陷報回來。

\n

⚠️ 腳本全綠不代表語意層也通過。 它只驗結構，改掉一處內容矛盾之後 JSON 完全不會變。\n語意層的判斷（矛盾、過時、重複）沒有機械證據，回報時要分開講。

\n
\n

Phase 3 — 獨立複驗

\n

\uD83D\uDD34 先凍結

\n

Phase 2 的改動要全部完成並提交（git）或備份定版（非 git）之後，才准派複驗。\n一邊改一邊驗等於叫對方驗一個會動的目標，結論無效、還浪費一輪。

\n

\uD83D\uDD34 要外部行程，不能用同 session 的 subagent

\n

subagent 繼承這個 session 的記憶注入，而那是 session 開始那一刻的快照 ——\n剛改完的東西不在裡面，連檔名都可能還是舊的。拿吃著舊快照的 agent 去驗磁碟真值，\n邏輯上不成立。 用獨立行程（例如另一套 CLI agent），它不吃這份注入才算外部視角。

\n

派工時要把標的目錄寫死、把寫入權關掉，否則它可能檢查錯的目錄，或動到剛凍結的檔案。

\n

兩種驗證題，抓的東西不重疊

\n

A. 機械事實查核 —— 答案非黑即白：MEMORY.md 結構與行數、改名前後的檔名各自存不存在、\n索引差集是否為空、[[...]] 解析失敗數是否為零、frontmatter 是否全數完整。

\n

B. Recall 可用性測試 —— 測「找不找得到」，設計比題目重要：

\n\n

\uD83D\uDD34 brief 要先寫明「哪些是刻意的」

\n

外部驗證者沒有脈絡。不先講，它一定會把既定決策當成缺陷報回來，然後你得逐條解釋 ——\n那正是審查迴圈燒時間的燃料。至少要先交代：刻意的外部連結、刻意超長的 canonical 檔、\n刻意不合併的規則群組、已知但這次不處理的待辦、以及不在掃描範圍的子目錄。

\n

判定與回退

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
結果動作
全過收工，回報改了什麼、驗了什麼
只揪出可修的小缺陷修掉 → 重新凍結 → 再驗一輪
結構性失敗（索引導不到、大量斷鏈、走不到答案）回退到 Phase 2 前的回退點，重新設計再來
\n

⚠️ 驗證結果是輸入、不是結論。 它報的每一條先自己複核再決定改不改，\n別因為「外部工具說的」就照做。特別留意三種誤判：把 user 刻意的決策當缺陷、\n把不在它視野內的東西（其他機器、已歸檔）當斷鏈、把「規則說不該存在」直接推成「該刪」。

\n

⚠️ 「審到沒問題為止」不是終止條件。 每修一次 diff 就更大，下一輪就有更多表面可挑，\n這是正回饋不是收斂。要收斂就把 diff 變小 —— 與其逐條硬補，不如把出錯表面整類移除\n（例如把散落的檢查邏輯收進一支測過的腳本）。判準改成「這條在實際使用路徑上打得到嗎」，\n打不到就記錄進文件、不動手。

\n
\n

Anti-patterns

\n\n

Important rules

\n
    \n
  1. Phase 1 唯讀不可協商 —— 報告階段禁用 Edit / Write / mv / rm / git
    2. \n
  2. Phase 2 需明確授權，且開工前四項前置缺一不可
    3. \n
  3. Phase 3 先凍結、要外部行程、標的寫死、寫入關掉
    4. \n
  4. Path 偵測順序固定 —— 5 級依序，找不到就停
    5. \n
  5. Severity 寧降勿升
    6. \n
  6. 每個 finding 必須有具體檔名
    7. \n
  7. 衝突永遠並列原句，不替 user 判定
    8. \n
  8. 報告印到對話即可，不另存檔
    9. \n
  9. 外部驗證是輸入不是結論，逐條複核
    10. \n
  10. 未來功能（cron 定排、跨機器比對）目前不存在 —— user 問起就說 v0.x 還沒做
    11. \n
\n","files":[{"path":"scripts/scan.py","sizeBytes":5588,"isText":true},{"path":"SKILL.md","sizeBytes":18229,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-18T13:27:28.34153Z","sha256":"5EE5C61E966DDCB2EFEE7D8F60A24A1F0C148B7F6CF03339B93E43D8115F98CE","sizeBytes":12374},"review":null,"source":{"repositoryUrl":"https://github.com/KerberosClaw/kc_ai_skills","path":"memory-lint","license":"MIT","commit":"2b453ffa281dc107732ca7659e863f5da955e07a","subtreeSha":"0E36F8FF0A2CABBC85DCAC088469523F90C2B829511A2576EBC59658CF0B4EF8","lastSyncedAt":"2026-09-27T19:30:37.836842Z"},"reviewedAt":"2026-09-18T13:28:22.578027Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/KerberosClaw/kc_ai_skills/tree/main/memory-lint"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kerberosclaw-kc-ai-skills@llmmart"},{"target":"git","command":"git clone https://github.com/KerberosClaw/kc_ai_skills.git"}]}