claude-mem：跨会话记忆插件怎么装，有哪些已知问题

claude-mem 是 thedotmack 开源的跨会话记忆插件，用 TypeScript 写成，把 AI 编码 agent 的工具调用压缩成摘要并注入后续会话，支持 Claude Code、Codex、Copilot 等宿主。这篇文章梳理安装命令、provider 配置与记忆落点，并整理 Issue 里暴露的版本错配、Windows worker 启动失败等问题，帮你在挂到生产仓库前判断是否值得装。

开一个新的 AI 编码会话，上一轮讨论过的目录结构、改过的接口、踩过的构建坑，全都得从头讲一遍。项目周期越长，这种重复越贵；同一个 bug 换个会话又被翻出来改一次。

claude-mem 是一个用 TypeScript 写的跨会话记忆插件，记录 AI 编码 agent 的工具调用，压缩成摘要后注入后续会话。

它的输入是会话过程本身：agent 调了哪些工具、读过哪些文件、观察到什么。输出是压缩后的语义摘要，写进记忆库，等下一次会话开始时自动取相关片段回填。宿主不止 Claude Code，README 列出的还有 OpenClaw、Codex、Gemini、Hermes、Copilot、OpenCode。

五分钟先跑通

环境要求是 Node.js >= 20.0.0。最短的一条命令是：

npx claude-mem install

安装器先把配置铺好，然后引导你在浏览器里登录 claude-mem，用邮箱 magic link，不需要填信用卡。登录会给账号分配一个 memory key，同时解锁 claude-mem observer，这部分记忆额度跑在你的套餐之外，免费 14 天。试用到期后如果不订阅，记忆会自动回落到你的 Anthropic 套餐。

其他宿主走对应的 --ide 参数：

npx claude-mem install --ide grok-bot
npx claude-mem install --ide opencode
npx claude-mem install --ide antigravity

Claude Code 也可以从插件市场装：

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

装完重启 Claude Code，之前会话的上下文就会出现在新会话里。

不想走登录流程的，可以显式传 --provider，或者设环境变量 CLAUDE_MEM_ONLINE_OPTIN=false，或者在 CI 和非交互 shell 里运行，这几种情况下安装器会直接装完。v13.28.0 修的就是这件事：没有 TTY 的安装以前会卡在 provider must be explicit 上。

仓库里特别提醒过，npm install -g claude-mem 只安装 SDK 和库，不会注册插件钩子，也不会搭建 worker service。装插件要用上面的 npx 命令或 /plugin。

跑通之后你会得到什么

重启宿主后，新会话开头会带上从记忆库里取回的片段，你不需要手动贴一句「上次我们做到哪了」。

记忆落在哪取决于你选的 provider。默认是 CMEM Pro 托管记忆，v13.26.0 起云同步从旧的 Cloudflare Worker hub 迁到 https://sync.cmem.ai（Fly + Neon Postgres）。想留在本机，就得显式开本地 observer。

仓库 topics 里标了 sqlite、chromadb、embeddings，说明底层有本地数据库和向量检索这两条线，但 README 节选里没有展开存储路径。本地记忆文件落在哪个目录，仓库里没有说明这一步。

下一步能做的就是检索：让后续会话去查历史观察项，而不是靠你把上下文重新读一遍。

主要功能

会话捕获与压缩：agent 在会话里的工具调用被记录成观察项，再用 AI 压成语义摘要。
跨会话注入：新会话开始时，相关摘要被回填进上下文，v13.27.1 起每个座席的 zz-claude-mem-inject.md 会把自己的项目行排在全局行前面，全局查询在窗口填满时直接跳过。
多宿主安装：一条 npx claude-mem install 覆盖 Claude Code，--ide 参数覆盖 Grok Bot、OpenCode、Antigravity CLI。
记忆检索：README 导航里列了 MCP Search Tools 一节，说明记忆可以通过 MCP 工具查询，具体工具名在仓库节选里没有展开。
成本报告：agent-cost-report 技能在 v13.27.0 按实测数据重建，把 Claude Code 和 Codex 的 transcript token 按 OpenRouter 列表价折算，结果标注为 ESTIMATED，观察者成本单独计价、不并入总额。
Awareness push：面向 Grok Bot 的试点，把 decision、bugfix、security_alert、sensitive 这几类观察项按日期追加到 memory/log/YYYY-MM.md，由 bot 自己从磁盘重读，不写 profile.md、user-memory 或项目记忆。
云同步容错：CMEM Pro 的同步收到 401 或 403 时会暂停、每小时重试一次，续订后自动恢复，不再无限重试。

常用参数与配置

--provider：显式指定记忆 provider，跳过登录引导。三选一是 claude-mem observer、你自己的 OpenRouter 或 Gemini key、你的 Anthropic 套餐。
--ide：取值有 grok-bot、opencode、antigravity。
CLAUDE_MEM_ONLINE_OPTIN=false：关闭在线选项，安装器不再要求账号交互。
CLAUDE_MEM_GROK_BOT_AWARENESS_ENABLED=false：关掉 Grok Bot 的 awareness push。

Grok Bot 走的是另一条路。它没有 host hooks，插件改为监听聊天日志文件，默认 provider 是 CMEM Pro，本地 observer 需要 --provider host 手动开启。安装这个插件不会顺带装上 Cursor。

结果在哪里看

新会话开头的上下文：注入成功后，宿主启动时的会话里会自动出现历史摘要。
Grok Bot 的日志：awareness 内容写进对应 bot 的 memory/log/YYYY-MM.md；活索引落在每个座席的 zz-claude-mem-inject.md，按 80 行窗口排布。
云同步状态：CMEM Pro 会把暂停原因写出来，比如订阅失效会提示去 cmem.ai/pro 续订。
成本报告：agent-cost-report 技能输出的 token 折算金额。
版本与运行状态：插件清单和 worker 自报的版本号要能对上，对不上时钩子会反复杀 worker。

实际使用中的坑

下面几条来自仓库的 Issue 列表，是真实用户踩过的。

Windows 11 上装完插件，第一次启动 Claude Code 时 worker service 在 37777 端口起不来。从 7.0.3 到 7.3.9 的反馈里都出现过这条报错，目前标记为已解决。
v13.24.0 打包的是 13.23.1 的 bundle，plugin.json 和 package.json 已经升到 13.24.0，worker 自报的版本却还是旧的，钩子会在每次事件里把 worker 杀掉，形成循环。13.24.2 到 13.24.5 又出现过一次同类回归，两次都标为已解决。
用一段时间后项目目录里会散落一堆 CLAUDE.md 观察文件，还会出现重复嵌套的目录。有用户专门开 Issue 问这件事，状态已解决。
配额守卫会在一份过了 resetsAt 的 seven_day 快照上中止，唯一的绕过办法是重启，而重启会丢掉内存里排队的任务。这条仍是待解决状态。

选型参考

下面两个都是站内已收录的记忆与上下文方向项目，放在一起是想给同类选型一个横向参照。

项目	适合谁	部署方式	主要限制	什么情况下选它更合适	项目地址
claude-mem	长期跑多个 AI 编码项目、在几个宿主之间来回切的开发者	npx 安装器加宿主插件，运行时要求 Node.js >= 20.0.0	默认走 CMEM Pro 托管记忆，本地 observer 要显式开；`npm install -g` 只得到 SDK，不注册钩子；会在项目目录留下观察文件	你要解决的是跨会话、跨宿主的记忆保持	claude-mem
LeanCTX	在意单次会话上下文塞不下、想就地压缩的编码者	仓库没有说明	未逐一核实	你要处理的是单次会话太长，而不是会话之间记不住	LeanCTX 原理拆解：本地压缩 AI 编码上下文
LEANN	想在本机对个人文档做检索的人	仓库没有说明	未逐一核实	你要检索的是自己的文档库，不是 agent 的会话历史	LEANN：把个人数据装进笔记本的本地 RAG 索引

claude-mem 的记忆默认托管在云端，安装器会引导你登录账号，本地 observer 需要显式加 --provider host 才启用。LeanCTX 和 LEANN 这类本地方案在这点上省心得多，数据不出本机。如果你的代码不允许任何内容离开本地，或者你要解决的只是单次会话的上下文长度，这几条限制就足以让你先看别的方案。

合规红线

claude-mem 记录的是 agent 在会话里做过的每一件事：读过哪些文件、执行过什么命令、命令输出是什么。默认 provider 是托管的 CMEM Pro，这些内容会同步到 https://sync.cmem.ai。

把插件挂到生产代码库之前，先确认三件事：仓库里的密钥和凭据会不会被读进观察项；观察项里可能夹带的客户数据是否允许离开本机；团队是否接受第三方托管记忆。要留在本机就显式走本地 observer。这项能力只适用于你自己有权处理的代码与数据，把公司或客户的敏感内容同步到第三方托管服务之前，需要先拿到明确授权。

什么情况下别用它

你在做一次性小改动，下次不会再回到这个项目。跨会话记忆的价值来自重复访问，单次任务里它只会多出一层插件和一个后台 worker。

你的代码或数据不允许任何内容离开本机，而你又不打算手动配置本地 observer，默认路径就是托管服务。

你无法接受插件往项目目录里写文件，哪怕只是 CLAUDE.md 这类观察文件。

你跑在 Windows 上，且不能容忍后台 worker 服务的偶发启动问题。

你的 Node 版本低于 20.0.0。

反过来，长期维护同一批项目、习惯在 Claude Code 和别的宿主之间切换、又愿意为记忆单独配一个 provider 的人，是它最合适的用户。仓库地址在 https://github.com/thedotmack/claude-mem，许可证为 Apache License 2.0，主要语言 TypeScript，当前 95011 star、8407 fork、210 个开放 Issue。

焚评：这个项目的量化评分

本项目的选题来自焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.9 分（满分 10）。下表是各维度的得分：

评分维度	得分
热度动量（权重 25%）	10.0 / 10
开发活跃（权重 25%）	10.0 / 10
社区响应（权重 15%）	10.0 / 10
文档质量（权重 15%）	9.6 / 10
发布节奏（权重 10%）	9.9 / 10
风险控制（权重 10%）	10.0 / 10

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。

claude-mem：给 AI 编码 agent 装跨会话记忆