你有没有过这种体验：昨天和 Claude Code 调了半天 Bug，项目结构、失败日志、排查路径都讲清楚了；今天打开新会话，对面又是一片空白。你得重新介绍项目背景，重新解释为什么这个接口重要，重新交代上次已经排除了哪些假设。
这不是 Claude 不够聪明，而是会话本身有天然边界。上下文窗口装得下当前对话，却装不下你几周、几个月甚至几个项目里的隐性经验。对个人来说，这会让 AI 协作变成重复交代背景；对团队来说，踩坑记录、决策理由、排查过程很容易散落在一次次会话里，最后还是靠人脑记忆。
claude-mem 要解决的，就是让 Claude Code 自动沉淀长期上下文，并在新会话里按需召回。
它不是让你多写一份文档，也不是要求你每次手动整理知识库。它更像给 Claude Code 装了一个本地记忆层：日常怎么提问、怎么调试、怎么执行工具，基本不变；有价值的对话、工具调用、决策和观察，会在后台被记录、总结、索引，等下次需要时再找回来。
为什么需要长期记忆
很多人刚开始用 AI 编程工具时，最强烈的感受是提效。它能读代码、改 Bug、写脚本、解释报错，看起来像一个随叫随到的协作者。但用久了以后，另一个问题会变得越来越明显：AI 很擅长处理当前上下文，却很难天然记住历史上下文。
比如你排查一个接口返回 500 的问题，第一天已经确认不是鉴权、不是参数缺失，也不是数据库连接异常，而是某个特定参数组合触发了旧逻辑。第二天新会话继续查，如果没有历史记忆，Claude 很可能重新从鉴权、参数、数据库这些常规路径开始分析。它不是故意绕远路，而是不知道你昨天已经走过这些路。
再比如团队做技术选型，半年前从 Redis 切到 Memcached，当时可能有延迟、成本、运维复杂度、业务访问模式等一堆取舍。半年后有人问为什么这么做，如果 PR 描述写得很粗，聊天记录又找不到，最后只能靠当事人回忆。技术决策一旦只存在脑子里，就很难被复用，也很难被审计。
测试工程师对这种痛点应该更敏感。很多质量问题不是一次定位完成的，而是跨天、跨版本、跨环境反复收敛：今天记录一个偶现条件，明天补一段日志，后天发现和某个依赖版本有关。没有记忆系统时，这些线索容易断在会话之间；有记忆系统时，它们至少有机会沉淀成可检索的项目历史。
所以，claude-mem 的价值不只是让 Claude 记住你是谁，而是让它记住你们已经做过什么、排除过什么、决定过什么。
claude-mem 是什么
claude-mem 是一个面向 Claude Code 的本地持久记忆系统。它的核心逻辑可以概括为一句话：把会话过程里的有效信息自动入库，再在后续会话里按相关性召回。
这里有两个关键词，一个是自动，一个是本地。
自动，意味着你不需要每次手动说：请把这段内容记下来。它通过生命周期 Hook 捕捉会话开始、用户提问、工具执行、会话结束等事件，在后台完成记录和总结。你正常使用 Claude Code，记忆会跟着你的工作流自然沉淀。
本地，意味着它主要把数据放在本机的 SQLite 和 Chroma 向量库里。对于很多研发、测试、内部项目场景来说，这比把所有历史上下文丢到第三方云端更容易接受。当然，本地不等于没有风险，只要会话里出现凭据、客户数据、PII，仍然要按敏感信息处理。
适合优先尝试 claude-mem 的场景很明确：长期维护同一个代码库、经常跨会话推进任务、项目里有大量隐性知识、团队希望把排查经验和决策过程沉淀下来。如果只是一次性脚本、临时问答，或者仓库里经常处理未脱敏敏感数据，就没必要一上来就启用。
自动记忆流程
claude-mem 的架构并不复杂，可以理解成三类入口加一个存储后端。
┌──────────────────────────────────────┐
│ Claude Code（用户交互层） │
└──────────────────┬───────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
生命周期 Hook MCP Tools Skill 集
（自动触发） （search/ （显式调用）
timeline/
get_observations）
└─────────────┼─────────────┘
▼
┌──────────────────────┐
│ Worker Service │
│ HTTP API :37777+UI │
└──────────┬───────────┘
▼
┌──────────────────────┐
│ 本地 SQLite（结构化） │
│ + Chroma（向量索引） │
└──────────────────────┘
生命周期 Hook 负责自动记录。会话开始时，它会尝试检索和当前目录、当前问题相关的历史；用户提问时，它会记录问题；工具执行后，它会记录关键工具调用；会话结束时，它会对这次会话做语义化总结，把值得复用的内容提炼成 observation。
MCP Tools 负责显式检索。search 用来找候选历史，timeline 用来查看某条记录前后的上下文，get_observations 用来拉取完整内容。这个设计比较实用，因为不是所有历史都需要展开，先拿摘要判断值不值得看，能减少不必要的上下文消耗。
Skill 集 负责把常见任务包装成更顺手的入口，比如 /mem-search 用来搜历史方案，/learn-codebase 用来学习新仓库，/weekly-digests 用来生成周报，/timeline-report 用来整理项目历程。
一次完整会话大致是这样流转的：
你 Claude Code Hook Worker SQLite/Chroma
│ │ │ │ │
│── 打开新会话 ───▶│ │ │ │
│ │── SessionStart▶│ │ │
│ │ │── 查相关历史 ─▶│ │
│ │ │ │── 向量检索 ───▶│
│ │ │ │◀── ID + 摘要 ──│
│ │◀── 注入上下文 ──│ │ │
│ │ │ │ │
│── 提问 ─────────▶│ │ │ │
│ │─ UserPrompt ──▶│── 记录提问 ───▶│── 存原始记录 ─▶│
│ │── 执行工具 ────▶│ │ │
│ │── PostToolUse─▶│── 记录工具 ───▶│── 入库 ───────▶│
│ │ │ │ │
│── 关闭会话 ─────▶│ │ │ │
│ │── Stop ───────▶│── 语义化总结 ─▶│── 写 obs ─────▶│
│ │ │ │── 建向量索引 ─▶│
真正值得注意的是最后一步。会话结束时，它不是简单把聊天记录原样堆进去，而是提炼出更适合检索的 observation。比如本次排查的结论、已经排除的路径、某个命令的异常结果、某次技术选择背后的理由。这些内容比原始聊天更适合下次召回。
不是全量注入
很多人一听长期记忆，第一反应是担心上下文爆炸。历史记录越多，每次会话是不是越慢、越贵、越混乱？
这个担心是合理的。长期记忆如果做成每次都全量注入，本质上就是把记忆变成噪音。claude-mem 的思路更接近渐进式检索：先搜索摘要，再按时间线补上下文，最后才拉完整 observation。
第一步是 search。它返回的是候选 ID 和摘要，成本较低，适合先判断有没有相关历史。比如你问以前怎么处理 JWT 过期后的静默刷新，它先给出几条可能相关的记录。
第二步是 timeline。如果某条记录看起来有用，可以查看它前后的时间线。很多工程问题只看单条结论不够，必须知道当时是在什么版本、什么约束、什么失败路径下做出的判断。
第三步是 get_observations。只有确认需要细节时，才拉完整内容。这样既保留了历史深度，又不会把每次会话都拖成历史包袱。
长期记忆真正有价值的地方，不是记得多，而是能在合适的时候召回合适的内容。
实际收益
最直接的收益是跨会话续接。你昨天查到 OAuth 死循环和回调参数有关，今天新会话继续推进时，不必再从业务背景讲起。只要相关 observation 被召回，Claude 就能知道上次已经排除了哪些路径，下一步应该验证什么。
第二个收益是检索历史方案。很多问题会反复出现，比如 JWT 过期、Webhook 签名、分布式锁、Node 版本兼容、CI 偶发失败。以前这些经验散在聊天里，找不到就等于没有；现在可以通过 /mem-search 用自然语言翻历史，把个人踩坑记录变成可复用资产。
第三个收益是陌生项目冷启动。刚接手一个仓库时，README 可能过期，文档可能没人维护，原作者也未必有空解释。通过 /learn-codebase 让 Claude 对主要文件做一次结构化学习，后续再问登录链路、配置加载、测试入口，命中率会更高。它不能替代工程师读代码，但能缩短从完全陌生到可以提问的距离。
第四个收益是周报和复盘。很多周报写不出来，不是因为没做事，而是过程材料太散。/weekly-digests 或 /timeline-report 可以把一周里的排查、实现、取舍重新组织出来。它不应该替你编成果，但可以帮你找回过程证据，让周报从流水账变成有决策脉络的记录。
第五个收益是团队交接。一个人做了两周功能，真正难交接的往往不是代码在哪，而是为什么这里绕了一下、为什么这个方案被放弃、为什么这个依赖不能升。只要这些内容曾经在会话里被讨论并沉淀下来，新接手的人就有机会自助检索，而不是反复打扰原作者。
对测试团队来说，这些收益尤其具体。测试环境的特殊配置、压测脚本的设计背景、自动化用例里的历史兼容逻辑、某个质量问题的排查路径，很多都不是代码本身能完整表达的。claude-mem 的价值，就是把这些代码之外的工程上下文也纳入协作范围。
安装和配置
安装方式有几种，常见的是直接通过 npm 安装：
# 方式 1：npm 安装，适合多数本地试用场景
npx claude-mem install
# 方式 2：Claude Code 插件市场，适合已经使用插件市场的用户
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
# 方式 3：其他 IDE，按实际使用的客户端选择参数
npx claude-mem install --ide gemini-cli
npx claude-mem install --ide opencode
基础依赖可以按这张表理解：
| 依赖 | 说明 |
|---|---|
| Node.js 18+ | 必须 |
| Claude Code 最新版 | 需带 plugin 支持 |
| Bun 运行时 | 缺失会自动安装 |
| uv（Python 包管理器） | 向量检索需要，缺失会自动安装 |
| SQLite 3 | 随包发行，无需自行准备 |
配置文件默认在 ~/.claude-mem/settings.json。常见关注点包括 Worker 端口、数据目录、日志级别和 Context 注入设置。一般个人试用不需要一开始就改太多配置，先跑起来观察命中率，比在配置项上过早优化更重要。
如果安装后 hook 报 Cannot find module 'zod/v3'，常见原因是对应 plugin 缓存目录缺少 node_modules。在 macOS 和 Claude Code 沙箱环境下，可以参考这些处理思路：
# 1. 进入对应版本目录
cd ~/.claude/plugins/cache/thedotmack/claude-mem/<新版本号>/
# 2. 如果旁边有可用的旧版本，可直接软链复用依赖
ln -s ../<旧版本号>/node_modules node_modules
# 3. 没有旧版本参考时，再在能联通公网的环境下安装依赖
bun install
# 也可以用 npm，减少无关审计输出
npm install --no-audit --no-fund
这里不建议把某个修复步骤当成永久标准答案。插件版本、包管理器、企业网络、沙箱权限都会影响实际处理方式。更稳妥的判断是：先确认缺哪个依赖，再看能否复用旧版本依赖，最后才考虑重新安装。
使用注意事项
长期记忆不是越多越好，尤其在团队环境里，首先要处理好边界。
第一是敏感数据边界。claude-mem 默认会把会话中不少内容持久化到本地数据库，如果你在对话里粘贴了 Token、密码、客户数据、PII，而没有做隔离，它就可能进入记忆系统。涉及这类内容时，要么临时关闭 plugin，要么至少用 <private>...</private> 包裹敏感片段，让它不要被持久化。
第二是事实时效边界。工具安装方式、插件市场路径、云同步能力、默认端口、依赖版本，都可能随着产品迭代变化。文章里可以给出当前经验，但发布前最好再复核一次官方文档或当前版本表现，避免把过期经验写成确定结论。
第三是团队共享边界。当前更稳妥的理解是：claude-mem 首先是本地记忆系统。如果想多人共用一份记忆，需要额外考虑共享目录、权限隔离、并发写入和合规问题。这个方向可以探索，但不适合在没有验证的情况下直接全员推广。
第四是召回质量边界。记忆系统的表现取决于历史 observation 的质量。如果平时会话很碎、问题描述很模糊、结束时没有形成清晰结论，后续召回也不会神奇地变准确。它能放大工程过程中的好记录习惯，但不能凭空制造不存在的上下文。
团队落地路径
我不建议一上来全团队同时启用。更稳的方式是分阶段试点。
第一阶段，个人试点。选 1~2 个长期维护、敏感数据较少的仓库，连续使用一周。重点观察三件事：SessionStart 是否能召回有用历史，/mem-search 是否能找到过去方案，Stop hook 生成的 observation 是否有复用价值。
第二阶段，小组试点。选 3~5 人的小组，在同一个项目里使用。重点验证交接、复盘、周报和重复踩坑提醒。这个阶段不要只看新鲜感，要看它有没有减少重复沟通，有没有帮新人更快理解项目背景。
第三阶段，再考虑团队规范。至少要明确哪些仓库不能启用，敏感内容如何标记，API Token 成本由谁承担，历史记忆如何备份，出现误召回或污染记忆时谁来处理。没有这些规则，长期记忆很容易从提效工具变成新的治理负担。
如果只是个人使用，门槛没那么高。先把它装到一个自己长期维护的非敏感仓库里，观察一周，看看它是否真的减少了重复交代背景的时间。这比先写一大堆制度更实际。
总结
claude-mem 的使用心智可以浓缩成一句话：日常怎么用 Claude Code，就继续怎么用，项目记忆会在后台自动沉淀。
你需要显式调用的时刻并不多。想翻历史方案时，用 /mem-search；想整理项目过程时，用 /timeline-report；想生成周报时，用 /weekly-digests；第一次进入新仓库时，用 /learn-codebase 做一次初始扫描。其他时候，主要依赖 Hook 自动记录和自动召回。
它的核心价值不只是多了几个工具，而是让 AI 协作从一次性问答变成可累积的工程过程。每次调试、每次决策、每次踩坑，都有机会成为下次工作的上下文。对测试工程师来说，这意味着环境配置、排查路径、脚本设计背景和质量风险判断，不再只靠人脑和零散 Wiki 维持。
当 Claude 能自动记住项目，AI 编程工具才更像一个长期协作者，而不是每次都要重新培训的新同事。