在持续使用Claude Code进行项目开发的过程中，我发现了一个让人崩溃的现象——每次重启Claude Code，它都像《海底总动员》里的多莉一样，把我们之前的所有讨论、决策、甚至代码架构彻底忘记。
这不仅意味着大量重复的上下文补充工作，更严重的是对Token的无谓浪费和协作效率的急剧下降。
这个问题的根源在于：Claude Code缺乏跨Session的持久化记忆机制。
带着这个痛点，我接触到了claude-mem这个项目，它提供了一个系统化的解决方案。
为什么Claude每次都会“失忆”
Claude Code的工作原理决定了它的"遗忘症"：每个新Session启动时，系统只能访问当前的对话内容，对历史工作一无所知。
这在短期对话中尚可接受，但在真实项目场景中会产生严重后果：
- 第一天实现用户认证，第二天Claude不知道采用的是什么认证方案
- 第三天无法回忆数据库Schema的设计决策
- 第四天重复解释API设计的原因和思路
更棘手的是Token限制问题。Claude Code每个Session约有50次工具调用额度，每次调用消耗1k-10k个Token。
用完即耗尽context，导致不得不重启并重新提供项目信息——这形成了一个恶性循环。
渐进式信息检索模型
如果两位同事在进行技术讨论，他们不会每次都从头开始。他们通常依靠：
- 记住关键决策（"我们选择Redis做缓存"）
- 保留问题印象（"那个并发Bug还没修"）
- 需要时查阅详细信息（"那个函数的完整实现"）
这种工作方式遵循渐进式记忆提取的逻辑：
- 第一层：存在性索引 - 知道做过这件事
- 第二层：摘要层面 - 理解大致内容
- 第三层：完整细节 - 查询原始数据
人类大脑不会把所有细节都装入工作记忆，这样会导致认知过载。我们只保留关键信息，需要时才调取详细内容。
Claude-Mem的架构设计
核心工作流程
Claude-Mem通过以下流程实现持久化记忆：
Session启动 ↓ 自动注入最近观察记录作为上下文 用户提问 ↓ 创建新session，保存prompt 工具执行 ↓ 捕获所有观察（文件读写、命令执行等） Worker处理 ↓ 用Claude Agent SDK提取学习成果 Session结束 ↓ 生成总结，准备下次使用
五个关键执行阶段
1. Context Hook - Session启动时的上下文注入
Claude Code启动时，Context Hook会自动触发，从数据库中提取最近10条观察记录，以索引形式注入Claude的上下文。这里的关键是使用"索引形式"而非完整内容：
- 🔴 [Decision] 选择Express作为API框架 (Token成本: ~500)
- 🔵 [Feature] 实现用户认证中间件 (Token成本: ~450)
- 🟤 [Bugfix] 修复并发写入导致的数据竞争 (Token成本: ~380)
这样Claude能够快速获得项目背景，而不会被冗余细节淹没。
2. User Message Hook - Session创建与Prompt记录
用户输入第一个问题时，系统创建新的Session并记录Prompt内容。这个Session会持续到Claude Code关闭或手动清除为止。
3. New/Save Hook - 观察数据的捕获
这是系统最核心的部分。每当Claude使用工具（read_file、write_file、bash等）时，Hook会捕获：
- 工具名称与参数
- 工具的输出结果
- 时间戳和Session ID
这些原始数据存入数据库，等待后续处理。
4. Worker Processing - AI驱动的学习成果提取
这是Claude-Mem最"优雅"的设计。后台Worker（由PM2管理）会：
- 监听新的观察记录
- 调用Claude Agent SDK进行AI分析
- 从工具调用中提取关键学习成果
例如，当Claude执行"npm install express"时，Worker会生成压缩的观察记录：
{
"type": "decision",
"concept": "framework-choice",
"narrative": "选择Express作为Web框架，因为它轻量且社区成熟",
"files": ["package.json"],
"tokens": 480
}
这条观察只消耗~500个Token，但包含了最关键的信息。压缩率高达95%。
5. Summary Hook - Session级别的总结生成
Claude Code关闭时，系统生成Session总结：
本次Session主要完成了项目初始化，选择了Express + SQLite技术栈，实现了基础的用户认证中间件，并修复了一个并发写入的Bug。
这个总结会在下次启动时显示在上下文顶部。
按需深度查询
Mem-Search Skill - 自然语言查询系统
如果Claude需要某个观察的完整细节，可以调用Mem-Search Skill进行查询。这使得信息获取遵循"按需加载"原则：
- 第一层：查看索引 - 了解存在哪些观察 (~10 Token/条)
- 第二层：查看摘要 - 理解大概内容 (~500 Token/条)
- 第三层：查询完整内容 - 获取详细工具输出 (~10k Token/条)
Claude可以自主决策：某个观察看起来不太相关，不值得花5k Token去查，不如直接读源代码（可能仅需1k Token）。
十种搜索操作能力
Mem-Search支持以下查询维度：
- 全文搜索观察 - 关键词匹配所有观察
- 搜索Session总结 - 找到相关历史Session
- 搜索用户Prompt - 查找之前提出的问题
- 按概念搜索 - 如"discovery"、"problem-solution"
- 按文件搜索 - 找涉及某文件的所有观察
- 按类型搜索 - decision、bugfix、feature、refactor等
- 最近上下文 - 获取最近的Session背景
- 时间线查询 - 查看时间点前后的发生事项
- 带时间线的搜索 - 搜索并返回相关时间线
- API帮助 - 查看搜索API文档
用户可以直接使用自然语言提问：
- "上个Session我们做了什么？"
- "我们之前修过这个Bug吗？"
- "认证是怎么实现的？"
- "最近对worker-service.ts做了哪些改动？"
Claude会自动调用Mem-Search查询相关记录并返回答案。相比传统MCP工具，mem-search作为"skill"而非"tool"，节省了约2,250个Token。
混合搜索：语义与关键词的融合
Claude-Mem采用Hybrid Search策略：
- SQLite FTS5 - 全文索引，实现快速关键词搜索
- Chroma向量数据库 - 语义相似度搜索
例如，当提问"我们是怎么处理并发问题的？"时：
- 关键词搜索会找到含"并发"的观察
- 语义搜索会找到含"race condition"、"mutex"、"lock"的观察
- 两者结合大幅提升准确率
Beta功能
核心机制：实时Transcript压缩
传统Claude Code的问题在于：工具输出会累积在context中，最终导致context耗尽。Endless Mode通过实时压缩解决这一问题：
- Working Memory (Context)：压缩后的观察 (~500 Token/条)
- Archive Memory (Disk)：完整工具输出，随时可调取
工作流程：
- 工具执行完成后立即生成观察摘要 (~500 Token)
- 原始输出存储到磁盘
- 用摘要替换context中的原始输出
效果：Context增长速度从O(N²)降低到O(N)，理论上支持20倍以上的工具调用而不耗尽context。
Trade-off：速度与容量
Endless Mode的代价是：每次工具执行后需要额外60-90秒来生成摘要。这就是为什么它仍处于Beta阶段。用户可以根据需求选择：
- 选择速度：使用稳定版，获得实时响应
- 选择容量：使用Beta版，获得"无限"context
可在 http://localhost:37777 的Web UI中切换版本，数据完全保留。
Web Viewer UI：实时的记忆可视化
Worker启动后，访问 http://localhost:37777 可以看到：
- 当前运行的所有Sessions
- 观察记录的完整时间线
- 每条观察的详细信息
- Token使用统计和成本分析
- 亮色/暗色主题切换（v5.1.2新增）
这个UI不仅美观，更能帮助优化工作流。通过观察UI，你会发现：
- 哪些工具调用产生了大量观察
- 哪些观察被标记为"critical"（🔴）
- 哪些Session的Token消耗特别高
实际使用体验
三个显著改变
1. 消除"教学"环节
以前每次启动Claude Code，需要花5-10分钟解释项目结构。现在可以直接说"继续昨天的工作"，Claude就知道该做什么。上下文注入使得Claude自动拥有项目背景。
2. Claude主动参考历史决策
当提问"应该用Redis还是Memcached做缓存？"时，Claude会回复：
"根据上次Session的讨论，我们决定用Redis，因为它支持持久化。"
并附上claude-mem:// 引用链接，指向那次决策的观察记录。这种体验接近于和记忆力良好的同事协作。
3. Token使用效率大幅提升
Claude无需每次都重新读取整个代码库，而是可以通过Mem-Search快速查询之前的处理方案。节省的Token意味着能进行更多工具调用，完成更复杂的任务。
技术架构详解
Claude-Mem的核心由6个异步执行的生命周期Hooks组成：
- context-hook - Session开始时注入上下文
- user-message-hook - 捕获用户的prompt
- new-hook - 工具执行前的准备工作
- save-hook - 保存工具执行结果
- summary-hook - Session结束时生成总结
- cleanup-hook - 清理临时数据
此外还有Smart Install (pre-hook)，检查依赖是否已缓存，将npm install时间从2-5秒降至10毫秒。
后端服务与数据存储
- Worker Service：由PM2管理的后台进程，提供HTTP API（端口37777）
- 数据存储：SQLite数据库（~/.claude-mem/claude-mem.db），使用FTS5进行全文索引
- 向量存储：Chroma Vector Database用于语义搜索
- API端点：10个搜索endpoint、Web Viewer UI、健康检查和日志接口
安装与配置
快速安装
在Claude Code的终端中执行：
/plugin marketplace add thedotmack/claude-mem/plugin install claude-mem
然后重启Claude Code即可。无需额外配置。
初始化流程
第一次启动时，Claude-Mem会自动：
- 初始化SQLite数据库
- 启动PM2 Worker
- 打开Web Viewer UI（http://localhost:37777）
系统要求
- Node.js 18.0.0或更高版本
- Claude Code最新版（支持plugin系统）
- PM2（已内置，无需全局安装）
- SQLite 3（已内置）
可选配置
通过 ./claude-mem-settings.sh 可配置：
- CLAUDE_MEM_MODEL - AI模型选择（默认claude-sonnet-4-5）
- CLAUDE_MEM_WORKER_PORT - Worker端口（默认37777）
- CLAUDE_MEM_DATA_DIR - 数据目录（仅开发用）
大多数场景下默认配置即可满足需求。
常见问题诊断
Worker未启动
运行命令：npm run worker:restart
上下文注入未生效
运行命令：npm run test:context 进行检查。首次使用时数据库中可能还没有观察记录。
搜索功能不工作
检查FTS5表是否存在：
sqlite3 ~/.claude-mem/claude-mem.db "SELECT name FROM sqlite_master WHERE type='table';"
若问题持续，可直接让Claude诊断："帮我诊断claude-mem"，Troubleshoot Skill会自动激活并提供修复方案。
总结
作为一个深度使用Claude Code开发者，我能感受到Claude-Mem解决的不仅是一个表面问题，而是触及AI协作本质的挑战。
这个项目证明了一个重要概念：AI的"记忆能力"并非固定限制，而是系统设计的产物。通过合理的架构——AI驱动的内容压缩、渐进式信息检索、混合搜索引擎、后台Worker管理——我们可以在有限的Token预算内实现几乎无限的记忆容量。
最深层的意义在于：Claude-Mem让跨Session协作变成了真正意义上的"对话"而不是"独立的问答"。你不再需要每次都从零开始教Claude你的项目，而是像和一个真正的同事沟通一样，基于共同的历史背景进行对话。这种模式转变将显著提升复杂项目的开发效率。
如果你也在使用Claude Code进行真实项目开发，如果你也为"Token耗尽"和"记忆丧失"感到困扰，Claude-Mem值得一试。它可能会重新定义你对AI编程助手的理解。
相关资源
-
GitHub: thedotmack/claude-mem -
完整文档: docs.claude-mem.ai -
安装指南: Installation Guide -
架构概览: Architecture Overview -
Beta 功能: Beta Features -
许可证: AGPL-3.0