claude-mem 深度体验：Claude Code 最强记忆插件，装完就不管了

前言

“昨天让 Claude 改的 bug，今天新开一个会话，它全忘了。”

这是 Claude Code 用户最深的痛点之一。每次新会话，Claude 就像失忆了一样，完全不记得昨天做过什么、改过哪些文件、为什么做了某个决策。你得从头解释一遍，费时费力。

最近，一个叫 claude-mem 的开源项目火爆全网，GitHub 上斩获 6 万+ Star，直接解决了这个问题。

今天这篇文章，我会带你搞清楚：claude-mem 是什么、怎么安装、怎么用、以及它为什么这么火。

一、claude-mem 是什么

一句话：claude-mem 是 Claude Code 的持久化记忆插件，自动记录每次会话的操作，压缩成可搜索的语义记忆，下次开新会话时自动注入上下文。

它解决了 Claude Code 最核心的短板：

没有 claude-mem	有 claude-mem
每次新会话从零开始	自动加载最近 10 次会话上下文
不记得昨天改过什么	完整记录所有工具调用和操作
需要反复解释项目背景	AI 自动理解项目演进历史
关掉终端就全忘了	记忆永久保存，随时搜索

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

claude-mem 的实现原理正是依托了 Claude Code 的 Hook 生命周期机制，想深入了解 Hook 可以看这篇《用 Hook 机制给 Claude Code 加上”刹车”和”安全带”》。

给技术党一张架构全景图：

二、核心功能

claude-mem 的能力远不止”记住上次做了什么”。它包含六大核心功能：

1. 自动捕获

每次 Claude 调用工具时，claude-mem 自动捕获：

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

完全自动，无需手动操作。

2. 智能压缩

不是简单地把日志存下来，而是用 AI 把原始操作压缩成结构化记忆：

Title — 简要描述发生了什么
Narrative — 详细解释
Facts — 关键发现（要点列表）
Type — 分类（决策、bug 修复、新功能等）
Files — 涉及哪些文件

这样下次注入上下文时，不会把海量原始日志塞进去，而是精准地注入”有意义的记忆”。

3. 会话摘要

Claude 每次完成回复时，自动生成会话摘要：

Request — 你要求了什么
Investigated — Claude 探索了什么
Learned — 关键发现和洞察
Completed — 完成了什么
Next Steps — 下一步要做什么

4. 渐进式上下文注入

这是 claude-mem 最精妙的设计，分三层控制 token 消耗：

Layer 1（自动）：启动时显示最近操作的标题索引，约 50-200 token
Layer 2（按需）：你问”上次那个 bug 怎么修的？“，Claude 调用 MCP 搜索工具获取详细信息
Layer 3（完全回溯）：直接读取源文件获取完整上下文

核心思路：先给 Claude 看目录，需要时再翻详细内容。

5. 语义搜索

底层用 ChromaDB 向量数据库 + SQLite FTS5 全文搜索 的混合架构，支持：

自然语言查询：“上次那个认证 bug 怎么修的？”
按文件搜索：“worker-service.ts 最近改了什么？”
按类型筛选：bugfix、feature、decision 等
时间线回溯：查看某个操作前后发生了什么

6. Web 查看器

内置 Web UI，访问 http://localhost:37777 可以实时查看：

记忆流（所有捕获的操作）
会话历史
搜索功能
设置和配置

三、安装 — 一行命令搞定

claude-mem 的安装极其简单，两种方式任选：

方式一：npx 安装（推荐）

npx claude-mem install

就这一行。安装完成后重启 Claude Code 即可。

方式二：Plugin 市场安装

在 Claude Code 中执行：

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

然后重启 Claude Code。

系统要求

Node.js 18.0.0 或更高版本
Claude Code 最新版（支持 Plugin）
Bun 运行时（自动安装）
SQLite 3（内置）

配置中文模式

安装后默认是英文，切换中文只需编辑配置文件：

# 编辑配置
vim ~/.claude-mem/settings.json

修改为：

{
  "CLAUDE_MEM_MODE": "code--zh"
}

重启 Claude Code 即可生效，所有记忆摘要都会以中文生成。

Mac 用户必看：MCP 连接失败排查

这是 Mac 版本最大的一个坑。 安装完成后，你可能会发现 claude-mem 的 MCP 服务器显示连接失败（红色状态），插件完全没有记忆功能。

根本原因：claude-mem 的 MCP 服务依赖 Bun 运行时，但 Claude Code 启动 MCP 服务器时使用的 PATH 环境变量和你终端里的不一样。即使你在终端里 bun --version 正常，Claude Code 可能找不到 bun 命令。

排查步骤：

1. 确认 bun 已安装并加入系统 PATH

# 检查 bun 是否存在
which bun

# 如果找不到，手动加入 .zshrc
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. 创建 bun 的符号链接到系统目录

这是最关键的一步。即使 bun 在你的 PATH 里，Claude Code 的 MCP 进程也可能找不到它：

# 将 bun 链接到 Homebrew 的 bin 目录（Mac 通用路径）
ln -sf $(which bun) /opt/homebrew/bin/bun

# 如果是 Intel Mac，路径不同
# ln -sf $(which bun) /usr/local/bin/bun

3. 修改 MCP 配置使用绝对路径

编辑 Claude Code 的 MCP 配置文件：

# 查看当前 MCP 配置
cat ~/.claude/settings.json | grep -A 10 "claude-mem"

找到 claude-mem 的 command 字段，把 bun 改成绝对路径：

{
  "mcpServers": {
    "claude-mem-mcp": {
      "command": "/opt/homebrew/bin/bun",
      "args": ["run", "/你的路径/.claude-mem/mcp-server.js"]
    }
  }
}

4. 验证 MCP 连接正常

重启 Claude Code，然后输入 /mcp 查看 MCP 服务器状态。如果 claude-mem-mcp 显示为绿色连接状态，说明修复成功。

快速诊断清单：

现象	原因	解决方案
MCP 显示红色	bun 不在 PATH 中	符号链接到 `/opt/homebrew/bin/`
Worker 端口 37777 不通	服务未启动	`curl http://localhost:37777/health` 检查
安装后无记忆记录	MCP 断连，Hook 无法通信	按上述步骤修复 MCP 连接
`bun: command not found`	bun 未安装	`curl -fsSL https://bun.sh/install \| bash`

四、使用 — 装完就不管了

claude-mem 最大的特点是 全自动运行，零手动干预。

完整工作流：

启动 Claude Code → 自动加载最近 10 次会话的上下文
正常工作 → 每次工具调用都被自动捕获
Claude 完成回复 → Stop Hook 自动生成会话摘要并保存
下次开新会话 → 之前的工作上下文自动出现

你唯一需要做的是：搜索历史。直接用自然语言问 Claude：

“上次我们修了哪些 bug？”
“认证功能是怎么实现的？”
“worker-service.ts 最近改了什么？”
“给我看看这个项目最近的工作记录”

Claude 会自动调用 claude-mem 的 MCP 搜索工具，从记忆库中检索相关信息。

隐私？不用担心

claude-mem 的所有数据都存在你本地（~/.claude-mem/），SQLite 数据库和 ChromaDB 向量库都在本机运行，不往任何云端传。不存在数据泄露的风险。

如果你不想让某些内容（比如 API Key、密码）出现在记忆库里污染搜索结果，可以用 private 标签排除：

<private>
API Key: sk-xxx
数据库密码: xxxxxx
</private>

被包裹的内容不会被记录。但说实话，大多数人压根用不上这个功能——反正数据都在你自己电脑上。

五、和 CLAUDE.md 记忆系统有什么区别

你可能已经在用 CLAUDE.md 做持久化记忆了，那 claude-mem 还有什么价值？

维度	CLAUDE.md	claude-mem
记忆类型	静态规则和偏好	动态操作记录
内容来源	手动编写	自动捕获
搜索能力	无（只能全文读取）	语义搜索 + 全文搜索
token 消耗	每次对话都加载全文	渐进式加载，按需获取
适用场景	”告诉 AI 我的规则"	"让 AI 记住它做了什么”

两者互补，不是替代。 CLAUDE.md 管”规则”，claude-mem 管”经历”。

欢迎关注公众号 FishTech Notes，一块交流使用心得！