Claude Dev Memory

讓 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 的關係

這兩個工具是互補的：

工具	類型	職責
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

配置

1. 取得 Letta API Key

1. 前往 Letta Cloud
2. 註冊帳號並取得 API Key
3. 建立 Agent 並記下 Agent ID

2. 配置 Claude Code

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"
      }
    }
  }
}

工具詳細說明

memory_status

查看記憶系統狀態。

回傳：連線狀態、Core Memory 使用量、Archival 記錄數

memory_recall

讀取 Core Memory，恢復專案上下文。

參數	類型	說明
block	string	all、project、learnings、decisions

memory_update

更新 Core Memory，記錄專案進度和決策。

參數	類型	說明
block	string	project、learnings、decisions
content	string	完整替換內容
append	string	附加內容（二選一）
auto_summarize	boolean	超過限制時自動摘要（預設 false）

memory_archive

存入 Archival Memory，保存完整文檔。

參數	類型	說明
content	string	要存檔的內容
type	string	spec、commit、learning、decision
tags	string[]	標籤陣列（方便搜尋）

memory_search

搜尋 Archival Memory，找出相關記錄。

參數	類型	說明
query	string	搜尋關鍵字
filter	string	all、spec、commit、learning、decision
limit	number	回傳筆數上限（預設 5）
min_relevance	number	最低相關度 0-1（預設 0.7）

MCP Resource

letta://memory/core

被動讀取 Core Memory 內容，回傳 JSON 格式的完整記憶資料。

使用情境

Session 開始時恢復上下文

Claude 使用 memory_recall 讀取 project 區塊
→ 立即了解專案背景，無需重新解釋

完成重要決策後記錄

Claude 使用 memory_update 更新 decisions 區塊
→ 下次 session 仍記得這個決策

保存完整 spec 文檔

Claude 使用 memory_archive，type 設為 spec
→ 完整內容存入 Archival，可語意搜尋

遇到類似問題時搜尋

Claude 使用 memory_search 搜尋相關記錄
→ 找出過去的解法，避免重複踩坑

與官方 letta-mcp 的差異

面向	官方 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) - 長期記憶後端

License

MIT