我先说一个我特别有感触的场景你和 Claude Code 来回磨了一整个下午把一个老项目里那几个坑人的历史包袱翻了个底朝天连“为什么当初要这么设计”都能讲出一大段故事了。第二天早上打开终端接着昨天的思路继续它却一脸茫然地看着你问出那句你最不想听到的话“这个项目的背景是什么你能给我介绍一下吗”那一刻我是崩溃的。模型本身没有变笨但每次新会话都像重新招了个实习生你上周教过的所有东西它全忘了。后来我开始用 claude-mem 这个开源工具把 Claude Code 的跨会话记忆真正补上了今天就把这套东西的来龙去脉、配置方式和踩坑经验完整写出来。1. 每个新会话都是“失忆”的最让我崩溃的三个时刻1.1 昨天拍板的架构决策今天要重新吵一遍做技术的人应该都有这种经历项目里一个模块到底是走微服务还是继续在单体里拆包这种决策通常不是一次能聊完的。你得翻历史代码、对比依赖关系、评估团队成员的水平最后才能得出一个“现阶段不要拆分”的结论。这个结论只存在昨天那次会话的记录里。今天你新开一个会话让 Claude 帮忙重构代码它不知道你昨天已经做过权衡很可能会一本正经地建议你“拆分出独立的服务”。你如果没坚持住就带着它往错误方向走了几步浪费小半天才发现方向不对还得折回来。1.2 改到一半的手艺活上下文像沙子一样流走写代码这件事特别依赖上下文。比如你在调一个数据同步脚本关键信息包括源表有 2000 万行、目标库有唯一键冲突、历史数据里有脏数据需要单独清洗、公司规定晚上 10 点以后才能跑批任务。这些信息散落在好几轮对话里。窗口还够的时候Claude 表现得像个高手一旦上下文被长日志挤掉它就变回那个“重启过的实习生”开始问你已经回答过的问题。你要么反复粘贴旧信息要么被它带到逻辑混乱的沟里去。1.3 为什么“提示词模板”治标不治本有人会说把项目背景写进一个 PROJECT_BACKGROUND.md每次开新会话就让 Claude 先读一遍不就行了这个思路对但没有完全对。问题在于项目背景是动态变化的今天你发现了一个历史 bug 的根因明天你调整了目录结构后天你确定了新的接口规范。这些增量信息你很难每次都手动维护进文档。更现实的是你经常忘了这件事——忘了告诉它它自然就不知道。claude-mem 解决的核心问题就是让“增量记忆”自动化对话结束后自动归档新会话开始时自动召回。它不是给模型本身加脑子而是给每个新会话提前发一张“你曾经知道什么”的提示卡。2. claude-mem 的完整工作链路从捕获、压缩到检索注入2.1 整体架构捕获、压缩、存储、注入四层把 claude-mem 想成是一个“贴身秘书”在给你做三件事速记、归档、发提示卡。它的架构其实很清晰可以分成四层层级对应模块职责捕获层Hooks / MCP 监听记录会话里的用户输入、助手回复、工具调用结果处理层压缩与摘要把冗长对话压成结构化短句控制 token 成本存储层SQLite 向量索引保存摘要、原始片段、嵌入向量、时间戳、项目归属注入层MCP 工具 上下文组装新会话启动时检索相关记忆拼进 messages 前缀这四层各干各的活互不阻塞。捕获是实时的处理通常放后台异步跑存储只是个数据库读写注入则发生在每次会话开始的时候。这也是它设计上比较聪明的地方不让记忆过程拖慢正常对话。2.2 捕获阶段怎么把对话变成“可记忆事件”claude-mem 跟 Claude Code 的集成走的是 Hooks 和 MCPModel Context Protocol。简单说每次你发消息、每次 Claude 回复、每次工具被调用都会产生一个事件这些事件就是“可记忆的原始素材”。但要注意不是所有对话内容都值得进记忆库。我跟你说“帮我看看这个报错”这种一句话请求没有太多长期价值而“这个模块我们决定不再维护后续迁移到 XXX 服务”这种结论就值得沉淀。所以 claude-mem 通常不只靠自动捕获还提供手动标记机制——在对话里输入类似/remember的指令把当前讨论的重点显式保存下来。我个人的实操习惯是在项目大决策、配置改动、名词定义这种关键节点手动标记一下平时的小修小补靠自动摘要兜底就行。2.3 压缩阶段用低成本“摘要通道”控制 token如果每轮对话原文都存进来那数据库很快就会被淹没检索时也会浪费大量 token。claude-mem 的默认思路是两级结构第一级原始分片。最近的对话按块保存保留相对完整的表述。第二级会话摘要。会话结束后用一个更便宜的模型比如 Haiku 级别的轻量模型把整个会话压成几百字的摘要作为长期记忆的主体。这里最关键的是压缩率的把握。我见过一个极端例子一次会话来回聊了 3 万 token最后摘要只有 400 token压缩率接近 98%。400 token 足够写下“结论是什么”“为什么这么定”“涉及哪些文件”而那些中间讨论的过程细节绝大部分是不需要长期记住的。你可以在配置里设置摘要触发阈值比如会话 token 超过 8000 才做摘要低于这个数就直接存原文。这个阈值设太低了会让记忆碎片化设太高了会浪费存储和 token。我建议从 8000 开始跑两周再根据实际项目体量调整。2.4 存储与检索SQLite 时间线 向量语义双通道claude-mem 默认把记忆存在本地 SQLite 文件里同时给摘要内容做向量化以便按“语义相似度”检索。这就像你有一个笔记本SQLite 负责按时间翻页“上周五我记过什么”向量索引负责按意思找“我记得之前聊过关于缓存失效的事情”。两个通道各有用途实际检索时通常合并打分score 语义相似度 × 时间衰减系数时间衰减做的是一件很朴素的事越久远的记忆自动降权。一个 90 天前的决策和当前问题的语义相似度就算再高也不如昨天的对话重要。这个逻辑不复杂但直接影响记忆质量。后面我会专门讲怎么调这个衰减参数。3. 从安装到接入 Claude Code一套完整的配置路径3.1 安装和初始化先说明版本前提claude-mem 是 Python 写的需要 Python 3.10 以上。我自己用 uv 管理 Python 工具链安装很干净uv tool install claude-mem如果你习惯 pip直接装也行pip install claude-mem装完后做初始化claude-mem init这个命令会在用户目录下生成一个配置目录默认是~/.claude-mem/。里面最关键的是config.toml所有记忆行为都由它控制。另外可以跑一下自带的自检命令claude-mem doctor它会把配置、数据库连接、MCP 配置这些逐一检查告诉你哪里没通。我第一次跑的时候它提示 Python 环境里的路径没对上换到 uv 管理的环境就好了。小问题但确实省了不少排查时间。3.2 config.toml 里的关键字段配置文件的写法是 TOML不复杂。我放一份我目前在用的简化配置然后逐个讲为什么这么设[storage] backend sqlite path ~/.claude-mem/memory.db max_item_age_days 90 [compression] enabled true target_model claude-3-5-haiku max_tokens 800 summary_threshold_tokens 8000 [retrieval] top_k 8 min_similarity 0.3 time_decay_factor 0.7 [semantic] enabled true embedding_model text-embedding-3-small [mcp] name claude-memmax_item_age_days 90表示超过 90 天的记忆默认不检索。注意这和“删除”是两码事它只是让过期记忆退出检索范围库文件还在。假如你想做季度总结历史数据仍可以从数据库里捞。target_model是摘要用的轻量模型我的是 Haiku 级别。这个不要图省事不设置否则默认用主模型做摘要等于每次会话结束还要烧一波不便宜的 token。top_k 8是每次新会话最多注入几条记忆。不要贪多后面我会讲为什么记忆注入不是越多越好。min_similarity 0.3是一个经验值。低于这个相似度的记忆会被过滤掉避免注入一堆“看起来沾边但实际没用”的旧内容。阈值设太高比如 0.7你可能会发现什么都检索不到。3.3 接入 Claude Code 的两种方式claude-mem 要跟 Claude Code 联动核心是靠 MCP 协议把自己注册成 Claude Code 可发现的工具服务。我个人的做法是直接使用 Claude Code 的 MCP 命令添加claude mcp add claude-mem -- claude-mem不同版本可能参数有细微差异安装好后用claude mcp --help确认一下就好。添加成功后你会在 Claude Code 的会话里看到 claude-mem 的可调用工具列表包括检索记忆、保存记忆、检查统计这类能力。另一种方式是手动改~/.claude/settings.json在mcpServers里手动加一条效果是一样的。我建议大部分人选第一种命令一行搞定还省得出错。3.4 验证记忆链路真的跑通了配置完之后别急着干正事先做一次完整验证开一个会话跟 Claude 闲聊一句“项目里最常说的缩写是 X代表 Y 模块”。里面可以特意造一个项目里不常见的名词组合。用/remember或者 claude-mem 提供的记忆保存工具把这句闲聊显式存下来。退出会话重新开一个新会话问它“你还记得 X 是什么吗”如果它能正确答出“X 代表 Y 模块”说明捕获、存储、检索、注入整条链路都通了。这里有个小技巧测试时最好用“不常见名词组合”防止 Claude 靠常识蒙对答案。比如随便编一个符号ZK-Token第二天看它还能不能想起来。我用这个方案跑了一周以后最直观的感受是每次开新会话Claude 会主动带上“上次我们正在做什么”的提示而不是让我重新铺垫一遍。那种感觉有点像早上到工位旁边同事跟你打了个招呼说“昨天那事我继续跟进哈”——离谱地顺畅。4. 让记忆真正“好用”的四个关键策略4.1 记忆注入预算是第一原则Claude 的上下文窗口再大也是有限资源。你如果把最近 50 条记忆全塞进去虽然技术上可能放得下但预算全被背景信息吃掉了留给真正任务处理的 token 就少了回答质量反而下降。我自己的原则是注入的记忆总量控制在 2000~3000 token 以内条数控制在 5~10 条。这在 config.toml 里就是top_k和max_tokens两个参数的事。宁可少而精不要大而全。记忆系统就像给主持人递提词卡几张小卡片就够了而不是塞一整本《百科全书》上去。4.2 时间衰减与永久记忆的搭配时间衰减系数很值得细调。它的原理是把“记忆的年龄”作为检索打分时的一个权重因子。比如你设置衰减因子的半衰期是 14 天那么一条 14 天前的记忆它的相似度分数会打五折28 天前打二五折。但有些记忆不该衰减比如架构决策项、代码风格约定、团队成员的分工。这类“规则型”记忆应该被固定住。实操上我会把这类内容用/remember保存时加上固定标记如果有 pin 参数的话让它们始终在注入名单里。做个简单计算你就明白价值了假设一条记忆的向量相似度是 0.75如果没有任何衰减90 天后它照样会排在最前面如果有衰减90 天后的有效分可能只有 0.1直接被过滤。前者会让旧信息干扰新决策后者能保证记忆库永远“保鲜”。4.3 多项目隔离防止记忆“串味”这是我踩过最大的坑之一。我同时维护一个小工具项目和一个公司数据项目两个项目里都有“任务队列”“批量处理”这种词。最开始我没做隔离结果在数据项目里写代码时Claude 时不时把工具项目里的旧决策翻出来还一本正经地用在一个完全不相关的场景里。建议在 config.toml 或者启动参数里把项目维度分开比如不同目录用不同的记忆库。claude-mem 本身支持按项目维度存储和过滤你要做的是确认它确实按路径或项目名隔离了。验证方法很简单在项目 A 里存一条“A 项目的关键变量名是 alpha”切到项目 B 里问它“alpha 是什么”如果它能答出来说明隔离没生效赶紧查配置。4.4 定期体检记忆库清理、修正、导出记忆库不用每天管但建议每个月做一次体检看有没有明显错误或过时的记忆手动删掉或修正。看记忆条数增长速率判断压缩策略是否合理。把重要的架构决策记忆导出成一份项目文档作为团队共享的背景资料。我用一个很土的办法每个月把记忆库里的摘要按时间排序刷一遍花十分钟过目就像给电脑清垃圾文件一样。这些看起来不起眼的操作能有效避免记忆库成为“事实垃圾场”。5. 实测中的意外情况与排查链路5.1 症状一新会话什么都没有注入第一反应是先确认“记忆到底存进去了没有”。打开 SQLite 数据库统计一下表里有几条记录sqlite3 ~/.claude-mem/memory.db SELECT count(*) FROM memories;如果记录数是 0说明捕获层就没工作往上看集成配置。如果记录数是几百条但新会话的注入列表还是空的那问题就出在检索层最可能是这几种min_similarity设太高过滤掉了所有结果。当前工作目录跟记忆库里的项目路径对不上触发了隔离过滤。时间范围设太短比如只检索最近 7 天但你测试的记忆是 10 天前存的。排查顺序建议是先看记录数再看项目名再看时间范围最后调相似度阈值。5.2 症状二检索到的记忆“牛头不对马嘴”这个症状很隐蔽——记忆确实注入了但注入的是不相关的旧决策。Claude 看到这些背景信息后有时候还会把它们当作当前任务的上下文导致回答跑偏。处理思路是双管齐下降低top_k从 10 调到 5减少“凑数记忆”。提高min_similarity到 0.4~0.5过滤低相关的垃圾。另外我在会话里发现一个规律语义检索对“名词短语”的匹配远好于“长句废话”。所以我在手动/remember时会刻意用“对象 动作 结论”的短句格式来写比如“订单导出采用异步任务方案避免接口超时”“配置中心迁移到 Vault不再使用明文 properties”这种结构化短句向量化之后的区分度明显更高检索准确率也更好。5.3 症状三SQLite 文件一段时间后明显膨胀记忆库跑了一个月数据库文件从几百 KB 涨到了几百 MB这是正常的但不完全是正常“该有”的。主要原因有两个一是没开启摘要压缩大量的原始对话分片被原文保存二是 SQLite 在 WAL 模式下会留下大量 WAL 文件碎片。解决方法确认[compression]配置已经开启summary_threshold_tokens别设太高。数据库表对应的原始内容可以设置保留期限比如只保留最近 30 天的原文更早的内容只保留摘要。定期执行一次 VACUUM回收 SQLite 的碎片空间。实测下来一次 VACUUM 可以把几个月的库文件缩掉 40%~60%治标也治本。5.4 症状四中文项目记忆检索效果不佳如果你的项目文档和对话都是中文可能会遇到一个尴尬英文记忆检索挺准中文记忆动不动就查不到。这跟 embedding 模型对中文的支持程度、分词粒度都有关系。排查经验是这样的优先选对中文支持良好的 embedding 模型不要用纯英文优化的老模型。手动保存记忆时把关键词用尽量标准的中文术语写不要用口语长句。比如“用户在下单页点了提交但没走完支付流程”这种叙述型内容不如存成“下单页支付流程转化率问题卡在支付回调”。检索时也用短关键词问不要用一大段描述去匹配。我在配置里把语义检索的召回阈值调低了一点因为中文向量相似度的绝对值普遍比英文低一些。这个问题“没有银弹”核心是得多实测两轮看哪组配置在你的项目语言组合下表现最稳定。5.5 还有一招显式地“教它记住”任何时候你发现 Claude 忘了某件重要的事别硬扯别骂它。用/remember类的指令补一条记忆然后让它基于记忆继续即可。这个习惯养成了以后整套记忆系统会越用越准。6. 如果让我从零开始再做一遍其实我现在再回头看最重要的体会是记忆工具要解决的从来不是“存得越多越好”而是“在该出现的时候出现”。claude-mem 这个工具帮我把“记忆”变成了可管理、可检索、可过期的基础设施这一点比单纯的对话记录仪强很多。如果让我从零开始再搭一遍我会只做三步装好工具、调通 MCP 注册、设置一个保守的注入预算。剩下的交给时间和真实使用数据去校准不折腾不炫技。最后多说一句任何记忆系统都会有误判和遗漏它替代不了你自己对项目大局的把控。你仍然需要定期回到真实代码和文档里确认 Claude 的记忆没有“越想越偏”。工具只是把上下文成本降下来了真正的判断力还在你手里。