claude-code-memory-setup 完整教學

1. 專案定位與價值

這是什麼？

claude-code-memory-setup 是一套開源設定指南（MIT 授權），教你如何將 Claude Code 從「每次開 session 都失憶」的狀態，改造為具備 persistent memory（持久記憶） 和 codebase awareness（程式碼感知） 的智慧 agent。

解決什麼問題？

使用 Claude Code 開發時，有兩個隱性的 token 消耗黑洞：

1. Session 失憶症（Amnesia）：每次新 session 都要重新說明專案背景、技術棧、過去決策。
2. Codebase 重複讀取：Claude Code 每個 session 都會重讀所有檔案來理解結構。一個 ~40 檔案的專案，每次要花 ~20,000 tokens 僅僅是「搞清楚環境」。每天 10 個 session = 200,000 浪費的 tokens。

三層解決架構

量化效果

在一個 126 個 TypeScript 檔案的 React + Supabase 專案實測：

• Graph nodes (圖節點)：332
• Edges (邊)：258
• Token reduction per query (每次查詢 token 縮減)：499x
• LLM cost for generation (生成成本)：0 tokens（AST 模式）
• 匯入的 chat 筆記：137 則
• 累積 permanent notes (永久筆記)：65+

2. 安裝指南

2.1 前置條件

• Claude Code 已安裝並完成認證
• Obsidian 已安裝（免費）
• Python 3.10+
• pip（用於安裝 graphify 和 chat extractor）

2.2 Step 1：建立 Obsidian Vault

在 Obsidian 中選擇「Create new vault」，設定名稱和位置。建議使用 單一 vault 管理所有專案：

1cd ~/vault  # 調整為你的路徑
2mkdir -p permanent inbox fleeting templates logs references
3mkdir -p my-project/{architecture,pipeline,data,features,logs}
4mkdir -p chats/{code,web}
5mkdir -p graphify

為什麼用單一 vault？ 每個專案一個 vault 會切割知識。單一 vault 讓「Supabase Auth」的筆記同時連結 project A 和 B，graph view（圖表檢視）會揭示意想不到的跨專案連結。

2.3 Step 2：建立 Vault 的 CLAUDE.md

在 vault 根目錄建立 CLAUDE.md，這是 Claude Code 自動讀取的指令檔：

 1# Vault — Instructions for Claude Code
 2
 3## What is this vault
 4Centralized knowledge base for all projects.
 5Persistent memory across sessions.
 6
 7## Zettelkasten Rules
 8
 9### Note creation
10- Use wikilinks: [[note-name]] (not markdown links)
11- Mandatory YAML frontmatter on every note
12- Filenames in kebab-case: `auth-flow.md`
13- 1 concept per permanent note (atomicity)
14- Minimum 2 wikilinks per note (dense linking)
15
16## Session Commands
17
18### /resume
19When you receive this command:
201. Read the 3 most recent session logs in logs/
212. Read architecture/decisions.md for the current project
223. Summarize current state and what's left to do
23
24### /save
25When you receive this command:
261. Create a session log in logs/YYYY-MM-DD-description.md
272. Record: what was done, decisions made, pending items
283. Add wikilinks to created/modified notes

2.4 Step 3：安裝 Graphify

1pip install graphifyy
2graphify install --platform claude

graphify install --platform claude 會在 ~/.claude/skills/graphify/SKILL.md 建立 skill 檔案。

如需 semantic extraction（語意抽取），需設定 API key：

1export ANTHROPIC_API_KEY="your-key-here"
2# 或
3export MOONSHOT_API_KEY="your-key-here"

純 AST 模式（零 LLM 成本）：

1graphify extract . --out ./graphify-out --no-cluster

2.5 Step 4：安裝 Chat Import Pipeline

1pip install claude-conversation-extractor
2mkdir -p ~/claude-exports/code ~/claude-exports/web
3mkdir -p ~/scripts

將 scripts/claude_to_obsidian.py 和 scripts/sync_claude_obsidian.sh 複製到 ~/scripts/：

1cp scripts/claude_to_obsidian.py ~/scripts/
2cp scripts/sync_claude_obsidian.sh ~/scripts/
3chmod +x ~/scripts/sync_claude_obsidian.sh

編輯 sync_claude_obsidian.sh 中的 VAULT_DIR 指向你的 vault。

2.6 Step 5：設定 Cron 自動同步（可選）

1(crontab -l 2>/dev/null; echo "0 22 * * * $HOME/scripts/sync_claude_obsidian.sh") | crontab -

3. 核心架構解析

3.1 系統全景

graph TB
    subgraph VAULT["Obsidian Vault（單一知識庫）"]
        PM[permanent/\n永久筆記]
        LOGS[logs/\nSession 日誌]
        CHATS[chats/\n匯入的對話]
        GF[graphify/\nCodebase 圖譜]
        PROJ[project-x/\n專案 MOC]
        CMD[CLAUDE.md\n全域指令]
    end

    subgraph REPO["Project Repository"]
        SRC[src/\n原始碼]
        PCMD[CLAUDE.md\n專案指令]
        GOUT[graphify-out/\ngraph.json + report]
        HOOK[.git/hooks/\npost-commit]
    end

    subgraph SCRIPTS["Scripts"]
        PY[claude_to_obsidian.py\nChat 處理器]
        SH[sync_claude_obsidian.sh\nCron wrapper]
    end

    CC[Claude Code] -->|"/resume 讀取"| CMD
    CC -->|"查詢 graph.json"| GOUT
    CC -->|"編輯程式碼"| SRC
    CC -->|"/save 寫入"| LOGS
    HOOK -->|"commit 觸發"| GOUT
    SH -->|"每日 cron"| PY
    PY -->|"加 frontmatter\n+ wikilinks"| CHATS

3.2 資料流三階段

sequenceDiagram
    participant U as 使用者
    participant CC as Claude Code
    participant V as Obsidian Vault
    participant G as Graphify
    participant S as Sync Script

    Note over U,S: === Session 開始 ===
    U->>CC: /resume
    CC->>V: 讀取最近 3 則 session log
    CC->>V: 讀取 architecture/decisions.md
    CC->>G: 查詢 graphify-out/graph.json
    CC-->>U: 摘要：目前進度 + 待辦

    Note over U,S: === 工作中 ===
    U->>CC: 開發 / 修 bug / 重構
    CC->>G: 查詢圖譜（~280 tokens）

    Note over U,S: === Session 結束 ===
    U->>CC: /save
    CC->>V: 建立 session log + wikilinks
    CC->>G: git commit → hook 自動重建圖譜

    Note over U,S: === 每日 cron ===
    S->>S: claude-extract → 匯出 .md
    S->>V: 加 frontmatter + tag + wikilinks → chats/

3.3 三層查詢規則

Claude Code 在此架構下遵循嚴格的三層查詢優先順序：

1. 第一層：查詢 graphify-out/graph.json 或 graphify-out/wiki/index.md（程式碼結構與連結）
2. 第二層：查詢 Obsidian vault（決策、進度、專案脈絡）
3. 第三層：只在前兩層無法回答時才讀取原始碼檔案

4. 核心功能詳解

4.1 Obsidian Zettelkasten — Persistent Memory（持久記憶）

原理：以單一 Obsidian vault 作為 Claude Code 的「第二大腦」。筆記遵循 Zettelkasten 方法論：原子性（一個概念一則筆記）、密集互連（每則至少 2 個 wikilinks）、標準化 metadata。

核心指令：

Vault 結構要點：

• permanent/ — Zettelkasten 永久筆記（經整理的知識）
• inbox/ — 原始擷取（想法、草稿）
• logs/ — Session 日誌
• project-x/ — 各專案的 MOC（Map of Content）、架構決策

4.2 Graphify — Codebase Knowledge Graph（程式碼知識圖譜）

原理：Graphify 透過 tree-sitter AST 解析，將程式碼庫轉換為可查詢的知識圖譜。所有處理 100% 本地完成，不傳送程式碼。

兩種執行模式：

產出檔案：

• graph.json — 可查詢的圖譜（核心）
• graph.html — 互動式視覺化
• GRAPH_REPORT.md — god nodes（超連結節點）、連結、指標
• wiki/ — Wikipedia 風格的文章（需 --wiki flag）
• cache/ — SHA256 快取（只處理修改過的檔案）

支援語言：Python、JavaScript、TypeScript、Go、Rust、Java、C、C++、Ruby、C#、Kotlin、Scala、PHP、Swift、Lua、Zig 等 20+ 種（透過 tree-sitter）。

4.3 Chat Import Pipeline — 對話歷史匯入

claude_to_obsidian.py（387 行 Python）：

核心處理流程：

1. 來源偵測（Origin Detection）：自動判斷 chat 來自 Claude Code 或 Claude Web
   • 路徑關鍵字偵測（code、claude-code、.claude/projects）
   • 內容指標偵測（````bash、$ claude、terminal` 等，>=2 命中判定為 code）
2. 自動標籤（Auto-tagging）：根據 KEYWORD_TAG_MAP 字典，掃描內容關鍵字產生 tag
   • 涵蓋語言/框架、AI/ML、自動化、Infra/DevOps、後端服務、知識管理等類別
   • 短關鍵字（如 sql、llm、api）使用 word boundary 匹配避免誤判
3. Frontmatter 生成：標準化 YAML header（title、tags、source、origin、created、type）
4. Wikilink 插入：掃描 vault 現有筆記名稱，在 chat 內容中插入 [[wikilinks]]
   • 只處理非程式碼區塊的文字
   • 每個筆記名稱只連結第一次出現
   • 長名稱優先匹配（避免短名稱搶佔）

sync_claude_obsidian.sh（46 行 Bash）：

Cron wrapper，每日自動執行：

1. claude-extract --all 匯出 Claude Code 對話
2. 呼叫 claude_to_obsidian.py --move 處理並移入 vault
3. 結果記錄到 sync.log

CLI 參數：

5. 應用場景

場景 A：Solo Developer — 日常開發

適合獨立開發者的標準工作流：

1. 開 session → /resume → Claude 自動載入上下文
2. 開發 → Graphify 提供程式碼導航
3. 結束 → /save → session log + wikilinks
4. git commit → hook 自動更新圖譜

場景 B：Multi-Repo Projects — 多 Repo 專案

以單一 vault 管理多個 repo：

1# 每個 repo 各自一個 graphify 子資料夾
2mkdir -p ~/vault/graphify/{project-a,project-b,project-c}
3
4# Skill 形式
5/graphify ~/project-a --obsidian --obsidian-dir ~/vault/graphify/project-a
6
7# Headless 形式
8cd ~/project-b && graphify extract . --out ./graphify-out
9ln -s $(pwd)/graphify-out ~/vault/graphify/project-b/graphify-out

場景 C：Team Onboarding — 團隊新人

新成員可透過 vault 的 graph view 快速理解：

• path:permanent — 只看已整理的知識
• path:graphify — 只看程式碼節點
• tag:chat-import — 查看歷史對話中的決策脈絡

場景 D：與 AI-Knowledge Template v1 整合

本專案的 Obsidian vault 概念與 AI-Knowledge Template v1 高度互補：

• AI-KT 的 inbox/ 等同 vault 的 inbox/
• Graphify 的 graph.json 等同 AI-KT Layer 4（graphify）
• Chat Import 的自動標籤可參考 AI-KT 的 frontmatter 標準

6. 資安掃描報告

掃描範圍

掃描所有 .py、.sh、.md 檔案，搜尋：eval、exec、os.system、subprocess、shell=True、pickle、__import__、secret、token、password、api_key 等高風險關鍵字。

掃描結果：🟢 安全

結論：此 repo 僅含文件處理腳本，不做網路連線、不執行動態程式碼、不呼叫外部程式。安全風險極低。

7. FAQ

Q1：vault 應該放在專案資料夾還是獨立位置？

A：放在 獨立位置（如 ~/vault），不要放在任何專案資料夾內。Claude Code 應在 專案資料夾 中執行開發，vault 透過 CLAUDE.md 參照。（Issue #5）

Q2：多 repo 專案怎麼處理？

A：所有 repo 共用同一個 vault。每個 repo 在 vault 中有自己的子資料夾（project-x/、graphify/project-x/）。透過 wikilinks 建立跨 repo 的知識連結。（Issue #4）

Q3：Graphify 出現 “unknown command ‘.’” 錯誤？

A：你正在使用 headless CLI，需要加子指令：

1# 正確
2graphify extract . --out ./graphify-out
3# 錯誤
4graphify .

或在 Claude Code 內用 skill 形式：/graphify . --obsidian

Q4：Graph 沒有產生 wiki/ 資料夾？

A：wiki/ 只在 skill 形式加 --wiki flag 時產生。Headless CLI 不支援 --wiki。

Q5：Obsidian graph view 是空的？

A：停用 graph filter 中的「Orphans」和「Existing files only」，然後 Cmd+Q 重啟 Obsidian。

Q6：cron 在 macOS 上不執行？

A：到 System Preferences → Privacy & Security → Full Disk Access，授權給你的終端應用程式。

8. 進階技巧

8.1 自訂 Keyword-to-Tag 映射

編輯 claude_to_obsidian.py 頂部的 KEYWORD_TAG_MAP，加入你的專案特定關鍵字：

1KEYWORD_TAG_MAP = {
2    # 你的專案
3    "my-app": "my-app",
4    "client-name": "client-work",
5    # 你的技術棧
6    "nextjs": "nextjs",
7    "prisma": "prisma",
8    ...
9}

8.2 Graphify Watch Mode — 自動重建

開發時在另一個終端窗口執行：

1graphify watch .

每次存檔自動重建圖譜，保持 graph.json 即時更新。

8.3 Git Hook — Commit 觸發重建

1graphify hook install

安裝後每次 git commit 自動重建圖譜。

8.4 Graphify Deep Mode — 語意邊

需要更深層的語意連結時，使用 --mode deep（需 API key，有 LLM 成本）：

1/graphify . --mode deep --obsidian --obsidian-dir ~/vault/graphify/project

8.5 推薦 Obsidian Plugin

9. 整合進其他工作流

與 AI-Knowledge Template v1 整合

與 RTK (Rust Token Killer) 互補

RTK 壓縮 CLI 輸出 token（60-90% 節省），Graphify 壓縮 codebase 理解 token（71.5x 節省）。兩者互不衝突，可同時使用。

與 CLAUDE.md 全域規範整合

在 vault 的 CLAUDE.md 中加入三層查詢規則，確保 Claude Code 優先查詢圖譜而非重讀原始碼。

10. 重點摘要 Checklist

• 建立單一 Obsidian vault，配置標準 Zettelkasten 資料夾結構
• 在 vault 根目錄建立 CLAUDE.md，定義 /resume 和 /save 指令
• 安裝 Graphify：pip install graphifyy && graphify install --platform claude
• 對專案執行首次圖譜生成：graphify extract . --out ./graphify-out
• 在專案 CLAUDE.md 加入三層查詢規則（Context Navigation）
• 安裝 Chat Import Pipeline：pip install claude-conversation-extractor
• 部署 claude_to_obsidian.py + sync_claude_obsidian.sh 到 ~/scripts/
• 自訂 KEYWORD_TAG_MAP 符合你的技術棧
• 可選：設定 cron 每日自動同步
• 可選：安裝 Git hook 自動重建圖譜
• 可選：啟用 watch mode 即時更新

11. 進一步閱讀

• Graphify — Codebase knowledge graph（MIT 授權）
• Obsidian — PKM and second brain（免費）
• Claude Code — Anthropic’s coding agent
• claude-conversation-extractor — Claude chat 匯出工具
• Zettelkasten Method — 原子筆記法介紹
• Issue #5：vault vs project folder 的執行位置討論
• Issue #4：multi-repo 的最佳實踐