一、痛点：为什么需要持久化内存？

在使用 Claude Code 进行项目开发时，你是否遇到过这些困扰：

• 会话重启后"失忆"：每次新开对话，Claude 都像是第一次见你的项目，需要重新解释业务逻辑
• 上下文窗口限制：长会话中，早期的关键决策和代码逻辑被挤出上下文
• 跨天开发断片：昨天讨论过的架构设计，今天需要从头再讲一遍
• 项目知识无法沉淀：团队的最佳实践、踩过的坑，无法被AI记住并复用

claude-mem 正是为解决这些问题而生。它是一个专为 Claude Code 构建的持久化内存压缩系统，让 Claude 能够像人类开发者一样，记住项目的"历史"，实现真正的跨会话知识连续性。

二、claude-mem 是什么？

核心定位

三、核心功能详解

1. 持久化内存：会话结束，记忆不结束

claude-mem 通过 5 个生命周期钩子（SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd）自动捕获会话中的关键信息：

• 你执行过的命令和工具调用
• 代码修改和文件操作
• 错误和调试过程
• 架构决策和讨论要点

这些信息会被压缩成语义摘要，存储在本地 SQLite 数据库中，下次会话启动时自动注入到 Claude 的上下文中。

2. 渐进式披露：省 token 的智能检索

claude-mem 采用三层工作流模式，避免一次性将所有历史记录塞进上下文：

优势：通过在获取详情前进行筛选，可节省约 10 倍 token 消耗，同时保证上下文的相关性。

3. 基于技能的搜索：自然语言查历史

claude-mem 提供了 4 个 MCP 搜索工具：

使用示例：

4. 隐私控制：敏感内容不上传

使用 <private> 标签包裹敏感信息，claude-mem 会自动排除这部分内容的存储，确保密码、密钥等隐私数据不会进入内存数据库。

5. Web 查看器界面

启动 worker 服务后，会在终端打印一个本地 URL，你可以通过浏览器实时查看内存流，直观地了解 Claude “记住了什么”。

四、快速上手：一条命令搞定安装

前置要求

• Node.js：20.0.0 或更高版本
• Claude Code：支持插件的最新版本
• Bun：JavaScript 运行时（如缺失会自动安装）
• uv：Python 包管理器（用于向量搜索，如缺失会自动安装）

安装方式

方式一：命令行安装（推荐）

方式二：通过插件市场安装

方式三：OpenClaw Gateway 一键安装

重启即生效

安装完成后，重启 Claude Code。来自先前会话的上下文将自动出现在新会话中，无需任何手动操作。

?? 注意：npm install -g claude-mem 仅安装 SDK/库本身，不会注册插件钩子或设置 worker 服务。请始终通过 npx claude-mem install 或 /plugin 命令进行安装。

五、配置：按需定制你的工作流

配置文件位于 ~/.claude-mem/settings.json，首次运行时自动生成默认设置。

语言与模式配置

claude-mem 支持多种工作流模式和语言：

支持 code--[lang] 格式，其中 [lang] 为 ISO 639-1 语言代码。修改后重启 Claude Code 即可生效。

可配置项

• AI 模型选择
• Worker 服务端口
• 数据目录位置
• 日志级别
• 上下文注入策略

六、工作原理：架构浅析

claude-mem 的架构设计简洁而高效：

核心组件

1. 生命周期钩子（5+1个）：嵌入 Claude Code 的执行流程，自动捕获事件
2. 智能安装器：缓存依赖检查，自动安装缺失的 Bun、uv 等工具
3. Worker 服务：本地 HTTP API 服务，提供搜索端点和 Web 查看器
4. SQLite 数据库：结构化存储会话、观察记录、语义摘要
5. Chroma 向量数据库：支持混合语义 + 关键词的智能检索
6. mem-search 技能：自然语言查询接口，渐进式披露结果

七、实际应用场景

场景1：长期项目开发

你在开发一个微服务架构项目，已经进行了 20 多次会话。每次新会话，Claude 都能记住：

• 各服务的职责划分
• 数据库表结构设计
• API 接口约定
• 已解决的坑和解决方案

场景2：Bug 追踪与修复

三天前你修复了一个棘手的并发 Bug，今天类似问题再次出现。通过自然语言搜索 "authentication bug"，Claude 能快速定位到之前的修复记录，避免重复踩坑。

场景3：团队协作知识沉淀

团队成员 A 解决了一个配置问题，claude-mem 记录了全过程。团队成员 B 遇到相同问题时，Claude 能直接引用 A 的解决方案，实现团队知识的"自动传承"。

场景4：代码审查辅助

Claude 记得你上周说过"这个项目要用策略模式重构支付模块"，当你今天提交新代码时，它能主动提醒是否符合既定的架构方向。

八、故障排除

常见问题

自动诊断

遇到问题直接向 Claude 描述，内置的 troubleshoot 技能会自动诊断并提供修复方案。

也可以手动生成 bug 报告：

九、与其他方案的对比

十、总结

claude-mem 填补了 Claude Code 在持久化上下文方面的空白，让 AI 编程助手从"会话级记忆"跃升到"项目级记忆"。它的核心价值在于：

• 零手动干预：全自动捕获和注入，不改变原有工作流
• 智能省 token：渐进式披露避免上下文爆炸
• 本地优先：数据存储在本地，隐私可控
• 开源可扩展：Apache 2.0 协议，可自由定制

如果你长期使用 Claude Code 进行项目开发，claude-mem 几乎是必装插件。它让 Claude 真正成为你项目的"长期合伙人"，而不是每次都要重新认识的"临时工"。