記憶管理
如何寫入 Claude Code 的自動記憶與 CLAUDE.md,使記憶庫在專案成長過程中仍可搜尋。
快速參考
| 使用者說... | 執行此動作 |
|---|---|
| 「記一下」(模糊、多條候選)/「覆盤」/「開發完了看有什麼值得記的」 | → 模式 1:候選評估(多候選篩選) |
| 「記一下今天那個 X 坑」(具體單條)/重大 bug 修完後/安全事件處置完/單次決策有非顯然結論 | → 模式 2:新建 memory(直接走) |
| 「更新這個 memory/修正 X 的結論」 | → 模式 3:update 既有 memory(優先於新建) |
| 待加段落超過 100 行或檔案已 > 4 個 H2 主題 | → 規則 6:拆分而非 update |
| 「改 schema/加新 type/改記憶結構」 | → 模式 4:結構性變更(必讀已踩坑清單) |
| 「新專案零記憶起步」/「怎麼開始」 | → 模式 5:零記憶 bootstrap |
| 「記憶系統看起來亂了/audit」 | → 專案根目錄有 scripts/audit-memory.sh 則執行;無則參考 templates/audit-memory.template.sh 自建 |
重要規則
規則 1:事實進 memory,方法進 skill
memory 檔案裝「踩過 X 坑」、「業界 Y 數據」、「專案 Z 狀態」;本 skill 裝「如何決定記什麼/怎麼寫/怎麼組織」。不要把 schema 規範寫到 memory 裡(類別錯誤)。
規則 2:先判斷「是否值得記」,再判斷「記到哪」
不是每個發現都該記。決策樹:
| 訊號 | 該記嗎 |
|---|---|
| 同樣的坑踩了第 2 次 | ✅ 必記 |
| 對抗審查發現非顯然的判斷 | ✅ 記決策的「Why」 |
| 業界對照/實測數字(可複用基線) | ✅ 記 |
| 一次性 debug 已修完無沈澱價值 | ❌ 不記(commit message 就夠) |
| 臨時狀態會變化 | ⚠️ 看持續性,長期才記 |
| 低頻但致命(半年沒讀但仍是唯一真相) | ✅ 留 —— 30 天未觸 ≠ 過時;刪的依據是「主題已消失/被取代」,不是「多久沒讀」 |
判斷「記到哪」—— 觸發就近性(locality)四級路由:
先問一個正交問題:「未來需要這條事實時,是正盯著某個具體程式碼位置,還是在做跨檔案決策/排查某類報錯?」
| 觸發條件 | 去處 | 機制 |
|---|---|---|
| 盯某一行/塊,WHY 一句話講得清 | 行內程式碼註解(就在那行上方) | 改檔案時 100% 撞見,0 索引成本 |
| 鎖定一組具體檔案的多點契約/檢查清單 | .claude/rules/<x>.md + paths: frontmatter | 碰匹配路徑自動注入 context |
| 觸發是場景/報錯/某類問題,或跨多檔案,或不屬於單個倉庫檔案(平台/SDK 坑) | memory(本系統) | description 命中 |
| 每個 session 都要守的規則(命令、技術棧、協作偏好) | CLAUDE.md | 常駐 |
綁某檔案的 feedback 預設 SPLIT:檔案局部內核 → 行內註解(寫前先 grep 那段程式碼,往往已有等價註解);memory 只留「跨檔案可複用的原則 + 指向該檔案的指標」。
三條防過度遷移護欄(預設 memory,寧可少遷):
- 抽掉具體檔案仍剩通用教訓 → 留 memory(如「別拿 optional 欄位做關鍵路徑決策」,具體檔案只是例子,原則可遷)
- 平台/SDK 行為跨多檔案復現 → 留 memory,哪怕有程式碼含義
- 墓碑(X 已退役→看 Y)/調查 SOP/業務經濟推理 → 留 memory(觸發在架構/場景層)
實證(一個 175 檔案生產庫的全量審計):僅 ~15% 條目綁單一檔案,且其中多數檔案內核早已在程式碼註解裡 —— 「遷移」多半是刪 memory 冗餘副本,不是真搬運。
.claude/rules/*.md 寫法(放專案 .claude/rules/,進 git → 跨機器/worktree 共享):
---
description: 一句話這條規則管什麼
paths:
- src/components/SomeDialog.tsx
- src/lib/providers/*.ts # 支援 glob
---
碰到上面路徑時自動注入的契約/檢查清單正文(多點 gotcha)。
⚠️ 原生 rules 注入的已知邊界(2026-07 核實,anthropics/claude-code issues):paths: 規則只在 Read 匹配檔案時注入,Write/新建檔案時不注入(#23478);使用者級 ~/.claude/rules/ 的 paths: 被忽略,只有專案級生效(#21858)。「建立新檔案時也必須生效」的契約要留在 CLAUDE.md,別只放 rules。
規則 3:優先 update 既有,不新建
主題相關已有檔案 → update 該檔案(加段落或加 changelog 段)。主題完全正交才新建。新建會導致主題碎片化 → 找東西難 → 失憶。
規則 4:memory 不自動載入,description 決定命中
topic 檔案(memory/*.md)在 session 啟動不載入,Claude 憑 MEMORY.md 索引裡的 description 判斷是否讀取。description 必須場景關鍵詞 + 核心結論混合,否則 Claude 會憑印象決定讀哪個。
原生機制核實(2026-07,官方 docs/en/memory):沒有向量/語意自動召回 —— 發現全靠「MEMORY.md 索引行 + 檔案名稱」,Claude 用 Read 按需讀取;讀取時 harness 會注入 "This memory is N days old" 時效提示。索引行 hook 的品質 = 命中率的全部,這是原生行為,不是本 skill 的約定。
規則 5:skill 自身要符合 skill 教的規範
如果本 skill 讓使用者寫 ## Why 段,本 skill 也應該解釋自己每條規則的 Why(它們都在本檔案 inline)。
Scope 注意:Rule 5 適用範圍是「方法/寫法/Quick Reference 形式等」,不遞迴適用 schema 規則。Schema(命名/frontmatter/Why 段)是給 memory 檔案的,不適用 skill 自身。Skill 不是 memory 檔案。
規則 6:何時拆分而非 update(防止單檔案/單組超載)
Rule 3 優先 update,但有閾值。觸發拆分的訊號(單檔案層):
| 訊號 | 行動 |
|---|---|
| 已有檔案 > 100 行,且要加的新內容跟原主題正交 | 拆出新檔案,不要塞 |
| 已有檔案已 ≥ 4 個 H2 頂層段,且新內容屬於第 5 個獨立主題 | 拆出新檔案 |
| 加段落後總長度跨過 150 行 | 評估是否拆(看主題獨立性) |
| 加的內容跟原檔案標題/description 不匹配 | 拆出新檔案(原檔案應該專注其聲明的主題) |
單組超載(索引層):
| 訊號 | 行動 |
|---|---|
| MEMORY.md 某大組條目數 ≥ 15 | 考慮建 hub memory(段落索引)替代扁平索引,新條目掛 hub |
| 一個組的 description 加起來掃一遍 > 25 行 | 同上 |
MEMORY.md > 23,000 字元(wc -m)或 > 190 行 | 🔴 原生硬限制 = 前 200 行 或 25K 字元,先到為準(官方 docs 措辭 "25KB",實測按 string length=字元執行:一份 27,972 字元/37.9KB 的索引恰在第 25,000 字元處截斷,按位元應提前 ~35%)。超出部分靜默不載入。⚠️ 別用 wc -c(位元組)估算:中文 UTF-8 每字 3 位元組,會高估 ~35% 餘量。接近上限時 harness 會注入警告,見到 Only part of it was loaded = 已經在丟索引 |
| 單條索引行 > ~160 字元 | description 堆太多細節 → 移進 topic 檔案或下沉到程式碼註解,索引只留「場景詞+核心結論」 |
為什麼單組超載也要管:Claude 憑 MEMORY.md 索引掃 description 命中,組內 20+ 條 description 憑一次掃描有遺漏率。建 hub 後,組索引只一行指向 hub,hub 內做主題地圖。
為什麼索引層整體最危險:單檔案/單組超載只是「命中力下降」;但索引整體被截斷 = 末尾整條不載入 = 命中力歸零,且靜默無報錯。所以 ⭐⭐⭐ 皇冠條目應放 MEMORY.md 靠頂部(抗截斷保險)。
超限/過大時的瘦身優先級(壓縮 description 是最差的第一招,自傷命中力):
- 先遷:檔案局部條目 → 行內註解/
.claude/rules(索引變小且命中率變高,見 Rule 2 四級路由) - 再刪:真墓碑(主題已消失/被取代且無防復活價值的)
- 再排:把 ⭐⭐⭐ 挪到 MEMORY.md 靠頂部
- 再分級:索引行按重要性分預算 — 皇冠條目 ≤160 字元,普通條目 ≤110,長尾低頻條目聚合成一行多鏈(
子主題 → [a](f1.md) · [b](f2.md),一行裝 5-10 個檔案)。另:連結 label 用去 type 前綴的短名([foo-bar](feedback_foo_bar.md)),別重複完整檔案名稱,每行省 12-45 字元 - 最後才壓縮單條 description 的資訊量
歷史踩坑案例(reference,非規則的一部分)
- 單檔案超載:一個 reference 檔案長到 130+ 行,塞了 7-8 個獨立子主題(基礎設施、cron 列表、故障手冊等),MEMORY.md 索引描述概括不全,Claude 命中不了具體子主題。拆成 5 個獨立 memory 後每個主題精準命中。
- 單組超載:某分組累積 20+ 條 entry,新 session Claude 掃索引時有遺漏,處理任務時重複造輪子。建一個 hub memory 聚合相關入口 → 解決。
- 索引層整體超載:MEMORY.md 漲到 43KB 位元組(≈31K 字元,超 25K 字元上限),93 條 description 各 400-900 字元,啟動時被靜默截斷,末尾 ⭐⭐⭐ 條目漏讀 → 一次調查裡把按設計運作的機制誤判成漏洞。教訓:description 不是越詳細越好,過詳細會撐爆索引反而害了命中。
- 位元組/字元混淆的誤校準:治理超載時把警告線按位元組(
wc -c)設成 32KB,而 harness 按字元執行(中文每字 3 位元組)→ 位元組線讓人以為還有餘量,索引再次被截。教訓:跟 harness 對表必須用同一單位,監控用wc -m。
工作模式
模式 1:候選評估(多候選,需要篩選)
觸發場景(多條候選 → 需要 Mode 1 篩選):
- 功能開發完/長 debug 完/對抗審查完
- 反濫用處置完(可能多個判斷點 + 教訓)
- 安全事件處置完/故障定位完
- 使用者說「記一下」(模糊,未指明具體哪個坑)
單條具體內容直接走 Mode 2:使用者說「記一下今天那個 wildcard bug」/「記一下連線洩漏的故障手冊」 → 已經明確單條 → Mode 2 不要 Mode 1。
步驟:
- 回顧本次對話關鍵節點(使用者校正、對抗審查發現、未預期 bug、業界對照查詢、單次決策的非顯然結論)
- 逐個套 Rule 2 決策樹,篩出值得記的
- 對每個候選,判斷:
- 是否已有 memory 檔案覆蓋?(grep MEMORY.md 索引)→ 有則走 Mode 3 update,無則走 Mode 2 新建
- 待加的內容是否超 Rule 6 拆分觸發線?→ 拆出新檔案
- 是否應該進 CLAUDE.md 而非 memory?(見下方表格)
- 跟使用者確認清單:列出「建議新增/建議 update/建議拆分」候選,等使用者確認再寫
memory vs CLAUDE.md 邊界:
| 內容性質 | 放哪 |
|---|---|
| 學到的具體踩坑(SDK bug、平台限制、業界數據) | memory feedback_* |
| 主題深度參考/標準方法/流程文件 | memory reference_* |
| 狀態性事實(進行中工作、臨時配置、當前架構快照) | memory project_* |
| 每次 session 都要遵守的規則(命令、技術棧、協作偏好) | CLAUDE.md |
| 特定檔案操作時才需要的規則 | .claude/rules/*.md 加 paths frontmatter |
模式 2:新建 memory(標準流程)
步驟 0:先過觸發就近性(Rule 2 四級路由)
寫之前先確認它真該進 memory:盯單一檔案 → 行內註解;一組檔案的契約 → .claude/rules+paths;場景/跨檔案/平台坑 → 才進 memory。綁檔案的 feedback 預設 SPLIT(內核進註解,memory 只留跨切原則 + 指標)。詳見 Rule 2。
步驟 1:確定 type
| Type | 何時用 | 必含資訊 |
|---|---|---|
| feedback | 學到的踩坑(SDK bug/平台限制/使用者偏好) | 原因(為什麼這個結論)+ 何時複用(觸發場景) |
| reference | 主題深度參考/標準方法/業界對照/複用 pipeline | 不強制原因段(描述性) |
| project | 狀態性事實(架構快照、進行中工作、經濟學分析) | 不強制原因段(狀態性) |
feedback 必含資訊的呈現形式(任一即可):
- 單獨段:
## Why或同義中文## 根因/## 原因/## 教訓/## 為什麼(audit 都接受) - 加粗行內:
**Why**:/**根因**:(短結論也可) - inline 在 description 或 ## 標題裡(如果結論本身已經隱含原因 + 何時複用,如對比 ❌/✅ 表格)
何時複用資訊:可以是單獨 ## How to apply 段,也可以是 description 含場景關鍵詞(如 tab 切換 / mutation 已經暗示觸發場景)。
步驟 2:檔案命名
<type>_<topic>[_<modifier>].md 全小寫底線:
- ✅
feedback_supabase_from_deadlock.md - ✅
reference_supabase_egress_favorites_refactor.md - ❌
feedback-supabase-deadlock.md(用了連字號) - ❌
FeedbackSupabaseDeadlock.md(駝峰式) - ❌
_schema.md(底線開頭會被當隱藏檔案,且 Claude 不會主動讀)
步驟 3:寫 frontmatter
---
name: kebab-case-slug
description: 場景關鍵詞 + 核心結論
type: feedback | reference | project # 平鋪(推薦)
# 或:
# metadata:
# type: feedback | reference | project # 巢狀(相容寫法)
---
type 欄位位置:type: 平鋪(推薦)或 metadata.type: 巢狀都接受。audit 腳本兩種都識別。新建檔案優先使用平鋪,跟現有多數對齊。
description 風格判定:
| ✅ 好 description | ❌ 壞 description |
|---|---|
瀏覽器端 supabase.from() mutation 在 tab 切換後死鎖,必須用 fetch() 調 REST API | Supabase 相關問題 |
CF Image Transformations 失敗 7 天快取 / cf-resized err= / FavoriteCard retry pattern | 圖片有時顯示不出來 |
RLS 策略必須用 (SELECT auth.uid()) 包裝,否則每行重複求值 | RLS 效能最佳化 |
判定標準:Claude 讀 description 時能不能立刻知道「這是 X 場景下要查的 Y 結論」。
步驟 4:寫正文
feedback 類(必含原因 + 何時複用):
# 標題(What — 一句話)
[核心結論 + 1-2 段背景]
## Why(或同義:## 根因 / ## 原因 / ## 教訓 / ## 為什麼)
[為什麼是這個結論 — 踩過的具體坑、對抗審查發現、使用者偏好]
**為什麼必填**:沒有原因段,下次重新討論同一決策時往往會得出同一個錯誤結論。
## How to apply(可省略,如 description 已含場景關鍵詞)
[何時複用這條 — 觸發場景、檢查清單、避坑步驟]
reference / project 類:不強制段結構,按主題自然組織即可。
步驟 5:加到 MEMORY.md 索引
- 選已有大組,不新建分組
- description 加到組內對應位置(高重要性用 ⭐⭐ / ⭐⭐⭐ 加粗)
- 跨主題:description 末尾加
(亦見 [[other-file]])
模式 3:Update 既有 memory(優先於新建)
步驟 1:用 grep 確認現有主題歸屬
grep -l "<關鍵詞>" memory/*.md
步驟 2:決定 update 方式
| 情況 | 怎麼 update |
|---|---|
| 新數據/新案例補充已有結論 | 在正文加段落或 changelog 段 |
| 已有結論被推翻 | 舊檔案頂部加 ⚠️ Superseded by [[new-file-slug]],新檔案正文寫「取代 [[old]] 的什麼部分」 |
| 只是 description 描述不夠清楚 | 改 MEMORY.md 索引,不改檔案本身(除非也加內容) |
步驟 3:同步 MEMORY.md
如果改了 description,MEMORY.md 對應行也要改。
模式 4:結構性變更(改 schema/加新 type/改分組)
必讀已踩過的坑清單:
- 不要嘗試 hook
if: "Write(memory/*.md)"glob 語法 —if:是 permission rule 不是 file glob,已驗證無效 - 不要用 exit 2 阻塞 hook — 已驗證破壞 pre-deploy batch 流(Claude 沒有自動重試機制)
- 不要把 schema 權威源放
_schema.md類底線開頭檔案 — Claude 不主動讀 topic 檔案 - 不要在專案
.claude/settings.json配 hook — 該目錄通常在.gitignore裡,不進 git 不跨 worktree - 加新必填欄位時同步 3 處:(a)本 skill 段「Mode 2 → 步驟 3」(b)MEMORY.md 頂部速查精華段(c)audit-memory.sh 腳本欄位列表
- 修 hook/加約束前先
bash scripts/audit-memory.sh看當前合規率 — <95% 才需要硬措施,≥95% 維持 soft warning - MEMORY.md 大小監控必須按字元(
wc -m)不是位元組(wc -c) — 原生上限 200 行/25K 字元按字元計;中文每字 3 位元組,按位元組校準會導致靜默截斷(見 Rule 6 歷史案例)
改 schema 流程:
- 跑 audit 拿當前基線
- 設計變更(改本 skill + 專案 hub)
- 驗證現有 memory 是否大批違反新規(>10% → 暫緩,先按新規遷移)
- 更新 MEMORY.md 精華段同步
- 改 audit 腳本欄位列表
- 複跑 audit 看新合規率
模式 5:零記憶 bootstrap(新專案)
當使用者在一個沒有 memory 系統的專案說「開始建記憶」:
步驟 1:確認 auto memory 目錄路徑
Claude Code 自動建 ~/.claude/projects/<project-slug>/memory/,其中 <project-slug> = 專案絕對路徑將 / 取代為 -。例:
- 專案
/Users/alice/Project/myapp→ slug-Users-alice-Project-myapp
如果 Claude Code 已經為該專案自動建立過 auto memory,目錄會存在。驗證:ls ~/.claude/projects/ | grep <專案名>。
步驟 2:建 MEMORY.md 索引
頂部範本(可壓縮到 ~25 行):
# <專案名> 專案記憶
## ⭐⭐⭐ 寫 memory 速查(硬規則)
- 檔案名:`<type>_<topic>.md` 全小寫底線;type ∈ {feedback, reference, project}
- 必填 frontmatter:name / description / type
- feedback 必須含 ## Why 段(或同義中文 ## 根因 / ## 教訓 / ## 原因)
- description 風格:場景關鍵詞 + 核心結論(單行 ≤160 字元)
- 同主題已有檔案 → update,不新建(超 Rule 6 閾值則拆)
- 本索引硬上限:前 200 行 或 25K 字元(先到為準),超出靜默不載入
- 詳細方法:memory-management skill
## ⭐ 專案主題列表
(暫無 — 後續按主題增加分組)
步驟 3:分組演進閾值(按檔案數決定結構)
| memory 檔案數 | 推薦結構 |
|---|---|
| < 15 條 | flat list,無分組(單一列表足夠,分組反而碎片化) |
| 15-25 條 | 引入 3-5 個大組(按主題聚合) |
| > 25 條 | 分組成熟,凍結分組禁止新建,新條目掛既有組(跨主題用 (亦見 X)) |
步驟 4:CLAUDE.md 頂部加 Memory 協議(3-5 行)
## Memory 管理
涉及 memory 寫入/更新/schema 調整時 → 使用 `memory-management` skill。
- 速查規則:MEMORY.md 頂部 ⭐⭐⭐ 段
- 體檢合規率:`bash scripts/audit-memory.sh`(可選,見 skill templates/)
步驟 5:複用本 skill 通用方法
不要把 skill 內容複製到專案。skill 在使用者級,所有專案共用一份方法。專案裡只放專案特定狀態(分組列表/待辦/專案特有踩坑)。
Schema 規範(權威源)
檔案命名
<type>_<topic>[_<modifier>].md 全小寫底線,type ∈ {feedback, reference, project}
必填 frontmatter
---
name: kebab-case-slug
description: 場景關鍵詞 + 核心結論
type: feedback | reference | project # 平鋪(推薦)
# 或:
# metadata:
# type: feedback | reference | project # 巢狀(相容)
---
audit 腳本兩種都識別。新建檔案優先平鋪。
feedback 必含資訊
原因段(任一):
## Why或同義中文標題## 根因/## 教訓/## 原因/## 為什麼/## Root cause(可帶英文:或中文:)- 加粗行內
**Why**:/**Why**:/**根因**:等
何時複用(任一):
- 單獨
## How to apply段 - description 含場景關鍵詞(隱含觸發場景即可)
description 風格
混合(場景關鍵詞 + 核心結論),讓 Claude 憑 description 命中「X 場景查 Y 結論」。單行 ≤ ~160 字元 —— 細節進 topic 檔案或程式碼註解(索引硬上限 = 200 行/25,000 字元先到為準,超出靜默不載入)
索引行格式
- [短標籤](完整檔案名.md) — hook。短標籤 = 去 type 前綴的連字號名(如 [supabase-from-deadlock](feedback_supabase_from_deadlock.md));長尾低頻條目用聚合行(子主題 → [a](f1.md) · [b](f2.md))
分組凍結
從既有大組選,禁止新建分組。歸屬模糊用 (亦見 hub-X) 跨參照。
常見錯誤
| 錯 | 對 |
|---|---|
| 憑印象寫 description「Supabase 問題」 | 寫場景關鍵詞 + 結論「supabase.from() tab 切換死鎖,用 fetch」 |
| feedback 只寫「是什麼」 | feedback 必帶 ## Why,保護未來不重新質疑 |
| 同主題新建第二個檔案 | 優先 update 既有,新建會碎片化 |
| 新建「網路問題」分組放 1 條 entry | 用既有分組,跨主題用 (亦見 X) |
| 把 schema 規範寫到 memory 檔案 | schema 在本 skill,memory 裝事實 |
| 用 hook exit 2 強制阻塞 | 用 soft warning(stderr + exit 0)或 audit 事後體檢 |
自我檢查(寫完後)
- 類型對嗎(feedback/reference/project)?
- 檔案名符合
<type>_<topic>.md全小寫底線? - frontmatter 3 欄位齊全(name / description / type)?
- feedback 類有原因段(
## Why或同義中文/加粗行內)? - description 含場景關鍵詞 + 核心結論?
- 已加到 MEMORY.md 索引正確大組下?
- 沒新建分組?(如果新建了,撤回放既有組)
- 跨主題加了
(亦見 X)提示? - Rule 6 檢查:新檔案 < 100 行 + < 5 個 H2 段?(如果 update 既有檔案讓它超閾值,改成拆出新檔案)
- 觸發就近性檢查(Rule 2):這條綁某個具體檔案嗎?若是,檔案局部 WHY 是否已/應在程式碼註解裡、memory 只留跨切原則?
- 索引層檢查:新增/改 description 後 MEMORY.md 仍 < 23,000 字元(
wc -m,不是位元組!)且 < 190 行 + 單行 ≤ ~160 字元? - 觸發力體檢:列 3 個未來可能問到的場景關鍵詞,模擬問「Claude 憑 description 會讀這個 memory 嗎?」(如果想像不出場景,description 不合格)
工具整合
audit 腳本是可選專案工具。
專案根目錄有 scripts/audit-memory.sh → 執行:
bash scripts/audit-memory.sh # 看合規率/列違規/列 30 天未觸
輸出:總檔案數/缺 frontmatter/缺 Why/MEMORY.md 斷鏈/30 天未觸/MEMORY.md 大小(字元+行,對照原生 200 行/25K 字元上限)/合規率%。 目標合規率 ≥ 95%。
沒有 audit 腳本 → 從範本自建:
# 使用者級 skill 自帶通用範本
cp ~/.claude/skills/memory-management/templates/audit-memory.template.sh \
<你的專案>/scripts/audit-memory.sh
# 修改 MEMORY_DIR 指向你專案的 auto memory 目錄
chmod +x <你的專案>/scripts/audit-memory.sh
bash <你的專案>/scripts/audit-memory.sh
參考預設 auto memory 路徑:~/.claude/projects/<project-slug>/memory/,見 Mode 5 步驟 1。