先说个我一直以来的感受给 Claude Code 这类 AI 编程工具写代码最折磨人的不是让它改 bug而是每次新开一个会话它就把上一轮聊的上下文忘得一干二净。上午刚讨论完模块划分下午新会话里问它“上次那个接口为什么这么设计”它一脸茫然。后来我找到了claude-mem这个开源项目才算是把“AI 失忆症”这个问题治住了。claude-mem本质上是一个给 Claude Code 用的记忆持久化工具它会自动把所有对话记录保存下来支持按项目、按时间、按关键词去语义检索还能在每次会话开始时自动把相关历史上下文注入进去同时帮你统计每条会话的 token 消耗。适合正在重度使用 Claude Code 做开发的人也适合那些在跨会话维护一个长期项目、反复需要“复盘”的开发者。这篇文章我把它的设计思路、核心机制、完整配置过程和踩过的坑都整理出来你可以直接照着抄作业。1. 为什么需要给 Claude 装上记忆1.1 会话割裂是 AI 辅助开发的真实痛点用过几天 Claude Code 的人应该都有这种体验单个会话内它很聪明代码改得又快又准但你一旦关闭终端、重新打开一个新会话它对你的项目几乎一无所知所有背景都要从头讲起。我参与维护的一个中型后端项目代码量不算大但因为业务复杂很多设计决策都散落在历史对话里。比如某个表为什么叫这个名、某个异步任务为什么用了消息队列而不是定时轮询这些当时都解释过。可一旦开新会话Claude 就全忘了于是你只能反复粘贴代码、反复解释背景甚至有时候它给出的建议会和上一次会话的处理方式冲突。这不是 Claude 本身能力不行而是会话上下文天然是隔离的。Claude Code 每个会话的初始 context 只包含项目文件、系统提示词和你手动补充的内容它看不到之前聊过什么。长时间、跨会话协作一多这种割裂感会变得非常明显。1.2 claude-mem 的定位不是聊天插件是记忆层claude-mem给自己的定位很简单它是 Claude Code 外挂的一层“长期记忆”。它不改变你日常工作流也不用你手动做任何操作所有对话都会被自动捕获、索引、存储在合适的时机自动注入回会话。我理解它的核心价值在于解决三个问题让新会话“想起”旧会话的关键信息不需要重复描述背景。支持按语义搜索历史对话不只是找关键词而是“模糊的、描述性的”回忆。统计 token 消耗并控制注入上下文的大小防止记忆注入太多把窗口撑爆。也就是说它不是简单的“日志记录”而是一个带检索和理解能力的记忆底座。这相当于给 Claude Code 装了一个“私人笔记本”它会自动帮你记、帮你找、帮你决定哪些内容该在当前对话里重提。2. 核心机制拆解记忆是怎么存下来、怎么找回的2.1 用 Hook 机制自动捕获每一次对话claude-mem最聪明的地方是没有自己改 Claude Code 的代码而是利用了 Claude Code 自带的Hook 机制。Claude Code 允许你在特定生命周期事件里挂载外部命令比如会话开始SessionStart、会话暂停SessionPause、会话恢复SessionResume有些版本叫 SessionStart等。claude-mem提供的 CLI 命令就是被这些 Hook 调用的。对话内容会被追加写入本地文件数据库则依赖SQLite做存储原始对话则落盘成 JSONL 文件。整个链路大概是这样的你正常使用 Claude Code 对话 → 每次对话更新触发 Hook → 新的消息文本被追加到会话记录文件 → 后台进程解析并写入 SQLite → 生成向量索引供后续检索。全程透明你甚至不会感觉到额外开销。这里值得多说一句的是Hook 的注入时机设计得很好。在 SessionStart 时做“记忆召回”是因为这时候新会话还没开始对话是注入历史上下文的黄金时间在 SessionPause 时做“写入保存”是因为会话结束或暂停时数据最完整不会丢失末尾对话。用自动化代替手动导出效率会高很多。2.2 语义检索原理从关键词匹配到向量召回claude-mem支持两种检索方式一种是传统的关键词/模糊检索还有一种是更高级的语义向量检索。关键词检索走的是 SQLite 里的查询速度快适合你记得原话或特殊标识符的场景比如搜一个函数名、一个报错信息。但它解决不了“模糊记忆”的问题你只记得当时聊过“怎么解决数据库连接泄漏”却想不起具体词汇这时候关键词检索就无能为力了。语义向量检索靠的是一种嵌入式文本表示。每次对话被存储时系统会把对话片段切成若干块每一块经过嵌入模型转换成一组高维向量embedding存储在本地。当你发起搜索时查询文本也会被转成向量然后计算它与历史所有片段的相似度把排名靠前的结果取回来。生活化类比一下关键词检索像在书架里根据书名找书你必须知道书名语义检索像跟图书管理员描述“我记得有一本书讲怎么修漏水的水管”管理员靠对内容的理解帮你把几本可能相关的都抱过来。对于跨会话知识召回后者显然更实用。2.3 token 统计与上下文窗口的控制逻辑记忆注入有个天然矛盾历史对话越多注入的上下文越大挤占了 Claude 处理当前任务的窗口空间。claude-mem通过 token 统计和截断机制来平衡这个矛盾。它在执行检索时会先估算每条候选记忆的 token 数量然后按排序从最相关开始逐条加入“待注入上下文”直到总 token 数接近你设定的上限默认值我印象里大约是 3000 或 4000。多出来的就不再注入宁可让 Claude 不知道也不能让它因为记忆把窗口塞满而“变笨”。这个设计思路很实在长期记忆不是越多越好而是在当前任务中最有用的那部分才值得注入。这里也涉及一个概念叫“上下文预算”——你给记忆分配多少 token给它多少预算它最多就只能给你挤出多少历史。后续会详细讲这个参数怎么调。3. 实操全流程把 claude-mem 跑起来3.1 安装与初始化claude-mem是 Node.js 编写的工具所以前提是你机器上得有 Node.js 和 npm或者 bun/deno 也行但 npm 最稳。我的安装环境是 macOS直接用 npm 全局安装npm install -g claude-mem安装完成后进入一个项目目录执行初始化claude-mem init这个命令会做几件事一是创建配置目录和 SQLite 数据库二是尝试在.claude下面配置 Hook三是测试嵌入模型是否可用。初始化过程会问你几个问题比如嵌入模型选什么默认选项我记得是基于本地的模型如果不可用它会提示你换成 API 模式。如果你只想在当前项目里启用就在项目根目录执行想全局启用则是执行类似claude-mem init --global这种参数。全局模式会把配置写到全局配置文件里一般放到~/.claude-mem/下。3.2 配置 Hook把记忆接到 Claude Code 里初始化完成后claude-mem会帮你更新 Claude Code 的 Hook 配置。如果你是在项目目录下初始化的配置文件就在.claude/settings.json里全局的话一般是~/.claude/settings.json。我手动查看过一次配置内容结构大致是这个样子{ hooks: { SessionStart: [ { matcher: , hooks: [ { type: command, command: claude-mem hook session-start } ] } ], SessionPause: [ { matcher: , hooks: [ { type: command, command: claude-mem hook session-pause } ] } ] } }Hook 的作用很像门口的地垫——每次 SessionStart 和 SessionPause 时Claude Code 会优先踩一下这块地垫执行里面的命令。SessionStart 时claude-mem会读取当前项目的记忆库做一次检索把相关上下文转化成一段文本注入到会话里而 SessionPause 时则负责把刚结束的对话写入记忆库。这里有一个很重要的细节如果你同时使用了其他修改 Claude Code Hook 的工具要注意配置的合并方式避免相互覆盖。我遇到过几次 Hook 配置被覆盖后claude-mem完全失效的情况后面会在避坑部分专门讲。3.3 日常使用与核心命令我实际用起来日常根本不需要关心它它会在后台自己跑。但有几个命令你还是要知道的# 手动查看当前项目的所有记忆 claude-mem view --project # 按关键词模糊搜索历史对话 claude-mem search 数据库连接泄漏 # 按时间范围过滤 claude-mem view --since 2024-01-01 --until 2024-02-01 # 查看 token 使用统计 claude-mem stats其中search是我用得最多的。你在新会话里想回顾旧内容时直接在命令行搜一下它会输出相关的对话摘要和片段不需要翻旧的终端记录。stats命令也很有用它可以按项目维度告诉你每个会话累积消耗了多少 token甚至可以按天统计。我拿它做过成本分析发现某些长期项目的 token 消耗比想象中高很多因为每次启动都会注入历史记忆虽然量不大但积累起来也是实实在在的开销。3.4 数据存储在哪里理解数据存储位置对于备份和排查问题很重要。默认情况下claude-mem的数据分成两块配置目录默认在~/.claude-mem/里面存放配置文件、全局数据库和日志。项目本地目录在每个启用claude-mem的项目下会生成.claude-mem/目录保存该项目专属的 JSONL 对话记录文件。实际存储路径可能会因为版本不同略有变化但大体上遵循这个规则。SQLite 数据库文件一般在配置目录下文件名类似mem.db或claude-mem.db。对话原文则以 JSONL 形式分散在各项目的.claude-mem/下每条记录包含时间戳、会话 ID、角色、消息文本等字段。如果你驱动开发时格外关注数据隐私这点就很友好所有数据默认都存在本地不上传任何云服务。嵌入请求是否走远端 API 取决于你选的嵌入模型如果选本地模型就是完全离线的。4. 配置参数与进阶玩法4.1 嵌入模型选型本地优先还是云 APIclaude-mem最关键的配置就是嵌入模型它直接决定语义搜索的质量和私密性。初始化时它会给几个选项本地嵌入模型我印象中默认基于 HuggingFace 的某个开源小模型比如all-MiniLM-L6-v2一类。好处是离线、隐私安全坏处是首次运行需要下载模型文件体积不小而且低配机器上语义检索速度会偏慢。云端 API 嵌入可选 OpenAI 或其他兼容 OpenAI 规范的嵌入接口。效果好、速度快但每一条对话片段都要发到云端你的对话数据相当于过了一遍第三方接口隐私性要自己评估。我个人的经验是项目代码里没有机密、追求开箱即用体验的话直接选云端 API 最省心如果处理的是客户敏感代码或私人笔记老老实实本地模型慢一点我也认了。如果你初始化之后后悔了可以直接改配置文件里embedding.model和embedding.provider这两个字段然后重新执行一次索引重建如果工具支持的话。改完记得重启 Claude Code 会话让新模型生效。4.2 token 相关的关键参数claude-mem的配置里和 token 强相关的参数主要有这几个我挨个说下我的调法参数名作用我常用的建议值memory.injectActualContext决定是否将实际检索到的记忆文本注入会话truemaxContextTokenLimit单次会话最多注入多少 token 的记忆20004000embedding.maxTokens单个文本块最多按多少 token 做向量化500history.skeletonTokenLimit会话历史摘要的 token 上限800maxContextTokenLimit是最重要的一个参数。设太高注入的记忆多、但 Claude 的注意力被稀释设太低很多关键记忆根本塞不进来。我长期项目上一般设 3000 左右短平快的项目 1500 就够。这里有个隐性逻辑每次注入不是只注入一条记忆而是会按相似度排序后把一组记忆拼在一起。参数相当于给这组记忆的总量设了天花板。被截断掉的低优先级记忆不会浪费它们仍然留在数据库里只是这次“不提醒”。4.3 按项目粒度隔离记忆claude-mem默认按项目目录隔离记忆也就是说你在 A 项目里聊的B 项目搜不到。这个设计我特别认可因为多项目同时铺开时如果记忆互相污染那才是灾难。隔离的实现方式不复杂就是为每个项目建立独立的语义数据和独立的 JSONL 文件。但要注意Hook 注入发生在会话启动时claude-mem会根据当前工作目录判断项目身份所以你的会话必须是在该项目目录下启动的才能正确匹配记忆。有个坑如果你用cd /path/to/project启动会话是正常的但如果你用类似claude-code /path/to/project这种带参数的方式启动当前工作目录可能不是你预期的地方记忆检索会匹配错库。解决办法是进入目录再启动或者用工具提供的--project参数手动指定。4.4 数据备份、迁移与跨机器使用换电脑或者重装系统的时候把记忆库迁移走会省不少事。你需要备份的就两块全局配置目录~/.claude-mem/和项目下的.claude-mem/目录。我试过直接把整个~/.claude-mem打包拷到新机器在新机器上重新跑一遍claude-mem init再覆盖回数据目录大部分记录都能恢复。但有一点麻烦embedding 模型如果换了比如旧机器用的 OpenAI新机器默认走了本地模型历史向量的维度可能对不上语义检索会失效。解决思路是要么保留和旧机器一致的嵌入模型配置要么迁移后执行一次全量重建索引。虽然重建会花时间但至少不用重新积攒历史。跨机器使用我目前的经验是Git 同步 JSONL 原始对话文件是可行的但向量数据不建议通过 Git 管理二进制大文件很容易冲突不如机器本地重建来得干净。5. 常见问题与避坑实录5.1 初始化时嵌入测试失败初始化claude-mem init的时候最常见的问题是本机没有安装可用的嵌入模型依赖。它会尝试加载某个本地模型如果你的网络环境访问不了 HuggingFace下载就会失败然后初始化过程直接中断。我当时的解决方法是初始化时配置选用云端 API 的嵌入方案。如果你早期选的是本地也可以在配置里改一下改成兼容 OpenAI 接口的地址把 API key 填进去测试就通过了。低配机器上我更推荐直接走 API别难为自己。5.2 Hook 不生效检查配置覆盖Hook 不生效是使用过程中最隐蔽的问题。我自己就遇到过设置里明明有claude-mem hook session-start但每次新开会话就是没有记忆注入。排查思路按顺序走先看 Claude Code 是否真的加载了这个设置文件再看是不是有其他工具比如我同时装了自动 commit 的插件覆盖了 Hook 数组最后可以手动在终端执行一遍claude-mem hook session-start如果手动执行正常问题就出在 Hook 配置本身。另一个容易忽略的点是路径问题。如果你的claude-mem是 npm 全局安装在 Hook 执行的 shell 环境里可能没有把 npm 的全局 bin 目录加进 PATH导致命令根本找不到。解决方法是写完配置后在终端执行claude-mem hook session-start确认命令本身可以直接跑通。5.3 注入太多记忆反而拖累生成质量我在使用中发现一个现象当你把maxContextTokenLimit调到非常大比如 8000 以上Claude 生成的代码质量反而下降。原因在于注入的记忆里混入了大量低价值的日常对话比如“这个函数有没有测过”这类过程性对话它们占据了注意力窗口把真正关键的架构决策挤压掉了。建议定期清理无价值的记忆。claude-mem我不知道是否有自动清理命令但你完全可以删掉 JSONL 文件里的低频噪声会话或者按时间范围把过老的、已归档的会话从库里删掉。我的策略是一个项目结束后立刻导出总结然后把旧会话清空保持库的简洁。5.4 存储膨胀与隐私边界长时间使用后.claude-mem目录会越来越大。JSONL 文件每秒追加SQLite 里还有向量数据。我见过一个跑了两个月的项目记忆目录接近 1GB。这种情况不用慌它不会影响正常使用只是备份起来吃力。你想瘦身的话可以清理掉那些明显无价值的会话记录或者只保留每条的摘要而不是全文。另外如果你在对话里输入了 API key、密码这类敏感信息它们会原样存进 JSONL重要项目我还是建议定期人工检查一下记忆库或者干脆只在非敏感代码仓库里启用自动记忆。6. 最后说两句真实体会claude-mem不是那种装上就能让 Claude 变聪明的神器它解决的是“连续性”的问题。它无法让 Claude 凭空理解你没聊过的东西但能让它记得你聊过的东西这个价值在长周期项目里尤其明显。用了大概两个月后我最大的感受是新会话里解释背景的次数少了很多Claude 给出的方案和之前讨论过的方向也能保持一致了。有一点我想强调依赖工具的同时别丢掉自己的判断力。记忆库里的内容本质上是原文快照如果当时讨论的思路本身是错的下次注入时它也不会自动纠错。所以该 review 还是要 reviewclaude-mem能帮你少解释几次但改不了的 bug、绕不开的架构债还是得你自己上。如果你也在用 Claude Code 做长期项目建议先小范围试用挑一个不那么敏感的项目跑上几天看看注入的上下文质量是否符合预期再决定要不要全面铺开。工具这东西只有自己实测过才知道适不适合。