Claude Code 终于有长期记忆了！claude-mem 持久化记忆系统完全指南
源码七号站独家深度解析 | 本文详细拆解 claude-mem 项目的核心原理与操作流程，帮助开发者彻底告别 AI 编程助手的"失忆"问题。
一、开篇：AI 编程助手的"失忆症"困境
相信每一位使用过 Claude Code 的开发者都有过这样的体验：
你和 Claude 协作了一整天，它帮你写了几千行代码，修复了十几个 Bug，你们配合得天衣无缝。然后你关掉终端，第二天满怀期待地打开 Claude Code，准备继续昨天的工作——
"抱歉，我不知道你在说什么。"
所有的上下文、所有的讨论、所有的项目背景——全部被清零了。就好像你在和一个失忆症患者合作写代码，每天早上都需要从头解释一遍：这个项目是干什么的、我们昨天做到哪里了、哪些问题还没解决......
这不是 Claude 的问题，而是大语言模型天生的局限性。Claude Code 的上下文窗口大约是 20 万 Token，说实话，对于复杂项目来说这点容量少得可怜。很多时候让它运行十几二十分钟，上下文就直接用满了。
这个痛点，正是 claude-mem 项目要解决的核心问题。
二、claude-mem 是什么？
claude-mem 是一个专门为 Claude Code 打造的持久化记忆压缩系统。它能够自动捕获你和 Claude 的对话上下文，让 AI 拥有真正的长期记忆能力。
简单来说，它的工作方式类似于给 Claude 配备了一个"私人秘书"——这个秘书会默默记录每次对话中发生的重要事情，当你下次开始新对话时，秘书会把相关的历史信息重新告诉 Claude，让它能够"记起"之前的工作内容。
2.1 项目基本信息
|
属性 |
信息 |
|
项目名称 |
claude-mem |
|
GitHub 仓库 |
|
|
官方网站 |
|
|
官方文档 |
|
|
开源协议 |
AGPL-3.0 |
|
系统支持 |
Windows、macOS、Linux |
2.2 核心特性一览
1. 持久化记忆
上下文会在会话之间自动保存，不需要手动操作。每次你结束一个编程会话，claude-mem 都会自动生成语义摘要，为下次会话做好准备。
2. 渐进式披露（Progressive Disclosure）
这是 claude-mem 的核心设计哲学。它采用分层记忆检索策略，模拟人类的记忆模式：
- 首先加载轻量级的"索引"——标题、类型、时间戳
- 只有在需要深入细节时，才获取完整的观察记录
- 这种方式既节省 Token，又不会在需要时显得"浅薄"
3. 智能搜索
可以通过自然语言搜索项目历史。比如你可以直接问 Claude：
- "上次我们修复了什么 Bug？"
- "我们之前是怎么实现用户认证的？"
- "这个 Bug 之前修过吗？"
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 操作）
执行内容：
- 检查并安装必要的依赖（如果需要）
- 启动 Worker 服务
- 从数据库中检索最近的观察记录
- 将相关上下文注入到新会话中
这是最关键的钩子之一，它确保每次你开始新会话时，Claude 都能"记起"之前的工作内容。
钩子二：UserPromptSubmit（用户提交提示）
触发时机： 用户发送消息给 Claude 时
执行内容：
- 记录用户的原始提示
- 保存用户请求以供后续分析
钩子三：PostToolUse（工具使用后）
触发时机： Claude 执行任何工具操作后
执行内容：
- 捕获工具执行的详细信息
- 记录文件操作（读取、写入、编辑）
- 记录 Shell 命令执行
- 记录代码搜索操作
- 记录 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 会自动将每个观察分类为以下类型之一：
|
类型 |
英文 |
说明 |
|
决策 |
decision |
架构选择、技术决策 |
|
Bug修复 |
bugfix |
问题诊断和修复 |
|
功能实现 |
feature |
新功能开发 |
|
重构 |
refactor |
代码重构 |
|
发现 |
discovery |
关于代码库的发现 |
这种分类使得后续搜索更加精准。比如你可以问："上周我们修复了哪些 Bug？"
四、安装配置完全指南
接下来源码七号站将带你一步步完成 claude-mem 的安装和配置。
4.1 系统要求
在安装之前，请确保你的系统满足以下要求：
|
要求 |
说明 |
|
Node.js |
18.0.0 或更高版本 |
|
Claude Code |
最新版本（需支持插件功能） |
|
Bun |
JavaScript 运行时（会自动安装） |
|
SQLite 3 |
用于持久化存储（已打包） |
|
内存 |
至少 4GB RAM |
|
磁盘空间 |
至少 100MB 可用空间 |
4.2 方式一：通过插件市场安装（推荐）
这是最简单的安装方式，只需要两行命令：
第一步：启动 Claude Code
在终端中启动 Claude Code。
第二步：添加插件市场并安装
在 Claude Code 中输入以下命令：
/plugin marketplace add thedotmack/claude-mem等待命令执行完成，然后输入：
/plugin install claude-mem安装程序会询问你安装范围，有以下选项：
- 全局安装（推荐）：在任何目录下使用 Claude Code 都能使用这个记忆工具
- 当前项目安装：只在当前项目中使用
建议选择第一个选项进行全局安装。
第三步：重启 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:status4.4 配置文件详解
claude-mem 的配置文件位于 ~/.claude-mem/settings.json，首次运行时会自动创建默认配置。
以下是主要配置项说明：
{
"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 |
数据存储目录 |
~/.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:context4. 检查数据目录
确认以下文件存在：
~/.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 会：
- 生成会话摘要
- 存储所有观察记录
- 为下次会话准备上下文
5.2 第二次对话：见证记忆的力量
步骤1：开启全新的 Claude Code 会话
完全关闭之前的终端，打开一个新的终端，启动 Claude Code：
claude步骤2：询问之前的工作
在这个全新的对话中（没有任何上下文），问 Claude：
上次我们做了一个什么项目？都实现了哪些功能？步骤3：见证奇迹
你会看到 Claude 开始查找之前的项目记录。它会回答类似这样的内容：
"根据历史记录，我们上次一起做了一个美发预约网站，实现了以下功能：
- 用户认证系统：包括用户注册、登录、注销功能
- 导航栏组件：响应式导航设计
- 首页展示：服务项目展示页面
- 预约功能：在线预约系统
- 个人中心：用户信息管理
整个网站使用了 [具体技术栈]，项目结构如下......"
这就是 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)这会返回一个轻量级的索引，包含标题、类型和时间戳。
第二步：识别相关条目
查看
