给你的 AI 编程助手装个长期记忆：claude-mem 让 Claude Code 关掉重开也不失忆

数据引自官方仓库与文档（2026-10-06 查）。

一句话： 9.6 万 Star 的开源插件（Apache-2.0），给 Claude Code、Codex、Gemini CLI 等编程 Agent 加一层跨会话记忆——自动记录它干过什么、压缩成摘要，下次开新会话时把相关上下文喂回去，不用每次重新交代项目背景。

痛点：会话一关，助手就失忆

用 Claude Code 这类工具改一个跨几天的项目，最烦的不是模型不够聪明，是它记不住事：

昨天刚定的接口约定、踩过的坑，今天开新会话全得重讲一遍；
会话一长就触发压缩，细节被压没，后半程开始重复犯错；
手写 CLAUDE.md 维护项目笔记能缓解，但全靠自觉，忙起来就断更。

本质问题是：Agent 的”工作记忆”只活在当前会话里，没有落盘，更没有按需取回的机制。

它解决什么：记录 → 压缩 → 按需注入

claude-mem 的思路是把记忆做成一个旁路系统，全程不用你手动记笔记：

自动记录：通过 5 个生命周期钩子（会话开始、提交提问、工具调用后、停止、会话结束）把 Agent 的工具调用过程记成一条条”观察”；
AI 压缩：后台 Worker 用你配置的模型把观察压成语义摘要，存进本地 SQLite（带 FTS5 全文索引），可选再建一份 Chroma 向量索引做语义搜索；
按需注入：新会话启动时，只挑和当前项目相关的记忆注入上下文，而不是把全部历史一股脑塞进去——官方把这套叫”渐进式披露”，省 token 是主要卖点（节省比例为官方/社区口径，待验证）；
能查能看：提供 MCP 搜索工具和 mem-search 技能，用自然语言查”我上周怎么修的那个登录 bug”；本地 Web 面板能实时看记忆流；项目文件夹还会自动生成带活动时间线的 CLAUDE.md；
隐私可控：内容里加 <private> 标签就不落库，敏感项目可以关掉跨来源注入。

和本站之前介绍的两个工具正好凑成一套：Agent Reach 给 Agent 装的是”眼睛”（联网读推特、Reddit、B 站），claude-mem 给的是”记性”；而 WeKnora 管的是文档知识库问答，和这种”Agent 自己的工作记忆”不是一回事，别混。

media generation claude mem cover 0 da450b8b 6729 40cf 8ea5 01dd1489a240

先看环境要求

Node.js：20.0.0 或更高，这是硬门槛；
Bun：≥ 1.0，安装时缺了会自动装，Worker 靠它跑；
uv：同样自动安装，给 Chroma 向量搜索提供 Python 环境；
宿主工具：Claude Code（插件支持最新版），也支持 Codex CLI、Gemini CLI、OpenCode、Cursor 等，各有对应的 --ide 安装方式；
硬件：不吃显卡、不占大内存，本质是个本地小服务 + SQLite 数据库，数据都在 ~/.claude-mem/ 里；
模型费用：观察压缩要调模型。可以走你自己的 Anthropic / OpenRouter / Gemini Key，官方还提供托管 observer（安装时邮箱登录，14 天试用，到期自动回落到你自己的方案）。不想注册账号，安装时显式指定 --provider 或走插件市场安装即可跳过。

上手：三步

1. 安装（选一种）

一条命令装好并注册钩子：

npx claude-mem install

或在 Claude Code 里走插件市场：

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

注意：npm install -g claude-mem 只装 SDK/库，不会注册钩子、也不会起 Worker，别用错——这是官方文档特意标注的坑。

2. 重启并验证

重启 Claude Code，随便在一个项目里干点活（读几个文件、改一处代码），然后开一个新会话，看它开场是否自动带上了上个会话的上下文。再打开 Worker 启动时打印的本地面板地址（常见是 localhost:37777，新版本按用户分配端口，以终端输出为准），能看到记忆一条条流进来，就说明链路通了。

3. 切中文模式（可选但推荐）

编辑 ~/.claude-mem/settings.json：

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

code--zh 是内置的简体中文模式（共 28 种语言），改完重启生效，之后生成的观察和摘要就是中文的，查历史时顺眼很多。

查历史的正确姿势：别直接让它”把详情全拉出来”。官方推荐三层走法——先 search 拿索引（一行一条，几十 token），看时间线 timeline 圈出感兴趣的几条，最后 get_observations 按 ID 取全文。先筛后取，官方称能省约 10 倍 token（待验证）。

Agent 排障玩法的更多思路，可以看本站这篇：Hermes Agent 深度配置指南，记忆层和网关层是两个维度的折腾。

常见问题

Q：装完新会话里没看到任何记忆？

A：先确认 Worker 在跑（看面板能否打开），再看数据目录 ~/.claude-mem/ 里有没有在长数据。钩子没注册成功是最常见原因，重跑 npx claude-mem install 或用插件市场方式重装。

Q：Worker 起不来？

A：按官方排障顺序来：确认 Bun 装好（bun --version）→ 看 Worker 日志 → 重启 Worker；端口被占就改 CLAUDE_MEM_WORKER_PORT 换端口再启动。

Q：向量搜索报错 / Chroma 起不来？

A：不用慌，它会自动降级成纯 SQLite FTS5 全文搜索，功能在、只是语义召回弱一点。想修就确认 uv/Python 正常后重启 Worker。

Q：提示数据库被锁（Database is locked）？

A：多半是残留进程占着库。停掉 Worker、清掉 stale 进程再重启即可。

Q：Windows 下报 npm 不是内部命令？

A：Node.js 没装或没进 PATH。装最新版 Node 安装包，装完重启终端再试。Windows 用户这一步最容易卡。

先泼三盆冷水

节省比例未经实测。 “省 75% token””省 10 倍”这类数字来自官方与社区口径，这次没条件本地跑量验证。记忆注入本身也要花 token，短会话、一锤子买卖的任务装它纯属增加开销。
压缩是有损的。 摘要记得住”修了登录 bug”，未必记得住当时那行关键 diff。重要约定该写进 CLAUDE.md 还是要写，别指望记忆层当唯一真相源；偶尔去面板里抽查它记了些什么。
它会记录你的工具调用内容。 虽然数据默认存本地、有 <private> 标签和脱敏选项，但碰敏感代码库前，先想清楚哪些东西不该进记忆库，别装完就裸奔。

另外提一句：这项目迭代非常猛（已发 350 多个版本，数据库 schema 还在涨），升级前扫一眼 release notes，跨大版本别无脑覆盖更新。

适合谁 / 不适合谁

适合：天天用 Claude Code / Codex 做跨天项目的人；同时开几个 Agent 工具、想共享一份项目记忆的人；受够了每次开会话重新交代背景的人。

不适合：只偶尔问一两个问题的一次性用户；对”工具在后台记录我干了什么”这件事本身就不舒服的人；希望装完就百分百准确复述历史细节的人——它记的是摘要，不是录像。

一句话

编程 Agent 缺的往往不是智商，是记性。claude-mem 用本地 SQLite + 向量索引把”记笔记、做摘要、按需取回”这套活全自动了，数据不出本机，中文模式开箱可用。如果你已经是重度 Agent 用户，这是目前最值得一试的记忆层；轻度用户先收藏，等项目变长了再装不迟。