用过 Claude Code 的朋友应该都有过这种体验昨天刚和 AI 对齐过的技术债清单今天新开一个会话它完全不记得上礼拜定下来的命名规范这周换了个窗口它就当没这回事。我最早以为这是模型能力问题后来才意识到症结在于 Claude Code 默认是无状态的——每个会话都是一张白纸。claude-mem 这个开源项目解决的就是这件事它给 Claude Code 装上了一套长期记忆自动把会话里的偏好、决策、项目知识抽出来存好下次开工前再自动注入回对话里。如果你已经用 Claude Code 写代码超过两周或者正在为AI 老忘事而头疼这篇文章值得你花十分钟看完。1. 先从痛点说起为什么 Claude Code 总是金鱼记忆1.1 无状态会话带来的重复劳动Claude Code 本质上是一个跑在终端里的智能体它每收到你的一句话都会基于当前上下文窗口里的内容做推理。这个上下文窗口就是它的工作记忆当前打开的代码、你刚发的消息、它自己的历史输出都在这里。问题是一旦新开一个会话或者隔了一段时间再回来上下文窗口就被清空了它对你的项目一无所知。我用一个实际场景说明白这件事。我之前维护一个内部工具仓库代码里有几条约定错误处理统一走pkg/errors自定义类型不用标准库的errors.New接口命名一律带Service后缀测试文件必须和源文件放同一个目录。这些约定我第一天就跟 Claude Code 说清楚了它也执行得很好。但第二天新开会话我又得重新把这些说一遍。如果是连续几天都在改同一个仓库等于每天都在给 AI 做岗前培训。你会说可以用 CLAUDE.md 把这些约定写进项目文档里啊。对静态规则确实能用这个方案解决但这里面有两个坎。第一CLAUDE.md 需要你手动维护今天临时决定这个模块我们不用 interface 了你很难记得去同步更新文档第二很多信息根本不适合写进静态文档比如昨天查出来线上超时是数据库连接池太小暂时把 MaxOpenConns 调到了 50等下周再加压测试这种动态决策记在文档里很快就过时了但不告诉 AI它可能又给你分析出完全过时的结论。1.2 从问一次答一次到有记忆的助手claude-mem 的思路其实不复杂既然 Claude Code 每次会话都会把对话记录写到本地日志里那我能不能解析这些日志把其中有长期价值的信息提取出来存到一个本地数据库里下次启动新会话前再把和当前项目相关的记忆自动捞出来塞给 Claude Code 当背景信息。这样 AI 就不是从零开始而是带着它亲眼见证过的项目历史来工作。这个思路听起来平淡但实现起来有几个很微妙的地方。第一不是所有对话内容都值得记住帮我看一下这个报错这种临时问答记下来纯粹是噪音第二记忆之间会有冲突你今天说用重构方案 A明天又推翻说改用方案 B注入的时候到底听哪个第三注入的记忆不能太多上下文窗口是宝贵的塞一千条记忆进去只会把模型淹死。claude-mem 在处理这些问题上的取舍我觉得是它最值得学习的地方后面我会逐个展开。1.3 它到底适合什么人用不是所有用 Claude Code 的人都需要 claude-mem。如果你是随手拿 AI 写个一次性脚本会话开完即弃那这套东西纯属多余。但如果你符合下面任何一条我觉得值得试试长期维护一个项目仓库每周至少有三天在同一个代码库里和 AI 协作经常需要切换分支、切换任务隔几天才回来改某个模块希望 AI 记得上次的进度和结论团队里多人共用一台开发机或同一套环境希望 AI 的记忆力不随会话结束而消失已经用 CLAUDE.md 管理静态规范但觉得动态决策、踩坑记录、阶段性结论没地方放。我自己属于第二和第四种的结合体。用下来最直观的感受是新会话打开后Claude Code 不再问我这个项目的错误处理规范是什么而是直接按之前的约定来写代码偶尔还会主动提醒我你上次说这个模块要等重构完再改现在要不要先处理那个横向越权的问题。这种连贯性是纯粹靠提示词工程给不出来的。2. claude-mem 的工作原理记忆从哪来、存到哪、怎么用2.1 数据来源读懂 Claude Code 的会话日志Claude Code 有一个很老实的习惯它把所有会话内容都以 JSONL 格式存在本地在~/.claude/projects/目录下。每个项目对应一个以项目路径哈希命名的子目录里面是时间戳加 UUID 命名的.jsonl文件每一行是一个事件包含用户消息、助手回复、工具调用、工具结果、系统事件等。这些日志本来是用来给用户回放会话、排查问题用的claude-mem 把它当成了记忆的原材料。我手动打开过一个.jsonl文件看过结构大概是这样的思路每一行都有一个type字段标明事件类型用户消息里带的是你真正输入的内容助手回复里除了文本还有它的思考过程摘要工具调用事件里则记录了它执行过哪些命令、读取过哪些文件、改动过哪些代码。把这些事件按时间顺序串起来基本就能还原出整个协作过程。claude-mem 做的第一步就是持续监听这个目录发现新的.jsonl文件或者文件有新写入时就进入提取流程。这里有个细节值得说它不能简单把整个文件读一遍就完事因为日志文件是追加写入的你得记录上次读到了第几行增量处理。否则每次处理全量文件项目大了之后性能会很差。我自己看它的行为是初次启动时会有一个全量扫描之后只关心增量部分这个设计在日志量大的项目里很关键。2.2 提取逻辑什么样的信息值得被记住从一堆对话事件里筛出值得记住的信息这是整个项目最见功夫的地方。纯靠正则匹配关键词肯定不行因为同样一句这里不要用指针值传递就够了在不同的上下文里可能意味着一个重大决策也可能只是一次随口建议。claude-mem 的做法我理解下来是组合了几条策略特征信号匹配捕捉一些明显带有决策感的表达比如以后我们都……这个方案不行换成……记住……原因是……这类句式同时关注工具调用结果里的代码变更摘要、文件写入路径、命令执行输出因为这些事件本身就代表项目状态发生了改变。交互结构分析用户在对话里追问、纠正 AI 的次数是重要信号。当用户明确说你不要这么写应该那样写时这往往意味着一个偏好被建立起来了当 AI 给出某个方案后用户接受并继续执行时说明这个方案至少在当时是有效的。时间衰减与去重短期内反复出现的主题会被聚合成一条记忆而不是每次出现都记一条。比如连续三次提到数据库连接池问题系统会把它们合并成一条关于连接池的演进记录而不是让三条碎片记忆同时存在。提取之后记忆会被打上类型标签。我实际用下来看到的常见分类大致有用户偏好代码风格、命名规则、技术选型倾向、项目知识架构约定、模块职责、依赖关系、决策记录为什么选 A 不选 B、工作流步骤这个项目的发布流程、测试方法、踩坑记录某个错误的原因和解决方式。这个分类非常重要因为不同类型的记忆在注入时有不同的优先级。比如用户偏好是长期有效的几乎每次都要带上踩坑记录只在遇到同类问题时才需要出现平时没必要占上下文。2.3 存储与检索为什么选 SQLite 加全文索引提取出来的记忆需要一个地方放。claude-mem 选择的是嵌入式 SQLite 数据库每台机器上独立一份不需要部署任何服务。这个选择在我看来非常务实。你要是让用户为了一套记忆功能去装 Elasticsearch 或者维护一个 Postgres那这个项目基本就没人用了。SQLite 单文件、零配置、跨平台、支持事务天然适合这种一人一机一库的场景。更重要的是SQLite 自带的 FTS5 扩展提供了全文检索能力。记忆这东西不像数据库里的订单记录那样靠精确匹配你问的是我们之前有没有讨论过错误处理但记忆里存的是用 pkg/errors 类型统一包装错误避免标准库 errors 引起的堆栈信息丢失。这俩没有共同关键词纯靠 SQL 的 LIKE 查询一点戏都没有。FTS5 能把文本切分成词项并建索引支持前缀查询、短语查询、BM25 相关度排序。claude-mem 在注入上下文前会把当前任务的关键词拼成全文检索条件取出相关度最高的若干条记忆再通过重排逻辑决定最终注入哪些。这里顺带提一个我遇到的坑FTS5 默认的分词器对英文友好但直接处理中文内容时会按单字切分导致检索效果很差。我的项目里有大量中文注释和中文对话刚开始注入出来的记忆经常是这不是我要问的。后来我给记忆表换成了带 trigram tokenizer 的配置或者在做全文索引前先对内容做预处理检索质量才明显改善。这个点我在后面排查清单里会再说一次如果你也是以中文协作为主请务必留意。2.4 注入机制记忆是怎么回到对话里的存进去的记忆如果永远躺在那那就只是个归档工具不是记忆力。claude-mem 提供了两条注入路径。第一条是非 MCP 模式也是我主力使用的方式。在 Claude Code 的配置里注册一个 SessionStart 钩子这个钩子会在每个新会话开始时执行一个命令。claude-mem 对应的命令会做两件事识别当前项目目录从数据库里检索出与该项目相关的记忆生成一段结构化文本作为初始上下文写入新会话。效果上就像你在新会话开头自己粘贴了一段项目背景简介只不过这段背景是自动生成的、且基于真实历史会话提炼的。第二条是 MCP 模式。现在的 Claude 客户端普遍支持 MCPModel Context Protocol它以标准化的方式给模型提供外部工具和上下文。claude-mem 可以作为 MCP 服务器运行让 Claude Code 在对话过程中按需主动查询记忆而不是只在会话开始时被动接收。这两种模式的取舍很清楚SessionStart 注入零延迟、但记忆固定在会话开头MCP 查询更灵活、可以针对当前讨论动态检索但会多一次工具调用往返而且需要你把模式切换配置好。我自己的习惯是日常开发用 SessionStart 注入兜底遇到复杂问题需要翻历史讨论时再切到 MCP 模式手动问一句关于 X 我们之前讨论过什么。3. 实战部署把 claude-mem 接入你的 Claude Code3.1 安装与初始化claude-mem 是命令行工具安装方式取决于你所在的平台。官方仓库的 README 里给了常见的安装入口我在 macOS 上用的方式是直接下载对应架构的预编译二进制放到$PATH下Linux 服务器上我用的是源码编译方式。如果你本地同时有 Go 工具链直接编译安装也很快。装完第一步是确认命令可用claude-mem --version能正常输出版本号说明二进制没问题。接下来是初始化。claude-mem 会默认把数据库存在用户主目录下的.claude-mem目录里你不需要手动建库第一次运行它就会自动创建。初始化过程中它会扫描~/.claude/projects/目录里已有的会话日志这时候程序会跑一小会儿因为要在存量日志里做全量提取。我建议你第一次初始化时选一个工作量不大、会话记录不算海量的项目试跑等流程走通了再放开到全部项目。直接对着一堆历史仓库做全量提取耗时可以接受但中间如果发现某些项目根本不需要记忆后面清理反而麻烦。初始化的日志输出中间可以看到它对每个项目路径的识别情况。我遇到过一种情况是同一台机器上旧版本 Claude Code 和新版本的项目目录哈希规则不一样导致 claude-mem 把同一个仓库当成了两个独立项目。后面我发现可以手动在配置里指定项目目录的映射关系把新旧哈希指向同一个项目名来合并记忆这个操作对重装过机器或者升级过客户端的朋友尤其有用。3.2 配置核心参数记忆阈值、注入条数与过滤规则claude-mem 的默认配置是开箱即用的但想让它贴合自己的工作习惯有几个参数值得认真调。我挑几个我觉得影响最大的说。注入条数上限这是最重要的一条。SessionStart 注入记忆时如果检索出的相关条目太多全部塞进去会占用大量上下文窗口甚至可能淹没用户真正要传达的指令。我一开始图省事把上限调到了 50结果 Claude Code 在开场白阶段就开始长篇大论复述旧话题正经工作反而被耽误了。后来我控制在 8 到 12 条左右效果最平衡。相关度阈值全文检索会按 BM25 算出每条记忆和当前任务的匹配度低于阈值的不注入。阈值太低会放进来一堆弱相关的记忆收益率很低阈值太高则可能一条都匹配不上记忆功能形同虚设。我的经验是先用默认值跑两周观察注入内容里有多少条是真正有用的再针对性上调或下调。忽略规则某些目录、某些关键词开头的记忆可能你根本不想让它进库。比如临时写的一些验证脚本、包含密钥的测试命令还有你明确不想被 AI 记住的敏感讨论。claude-mem 支持配置忽略规则从源头过滤掉这些内容比事后删库要靠谱得多。这里我特别想强调敏感信息的问题。Claude Code 会话日志里可能会出现过 API Key、数据库密码、内网地址这些内容。claude-mem 提取记忆时不会智能判读它是否敏感只要语义上值得记它就照单全收。所以我强烈建议你在正式使用前先去看一眼提取后的记忆里有没有混入凭据类信息该加忽略规则加忽略规则该清理清理。本地存储这一点上它做得好不会把数据传出去但自己机器上的数据泄露风险依然要靠配置来挡。3.3 注册 SessionStart 钩子让记忆自动注入要让记忆在每次新会话开始时自动出现需要给 Claude Code 配置一个钩子。Claude Code 的配置系统支持在不同层级覆盖设置全局配置在用户主目录下项目级配置在仓库目录下。claude-mem 的做法是修改全局配置因为记忆功能应该对所有项目都生效。我当时是在终端里直接执行配置命令把 SessionStart 事件指向了 claude-mem 提供的上下文输出命令。命令格式大概是这样的逻辑claude config set -g hooks.SessionStart {hooks: [{type: command, command: claude-mem-context}]}配置完成后重新打开 Claude Code 会话当你看到新会话的开头出现一段以下是本项目的相关历史记忆之类的系统注入内容就说明钩子生效了。这里有个容易踩的坑钩子的执行环境可能不继承你终端里$PATH的完整配置claude-mem-context命令如果没装到系统级路径下钩子会静默失败表现为记不住东西但你找不到报错。排查方法很简单先手动在终端里跑一下claude-mem-context看它能不能正常输出记忆文本能输出说明命令本身没问题再去查钩子的环境变量配置。3.4 手动干预用 CLI 查看、检索和修正记忆自动化的东西总会出错所以 claude-mem 也提供了一套手动操作命令。最常用的是查看某条记忆的原文来源因为记忆是提炼过的产物有时候你会看到一条结论正确但没头没尾的记录比如用户认为这个模块应该重写但不知道它是针对哪个文件说的。逐条溯源到原始会话日志能帮你确认这条记忆是不是可靠。我每周都会花几分钟做一次记忆体检打开终端的 TUI 界面按项目筛选记忆列表删掉一些已经过时的决策记录修正一些分类错误的条目。这个维护成本不高但收益很明显。记忆库就像人的长期记忆一样如果里面存了大量错误结论、过期信息后续注入的上下文质量就会直线下降。定期清理看似麻烦其实是保证整个系统长期可用的关键动作。还有一个进阶用法是手动追加记忆。比如你在线下会议里和同事讨论定了一个技术方案这个方案并不会出现在 Claude Code 的会话日志里但你想让它之后变成 AI 的参考背景。这时可以手动写入一条记忆把方案要点存进去。这样一来AI 能知道的东西就不仅限于它和你对话时发生的事了而是可以覆盖到整个项目的运行脉络里。4. 实际场景里的效果与边界哪些问题真被解决了哪些还要补位4.1 场景一跨会话回到旧模块不再需要考古式提问我最典型的场景是改一个两周没碰过的模块。以前的做法是先把相关文件打开在对话里贴一段代码然后从头跟 AI 解释这个模块的现状和遗留问题。这个过程往往要花十几分钟而且解释得还不一定完整经常发生我漏掉一个重要背景导致 AI 给出方向性错误建议的情况。接上 claude-mem 之后这个场景变成了打开会话直接问问题。Claude Code 开局就带着这个模块相关的历史记忆包括我之前改过哪些逻辑、踩过哪个坑、下一步的计划是什么。它会直接接上上次的思路往下聊甚至主动提起你之前提到这个函数的并发问题还没处理现在要先看那个吗。这种连续性带来的效率提升不是省了五分钟描述问题那么简单而是 AI 的输出从一开始就建立在正确上下文上方向性错误明显变少。4.2 场景二CLAUDE.md 管静态规范claude-mem 管动态决策CLAUDE.md 和 claude-mem 不是替代关系而是互补关系这个定位我觉得特别重要。CLAUDE.md 适合放那些长期稳定、不会频繁变化的内容项目简介、目录结构、代码风格、命令用法。这些都是项目身份的一部分应该由人来显式定义不应该让 AI 从会话里归纳。原因很简单归纳出来的规则有概率出错而项目规范类的东西错一次影响面就很大。claude-mem 适合放的则是不断演进的动态信息。比如今天调试发现的性能瓶颈、上周确认放弃的技术方案、当前正在推进的重构方向。这些信息过两周可能就失效了但它们对当下工作的指导意义非常大。让 AI 从对话历史里自动提取这些信息时效性和颗粒度都远好过人手维护文档。我在项目里试行了一个分工CLAUDE.md 里只写不会轻易改变的约定每次要改都得走评审claude-mem 里则什么都不限制让 AI 尽量多记动态信息。这个搭配用了一个多月没有出现记忆污染静态规范的情况反而因为动态信息有了去处CLAUDE.md 的改动频率大大降低了。4.3 边界在哪里别指望它替代代码注释和文档claude-mem 也不是万能的有些场景它帮不上忙甚至会造成干扰。我见过有人把希望寄托在它身上指望 AI记住所有代码逻辑然后就可以少写注释少写文档了。这是很大的误解。记忆记录的是你和 AI 之间的交互结论不是代码本身的完整状态。如果代码后来被修改了记忆不会自动跟着更新除非你在新会话里明确告诉 AI这个模块已经重构了。它本质上是一个高层对话背景替代不了代码库本身作为最权威信息来源的位置。另外跨项目的记忆边界要高亮出来。claude-mem 按项目目录隔离记忆意味着 A 项目的技术决策不会注入到 B 项目的会话里。这个设计是对的否则个人偏好和工作项目的信息会混在一起。但如果你有两个仓库其实属于同一套系统架构互相之间有强技术关联那你可能需要考虑给它们配置成共享记忆或者手动在一方的记忆库里补充另一方的关键结论。4.4 团队协作时的注意事项claude-mem 目前在我看来更偏向单人开发的工具。团队协作场景下每个人的记忆库都在自己机器上你在这里积累的对话记忆队友那边完全没有。如果两个人先后在同一个仓库上让 AI 干活AI 只会记得当前操作者经历过的事。这不是 claude-mem 独有的缺陷Claude Code 本身的多会话、多人协作就是同一个问题。不过它也不是完全没有团队价值。在一些小团队里大家共用一台开发服务器、共用同一个系统账号操作同一个代码目录这种情况下会话日志是共享的claude-mem 就能自然覆盖到不同人的会话历史相当于团队共享记忆。要是大家各自用笔记本就想办法把记忆数据库文件定期同步或者约定只共享项目级的核心决策记录。这一块官方设计上没有给太强的一致性保障我更倾向于把它定位成个人效率工具团队协作还是以文档和代码评审为主记忆库当辅助参考就行。5. 我踩过的坑与排查清单从失效到好用的调整记录5.1 新会话开头没有自动注入记忆这是最常见的现象我也被坑过一次。装完 claude-mem配置好钩子满心期待地打开新会话结果开头干干净净一条记忆都没有。排查路径我理顺一下先手动执行claude-mem-context如果命令能输出内容说明数据库和检索没问题如果提示找不到项目或匹配不到记忆可能是项目目录映射不对如果命令报 command not found那就是$PATH问题。其中最隐蔽的是钩子环境变量问题。Claude Code 的钩子很多时候不会走你 shell 配置文件里加的路径导致它在跑命令时找不到 claude-mem 的二进制。解决方案很直接把 claude-mem 的安装路径用绝对路径写进钩子配置或者做一个软链接放到/usr/local/bin这类系统目录下。改完再验证一次基本就能恢复。5.2 注入的记忆相关度低甚至完全不该出现这里我调整过两轮程序方面的配置弯曲过一条弯路。第一轮问题出在阈值设置上我把相关度阈值调得太低导致 FTS5 检索出来的记忆什么都有注入的内容和当前任务只有弱关联。第二轮问题我定位到的是中文分词问题。我项目里有大量中文注释和中文对话默认 tokenizer 把中文句子拆成了单个字检索连接池变成了检索连接池三个字返回的结果自然毫无意义。最后我做的调整是给记忆表启用更适合中文的分词配置同时在写入记忆前对一些高频中文术语做了归一化处理比如统一连接池数据库连接池db 连接池为同一主题。这一套组合下来中文场景的检索质量才真正对得起全文索引这个功能名。如果你也以中文协作为主建议把这块当成标配配置来做别等检索效果差到忍不了才回头改。5.3 记忆库膨胀后性能下降用了大概一个月后我注意到claude-mem-context的运行时间变长了从原先的一秒以内涨到了几十秒级别。看下来问题出在两个地方。一是数据库里积累了海量历史会话的提取结果但其中大量记忆已经过时永远不可能再被检索命中可它们的索引还在二是 SessionStart 每次都要跑一次全量扫描来确认有哪些新增日志项目会话文件多了以后这个扫描本身也是有开销的。解决思路分几步。首先是把关跑在定期清理上删掉三个月以上未命中的记忆条目把超过一定会话数的最早记录折叠成摘要。其次是给监听机制做增量标记避免每次扫描全量大目录。这些功能有些是 claude-mem 自带的管理命令有些需要自己配合脚本做。做完一轮清理后命令运行时间重新降回秒级也说明这类工具长期用下来主要的维护成本确实在数据卫生上。5.4 常见问题速查表我把这段时间遇到的高频问题整理成一个表方便以后快速定位症状可能原因处理方式新会话无记忆注入钩子未配置或命令找不到手动跑 claude-mem-context检查 PATH 配置注入内容与当前任务无关相关度阈值过低调高阈值并检查 FTS5 分词配置中文检索效果极差默认 tokenizer 不适合中文换成支持中文的分词方式做术语归一化记忆库越来越大、命令变慢过期记忆堆积、全量扫描定期清理未命中条目配置增量监听同一个仓库被识别成两个项目客户端升级导致目录哈希变化手动映射新旧项目目录为同一项目敏感信息被记录缺少忽略规则和过滤配置忽略规则定期人工检查记忆库5.5 关于日常维护我现在的固定流程说到底claude-mem 不是装上就不管的东西。我现在养成了两个习惯。第一个是每周看一次记忆列表删掉明显过时的条目修正分类错误的记录就像整理自己的笔记第二个是每次要开始一个相对重要的新任务前先手动过一遍即将注入的记忆有哪些确保 AI 开局拿到的背景是准确的。这个操作只需要半分钟但能让后续整个会话顺畅很多。另外一个小技巧是当我觉得某条记忆特别重要时我会手动给它在分类里打上高优先级标签确保它在注入时的排序里永远排在前排。虽然大部分情况下自动相关度排序够用但关键项目决策和敏感的技术约束值得人为加一层保障。写在最后的个人体会claude-mem 给我的最大启发是AI 工具真正走向好用靠的不只是模型本身变强还有一层容易被忽略的工作就是协助它维护长期上下文。你不能指望 LLM 每次会话都从零开始学习你的项目就像你不能指望一个新同事不看任何交接文档就接起你的工作。给 Claude Code 装上记忆库本质上是把交接文档这个环节自动化了。我自己在从零配置到日常维护的整个过程中最大的感受是它的默认配置够用但离贴合个人工作流还有一段距离那段距离需要你根据自己的项目形态、语言习惯和敏感边界去补齐。如果你正在被 AI 的失忆困扰花一个下午把它跑起来再花两周慢慢调教大概率会觉得这笔投入是这两年最值的效率投资。