claude-mem：五万星插件让Claude Code拥有跨会话记忆

你是不是也遇到过这种崩溃时刻？

周一用 Claude Code 写了个登录模块，聊得挺好，代码也生成了。周三继续开发，新开一个会话，Claude 完全不记得之前干了什么——你不得不重新解释一遍项目结构、技术选型、已完成的接口……一个下午就这么交代了。更惨的是，上次修bug时踩的坑，这次又踩了一遍，因为Claude根本没记住上次的经验教训。

这不是你一个人的问题，这是所有用 AI 编程助手的开发者共同的痛点：AI 没有持久记忆，每次对话都是从零开始。而今天要介绍的这个项目， GitHub 上狂揽 54000+ Star 的 claude-mem，就是来彻底解决这个问题的。

claude-mem 是什么？

一句话：claude-mem 是一个 Claude Code 插件，它能自动记录你在编程会话中的一切操作，用 AI 压缩成语义摘要，并在未来的会话中自动注入相关上下文。

简单说，就是给 Claude Code 装上了一个"长期记忆大脑"。你上次做了什么、修了哪些bug、做了哪些架构决策，它都记得，下回开会自动告诉你。

核心功能一览

安装步骤（手把手教程）

前置条件

在安装 claude-mem 之前，你需要确保：

1. 已安装 Node.js 18.0.0 或更高版本 —— 这是运行环境
2. 已安装 Claude Code —— 这是插件宿主，没它不行
3. 操作系统：macOS / Windows / Linux 均支持

检查 Node.js 版本：

node --version
# 应该显示 v18.x.x 或更高

如果你还没装 Node.js，去 nodejs.org 下载安装，建议选 LTS 版本。

安装 Claude Code

如果你还没有 Claude Code，先安装它：

# 使用 npm 全局安装
npm install -g @anthropic-ai/claude-code

安装完成后再执行登录：

claude login

安装 claude-mem（推荐方式）

最简单的安装方式，一条命令搞定：

macOS / Linux：

npx claude-mem install

Windows（PowerShell）：

npx claude-mem install

如果你在 Windows 上看到 npm: The term 'npm' is not recognized 的错误，说明 Node.js 没有正确加入 PATH。去 nodejs.org 重装并勾选"Add to PATH"选项，然后重启终端。

安装器会自动完成以下工作：

• 检测你已安装的 IDE（Claude Code、Cursor、Gemini CLI、Windsurf 等）
• 复制插件文件到正确位置
• 在 Claude Code 中注册插件
• 安装所有依赖（包括 Bun 和 uv，缺啥装啥）
• 自动启动 Worker 服务

另外两种安装方式

方式二：Claude Code 插件市场安装

在 Claude Code 交互界面中直接输入：

/plugin marketplace add thedotmack/claude-mem

/plugin install claude-mem

这种方式更直观，不用离开 Claude Code 的界面。

方式三：从源码构建安装

适合想要二次开发或者研究源码的同学：

# 克隆仓库
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem

# 安装依赖
npm install

# 构建hooks和Worker服务
npm run build

# Worker会在首次Claude Code会话时自动启动
# 或者手动启动：
npm run worker:start

# 检查Worker是否运行
npm run worker:status

⚠️ 重要提醒

不要用 npm install -g claude-mem 来安装！ 这样只会安装 SDK 库，不会注册插件钩子，也不会启动 Worker 服务。正确方式只有两种：npx claude-mem install 或 /plugin 命令。

安装后的验证

安装完成后，重启 Claude Code，然后可以这样验证：

# 检查hooks配置
cat plugin/hooks/hooks.json

# 查看Worker日志
npm run worker:logs

# 测试上下文检索
npm run test:context

数据默认存放在 ~/.claude-mem/ 目录下：

• 数据库：~/.claude-mem/claude-mem.db
• 日志：~/.claude-mem/logs/worker-YYYY-MM-DD.log
• 设置：~/.claude-mem/settings.json

如果想自定义数据目录，可以设置环境变量：

export CLAUDE_MEM_DATA_DIR=/your/custom/path

使用方法

基础用法：开箱即用

安装完成并重启 Claude Code 后，claude-mem 就开始自动工作了，你不需要做任何额外操作。

整个工作流程是这样的：

1. 启动 Claude Code —— 自动加载最近10个会话的上下文
2. 正常编写代码 —— 你每一步操作（读文件、写文件、执行命令等）都会被自动捕获
3. Claude 完成本次回复 —— Stop 钩子自动生成会话摘要并保存
4. 下次开会话 —— 历史工作自动出现在新会话的上下文中

它会捕获的内容包括：

• Read —— 文件读取和内容访问
• Write —— 新文件创建
• Edit —— 文件修改
• Bash —— 命令执行
• Glob —— 文件模式搜索
• Grep —— 内容搜索
• 以及所有其他 Claude Code 工具的操作

每条捕获的记录会自动提取：标题、副标题、叙事描述、关键事实、概念标签、类型分类（决定、bug修复、新功能等）、涉及的文件。

进阶用法：用自然语言搜索历史记忆

除了自动上下文注入，claude-mem 还提供了强大的 MCP 搜索工具。你只需要像平常一样跟 Claude 说话：

• "上次我们修了哪些bug？"
• "认证模块是怎么实现的？"
• "worker-service.ts 最近的改动是什么？"
• "给我看看这个项目最近的工作"

Claude 会自动识别你的意图，调用搜索工具来查询历史。

搜索遵循三层渐进式查询流程，非常省 token：

第一层：搜索索引（每条记录约50-100 token）

search(query="数据库迁移", type="bugfix", limit=10)

返回紧凑的索引表，包含ID、标题、日期、类型。

第二层：时间线上下文

timeline(anchor=12345, depth_before=3, depth_after=3)

获取某个观察记录前后的时间线上下文，了解事情的前因后果。

第三层：获取完整细节

get_observations(ids=[123, 456, 789])

只对你真正需要的记录获取完整信息，每条约500-1000 token。

这种分层方式相比传统一次性拉取全部信息，能节省约10倍的 token。

搜索还支持高级语法：

# 布尔运算
search(query="认证 AND JWT")
search(query="OAuth OR JWT")
search(query="安全 NOT 已废弃")

# 精确短语匹配
search(query='"数据库迁移"')

# 按列搜索
search(query="title:认证")
search(query="concepts:安全")

# 日期范围筛选
search(query="性能优化", dateStart="2025-10-01", dateEnd="2025-10-31")

# 按项目筛选
search(query="API", project="my-app", limit=15)

# 分页
search(query="重构", limit=10, offset=20)

高阶用法：Web 可视化界面

安装后，浏览器打开 http://localhost:37777 你就能看到一个实时记忆流界面：

• 查看所有会话记录和观察数据
• 浏览每条记录的详细信息
• 设置界面可以切换功能选项
• 还可以切换到 Beta 通道尝鲜新功能

隐私控制

如果你有敏感信息不想被记录，用 <private> 标签包裹：

这个API密钥是 <private>sk-xxxxx</private>，请配置到环境变量中。

被 <private> 标签包裹的内容不会被存储到记忆数据库中。

实际场景举例

跟同类方案对比

很多人会问：Claude Code 自己不是有记忆功能吗？干嘛还需要 claude-mem？这个问题问得好，我们来看对比：

核心差异一句话总结： Claude Code 自带的 CLAUDE.md 是"你手动写规则让AI遵守"，而 claude-mem 是"AI自动记住你做过的所有事并在需要时主动注入"。前者是静态的规则本，后者是动态的记忆系统，这是本质区别。

另外，claude-mem 还支持 Cursor、Gemini CLI、Windsurf 等多个开发工具，不仅仅局限于 Claude Code。而它的 54000+ Star 也充分说明了这个项目的实用价值和社区认可度。

小结

claude-mem 用一句话概括：给 AI 编程助手装上长期记忆，让它真正成为理解你项目的搭档，而不是每次都从零开始的陌生人。 一条 npx claude-mem install 就能搞定，全自动运行，不需要你操心。54000+ Star 的开源项目，5万多人用脚投票，值得一试。

项目地址： https://github.com/thedotmack/claude-mem

文档地址： https://docs.claude-mem.ai/