Claude Code 持久化记忆插件 claude-mem 完全指南

4. 可视化管理界面

claude-mem 提供一个实时 Web 界面（运行在 http://localhost:37777/），你可以：

• 查看记忆流
• 浏览所有记忆内容
• 按类型过滤（决策、Bug 修复、功能实现等）
• 切换不同项目
• 调整各种设置

5. 隐私控制

你可以排除敏感内容，完全掌控哪些信息被存储。通过 <private> 标签包裹的内容不会被记录。

6. 全自动运行

无需手动干预，后台透明运行，自动完成所有记忆管理工作。

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

要真正理解 claude-mem 的价值，我们需要深入了解它的技术架构。这一部分内容稍微偏技术向，但本文尽量用通俗的语言来解释。

3.1 整体架构概览

claude-mem 的核心设计理念是：它不会中断或修改 Claude Code 的行为，而是从外部观察，通过生命周期钩子提供价值。

整个系统由以下几个核心组件构成：

┌─────────────────────────────────────────────────────────────┐
│ Claude Code 会话                                              │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 生命周期钩子 (Lifecycle Hooks)                               │
│ SessionStart → UserPromptSubmit → PostToolUse → Stop        │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Worker 服务 (后台处理)                                        │
│ 通过 Claude Agent SDK 提取学习内容                           │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 双数据库存储系统                                             │
│ SQLite (结构化) + ChromaDB (向量化)                         │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 下次会话开始时自动注入相关上下文                             │
└─────────────────────────────────────────────────────────────┘

3.2 五大生命周期钩子详解

claude-mem 使用 5 个生命周期钩子来捕获和处理会话信息。这些钩子会在 Claude Code 的关键时刻自动触发。

钩子一：SessionStart（会话开始）

触发时机： Claude Code 启动时（包括 startup、clear 或 compact 操作）

执行内容：

1. 检查并安装必要的依赖（如果需要）
2. 启动 Worker 服务
3. 从数据库中检索最近的观察记录
4. 将相关上下文注入到新会话中

这是最关键的钩子之一，它确保每次你开始新会话时，Claude 都能"记起"之前的工作内容。

钩子二：UserPromptSubmit（用户提交提示）

触发时机： 用户发送消息给 Claude 时

执行内容：

• 记录用户的原始提示
• 保存用户请求以供后续分析

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

触发时机： Claude 执行任何工具操作后

执行内容：

1. 捕获工具执行的详细信息
2. 记录文件操作（读取、写入、编辑）
3. 记录 Shell 命令执行
4. 记录代码搜索操作
5. 记录 Web 操作

这个钩子会捕获几乎所有的工具执行记录，包括：

• 文件操作：Write、Read、Edit
• Shell 命令：Bash
• 代码搜索：Grep、Glob
• Web 操作：WebFetch、WebSearch
• 笔记本编辑：NotebookEdit

钩子四：Stop（会话停止）

触发时机： Claude 停止当前任务时

执行内容：

• 生成当前会话的 AI 驱动摘要
• 记录已完成的工作
• 标记待处理的任务

摘要的格式如下：

<summary>
  <request>用户的原始请求</request>
  <investigated>检查了什么</investigated>
  <learned>关键发现</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（会话结束）

触发时机： Claude Code 会话完全结束时

执行内容：

• 标记会话为已完成
• 清理临时资源
• 确保所有数据持久化

3.3 异步处理架构：快速响应 + 后台处理

claude-mem 采用了一个巧妙的架构设计来确保不影响 Claude Code 的响应速度：

前端钩子（快速）：

┌─────────────────────────────────────────────────────────────┐
│ HOOK (快速层)                                                │
│ 1. 读取 stdin (< 1ms)                                        │
│ 2. 插入队列 (< 10ms)                                         │
│ 3. 返回成功 (总计 < 20ms)                                    │
└─────────────────────────────────────────────────────────────┘
↓ (队列)

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

┌─────────────────────────────────────────────────────────────┐
│ WORKER (慢速层)                                              │
│ 1. 每秒轮询队列                                              │
│ 2. 通过 Claude SDK 处理观察 (5-30 秒)                          │
│ 3. 解析并存储结果                                            │
│ 4. 标记观察已处理                                            │
└─────────────────────────────────────────────────────────────┘

这种设计的好处是：

• 钩子执行极快（毫秒级），不会阻塞 Claude Code
• 真正的 AI 处理在后台进行
• 即使后台处理失败，也不会影响用户体验

3.4 双数据库存储系统

claude-mem 使用两个数据库来存储记忆：

1. SQLite 数据库（结构化存储）

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

用途：

• 存储观察记录
• 存储会话信息
• 存储摘要
• 支持全文搜索（FTS5）

2. ChromaDB（向量数据库）

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

用途：

• 存储向量嵌入
• 支持语义搜索
• 根据含义（而非关键词）查找相关内容

这种双数据库架构使得 claude-mem 既能进行精确的关键词搜索，也能进行"模糊"的语义搜索。

3.5 记忆分类系统

claude-mem 会自动将每个观察分类为以下类型之一：

这种分类使得后续搜索更加精准。比如你可以问："上周我们修复了哪些 Bug？"

四、安装配置完全指南

下面将带你一步步完成 claude-mem 的安装和配置。

4.1 系统要求

在安装之前，请确保你的系统满足以下要求：

4.2 方式一：通过插件市场安装（推荐）

这是最简单的安装方式，只需要两行命令：

第一步：启动 Claude Code

在终端中启动 Claude Code。

第二步：添加插件市场并安装

在 Claude Code 中输入以下命令：

/plugin marketplace add thedotmack/claude-mem

等待命令执行完成，然后输入：

/plugin install claude-mem

安装程序会询问你安装范围，有以下选项：

1. 全局安装（推荐）：在任何目录下使用 Claude Code 都能使用这个记忆工具
2. 当前项目安装：只在当前项目中使用

建议选择第一个选项进行全局安装。

第三步：重启 Claude Code

安装完成后，重启 Claude Code 让配置生效。

第四步：验证安装

重启后，输入以下命令查看已安装的插件：

/plugin

按 Tab 键切换，你应该能看到 claude-mem 插件已经出现在列表中。

4.3 方式二：从源码安装（进阶）

如果你需要进行开发测试，或者想要修改源码，可以选择从源码安装：

# 克隆仓库
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
# 安装依赖
npm install
# 构建钩子和 Worker 服务
npm run build
# 手动启动 Worker 服务（可选，首次会话会自动启动）
npm run worker:start
# 验证 Worker 运行状态
npm run worker:status

4.4 配置文件详解

claude-mem 的配置文件位于 ~/.claude-mem/settings.json，首次运行时会自动创建默认配置。

以下是主要配置项说明：

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

配置项解释：

关于模型配置的说明：

这里可能有人会疑惑：为什么要在配置中设置模型？需要配置 API Key 吗？

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

claude-mem 会作为 Claude Code 的子进程运行，它会复用 Claude Code 的登录认证，通过 Claude Code 来调用 AI 模型。所以只要你能正常启动 Claude Code，claude-mem 就能正常工作。

4.5 环境变量配置（可选）

如果你需要自定义某些配置，可以通过环境变量来覆盖：

# 自定义数据目录
export CLAUDE_MEM_DATA_DIR=/custom/path
# 自定义 Worker 端口
export CLAUDE_MEM_WORKER_PORT=8080
# 设置上下文观察数量
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. 检查数据目录

确认以下文件存在：

• ~/.claude-mem/claude-mem.db - 数据库文件
• ~/.claude-mem/.worker.pid - Worker 进程 ID 文件
• ~/.claude-mem/.worker.port - Worker 端口文件
• ~/.claude-mem/settings.json - 配置文件

五、实战演练：从零开始体验持久化记忆

现在让我们通过一个完整的实战案例来体验 claude-mem 的强大功能。

5.1 第一次对话：创建项目

步骤 1：启动新的 Claude Code 会话

claude

步骤 2：让 Claude 创建一个项目

向 Claude 发送请求：

请帮我创建一个美发预约网站，需要包含以下功能：
1. 用户注册和登录
2. 服务项目展示
3. 在线预约功能
4. 个人中心

步骤 3：观察 claude-mem 的工作

在 Claude 开始工作的同时，打开浏览器访问 http://localhost:37777/，你会看到 Web 界面开始记录各种信息：

• 项目初始化过程
• 文件创建记录
• 代码编写过程
• 目录结构搭建

步骤 4：完成项目并退出

等 Claude 完成项目后，你可以结束会话。此时 claude-mem 会：

1. 生成会话摘要
2. 存储所有观察记录
3. 为下次会话准备上下文

5.2 第二次对话：见证记忆的力量

步骤 1：开启全新的 Claude Code 会话

完全关闭之前的终端，打开一个新的终端，启动 Claude Code：

claude

步骤 2：询问之前的工作

在这个全新的对话中（没有任何上下文），问 Claude：

上次我们做了一个什么项目？都实现了哪些功能？

步骤 3：见证奇迹

你会看到 Claude 开始查找之前的项目记录。它会回答类似这样的内容：

"根据历史记录，我们上次一起做了一个美发预约网站，实现了以下功能：

1. 用户认证系统：包括用户注册、登录、注销功能
2. 导航栏组件：响应式导航设计
3. 首页展示：服务项目展示页面
4. 预约功能：在线预约系统
5. 个人中心：用户信息管理

整个网站使用了 [具体技术栈]，项目结构如下......"

这就是 claude-mem 的神奇之处——新的对话中，Claude 依然能够"记住"之前的工作！

5.3 更多实用场景

场景一：继续之前的工作

继续完善我们之前做的美发网站，添加一个评价系统

Claude 会直接知道你说的是哪个项目，无需重新解释。

场景二：排查历史 Bug

之前我们在用户登录功能上遇到过什么问题？是怎么解决的？

claude-mem 会搜索历史记录，找出相关的 Bug 修复记录。

场景三：查看决策历史

我们为什么选择使用 JWT 而不是 Session？

如果之前有过相关讨论，Claude 能够找到当时的决策记录。

六、Web 管理界面使用指南

claude-mem 的 Web 界面是一个强大的管理工具，让我们详细了解它的功能。

6.1 访问界面

打开浏览器，访问：http://localhost:37777/

6.2 主要功能区域

1. 记忆流（Memory Stream）

这是主界面，显示所有的观察记录。每条记录包含：

• 时间戳
• 类型标签（decision、bugfix、feature 等）
• 涉及的文件
• 观察内容摘要

2. 项目切换

如果你有多个项目，可以在界面中切换不同项目的记忆。

3. 过滤功能

可以按照以下维度过滤记忆：

• 观察类型（决策、Bug 修复、功能等）
• 时间范围
• 涉及的文件

4. 设置面板

点击设置图标，可以配置：

• 应包含哪些观察类型
• 排除哪些内容
• 切换稳定版/测试版

5. 事实叙述（Fact Narrative）

点击某条记忆的"事实叙述"按钮，可以看到更详细的记录，包括：

• 具体做了什么操作
• 相关的上下文信息
• 标签信息

6.3 Beta 功能：Endless Mode

claude-mem 提供了一个实验性功能叫 Endless Mode（无尽模式），这是一种仿生记忆架构，用于大幅延长会话长度。

问题背景：

标准的 Claude Code 会话在大约 50 次工具使用后就会触及上下文限制。每个工具添加 1-10k+ Token，而且 Claude 在每次响应时都会重新合成所有之前的输出（O(N²) 复杂度）。

Endless Mode 的解决方案：

• 分离工作记忆（Working Memory）和归档记忆（Archive Memory）
• 工作记忆：当前活跃的观察
• 归档记忆：存储在磁盘上的完整输出，可快速调用
• 复杂度从 O(N²) 降低到接近线性

启用方式：

在 Web 界面的 Settings 中切换到 Beta 版本即可尝试。

注意事项：

• Endless Mode 会增加延迟（每个工具约 60-90 秒）
• 目前仍处于实验阶段
• 适合需要长时间持续工作的场景

七、搜索功能深度使用

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

7.1 自然语言搜索

最简单的方式是直接用自然语言提问：

上次会话我们修复了什么 Bug？

我们是怎么实现用户认证的？

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

7.2 结构化搜索

claude-mem 支持一个三层工作流模式来进行高效搜索：

第一步：搜索索引

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

这会返回一个轻量级的索引，包含标题、类型和时间戳。

第二步：识别相关条目

查看返回的索引，找到相关的记录 ID（比如 #123、#456）。

第三步：获取完整详情

get_observations(ids=[123, 456])

获取特定记录的完整内容。

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 标签

在你的代码或对话中，使用 <private> 标签包裹不想被记录的内容：

<private> 这里的内容不会被 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

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

export CLAUDE_MEM_WORKER_PORT=8080

3. 手动启动 Worker：

bun plugin/scripts/worker-service.cjs

9.2 记忆没有被保存

症状： 完成会话后，下次对话 Claude 依然不记得

排查步骤：

1. 检查 Worker 是否运行：

npm run worker:status

2. 检查数据库文件是否存在：

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

3. 查看 Worker 日志：

npm run worker:logs

9.3 依赖安装失败

症状： 安装过程中提示依赖错误

解决方案：

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

node --version

2. 手动安装依赖：

cd ~/.claude/plugins/marketplaces/thedotmack npm install

9.4 上下文注入过多/过少

症状： 每次会话开始时注入的历史信息太多或太少

解决方案：

调整上下文观察数量配置：

export CLAUDE_MEM_CONTEXT_OBSERVATIONS=5 # 减少
# 或
export CLAUDE_MEM_CONTEXT_OBSERVATIONS=20 # 增加

9.5 使用自动诊断功能

claude-mem 内置了自动诊断功能。如果遇到问题，可以直接向 Claude 描述问题，troubleshoot skill 会自动激活并提供修复建议。

你也可以生成详细的 Bug 报告：

cd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report

十、进阶配置与优化

10.1 使用其他 AI 提供商

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

使用 OpenRouter：

export CLAUDE_MEM_PROVIDER=openrouter
export OPENROUTER_API_KEY=your-api-key

使用 Gemini：

export CLAUDE_MEM_PROVIDER=gemini
export GEMINI_API_KEY=your-api-key

10.2 自定义模式和语言

claude-mem 支持自定义模式文件，位于 ~/.claude-mem/modes/。可以为不同的编程语言或工作模式配置不同的提示词。

10.3 记忆导出与导入

如果需要在不同机器间迁移记忆，可以使用导出/导入功能。详细说明请参考官方文档的 Memory Export/Import 页面。

10.4 与 Cursor IDE 集成

claude-mem 不仅支持 Claude Code，还支持 Cursor IDE。配置方式略有不同，请参考官方文档的 Cursor Integration 页面。

十一、技术架构图解

为了帮助读者更直观地理解 claude-mem 的工作方式，这里提供几张关键的架构图解。

11.1 数据流向图

用户输入 ↓
Claude Code 处理 ↓
PostToolUse 钩子触发 ↓
观察数据发送到 Worker ↓
Worker 调用 AI 提取语义 ↓
双数据库存储
├── SQLite (结构化索引)
└── 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 处理动态的工作记忆和历史追溯

12.2 与其他记忆插件的对比

市面上有一些其他的 AI 记忆解决方案，但 claude-mem 有几个独特优势：

1. 专为 Claude Code 优化：深度集成生命周期钩子
2. 语义压缩：不是简单存储日志，而是提取有意义的观察
3. 隐私友好：支持细粒度的隐私控制
4. 开源透明：代码可审计，数据完全本地化

十三、适用场景分析

13.1 最适合的场景

1. 长期重构项目

在进行跨越多天的复杂重构时，持久化记忆能帮助 Claude 记住：

• 重构的目标和动机
• 已完成的部分
• 待处理的问题
• 之前的决策依据

2. 多模块大型项目

当项目涉及多个模块时，Claude 能够记住：

• 模块间的依赖关系
• 之前的架构讨论
• 各模块的实现细节

3. 团队协作项目

虽然 claude-mem 主要是个人工具，但在团队项目中：

• 每个人都有自己的记忆库
• 可以通过导出/导入分享关键决策
• 保持个人工作流的连续性

4. 学习和探索性开发

在学习新技术时，claude-mem 能帮你记住：

• 之前尝试过什么
• 什么方法有效/无效
• 学习过程中的关键发现

13.2 不太适合的场景

1. 一次性脚本任务

如果只是写一个简单的一次性脚本，记忆功能的价值有限。

2. 高度机密项目

尽管有隐私保护机制，但对于极度敏感的项目，任何形式的持久化存储都需要谨慎评估。

3. 资源受限环境

claude-mem 需要运行后台 Worker 服务，会占用一定的系统资源。在资源极度受限的环境中可能不太合适。

十四、升级与维护

14.1 自动升级

通过插件市场安装的 claude-mem 会自动升级。当有新版本可用时，SessionStart 钩子会自动检测并更新。

14.2 手动升级

如果需要手动升级，可以执行：

/plugin update claude-mem

14.3 版本历史重要更新

v9.0.0：

• 修复了多个关键 Bug
• 设置文件首次运行时自动创建
• 修复了钩子执行问题

v8.2.0：

• 清理了大量冗余代码（删除 984 行）
• 简化了会话管理
• 修复了时间戳损坏问题

v7.1.0：

• 用原生 Bun 进程管理替换了 PM2
• 迁移过程自动完成

v5.4.0+：

• 基于技能的搜索替换了 MCP 工具
• 每个会话节省约 2,250 Token

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

十五、开源协议说明

claude-mem 使用 AGPL-3.0 开源协议。这意味着：

你可以：

• 免费使用
• 修改源码
• 部署到自己的环境

但你需要：

• 如果你修改后作为网络服务提供给他人，必须开源你的修改
• 衍生作品必须使用相同的协议

对于普通开发者来说，直接使用没有任何限制。但如果你是企业用户，想要将 claude-mem 集成到内部平台并提供给第三方使用，建议进行法律评估。

十六、总结与展望

16.1 核心价值回顾

claude-mem 解决了 AI 编程助手的一个根本性问题：上下文遗忘。

通过这个项目，你可以：

• 告别每天重复解释项目背景的烦恼
• 让 Claude 记住你的编码习惯和项目架构
• 快速搜索历史工作内容
• 保持跨会话的工作连续性

16.2 最佳实践建议

1. 安装后先进行一次完整的项目讨论，让 claude-mem 建立初始记忆库
2. 定期查看 Web 界面，了解 Claude 记住了什么
3. 善用隐私标签保护敏感信息
4. 结合 CLAUDE.md 使用，静态知识放 CLAUDE.md，动态记忆交给 claude-mem
5. 遇到问题时使用内置诊断功能

16.3 未来展望

根据项目的发展趋势，claude-mem 可能会在以下方向继续进化：

• 更智能的记忆压缩算法
• 团队共享记忆功能
• 更多 IDE 的支持
• 更强大的语义搜索能力

附录：相关资源链接