讓 Claude Code 具備跨 session 的長期記憶能力
Session 1 Session 2
┌─────────────────┐ ┌─────────────────┐
│ 學到了解法 A │ /clear │ 這問題怎麼解？ │ ← 學習消失
│ 決定用架構 B │ ───────> │ 要用什麼架構？ │ ← 決策遺失
│ 專案進度 70% │ │ 做到哪了？ │ ← 進度歸零
└─────────────────┘ └─────────────────┘
Claude Code 的限制：
- 每次
/clear或新 session 就完全失憶 - 過去的學習和決策無法累積
- 沒有工具可以主動保存重要資訊
這個 MCP Server 提供 5 個工具，讓 Claude 可以主動讀寫長期記憶：
| 工具 | 用途 |
|---|---|
memory_status |
查看記憶系統狀態 |
memory_recall |
讀取 Core Memory |
memory_update |
更新 Core Memory |
memory_archive |
存入 Archival Memory（完整文件） |
memory_search |
語意搜尋歷史記錄 |
┌─────────────────────────────────────────────────────────────────┐
│ Core Memory │
│ (小而重要，~2000 tokens) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ project │ │ learnings │ │ decisions │ │
│ │ 專案概述 │ │ 學習紀錄 │ │ 架構決策 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Archival Memory │
│ (大而完整，無限制) │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ specs │ │ commits │ │learnings│ │decisions│ │
│ │完整規格 │ │提交記錄 │ │詳細筆記 │ │完整文檔 │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────────┘
設計理念：
- Core Memory：摘要性質，每次對話都載入，讓 Claude 快速了解專案
- Archival Memory：完整內容，需要時搜尋取用，保留所有細節
這兩個工具是互補的：
| 工具 | 類型 | 職責 |
|---|---|---|
| claude-memory-hook | Hook | 啟動時顯示狀態（被動） |
| claude-dev-memory | MCP Server | 提供讀寫記憶工具（主動） |
┌─────────────────────────────────────────────────────────────────┐
│ claude-memory-hook │
│ → Session 開始時自動執行 │
│ → 顯示 Git、規格進度、Letta 記憶摘要、提醒 │
├─────────────────────────────────────────────────────────────────┤
│ claude-dev-memory（本專案） │
│ → 提供 MCP 工具讓 Claude 主動讀寫記憶 │
│ → memory_recall / memory_update / memory_archive / memory_search│
└─────────────────────────────────────────────────────────────────┘
npm install -g claude-dev-memory或使用 npx（無需安裝）：
npx claude-dev-memory- 前往 Letta Cloud
- 註冊帳號並取得 API Key
- 建立 Agent 並記下 Agent ID
claude mcp add claude-dev-memory -s user -- npx claude-dev-memory設定環境變數：
# 在 shell profile 或專案 .env 中
export LETTA_API_KEY=sk-let-xxxxx
export LETTA_AGENT_ID=agent-xxxxx或使用 JSON 配置（~/.claude.json）：
{
"mcpServers": {
"claude-dev-memory": {
"command": "npx",
"args": ["claude-dev-memory"],
"env": {
"LETTA_API_KEY": "your-api-key",
"LETTA_AGENT_ID": "agent-xxxxx"
}
}
}
}查看記憶系統狀態。
回傳：連線狀態、Core Memory 使用量、Archival 記錄數
讀取 Core Memory，恢復專案上下文。
| 參數 | 類型 | 說明 |
|---|---|---|
| block | string | all、project、learnings、decisions |
更新 Core Memory，記錄專案進度和決策。
| 參數 | 類型 | 說明 |
|---|---|---|
| block | string | project、learnings、decisions |
| content | string | 完整替換內容 |
| append | string | 附加內容（二選一） |
| auto_summarize | boolean | 超過限制時自動摘要（預設 false） |
存入 Archival Memory，保存完整文檔。
| 參數 | 類型 | 說明 |
|---|---|---|
| content | string | 要存檔的內容 |
| type | string | spec、commit、learning、decision |
| tags | string[] | 標籤陣列（方便搜尋） |
搜尋 Archival Memory，找出相關記錄。
| 參數 | 類型 | 說明 |
|---|---|---|
| query | string | 搜尋關鍵字 |
| filter | string | all、spec、commit、learning、decision |
| limit | number | 回傳筆數上限（預設 5） |
| min_relevance | number | 最低相關度 0-1（預設 0.7） |
被動讀取 Core Memory 內容，回傳 JSON 格式的完整記憶資料。
Claude 使用 memory_recall 讀取 project 區塊
→ 立即了解專案背景，無需重新解釋
Claude 使用 memory_update 更新 decisions 區塊
→ 下次 session 仍記得這個決策
Claude 使用 memory_archive，type 設為 spec
→ 完整內容存入 Archival，可語意搜尋
Claude 使用 memory_search 搜尋相關記錄
→ 找出過去的解法，避免重複踩坑
| 面向 | 官方 letta-mcp | claude-dev-memory |
|---|---|---|
| 目標用戶 | 通用 AI 應用 | Claude Code 開發者 |
| Memory 結構 | 單一 human block | project / learnings / decisions |
| Agent 策略 | 自動建立 per user | 指定現有 Agent |
| 額外功能 | - | Token 計算、狀態檢查、類型標籤 |
| 變數 | 說明 | 預設值 |
|---|---|---|
| LETTA_API_KEY | Letta Cloud API Key | (必填) |
| LETTA_AGENT_ID | 指定使用的 Agent ID | (選填) |
| LETTA_BASE_URL | Letta API URL | https://api.letta.com |
可在專案目錄建立 .claude/letta.json 覆蓋全域設定：
{
"agent_id": "agent-xxx"
}git clone https://github.com/miles990/claude-dev-memory.git
cd claude-dev-memory
npm install # 安裝依賴
npm run build # 編譯
npm test # 測試
npm run dev # 開發模式- claude-memory-hook - Session 啟動時自動載入記憶狀態的 Hook
- Letta (MemGPT) - 長期記憶後端
MIT