claude-mem:让 AI 编程助手拥有跨会话记忆的开源工具

这个项目是什么

用 Claude Code 写过代码的人大概都有这个体验：每次开一个新会话，之前做的决定全没了。你昨天花了半小时跟它解释的架构思路，今天它一无所知。你得从头再讲一遍。

claude-mem解决的就是这个问题。

它的原理说起来不复杂：在你用 Claude Code（或者 Codex、Cursor、Gemini 等十几个 AI 编程工具）干活的时候，它在后台自动记录每次工具操作，然后用 AI 把这些操作压缩成简短的"观察笔记"，存到本地 SQLite 数据库里。下次开新会话时，相关的上下文会被自动注入回去。

你不需要手动操作什么，装完就自动跑。

作者 Alex Newman（@thedotmack）从去年开始做这个项目，现在版本号已经到 15.9.0了。本周在 GitHub 上涨了 7,995 颗星，总星数突破 11 万。说实话这个增长速度在 TypeScript 项目里相当猛。

为什么这周涨这么快

我翻了一下最近的提交记录，找到几个比较合理的解释。

首先是 PR #2255，这是仓库历史上最大的一次更新。整个安装流程被重新设计了，队列引擎从底层重写了一版（之前的版本有静默丢数据的 bug），还加了 ASCII 动画横幅和毛玻璃 UI。一口气删了 14,000 多行注释代码，整个项目瘦了不少。

其次是对接的 AI 工具越来越多。从最初的 Claude Code 独占，到现在支持 Codex、Cursor、Gemini、Grok Bot、OpenCode、T3 Code、Antigravity CLI 等 9 个以上的平台。每个平台都有自己的插件目录，用户基数自然就上去了。

还有一个原因是时机。最近 AI 编程工具整体在爆发期，Claude Code 的插件市场刚上线不久，大家对"让 AI 记住我"这个需求比以前强烈得多。

搭建教程：从零到跑通

第一步：确认环境

claude-mem 对环境有几项硬性要求：

先查一下 Node 版本：

node --version

如果低于 20，去 nodejs.org下载最新的 LTS 版本。Windows 用户装完记得重启终端，不然 PATH 不生效。

第二步：安装 claude-mem

核心命令就一行：

npx claude-mem install

安装过程会做这些事：

1. 检查依赖，缺失的 Bun 和 uv 会自动帮你装
2. 注册 Claude Code 的生命周期钩子
3. 启动 Worker 服务（本地 HTTP API）
4. 提示你在浏览器里登录 claude-mem

登录这一步用的是邮箱魔法链接，不需要信用卡。登录后会给你一个 memory key，解锁 claude-mem observer 功能，附带 30 天免费试用。

如果你不想登录，可以这样跳过：

npx claude-mem install --provider anthropic

或者设环境变量：

export CLAUDE_MEM_ONLINE_OPTIN=false

第三步：理解安装发生了什么

装完之后，你的系统里多了这些东西：

钩子启动器位置：

• Linux/macOS: 放在 PATH 上的某个位置
• Windows: %LOCALAPPDATA%\claude-mem\bin\claude-mem.exe

配置文件：

~/.claude-mem/settings.json

数据存储：

• SQLite 数据库（会话、观察记录、摘要）
• Chroma 向量数据库
  （语义搜索）
• 截图目录（默认关闭）：~/.claude-mem/media-v1/

第四步：验证安装是否成功

重启 Claude Code，随便开一个新会话。正常情况下，启动时会看到 Worker 的 URL 输出，类似：

Worker running at http://localhost:37xxx

端口号是动态分配的，公式是 37700 + uid % 100。这个设计比之前写死 37777好一些，多用户环境下不容易冲突。

如果你在 Windows 上遇到 hooks 找不到 claude-mem 可执行文件的错误：

Executable not found in $PATH: "claude-mem"

跑一下诊断：

npx claude-mem doctor

第五步：正常使用

装完之后不需要做任何额外操作。你照常用 Claude Code 写代码，claude-mem 在后台自动工作：

• 你每次读文件、编辑代码时
  ，PostToolUse钩子自动触发，记录这次操作
• 会话结束时
  ，AI 把这一轮的操作压缩成观察笔记
• 下次开会话时
  ，相关的上下文自动注入到 SessionStart

如果你写代码时涉及到敏感信息，可以用 <private>标签包裹，那部分不会被记录：

<private>
API_KEY=sk-xxx
</private>

第六步：搜索历史记忆

claude-mem 提供了一套三层搜索工作流，设计上是为了省 token：

第一层 — 搜索索引（~50-100 tokens/条）

search(query="authentication bug", type="bugfix", limit=10)

返回精简的索引列表，每条带一个 ID。

第二层 — 查看时间线

timeline(observation_id=123)

看看这个观察前后发生了什么。

第三层 — 获取完整详情（~500-1000 tokens/条）

get_observations(ids=[123, 456])

只对你筛过的 ID 拉完整内容。

这个设计挺聪明的。如果直接拉全部详情，token 消耗会大十倍。先看索引再拉详情，等于做了个低成本过滤。

第七步：配置中文模式

claude-mem 支持多语言模式，包括简体中文。编辑配置文件：

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

改完重启 Claude Code 就生效。这个模式下，生成的观察笔记会用中文写。

查看所有可用模式：

ls ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/

目前内置的有 code（英文默认）、code--zh（中文）、code--ja（日语）。

第八步：给其他 AI 工具安装

如果你不只使用 Claude Code，claude-mem 也支持其他平台：

给 Cursor 装：

npx claude-mem install --ide cursor

给 Codex 装：

npx claude-mem install --ide codex

给 T3 Code 装（同时支持 Codex 和 Claude Code）：

npx claude-mem install --ide t3code

给 OpenCode 装（需 1.3.4+）：

npx claude-mem install --ide opencode

给 Grok Bot 装：

npx claude-mem install --ide grok-bot

Grok Bot 比较特殊，它没有宿主钩子，是通过监控聊天日志文件来工作的。默认用 CMEM Pro 托管记忆，想用本地 observer 的话加 --provider host。

第九步：使用 Docker 部署（团队场景）

对于团队使用，可以用 Docker 部署 Worker 服务。关键设计点：

• Worker API 默认无认证（假设在私有网络里）
• 在 Docker Compose 中，Worker 放在私有网络
• 一个小型网关容器做中继，只转发 observer 调用到 LiteLLM，并响应 GET /api/health健康检查

这种架构下，外部网络只能触达网关，Worker 本身不暴露。

第十步：排查问题

遇到问题先跑诊断：

npx claude-mem doctor

如果你想自动生成 bug 报告：

cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report

直接在 Claude Code 里描述问题也行，claude-mem 有个 troubleshoot 技能会自动诊断。

架构拆解：它到底怎么工作的

整个流程的入口是 6 个生命周期钩子：

每个钩子实际执行的是 claude-mem hook claude-code <event>这个命令，由安装在 PATH 上的启动器调用。不是 shell 脚本，是一个编译好的可执行文件。

我个人的几点理解

谁适合用

命令速查