Claude Memory Compiler 完整教學

1. 專案定位與背景

這是什麼？

Claude Memory Compiler 是一套將 Claude Code 對話自動轉化為結構化知識庫的系統。靈感來自 Andrej Karpathy 提出的 LLM Knowledge Base 架構，但不是擷取網路文章，而是從你自己與 Claude Code 的對話中萃取知識。

核心理念：編譯器類比 (Compiler Analogy)

1daily/          = 原始碼      (你的對話 — 原始素材)
2LLM             = 編譯器      (萃取並組織知識)
3knowledge/      = 執行檔      (結構化、可查詢的知識庫)
4lint            = 測試套件    (一致性健康檢查)
5queries         = 執行期      (使用知識)

你不需要手動整理知識。你只要進行對話，LLM 負責合成、交叉引用與維護。

為什麼不用 RAG？

Karpathy 的洞察：在個人規模（50-500 篇文章）下，LLM 閱讀結構化的 index.md 比向量相似度檢索 (vector similarity) 表現更好。LLM 理解你真正在問什麼；cosine similarity 只找到相似的詞。RAG 在文章數超過 ~2,000 篇、index 超出 context window 時才有必要。

2. 安裝指南

前置需求

  • Python >= 3.12
  • uv 套件管理器
  • Claude Code 已安裝並有有效的 Claude subscription (Max / Team / Enterprise)
  • 不需要另外申請 API key — 系統使用 Claude Code 內建的認證 (~/.claude/.credentials.json)

安裝步驟

 1# 1. Clone repo
 2git clone https://github.com/coleam00/claude-memory-compiler.git
 3cd claude-memory-compiler
 4
 5# 2. 安裝 Python 依賴
 6uv sync
 7
 8# 3. 將 hooks 設定複製到你的目標專案
 9# 方法 A：全新設定
10cp .claude/settings.json <your-project>/.claude/settings.json
11
12# 方法 B：合併到既有設定
13# 手動將 hooks 區段合併到你現有的 .claude/settings.json

設定檔說明 (.claude/settings.json)

 1{
 2  "hooks": {
 3    "SessionStart": [{
 4      "matcher": "",
 5      "hooks": [{ "type": "command", "command": "uv run python hooks/session-start.py", "timeout": 15 }]
 6    }],
 7    "PreCompact": [{
 8      "matcher": "",
 9      "hooks": [{ "type": "command", "command": "uv run python hooks/pre-compact.py", "timeout": 10 }]
10    }],
11    "SessionEnd": [{
12      "matcher": "",
13      "hooks": [{ "type": "command", "command": "uv run python hooks/session-end.py", "timeout": 10 }]
14    }]
15  }
16}
  • matcher 為空字串表示匹配所有事件
  • timeout 控制 hook 最大執行秒數（hooks 本身只做本地 I/O，不呼叫 API）
  • 路徑使用相對路徑，從專案根目錄起算

驗證安裝

安裝完成後，下次開啟 Claude Code session 時：

  1. session-start.py 會自動注入知識庫 index 到 context
  2. 結束 session 或觸發 context compaction 時，對話會被自動擷取
  3. 查看 scripts/flush.log 確認背景程序是否正常運作

3. 核心架構解析

三層架構


graph TB
    subgraph "Layer 1: 對話擷取"
        A[Claude Code Session] -->|SessionEnd hook| B[session-end.py]
        A -->|PreCompact hook| C[pre-compact.py]
        B --> D[flush.py
背景程序]
        C --> D
    end

    subgraph "Layer 2: 知識編譯"
        D -->|萃取重點| E[daily/YYYY-MM-DD.md]
        E -->|6PM 自動 or 手動| F[compile.py]
        F --> G[knowledge/concepts/]
        F --> H[knowledge/connections/]
        F --> I[knowledge/qa/]
        F --> J[knowledge/index.md]
    end

    subgraph "Layer 3: 知識注入與查詢"
        K[session-start.py] -->|讀取 index.md| A
        L[query.py] -->|Index-guided| G
        L --> H
        L --> I
        M[lint.py] -->|7 項檢查| G
    end

    style A fill:#e1f5fe
    style F fill:#fff3e0
    style L fill:#e8f5e9

資料流動循環


sequenceDiagram
    participant U as 使用者
    participant CC as Claude Code
    participant SE as SessionEnd Hook
    participant FL as flush.py
    participant DL as daily/*.md
    participant CP as compile.py
    participant KB as knowledge/
    participant SS as SessionStart Hook

    U->>CC: 開始對話
    SS->>CC: 注入 index.md + 最近 daily log
    U->>CC: 工作中...
    Note over CC: Context 快滿
    CC->>SE: PreCompact 觸發
    SE->>FL: 背景萃取 context
    FL->>DL: 追加到今日 daily log
    U->>CC: 結束 session
    CC->>SE: SessionEnd 觸發
    SE->>FL: 背景萃取 transcript
    FL->>DL: 追加到今日 daily log
    Note over FL: 若 >= 18:00
    FL->>CP: 自動觸發編譯
    CP->>KB: 寫入 concepts / connections / index
    Note over SS: 下次 session
    SS->>CC: 注入更新後的 index

目錄結構

 1claude-memory-compiler/
 2├── .claude/settings.json      # Hook 設定檔
 3├── AGENTS.md                  # Schema 定義（LLM 編譯器規格書）
 4├── hooks/
 5│   ├── session-start.py       # Layer 3: 知識注入
 6│   ├── session-end.py         # Layer 1: 對話擷取（session 結束）
 7│   └── pre-compact.py         # Layer 1: 對話擷取（context 壓縮前）
 8├── scripts/
 9│   ├── compile.py             # Layer 2: 知識編譯器
10│   ├── query.py               # Layer 3: 知識查詢
11│   ├── lint.py                # 健康檢查
12│   ├── flush.py               # 背景記憶萃取
13│   ├── config.py              # 路徑常數
14│   └── utils.py               # 共用工具
15├── daily/                     # 每日對話日誌（append-only, immutable）
16├── knowledge/                 # 編譯後的知識文章
17│   ├── index.md               # Master catalog
18│   ├── log.md                 # 編譯日誌
19│   ├── concepts/              # 概念文章
20│   ├── connections/           # 交叉洞察
21│   └── qa/                    # 查詢回存文章
22└── reports/                   # Lint 報告

4. 核心功能詳解

4.1 Hook 系統：自動對話擷取

session-start.py（SessionStart hook）

  • 功能： 讀取 knowledge/index.md + 最近的 daily log，注入到新 session 的 context 中
  • 特性： 純本地 I/O，無 API 呼叫，< 1 秒完成
  • 最大 context 注入： 20,000 字元
  • 輸出格式： JSON {"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "..."}}

session-end.py（SessionEnd hook）

  • 功能： 讀取 JSONL transcript，萃取最後 30 turns（最多 15,000 字元），spawn flush.py 為背景程序
  • 遞迴防護 (recursion guard)： 檢查 CLAUDE_INVOKED_BY 環境變數，若已設定則立即退出
  • 跨平台： Windows 用 CREATE_NO_WINDOW，Mac/Linux 用 start_new_session=True
  • 最低 flush 門檻： 至少 1 個對話 turn

pre-compact.py（PreCompact hook）

  • 功能： 與 session-end.py 架構相同，但在 context window 自動壓縮前觸發
  • 重要性： 長時間 session 可能多次觸發 auto-compaction，若沒有 PreCompact hook，中間的 context 會在 summarization 時遺失
  • 最低 flush 門檻： 至少 5 個對話 turns
  • 已知問題： Claude Code bug #13668 可能導致 transcript_path 為空

4.2 flush.py：背景記憶萃取

運作流程：

  1. 設定 CLAUDE_INVOKED_BY=memory_flush 防止遞迴
  2. 讀取 pre-extracted conversation context（.md 暫存檔）
  3. 去重機制 (deduplication)： 同一 session 60 秒內不重複 flush
  4. 呼叫 Claude Agent SDK：query() with allowed_tools=[], max_turns=2
  5. Claude 判斷值得保存的內容 — 回傳結構化 bullet points 或 FLUSH_OK
  6. 追加到 daily/YYYY-MM-DD.md
  7. 清除暫存檔
  8. End-of-day 自動編譯： 若本地時間 >= 18:00 且今日 daily log 有變動（SHA-256 hash 比對），自動觸發 compile.py

Daily log 格式：

 1# Daily Log: YYYY-MM-DD
 2
 3## Sessions
 4
 5### Session (HH:MM) - Brief Title
 6**Context:** 使用者在做什麼
 7**Key Exchanges:** 重要的問答交流
 8**Decisions Made:** 決策與理由
 9**Lessons Learned:** 踩到的坑與學到的教訓
10**Action Items:** 後續待辦

4.3 compile.py：知識編譯器

核心機制：

  • 使用 Claude Agent SDK 的 async streaming query() 介面
  • allowed_tools： ["Read", "Write", "Edit", "Glob", "Grep"]
  • permission_mode： "acceptEdits" — 自動核准所有檔案操作
  • max_turns： 30
  • 增量編譯： 透過 state.json 追蹤 daily log 的 SHA-256 hash，跳過未變動的檔案

prompt 組成：

  1. AGENTS.md schema（編譯規格書）
  2. 現有的 index.md
  3. 所有現有 wiki articles 全文
  4. 待編譯的 daily log

產出的文章類型：

類型路徑說明
Concept (概念)knowledge/concepts/原子化知識文章：事實、模式、決策、偏好、教訓
Connection (連結)knowledge/connections/跨概念的交叉洞察，連結 2+ 個 concept
Q&A (問答)knowledge/qa/查詢回存的答案，讓知識庫持續增長

CLI 指令：

1uv run python scripts/compile.py              # 只編譯新的/有變動的
2uv run python scripts/compile.py --all        # 強制全部重新編譯
3uv run python scripts/compile.py --file daily/2026-04-01.md  # 指定檔案
4uv run python scripts/compile.py --dry-run    # 預覽不執行

4.4 query.py：Index-Guided 知識查詢

  • 將整個知識庫（index + 全部文章）載入 context
  • LLM 讀取 index，選擇 3-10 篇相關文章，合成答案
  • --file-back 選項： 將答案回存為 knowledge/qa/ 文章，實現知識的「複利效應」(compounding loop)
1uv run python scripts/query.py "What auth patterns do I use?"
2uv run python scripts/query.py "What's my error handling strategy?" --file-back

4.5 lint.py：7 項知識庫健康檢查

檢查項目類型偵測內容
Broken links (斷鏈)結構性[[wikilinks]] 指向不存在的文章
Orphan pages (孤兒頁)結構性沒有任何入向連結的文章
Orphan sources (未編譯來源)結構性尚未編譯的 daily log
Stale articles (過時文章)結構性來源 log 在編譯後有變動
Missing backlinks (缺少反向連結)結構性A 連結到 B，但 B 沒連結回 A
Sparse articles (稀疏文章)結構性低於 200 字的文章
Contradictions (矛盾偵測)LLM跨文章的衝突宣稱（需 LLM 判斷）
1uv run python scripts/lint.py                    # 全部檢查
2uv run python scripts/lint.py --structural-only  # 跳過 LLM 檢查（免費）

5. 應用場景

5.1 個人開發知識累積

最直接的用途：在日常使用 Claude Code 開發的過程中，自動累積「做了什麼決策、為什麼、踩了哪些坑」的結構化知識。下次遇到類似問題時，SessionStart hook 會自動將相關知識注入 context。

5.2 專案 onboarding

新成員加入專案時，可以直接查詢知識庫了解團隊的技術決策歷史：

1uv run python scripts/query.py "Why did we choose Supabase over Firebase?"

5.3 架構決策記錄 (ADR)

系統自動從對話中萃取架構決策，比手動維護 ADR 文件更低摩擦。Connection articles 自動揭示跨模組的非明顯關聯。

5.4 Obsidian 知識圖譜

知識庫使用 Obsidian-style [[wikilinks]]，可直接用 Obsidian 打開 knowledge/ 目錄，享受 graph view、backlinks 和全文搜尋。

6. 資安掃描報告

掃描結果：🟢 低風險

掃描範圍： 全部 .py / .md 檔案，搜尋 eval / exec / subprocess / shell=True / http / requests / pickle / secret / token / password / api_key 等敏感關鍵字。

發現：

項目風險等級說明
subprocess.Popen (hooks)🟢 低session-end.py 和 pre-compact.py 使用 subprocess 啟動背景程序。參數為硬編碼路徑（uv run python flush.py），無使用者輸入注入風險。Windows 上使用 CREATE_NO_WINDOW 避免主控台閃現。
subprocess.Popen (flush.py)🟢 低flush.py 中 maybe_trigger_compilation() 啟動 compile.py。同樣為硬編碼路徑，無注入風險。
permission_mode="acceptEdits"🟡 注意compile.py 和 query.py 使用 Agent SDK 時設定自動核准所有檔案操作。這是功能需求（LLM 需要直接寫入 knowledge/ 目錄），但意味著 LLM 有完整的檔案讀寫權限。建議限制 cwd 範圍。
無 API Key 外洩🟢 安全不在程式碼中硬編碼任何 API key，使用 Claude Code 內建認證。
無 shell=True🟢 安全所有 subprocess 呼叫都不使用 shell=True，避免 shell injection。
無 eval / exec🟢 安全無動態程式碼執行。
無外部 HTTP 請求🟢 安全不直接呼叫 requests / urllib / curl，所有 LLM 通訊透過 Claude Agent SDK。

總結： 程式碼安全性良好。唯一需注意的是 permission_mode="acceptEdits" 給予 LLM 自動檔案操作權限，這是設計需求而非漏洞。無授權 (LICENSE) 是法律層面的注意事項。

7. 常見問題 FAQ

Q1: 需要 API key 嗎？

不需要。系統使用 Claude Code 內建的認證（~/.claude/.credentials.json），費用涵蓋在你的 Claude subscription (Max / Team / Enterprise) 中。

Q2: 為什麼自動編譯只在 18:00 以後觸發？

這是 flush.py 中的 COMPILE_AFTER_HOUR = 18 設定。設計理念是讓一整天的對話累積到 daily log 後，在晚上一次性編譯。你可以修改這個常數，或隨時手動執行 uv run python scripts/compile.py。

Q3: 每次編譯要花多少錢？

約 $0.45-0.65 per daily log。成本隨知識庫增長而增加，因為 compile prompt 包含所有現有文章。

Q4: token 消耗量大怎麼辦？

這是已知的 open issue (#3, #5)。目前 compile.py 和 query.py 會將整個知識庫塞入 prompt。當文章數超過 ~100 篇時，可能觸及 context window 限制。長期解決方案是在 ~2,000+ 篇時加入 hybrid RAG。

Q5: 可以搭配 Obsidian 使用嗎？

可以。知識庫是純 Markdown + [[wikilinks]]，直接用 Obsidian 打開 knowledge/ 目錄即可。已有 .gitignore 排除 .obsidian/ 目錄。

Q6: 為什麼沒有 LICENSE？

目前是 open issue (#11, #23)。社群建議新增 MIT 或 Apache 2.0。在正式授權前，使用時需注意法律風險。

Q7: 同一 session 會重複 flush 嗎？

不會。flush.py 有去重機制 (last-flush.json)，同一 session_id 在 60 秒內不會重複處理。

8. 進階技巧

8.1 自訂文章類型

在 knowledge/ 下新增目錄（如 people/、projects/、tools/），並在 AGENTS.md 中定義文章格式，最後更新 utils.py 的 list_wiki_articles() 讓系統能掃描到新目錄。

8.2 調整編譯時間

修改 scripts/flush.py 中的常數：

1COMPILE_AFTER_HOUR = 18  # 改為你偏好的小時數，例如 12 表示中午

8.3 手動編譯特定日期

1uv run python scripts/compile.py --file daily/2026-04-01.md

8.4 查詢並回存答案（知識複利）

1uv run python scripts/query.py "How should I structure API error responses?" --file-back

使用 --file-back 讓每次查詢的答案都成為知識庫的一部分。下次問類似問題時，系統會參考先前的回答，形成知識的複利效應 (compounding loop)。

8.5 結構性 lint（免費）

1uv run python scripts/lint.py --structural-only

跳過需要 LLM 的矛盾偵測，其餘 6 項結構性檢查完全免費。

8.6 調整 context 萃取量

在 hooks/session-end.py 和 hooks/pre-compact.py 中：

1MAX_TURNS = 30          # 最多擷取幾個對話 turn
2MAX_CONTEXT_CHARS = 15_000  # 最大字元數
3MIN_TURNS_TO_FLUSH = 1     # 最低 turn 數門檻

9. 整合進其他工作流

9.1 與 AI-knowledge_template v1 的互補性

面向claude-memory-compilerAI-knowledge_template v1
知識來源Claude Code 對話 transcript外部 URL / GitHub / paper / 影片
組織方式LLM 自動編譯 wiki手動 / 半自動 layer 工作流
檢索Index-guided (index.md)paper-qa-lite RAG / quarkdown search
輸出Markdown + wikilinksMarkdown + quarkdown HTML + PDF
擴展性~500 篇內最佳依 layer 而異

整合建議：

  • 將 knowledge/ 目錄的重要 concept articles 匯入 AI-knowledge_template 的 inbox/ 作為知識來源
  • 使用 paper-qa-lite 對 knowledge/ 目錄做 RAG 問答，當文章數超過 index-guided 的有效範圍時特別有用
  • 用 graphify 對 knowledge/ 目錄建立知識圖，視覺化概念之間的關聯

9.2 與 CI/CD 整合

1# 在 CI pipeline 中加入 lint 檢查
2uv run python scripts/lint.py --structural-only
3# 若有 error 則 fail build

9.3 多專案共享

目前設計為單一專案使用。若要跨專案共享：

  1. 將 knowledge/ 目錄做成 git submodule
  2. 或用 symlink 指向共用目錄
  3. 注意 config.py 中的路徑常數需調整

10. 重點摘要 Checklist

  • 安裝： uv sync + 複製 .claude/settings.json
  • 驗證： 開啟 Claude Code session，查看 scripts/flush.log 確認 hook 運作
  • 理解三層架構： hooks (擷取) → flush/compile (編譯) → session-start/query (查詢)
  • 注意 18:00 限制： 自動編譯預設只在 18:00 後觸發，可手動 compile.py 或修改 COMPILE_AFTER_HOUR
  • 成本意識： 每日編譯 ~$0.50，token 消耗隨知識庫增長
  • 無 LICENSE： 目前無正式授權，使用前評估法律風險
  • Obsidian 整合： 直接 vault 指向 knowledge/ 即可
  • 定期 lint： 至少每週跑一次 lint.py --structural-only 維護知識庫健康
  • 知識複利： 善用 query.py --file-back 讓每次查詢都累積知識

11. 進一步閱讀

  • AGENTS.md（完整技術參考）： 包含所有文章格式 schema、hook 架構細節、script 內部實作、跨平台說明、成本估算、自訂選項
  • Karpathy’s LLM Knowledge Base： 原始架構靈感來源
  • Claude Agent SDK： 系統核心依賴，提供 LLM 呼叫與工具使用能力
  • uv 套件管理器： 本專案使用的 Python 套件管理器
  • GitHub Issues： 查看 open issues 了解已知問題與社群討論