Claude Code 終于有長期記憶了！claude-mem 持久化記憶系統(tǒng)完全指南

源碼七號站獨家深度解析

?| 本文詳細拆解 claude-mem 項目的核心原理與操作流程，幫助開發(fā)者徹底告別 AI 編程助手的”失憶”問題。

---

一、開篇：AI 編程助手的”失憶癥”困境

相信每一位使用過 Claude Code 的開發(fā)者都有過這樣的體驗：

你和 Claude 協(xié)作了一整天，它幫你寫了幾千行代碼，修復了十幾個 Bug，你們配合得天衣無縫。然后你關掉終端，第二天滿懷期待地打開 Claude Code，準備繼續(xù)昨天的工作——

“抱歉，我不知道你在說什么。”

所有的上下文、所有的討論、所有的項目背景——全部被清零了。就好像你在和一個失憶癥患者合作寫代碼，每天早上都需要從頭解釋一遍：這個項目是干什么的、我們昨天做到哪里了、哪些問題還沒解決……

這不是 Claude 的問題，而是大語言模型天生的局限性。Claude Code 的上下文窗口大約是 20 萬 Token，說實話，對于復雜項目來說這點容量少得可憐。很多時候讓它運行十幾二十分鐘，上下文就直接用滿了。

這個痛點，正是 claude-mem 項目要解決的核心問題。

---

二、claude-mem 是什么？

claude-mem 是一個專門為 Claude Code 打造的持久化記憶壓縮系統(tǒng)。它能夠自動捕獲你和 Claude 的對話上下文，讓 AI 擁有真正的長期記憶能力。

簡單來說，它的工作方式類似于給 Claude 配備了一個”私人秘書”——這個秘書會默默記錄每次對話中發(fā)生的重要事情，當你下次開始新對話時，秘書會把相關的歷史信息重新告訴 Claude，讓它能夠”記起”之前的工作內(nèi)容。

2.1 項目基本信息

屬性	信息
項目名稱	claude-mem
GitHub 倉庫	https://github.com/thedotmack/claude-mem
官方網(wǎng)站	https://claude-mem.ai
官方文檔	https://docs.claude-mem.ai
開源協(xié)議	AGPL-3.0
系統(tǒng)支持	Windows、macOS、Linux

2.2 核心特性一覽

1. 持久化記憶

上下文會在會話之間自動保存，不需要手動操作。每次你結(jié)束一個編程會話，claude-mem 都會自動生成語義摘要，為下次會話做好準備。

2. 漸進式披露（Progressive Disclosure）

這是 claude-mem 的核心設計哲學。它采用分層記憶檢索策略，模擬人類的記憶模式：

• 首先加載輕量級的”索引”——標題、類型、時間戳
• 只有在需要深入細節(jié)時，才獲取完整的觀察記錄
• 這種方式既節(jié)省 Token，又不會在需要時顯得”淺薄”

3. 智能搜索

可以通過自然語言搜索項目歷史。比如你可以直接問 Claude：

• “上次我們修復了什么 Bug？”
• “我們之前是怎么實現(xiàn)用戶認證的？”
• “這個 Bug 之前修過嗎？”

4. 可視化管理界面

claude-mem 提供一個實時 Web 界面（運行在?http://localhost:37777），你可以：

• 查看記憶流
• 瀏覽所有記憶內(nèi)容
• 按類型過濾（決策、Bug修復、功能實現(xiàn)等）
• 切換不同項目
• 調(diào)整各種設置

5. 隱私控制

你可以排除敏感內(nèi)容，完全掌控哪些信息被存儲。通過?<private>?標簽包裹的內(nèi)容不會被記錄。

6. 全自動運行

無需手動干預，后臺透明運行，自動完成所有記憶管理工作。

---

三、claude-mem 的工作原理深度解析

要真正理解 claude-mem 的價值，我們需要深入了解它的技術架構。這一部分內(nèi)容稍微偏技術向，但源碼七號站會盡量用通俗的語言來解釋。

3.1 整體架構概覽

claude-mem 的核心設計理念是：它不會中斷或修改 Claude Code 的行為，而是從外部觀察，通過生命周期鉤子提供價值。

整個系統(tǒng)由以下幾個核心組件構成：

┌─────────────────────────────────────────────────────────────┐│ ? ? ? ? ? ? ? ? ? ?Claude Code 會話 ? ? ? ? ? ? ? ? ? ? ? ? ?│└─────────────────────────────────────────────────────────────┘? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ↓┌─────────────────────────────────────────────────────────────┐│ ? ? ? ? ? ? ?生命周期鉤子 (Lifecycle Hooks) ? ? ? ? ? ? ? ? ? ││ ? ?SessionStart → UserPromptSubmit → PostToolUse → Stop ? ? ?│└─────────────────────────────────────────────────────────────┘? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ↓┌─────────────────────────────────────────────────────────────┐│ ? ? ? ? ? ? ? ? ? Worker 服務 (后臺處理) ? ? ? ? ? ? ? ? ? ? ?││ ? ? ? ? 通過 Claude Agent SDK 提取學習內(nèi)容 ? ? ? ? ? ? ? ? ? ?│└─────────────────────────────────────────────────────────────┘? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ↓┌─────────────────────────────────────────────────────────────┐│ ? ? ? ? ? ? ? ? ? ? 雙數(shù)據(jù)庫存儲系統(tǒng) ? ? ? ? ? ? ? ? ? ? ? ? ?││ ? ? ? ? ? ?SQLite (結(jié)構化) + ChromaDB (向量化) ? ? ? ? ? ? ? ?│└─────────────────────────────────────────────────────────────┘? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ↓┌─────────────────────────────────────────────────────────────┐│ ? ? ? ? ? ? ?下次會話開始時自動注入相關上下文 ? ? ? ? ? ? ? ? ? │└─────────────────────────────────────────────────────────────┘

3.2 五大生命周期鉤子詳解

claude-mem 使用 5 個生命周期鉤子來捕獲和處理會話信息。這些鉤子會在 Claude Code 的關鍵時刻自動觸發(fā)。

鉤子一：SessionStart（會話開始）

觸發(fā)時機：?Claude Code 啟動時（包括 startup、clear 或 compact 操作）

執(zhí)行內(nèi)容：

1. 檢查并安裝必要的依賴（如果需要）
2. 啟動 Worker 服務
3. 從數(shù)據(jù)庫中檢索最近的觀察記錄
4. 將相關上下文注入到新會話中

這是最關鍵的鉤子之一，它確保每次你開始新會話時，Claude 都能”記起”之前的工作內(nèi)容。

鉤子二：UserPromptSubmit（用戶提交提示）

觸發(fā)時機：?用戶發(fā)送消息給 Claude 時

執(zhí)行內(nèi)容：

• 記錄用戶的原始提示
• 保存用戶請求以供后續(xù)分析

鉤子三：PostToolUse（工具使用后）

觸發(fā)時機：?Claude 執(zhí)行任何工具操作后

執(zhí)行內(nèi)容：

1. 捕獲工具執(zhí)行的詳細信息
2. 記錄文件操作（讀取、寫入、編輯）
3. 記錄 Shell 命令執(zhí)行
4. 記錄代碼搜索操作
5. 記錄 Web 操作

這個鉤子會捕獲幾乎所有的工具執(zhí)行記錄，包括：

• 文件操作：Write、Read、Edit
• Shell 命令：Bash
• 代碼搜索：Grep、Glob
• Web 操作：WebFetch、WebSearch
• 筆記本編輯：NotebookEdit

鉤子四：Stop（會話停止）

觸發(fā)時機：?Claude 停止當前任務時

執(zhí)行內(nèi)容：

• 生成當前會話的 AI 驅(qū)動摘要
• 記錄已完成的工作
• 標記待處理的任務

摘要的格式如下：

<summary>? <request>用戶的原始請求</request>? <investigated>檢查了什么</investigated>? <learned>關鍵發(fā)現(xiàn)</learned>? <completed>已完成的工作</completed>? <next_steps>剩余任務</next_steps>? <files_read>? ? <file>path/to/file1.ts</file>? </files_read>? <files_modified>? ? <file>path/to/file2.ts</file>? </files_modified>? <notes>額外上下文</notes></summary>

鉤子五：SessionEnd（會話結(jié)束）

觸發(fā)時機：?Claude Code 會話完全結(jié)束時

執(zhí)行內(nèi)容：

• 標記會話為已完成
• 清理臨時資源
• 確保所有數(shù)據(jù)持久化

3.3 異步處理架構：快速響應 + 后臺處理

claude-mem 采用了一個巧妙的架構設計來確保不影響 Claude Code 的響應速度：

前端鉤子（快速）：

┌─────────────────────────────────────────────────────────────┐│ ? ? ? ? ? ? ? ? ? ? ?HOOK (快速層) ? ? ? ? ? ? ? ? ? ? ? ? ? ││ ? ? 1. 讀取 stdin (< 1ms) ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?││ ? ? 2. 插入隊列 (< 10ms) ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ││ ? ? 3. 返回成功 (總計 < 20ms) ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?│└─────────────────────────────────────────────────────────────┘? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ↓ (隊列)

后臺 Worker（慢速但不阻塞）：

┌─────────────────────────────────────────────────────────────┐│ ? ? ? ? ? ? ? ? ? ? WORKER (慢速層) ? ? ? ? ? ? ? ? ? ? ? ? ?││ ? ? 1. 每秒輪詢隊列 ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?││ ? ? 2. 通過 Claude SDK 處理觀察 (5-30秒) ? ? ? ? ? ? ? ? ? ? ││ ? ? 3. 解析并存儲結(jié)果 ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?││ ? ? 4. 標記觀察已處理 ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?│└─────────────────────────────────────────────────────────────┘

這種設計的好處是：

• 鉤子執(zhí)行極快（毫秒級），不會阻塞 Claude Code
• 真正的 AI 處理在后臺進行
• 即使后臺處理失敗，也不會影響用戶體驗

3.4 雙數(shù)據(jù)庫存儲系統(tǒng)

claude-mem 使用兩個數(shù)據(jù)庫來存儲記憶：

1. SQLite 數(shù)據(jù)庫（結(jié)構化存儲）

位置：~/.claude-mem/claude-mem.db

用途：

• 存儲觀察記錄
• 存儲會話信息
• 存儲摘要
• 支持全文搜索（FTS5）

2. ChromaDB（向量數(shù)據(jù)庫）

位置：~/.claude-mem/chroma/

用途：

• 存儲向量嵌入
• 支持語義搜索
• 根據(jù)含義（而非關鍵詞）查找相關內(nèi)容

這種雙數(shù)據(jù)庫架構使得 claude-mem 既能進行精確的關鍵詞搜索，也能進行”模糊”的語義搜索。

3.5 記憶分類系統(tǒng)

claude-mem 會自動將每個觀察分類為以下類型之一：

類型	英文	說明
決策	decision	架構選擇、技術決策
Bug修復	bugfix	問題診斷和修復
功能實現(xiàn)	feature	新功能開發(fā)
重構	refactor	代碼重構
發(fā)現(xiàn)	discovery	關于代碼庫的發(fā)現(xiàn)

這種分類使得后續(xù)搜索更加精準。比如你可以問：”上周我們修復了哪些 Bug？”

---

四、安裝配置完全指南

接下來源碼七號站將帶你一步步完成 claude-mem 的安裝和配置。

4.1 系統(tǒng)要求

在安裝之前，請確保你的系統(tǒng)滿足以下要求：

要求	說明
Node.js	18.0.0 或更高版本
Claude Code	最新版本（需支持插件功能）
Bun	JavaScript 運行時（會自動安裝）
SQLite 3	用于持久化存儲（已打包）
內(nèi)存	至少 4GB RAM
磁盤空間	至少 100MB 可用空間

4.2 方式一：通過插件市場安裝（推薦）

這是最簡單的安裝方式，只需要兩行命令：

第一步：啟動 Claude Code

在終端中啟動 Claude Code。

第二步：添加插件市場并安裝

在 Claude Code 中輸入以下命令：

/plugin marketplace add thedotmack/claude-mem

等待命令執(zhí)行完成，然后輸入：

/plugin install claude-mem

安裝程序會詢問你安裝范圍，有以下選項：

1. 全局安裝
   
   （推薦）：在任何目錄下使用 Claude Code 都能使用這個記憶工具
2. 當前項目安裝：只在當前項目中使用

建議選擇第一個選項進行全局安裝。

第三步：重啟 Claude Code

安裝完成后，重啟 Claude Code 讓配置生效。

第四步：驗證安裝

重啟后，輸入以下命令查看已安裝的插件：

/plugin

按 Tab 鍵切換，你應該能看到 claude-mem 插件已經(jīng)出現(xiàn)在列表中。

4.3 方式二：從源碼安裝（進階）

如果你需要進行開發(fā)測試，或者想要修改源碼，可以選擇從源碼安裝：

# 克隆倉庫git clone https://github.com/thedotmack/claude-mem.gitcd claude-mem# 安裝依賴npm install# 構建鉤子和 Worker 服務npm run build# 手動啟動 Worker 服務（可選，首次會話會自動啟動）npm run worker:start# 驗證 Worker 運行狀態(tài)npm run worker:status

4.4 配置文件詳解

claude-mem 的配置文件位于?~/.claude-mem/settings.json，首次運行時會自動創(chuàng)建默認配置。

以下是主要配置項說明：

{? "provider": "claude",? "model": "claude-sonnet-4-5-20250929",? "workerPort": 37777,? "dataDir": "~/.claude-mem",? "logLevel": "info",? "contextObservations": 10}

配置項解釋：

配置項	說明	默認值
provider	AI 提供商	claude
model	使用的模型	claude-sonnet-4-5-20250929
workerPort	Worker 服務端口	37777
dataDir	數(shù)據(jù)存儲目錄	~/.claude-mem
logLevel	日志級別	info
contextObservations	注入上下文的觀察數(shù)量	10

關于模型配置的說明：

這里可能有人會疑惑：為什么要在配置中設置模型？需要配置 API Key 嗎？

答案是：不需要配置 API Key！

claude-mem 會作為 Claude Code 的子進程運行，它會復用 Claude Code 的登錄認證，通過 Claude Code 來調(diào)用 AI 模型。所以只要你能正常啟動 Claude Code，claude-mem 就能正常工作。

4.5 環(huán)境變量配置（可選）

如果你需要自定義某些配置，可以通過環(huán)境變量來覆蓋：

# 自定義數(shù)據(jù)目錄export CLAUDE_MEM_DATA_DIR=/custom/path# 自定義 Worker 端口export CLAUDE_MEM_WORKER_PORT=8080# 設置上下文觀察數(shù)量export CLAUDE_MEM_CONTEXT_OBSERVATIONS=15# 設置跳過的工具（不記錄這些工具的使用）export CLAUDE_MEM_SKIP_TOOLS="ListMcpResourcesTool,SlashCommand"

4.6 驗證安裝是否成功

安裝完成后，你可以通過以下方式驗證：

1. 訪問 Web 界面

打開瀏覽器，訪問?http://localhost:37777，你應該能看到 claude-mem 的管理界面。

2. 檢查 Worker 日志

npm run worker:logs

或者查看日志文件：~/.claude-mem/logs/worker-YYYY-MM-DD.log

3. 測試上下文檢索

npm run test:context

4. 檢查數(shù)據(jù)目錄

確認以下文件存在：

• ~/.claude-mem/claude-mem.db
  
  ?– 數(shù)據(jù)庫文件
• ~/.claude-mem/.worker.pid
  
  ?– Worker 進程 ID 文件
• ~/.claude-mem/.worker.port
  
  ?– Worker 端口文件
• ~/.claude-mem/settings.json
  
  ?– 配置文件

---

五、實戰(zhàn)演練：從零開始體驗持久化記憶

現(xiàn)在讓我們通過一個完整的實戰(zhàn)案例來體驗 claude-mem 的強大功能。

5.1 第一次對話：創(chuàng)建項目

步驟1：啟動新的 Claude Code 會話

claude

步驟2：讓 Claude 創(chuàng)建一個項目

向 Claude 發(fā)送請求：

請幫我創(chuàng)建一個美發(fā)預約網(wǎng)站，需要包含以下功能：1. 用戶注冊和登錄2. 服務項目展示3. 在線預約功能4. 個人中心

步驟3：觀察 claude-mem 的工作

在 Claude 開始工作的同時，打開瀏覽器訪問?http://localhost:37777，你會看到 Web 界面開始記錄各種信息：

• 項目初始化過程
• 文件創(chuàng)建記錄
• 代碼編寫過程
• 目錄結(jié)構搭建

步驟4：完成項目并退出

等 Claude 完成項目后，你可以結(jié)束會話。此時 claude-mem 會：

1. 生成會話摘要
2. 存儲所有觀察記錄
3. 為下次會話準備上下文

5.2 第二次對話：見證記憶的力量

步驟1：開啟全新的 Claude Code 會話

完全關閉之前的終端，打開一個新的終端，啟動 Claude Code：

claude

步驟2：詢問之前的工作

在這個全新的對話中（沒有任何上下文），問 Claude：

上次我們做了一個什么項目？都實現(xiàn)了哪些功能？

步驟3：見證奇跡

你會看到 Claude 開始查找之前的項目記錄。它會回答類似這樣的內(nèi)容：

“根據(jù)歷史記錄，我們上次一起做了一個美發(fā)預約網(wǎng)站，實現(xiàn)了以下功能：

1. 用戶認證系統(tǒng)
   
   ：包括用戶注冊、登錄、注銷功能
2. 導航欄組件
   
   ：響應式導航設計
3. 首頁展示
   
   ：服務項目展示頁面
4. 預約功能
   
   ：在線預約系統(tǒng)
5. 個人中心
   
   ：用戶信息管理

整個網(wǎng)站使用了 [具體技術棧]，項目結(jié)構如下……”

這就是 claude-mem 的神奇之處——新的對話中，Claude 依然能夠”記住”之前的工作！

5.3 更多實用場景

場景一：繼續(xù)之前的工作

繼續(xù)完善我們之前做的美發(fā)網(wǎng)站，添加一個評價系統(tǒng)

Claude 會直接知道你說的是哪個項目，無需重新解釋。

場景二：排查歷史 Bug

之前我們在用戶登錄功能上遇到過什么問題？是怎么解決的？

claude-mem 會搜索歷史記錄，找出相關的 Bug 修復記錄。

場景三：查看決策歷史

我們?yōu)槭裁催x擇使用 JWT 而不是 Session？

如果之前有過相關討論，Claude 能夠找到當時的決策記錄。

---

六、Web 管理界面使用指南

claude-mem 的 Web 界面是一個強大的管理工具，讓我們詳細了解它的功能。

6.1 訪問界面

打開瀏覽器，訪問：http://localhost:37777

6.2 主要功能區(qū)域

1. 記憶流（Memory Stream）

這是主界面，顯示所有的觀察記錄。每條記錄包含：

• 時間戳
• 類型標簽（decision、bugfix、feature 等）
• 涉及的文件
• 觀察內(nèi)容摘要

2. 項目切換

如果你有多個項目，可以在界面中切換不同項目的記憶。

3. 過濾功能

可以按照以下維度過濾記憶：

• 觀察類型（決策、Bug修復、功能等）
• 時間范圍
• 涉及的文件

4. 設置面板

點擊設置圖標，可以配置：

• 應包含哪些觀察類型
• 排除哪些內(nèi)容
• 切換穩(wěn)定版/測試版

5. 事實敘述（Fact Narrative）

點擊某條記憶的”事實敘述”按鈕，可以看到更詳細的記錄，包括：

• 具體做了什么操作
• 相關的上下文信息
• 標簽信息

6.3 Beta 功能：Endless Mode

claude-mem 提供了一個實驗性功能叫?Endless Mode（無盡模式），這是一種仿生記憶架構，用于大幅延長會話長度。

問題背景：

標準的 Claude Code 會話在大約 50 次工具使用后就會觸及上下文限制。每個工具添加 1-10k+ Token，而且 Claude 在每次響應時都會重新合成所有之前的輸出（O(N2) 復雜度）。

Endless Mode 的解決方案：

• 分離工作記憶（Working Memory）和歸檔記憶（Archive Memory）
• 工作記憶：當前活躍的觀察
• 歸檔記憶：存儲在磁盤上的完整輸出，可快速調(diào)用
• 復雜度從 O(N2) 降低到接近線性

啟用方式：

在 Web 界面的 Settings 中切換到 Beta 版本即可嘗試。

注意事項：

• Endless Mode 會增加延遲（每個工具約 60-90 秒）
• 目前仍處于實驗階段
• 適合需要長時間持續(xù)工作的場景

---

七、搜索功能深度使用

claude-mem 的搜索功能是其核心價值之一，讓我們深入了解如何充分利用它。

7.1 自然語言搜索

最簡單的方式是直接用自然語言提問：

上次會話我們修復了什么 Bug？

我們是怎么實現(xiàn)用戶認證的？

最近對 worker-service.ts 做了什么修改？

7.2 結(jié)構化搜索

claude-mem 支持一個三層工作流模式來進行高效搜索：

第一步：搜索索引

search(query="authentication bug", type="bugfix", limit=10)

這會返回一個輕量級的索引，包含標題、類型和時間戳。

第二步：識別相關條目

查看返回的索引，找到相關的記錄 ID（比如?#123、#456）。

第三步：獲取完整詳情

get_observations(ids=[123, 456])

獲取特定記錄的完整內(nèi)容。

7.3 高級過濾

可以使用以下過濾條件：

按類型過濾：

type:decision file:auth.ts

按文件過濾：

"What decisions affected index.ts?"

語義搜索：

"What do we know about auth?"

兩種搜索方式都能工作：關鍵詞搜索使用 SQLite 的 FTS5 引擎，語義搜索使用 ChromaDB 的向量匹配。

---

八、隱私保護機制

對于涉及敏感信息的項目，claude-mem 提供了完善的隱私保護機制。

8.1 使用 Private 標簽

在你的代碼或?qū)υ捴?，使?<private>?標簽包裹不想被記錄的內(nèi)容：

<private>這里的內(nèi)容不會被 claude-mem 記錄API_KEY="sk-xxxxx"</private>

8.2 配置跳過的工具

可以通過配置跳過某些工具的記錄：

export CLAUDE_MEM_SKIP_TOOLS="ListMcpResourcesTool,SlashCommand,AskUserQuestion"

8.3 手動清理記憶

如果需要，你可以手動刪除某些記憶記錄：

1. 打開 Web 界面?http://localhost:37777
2. 找到需要刪除的記錄
3. 進行刪除操作

---

九、常見問題與故障排除

9.1 Worker 服務無法啟動

癥狀：?安裝后 Worker 服務無法在端口 37777 啟動

解決方案：

1. 檢查端口是否被占用：

lsof -i :37777

1. 如果端口被占用，可以修改配置使用其他端口：

export CLAUDE_MEM_WORKER_PORT=8080

1. 手動啟動 Worker：

bun plugin/scripts/worker-service.cjs

9.2 記憶沒有被保存

癥狀：?完成會話后，下次對話 Claude 依然不記得

排查步驟：

1. 檢查 Worker 是否運行：

npm run worker:status

1. 檢查數(shù)據(jù)庫文件是否存在：

ls -la ~/.claude-mem/claude-mem.db

1. 查看 Worker 日志：

npm run worker:logs

9.3 依賴安裝失敗

癥狀：?安裝過程中提示依賴錯誤

解決方案：

1. 確保 Node.js 版本 >= 18：

node --version

1. 手動安裝依賴：

cd ~/.claude/plugins/marketplaces/thedotmacknpm install

9.4 上下文注入過多/過少

癥狀：?每次會話開始時注入的歷史信息太多或太少

解決方案：

調(diào)整上下文觀察數(shù)量配置：

export CLAUDE_MEM_CONTEXT_OBSERVATIONS=5 ?# 減少# 或export CLAUDE_MEM_CONTEXT_OBSERVATIONS=20 # 增加

9.5 使用自動診斷功能

claude-mem 內(nèi)置了自動診斷功能。如果遇到問題，可以直接向 Claude 描述問題，troubleshoot skill 會自動激活并提供修復建議。

你也可以生成詳細的 Bug 報告：

cd ~/.claude/plugins/marketplaces/thedotmacknpm run bug-report

---

十、進階配置與優(yōu)化

10.1 使用其他 AI 提供商

除了默認的 Claude，claude-mem 還支持其他 AI 提供商：

使用 OpenRouter：

export CLAUDE_MEM_PROVIDER=openrouterexport OPENROUTER_API_KEY=your-api-key

使用 Gemini：

export CLAUDE_MEM_PROVIDER=geminiexport GEMINI_API_KEY=your-api-key

10.2 自定義模式和語言

claude-mem 支持自定義模式文件，位于?~/.claude-mem/modes/?？梢詾椴煌木幊陶Z言或工作模式配置不同的提示詞。

10.3 記憶導出與導入

如果需要在不同機器間遷移記憶，可以使用導出/導入功能。詳細說明請參考官方文檔的 Memory Export/Import 頁面。

10.4 與 Cursor IDE 集成

claude-mem 不僅支持 Claude Code，還支持 Cursor IDE。配置方式略有不同，請參考官方文檔的 Cursor Integration 頁面。

---

十一、技術架構圖解

為了幫助源碼七號站的讀者更直觀地理解 claude-mem 的工作方式，這里提供幾張關鍵的架構圖解。

11.1 數(shù)據(jù)流向圖

用戶輸入? ? ↓Claude Code 處理? ? ↓PostToolUse 鉤子觸發(fā)? ? ↓觀察數(shù)據(jù)發(fā)送到 Worker? ? ↓Worker 調(diào)用 AI 提取語義? ? ↓雙數(shù)據(jù)庫存儲├── SQLite (結(jié)構化索引)└── ChromaDB (向量嵌入)? ? ↓下次會話 SessionStart 時檢索? ? ↓相關上下文注入新會話

11.2 組件交互圖

┌─────────────────────────────────────────────────────────────┐│ ? ? ? ? ? ? ? ? ? ? ?Claude Code IDE ? ? ? ? ? ? ? ? ? ? ? ? ││ ?┌─────────────────────────────────────────────────────────┐││ ?│ ? ? ? ? ? ? ? ? ? ?Lifecycle Hooks ? ? ? ? ? ? ? ? ? ? ? │││ ?│ ?SessionStart → UserPrompt → PostToolUse → Stop → End ? │││ ?└─────────────────────────────────────────────────────────┘│└─────────────────────────────────────────────────────────────┘? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ↓ HTTP┌─────────────────────────────────────────────────────────────┐│ ? ? ? ? ? ? ? ? ? Worker Service (:37777) ? ? ? ? ? ? ? ? ? ?││ ?┌──────────────┐ ?┌──────────────┐ ?┌──────────────────┐ ?││ ?│ SessionRoutes│ ?│ ObservationAPI│ ?│ ContextBuilder ?│ ?││ ?└──────────────┘ ?└──────────────┘ ?└──────────────────┘ ?│└─────────────────────────────────────────────────────────────┘? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ↓┌─────────────────────────────────────────────────────────────┐│ ? ? ? ? ? ? ? ? ? ? ?AI Providers ? ? ? ? ? ? ? ? ? ? ? ? ? ?││ ?┌──────────┐ ?┌──────────────┐ ?┌────────────────────┐ ? ?││ ?│ SDKAgent │ ?│ GeminiAgent ?│ ?│ OpenRouterAgent ? ?│ ? ?││ ?│ (Claude) │ ?│ ? ? ? ? ? ? ?│ ?│ ? ? ? ? ? ? ? ? ? ?│ ? ?││ ?└──────────┘ ?└──────────────┘ ?└────────────────────┘ ? ?│└─────────────────────────────────────────────────────────────┘? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ↓┌─────────────────────────────────────────────────────────────┐│ ? ? ? ? ? ? ? ? ? ? ?Database Layer ? ? ? ? ? ? ? ? ? ? ? ? ?││ ?┌─────────────────────┐ ? ?┌─────────────────────┐ ? ? ? ?││ ?│ ? ? ?SQLite ? ? ? ? │ ? ?│ ? ? ?ChromaDB ? ? ? │ ? ? ? ?││ ?│ ?(Structured + FTS) │ ? ?│ ?(Vector Search) ? ?│ ? ? ? ?││ ?└─────────────────────┘ ? ?└─────────────────────┘ ? ? ? ?│└─────────────────────────────────────────────────────────────┘

---

十二、與其他記憶方案的對比

12.1 為什么不直接用 CLAUDE.md？

Claude Code 本身支持通過?CLAUDE.md?文件來存儲項目上下文。但這種方式有幾個局限性：

特性	CLAUDE.md	claude-mem
自動化程度	需要手動維護	全自動
記憶粒度	宏觀概述	精細觀察
搜索能力	無	全文+語義搜索
歷史追溯	無版本歷史	完整時間線
適用場景	靜態(tài)項目知識	動態(tài)工作記憶

最佳實踐是將兩者結(jié)合使用：

• CLAUDE.md
  
  ?存儲穩(wěn)定的項目約定、架構決策
• claude-mem
  
  ?處理動態(tài)的工作記憶和歷史追溯

12.2 與其他記憶插件的對比

市面上有一些其他的 AI 記憶解決方案，但 claude-mem 有幾個獨特優(yōu)勢：

1. 專為 Claude Code 優(yōu)化
   
   ：深度集成生命周期鉤子
2. 語義壓縮
   
   ：不是簡單存儲日志，而是提取有意義的觀察
3. 隱私友好
   
   ：支持細粒度的隱私控制
4. 開源透明
   
   ：代碼可審計，數(shù)據(jù)完全本地化

---

十三、適用場景分析

13.1 最適合的場景

1. 長期重構項目

在進行跨越多天的復雜重構時，持久化記憶能幫助 Claude 記?。?/span>

• 重構的目標和動機
• 已完成的部分
• 待處理的問題
• 之前的決策依據(jù)

2. 多模塊大型項目

當項目涉及多個模塊時，Claude 能夠記?。?/span>

• 模塊間的依賴關系
• 之前的架構討論
• 各模塊的實現(xiàn)細節(jié)

3. 團隊協(xié)作項目

雖然 claude-mem 主要是個人工具，但在團隊項目中：

• 每個人都有自己的記憶庫
• 可以通過導出/導入分享關鍵決策
• 保持個人工作流的連續(xù)性

4. 學習和探索性開發(fā)

在學習新技術時，claude-mem 能幫你記?。?/span>

• 之前嘗試過什么
• 什么方法有效/無效
• 學習過程中的關鍵發(fā)現(xiàn)

13.2 不太適合的場景

1. 一次性腳本任務

如果只是寫一個簡單的一次性腳本，記憶功能的價值有限。

2. 高度機密項目

盡管有隱私保護機制，但對于極度敏感的項目，任何形式的持久化存儲都需要謹慎評估。

3. 資源受限環(huán)境

claude-mem 需要運行后臺 Worker 服務，會占用一定的系統(tǒng)資源。在資源極度受限的環(huán)境中可能不太合適。

---

十四、升級與維護

14.1 自動升級

通過插件市場安裝的 claude-mem 會自動升級。當有新版本可用時，SessionStart 鉤子會自動檢測并更新。

14.2 手動升級

如果需要手動升級，可以執(zhí)行：

/plugin update claude-mem

14.3 版本歷史重要更新

v9.0.0：

• 修復了多個關鍵 Bug
• 設置文件首次運行時自動創(chuàng)建
• 修復了鉤子執(zhí)行問題

v8.2.0：

• 清理了大量冗余代碼（刪除 984 行）
• 簡化了會話管理
• 修復了時間戳損壞問題

v7.1.0：

• 用原生 Bun 進程管理替換了 PM2
• 遷移過程自動完成

v5.4.0+：

• 基于技能的搜索替換了 MCP 工具
• 每個會話節(jié)省約 2,250 Token

完整的更新日志請參考：https://github.com/thedotmack/claude-mem/blob/main/CHANGELOG.md

---

十五、開源協(xié)議說明

claude-mem 使用?AGPL-3.0?開源協(xié)議。這意味著：

你可以：

• 免費使用
• 修改源碼
• 部署到自己的環(huán)境

但你需要：

• 如果你修改后作為網(wǎng)絡服務提供給他人，必須開源你的修改
• 衍生作品必須使用相同的協(xié)議

對于普通開發(fā)者來說，直接使用沒有任何限制。但如果你是企業(yè)用戶，想要將 claude-mem 集成到內(nèi)部平臺并提供給第三方使用，建議進行法律評估。

---

十六、總結(jié)與展望

16.1 核心價值回顧

claude-mem 解決了 AI 編程助手的一個根本性問題：上下文遺忘。

通過這個項目，你可以：

• 告別每天重復解釋項目背景的煩惱
• 讓 Claude 記住你的編碼習慣和項目架構
• 快速搜索歷史工作內(nèi)容
• 保持跨會話的工作連續(xù)性

16.2 最佳實踐建議

1. 安裝后先進行一次完整的項目討論
   
   ，讓 claude-mem 建立初始記憶庫
2. 定期查看 Web 界面
   
   ，了解 Claude 記住了什么
3. 善用隱私標簽
   
   保護敏感信息
4. 結(jié)合 CLAUDE.md 使用
   
   ，靜態(tài)知識放 CLAUDE.md，動態(tài)記憶交給 claude-mem
5. 遇到問題時使用內(nèi)置診斷功能

16.3 未來展望

根據(jù)項目的發(fā)展趨勢，claude-mem 可能會在以下方向繼續(xù)進化：

• 更智能的記憶壓縮算法
• 團隊共享記憶功能
• 更多 IDE 的支持
• 更強大的語義搜索能力

---

本文由源碼七號站原創(chuàng)，轉(zhuǎn)載請注明出處。

如果這篇文章對你有幫助，歡迎關注源碼七號站獲取更多高質(zhì)量的技術內(nèi)容。我們專注于發(fā)掘和解析最有價值的開源項目，幫助開發(fā)者提升工作效率。

---

附錄：相關資源鏈接

資源	鏈接
GitHub 倉庫	https://github.com/thedotmack/claude-mem
官方網(wǎng)站	https://claude-mem.ai
官方文檔	https://docs.claude-mem.ai
問題反饋	https://github.com/thedotmack/claude-mem/issues

---

最后更新：2026年1月

源碼七號站原創(chuàng)整理發(fā)布

PS：獲取更多AI&新自媒體&電商&源碼等干貨教程，請搜索訪問我們的網(wǎng)站 [源碼七號站]，一個安靜的AI互助學習公益社區(qū)。