★ FEATURED ARTICLE 1. 项目概述claude-mem 到底解决的是什么问题先说结论claude-mem 是一个给 Claude Code 补上“长期记忆”的轻量方案它的核心思路是把每次会话里的关键信息抽出来存进本地数据库下次开新会话的时候再自动带回来。如果你用过 Claude Code 做过稍长一点的开发任务一定遇到过这种情况上一次会话里已经查清楚的技术决策、项目约束、文件位置隔一天新开会话就全忘了又得重新解释一遍甚至得把上一轮对话翻出来人工复制粘贴。我用了一个月之后最大的感受是它不是在“记录对话”而是在“沉淀项目上下文”。这个工具适合谁首先是重度使用 Claude Code 做日常开发的工程师尤其是同时维护多个项目、经常在不同任务之间来回切换的人。其次是团队里负责技术基建、想把 AI 编程助手的产出沉淀成团队资产的开发者。至于只用 Claude Code 偶尔写个脚本、改个 bug 的朋友它的价值没那么明显——但一旦你开始在一个项目里连续工作一周以上你就会发现有个长期记忆层和没有是完全两种体验。它的具体实现并不神秘Claude Code 本身支持 MCPModel Context Protocol扩展能力claude-mem 就是作为一个 MCP 服务运行在你本机监听每一轮对话把其中符合“值得记住”标准的信息提取出来经过 embedding 向量化之后写入 SQLite 向量索引。之后你会话中如果提到相关内容它再把匹配到的记忆作为上下文注入回去。简单说它做了一道“先总结记忆、再按需回忆”的工序而不是一字不差地录屏。我在第一次看到这个项目的 README 时第一反应是“这不就是给终端里的 Claude 装了个外挂大脑吗”。实际用下来它的确改变了我组织代码工作的方式。过去我靠 CHANGELOG、README、docs 目录来沉淀项目知识但这些东西都有滞后性——代码写完了才补文档决策做完了才写记录。claude-mem 的价值在于它把“沉淀”这件事的时点前移到了对话发生的当下让知识在产生的那一刻就被结构化保存。2. 安装与配置两条路线以及我为什么选择了 MCP 方式2.1 快速安装脚本一键搞定官方提供了一条一键安装命令本质上是下载预编译的二进制文件然后写配置文件。如果你在 macOS 或者 Linux 上执行安装脚本它会自动探测你已有的 Claude Code 配置目录然后把 claude-mem 追加到 MCP 配置里。Windows 用户建议直接走源码构建或者用 WSL 跑 Linux 版本我在 Windows 裸环境下没折腾成功过主要卡在 SQLite 的编译依赖上后面会展开说。装完之后最关键的一步是验证 MCP 连接是否正常。在 Claude Code 里输入/mcp如果能看到类似claude-mem (connected)的状态就说明服务已经注册成功。这时候你可以继续往下配置 embedding 模型——claude-mem 默认使用的是本地嵌入方案不需要外部 API。这一点对很多人来说可能是优点但对另外一些人来说可能是缺点本地嵌入模型的语义理解能力比大模型 API 差不少后面我会对比实测效果。2.2 源码构建适合想改逻辑的人如果你打算自己改代码或者需要给公司内网环境部署源码构建是绕不开的。项目主要是 Go 写的前端管理面板可能要看具体版本我建议先看一眼仓库里的go.mod文件确认 Go 版本要求。构建流程大致是git clone https://github.com/your-username/claude-mem.git cd claude-mem make build构建产物会放在bin/目录下接下来手动把它注册为 MCP 服务。这里有一个很多新手容易踩的坑Claude Code 的 MCP 配置有两种作用域一种是用户级~/.claude.json或~/.claude/settings.json一种是项目级.mcp.json。如果你只是想自己体验配置用户级就行如果是团队协作强烈建议用项目级配置并把.mcp.json提交到 Git 仓库这样所有克隆项目的人都能自动继承这套记忆配置。不过要注意项目级配置意味着每个人的记忆库是独立的不会共享——这涉及到工具的一个边界我后面会讲。2.3 环境变量与关键参数不管用哪种方式安装都需要关注几个环境变量CLAUDE_MEM_DB_PATH数据库文件位置默认在~/.claude-mem/下多项目场景建议改成项目内路径。CLAUDE_MEM_EMBEDDING_MODEL选择本地嵌入模型可选值取决于你编译时打包了哪些模型。CLAUDE_MEM_MAX_MEMORIES单次注入的回忆条数上限默认我印象中是 5调高会提升召回率但占用更多上下文窗口。CLAUDE_MEM_TTL记忆有效期默认是 30 天过期记忆会被清理。提示不要在一开始就追求大而全的配置。先用默认参数跑一周记录下你实际遇到的“该记住的没记住”的案例再针对性地调整参数。盲目调参数只会让你分不清问题出在提取环节还是检索环节。3. 核心机制深挖记忆从提取到注入一条链路四个环节3.1 事件监听每一轮对话都不放过Claude Code 每一次用户发送消息、Claude 每输出一条回复都会产生 MCP 事件。claude-mem 的做法是订阅这些事件流而不是事后对整个会话做批量分析。这个设计差别很关键批量分析的问题是它拿不到“实时会话状态”比如某条消息后面又被用户纠正过——如果你只对最终结果做快照就会把已经被否定的方案也当成共识记下来。而事件级监听可以在每条消息产生时就判断这句话里有没有值得提取的信息我从实现角度猜测它是靠一组启发式规则来判断“这条消息有没有记忆点”的而不是每句都跑一次大模型。比如包含“记住”“决定”“不要”“必须”“项目结构是”这类强指令词的消息优先级会更高普通的闲聊、临时调试输出则会被过滤。这种策略的成本很低但也意味着它可能错过一些“没有关键词但确实很重要”的信息比如一段代码里隐含着某个架构约束。所以我后来习惯在对话里显式地说“这个约束记一下”把它当作一种主动式记忆触发。3.2 信息提取用 LLM 做结构化但控制成本识别出候选消息之后claude-mem 会调用一次 LLM具体模型取决于你的配置来把原始对话转成结构化的记忆条目。这一步的输出不是原文摘录而是提炼后的语义单元大概长这样{ type: decision, subject: 数据库选型, content: 项目使用 SQLite 作为本地存储理由是零运维、单文件备份方便业务量增长后再考虑迁移到 PostgreSQL, tags: [database, sqlite, architecture], importance: 0.92, timestamp: 2025-04-10T10:30:00Z }我特别看了一下它对“重要性”的打分逻辑背后应该是参考了多个信号显式的决策动词、是否涉及项目级主题、是否包含具体技术栈关键词、对话中是否被反复提及。这个打分直接决定了以后这条记忆的召回权重所以它比内容本身更影响体验。这里有个成本控制点不是每条记忆提取都值得调一次大模型。claude-mem 做了两级过滤第一级是前面说的规则判断第二级是如果同一主题在短时间窗口内多次出现它会做去重合并。这种“先便宜过滤、再贵提取”的模式我在其他工具里也见过算是一种成熟的工程妥协。3.3 存储与向量化为什么是 SQLite 而不是 JSON 文件记忆条目提取完成后会同时写入两类存储原始结构数据落在 SQLite 表里语义向量落在向量索引里。用 SQLite 的直观好处是无服务、单文件、备份拷贝都方便一个项目一个claude-mem.db文件比单独跑一个向量数据库轻量得多。向量索引部分我记得默认用的是基于 SQLite 的扩展方案类似 sqlite-vec 的思路而不是外挂 Chroma 或者 Milvus 这类服务。这进一步降低了部署门槛。说句实话起初我觉得“本地嵌入 SQLite 向量索引”是不是太简陋了后来跑了几个真实项目对比发现对于个人开发这种规模记忆条目几千条封顶本地方案完全够用。它的瓶颈不在检索速度而在嵌入模型的语义理解质量。3.4 回忆注入什么时候把记忆塞回上下文回忆触发是整个链路里我对效果最敏感的一环。claude-mem 会实时把当前用户消息拆成 query算出语义向量然后去向量索引里做相似度检索。当相似度超过阈值它就把对应的记忆条目作为上下文块注入到 Claude 的系统提示里。这个注入发生在当前轮次的请求发出之前所以 Claude 在回答时已经“天然知道”了这些历史信息——它不是在对话中途弹出来给你看而是静默地融入了模型输入。默认的相似度阈值、回忆条数上限都直接影响回答质量。阈值太高就什么都回忆不起来太低了则会塞进一堆无关记忆污染模型的注意力。我在实践里发现默认值是偏保守的尤其是针对跨会话的隐式上下文多加大约 20% 的召回量通常效果更好。具体参数我会在下一章给出一份我自己的调校表。4. 实操配置我的一套经过两周验证的参数与工作流4.1 embedding 模型选型与对比claude-mem 的安装文档里会提到可选的 embedding 模型。我对比了默认本地模型和一个中等规模的云端 embedding API测了 20 组真实项目对话结论如下对比维度默认本地模型API embedding 模型语义理解准确度一般关键词匹配为主明显更好能理解同义表达单条记忆召回准确率约 70%约 90%延迟本地毫秒级网络 100-300ms隐私性完全离线数据出本机成本0按 token 计费配置复杂度无需额外配置需要 API key 与环境变量我的建议是如果你的项目里有很多专有名词、缩写、团队内部黑话默认本地模型大概率会让你失望。比如你说“把那个计费的重试逻辑改成指数退避”本地模型可能抓不到“计费”和“重试”之间的关联回忆时会召回一些无关内容。而 API 模型基本能正确建立这种语义关系。不过我不推荐一上来就上 API embedding先用本地模型跑几天把实际遇到的召回失败案例记下来再决定是否值得为了更好的体验引入网络依赖。有时候你会发现失败的原因不是因为 embedding 模型太弱而是你自己在对话里表达得太模糊。4.2 数据库位置单项目隔离 vs 全局统一默认情况下 claude-mem 会把所有项目的记忆混在一个数据库里。我的实测体验是千万不要这样用。你同时开发 A 项目和 B 项目的时候A 项目的记忆会污染 B 项目的检索结果导致 Claude 一本正经地引用另一个项目的技术决策。解决方案很简单按项目隔离export CLAUDE_MEM_DB_PATH$(pwd)/.claude-mem/db.sqlite3在每个项目目录下设置这个环境变量或者在项目级.mcp.json里固定配置。这样数据库就跟着项目走了配合 Git 仓库时记得把.claude-mem/加入.gitignore除非你有意分享记忆库给团队成员——但我不建议提交数据库文件因为二进制文件 diff 不友好而且记忆里可能夹带敏感信息。4.3 我的核心参数调校表经过两周的实际使用和反复调参以下是我目前稳定使用的参数组合CLAUDE_MEM_EMBEDDING_MODEL设置为 API 模型如果你愿意接受外部调用。CLAUDE_MEM_MAX_MEMORIES从默认的 5 调到 8。调高的收益是召回更全代价是每轮请求会多占用大约 1500 token 的上下文。我的项目上下文窗口还剩余量所以可以这么调。CLAUDE_MEM_SIMILARITY_THRESHOLD从默认的 0.75 调到 0.65换来更多潜在相关记忆的召回通常不影响准确率。CLAUDE_MEM_TTL调整为 90 天。项目里很多技术债务决策在三个月后回头看仍然有效30 天太短了。调完这些参数之后我刻意做了一组对照测试让 Claude Code 分别在开启和关闭 claude-mem 的情况下完成同一个需求——“修改之前确定的用户鉴权流程改造成支持 refresh token”。关闭记忆的时候它重新向我确认了三次旧设计开启记忆的时候它能直接报出当前鉴权流程的文件位置、使用的库、之前的改造约束然后直接给出改动方案。这种对比最能说明问题。4.4 主动标记记忆改变你的对话习惯用了一阵子之后我对这个工具的理解发生了一个重要的变化它不是一个完全被动的后台工具它的效果高度依赖你的对话方式。现在我会有意识地在对话里使用一些“记忆标记语”比如“记住这个模块以后不允许引入 lodash。”“这个决定先记录下来后续可能还要调整。”“注意测试环境数据库密码不要写进代码。”我发现这种显式表达能显著提高记忆提取的准确率。而如果我用一种模糊的表达比如“这个还是别用了”claude-mem 可能无法判断我是在说临时调试指令还是长期约束最终也提取不出有效记忆。所以与其埋怨工具不够聪明不如先把自己的表达习惯调教好。5. 应用场景与工作流重组claude-mem 给我带来的实际变化5.1 跨会话接管未完成任务以前我有一个很痛的经验周五下午写到一半的功能周一早上新开会话、让 Claude 继续的时候它完全不记得之前定义过的数据结构、接口签名和待办清单。我只能先把上周的对话文件翻出来手动摘录几段关键信息粘贴进去。有时候粘贴完才发现之前对话里还有一个后来被推翻的设计方案没有标注清楚导致 Claude 又把旧方案拾起来了。有了 claude-mem 之后这个过程变成了新开会话直接说“继续完成之前那个用户导入功能”它会自动召回相关记忆包括我已经决定的导入模板格式、异常处理规则、还有“禁止覆盖已有用户”这条约束。我不需要再从旧对话里摘录任何内容——这省下的不只是时间更是上下文切换时的认知负担。实测下来一个中断了两天的任务重新接续的“热身会话”从过去的十几次来回缩短到了两三次。5.2 沉淀“技术决策”而不是复制代码claude-mem 提取记忆的最小单元是“决策事件”而不只是“代码片段”。这带来一个很有意思的价值它沉淀的是为什么而不是怎么做。比如两周前我因为性能问题决定把某个接口的批量查询改成并发分批查询当时在对话里跟 Claude 讨论过并发数上限、错误重试策略、结果合并顺序。这些决策最后没有全部写进代码注释里但都被 claude-mem 记录下来了。两周后我再次改到这个模块Claude 直接带着这些上下文给出建议它的回答看起来就像“记得我们当时讨论过的事情”这比我再重新解释一遍上下文效率高太多了。我还做过一个实验让 Claude Code 基于 claude-mem 的记忆库自动生成一份项目架构决策记录文档。它能把分散在几十个 session 里的零散决策汇总成结构化文档直接作为 ADR 的初稿。这个流程以前需要人工回忆、梳理现在基本可以自动化。5.3 多项目并行时的记忆隔离与切换同时开三个项目终端的人应该懂这种混乱A 项目里讨论过的代码规范换到 B 项目就完全不适用。如果记忆库不分隔Claude 在 B 项目里可能突然冒出一句“按照我们之前的约定这里应该用 pnpm”但它引用的是你在 A 项目里的约定。按项目隔离之后每个项目的记忆只在该项目的会话里生效这种串味问题就消失了。值得注意的点是项目隔离之后你仍然可以保留一个“个人全局记忆区”我用来存一些不绑定特定项目但随时可能用到的东西比如个人编码风格偏好、常用工具链版本、关于某个框架的通用经验。claude-mem 目前没有直接提供“跨库联动”功能但你可以通过环境切换的方式在不同项目终端里请求同一个全局记忆库这需要你在启动前手动指定数据库路径稍微有点麻烦不过可接受。5.4 与团队协作边界在哪里这里要说一个比较现实的边界问题claude-mem 的记忆默认是本地、单人的。就算你把数据库文件丢给同事它也缺乏冲突合并机制两个人各写各的最后没法干净地合并。它不像 Notion 那样支持多人实时编辑也不像代码仓库那样有 diff/merge。所以我的结论是在“团队共享上下文”这件事上claude-mem 能提供的价值非常有限。如果你们团队想要的是“所有成员的 AI 助手都了解同一个项目背景”那更适合的路径是把项目文档做好用 claude-mem 作为个人层补充而不是把它变成团队知识库。不过有一个搭配玩法很有意思把.mcp.json文件提交进 Git让团队所有成员都启动 claude-mem再约定一张ARCHITECTURE.md里面写清楚常用技术决策和术语表。这样每个成员的个人记忆库虽然独立但启动时都配合读取同一份权威文档能让个人记忆和团队基线保持方向上的一致。我自己在团队里就是这么带的。6. 常见问题与排查技巧实录6.1 安装后 /mcp 显示 connected但对话里没有回忆注入这个现象很隐蔽我调试了两天才找到原因MCP 连接成功只代表服务能启动不代表事件流已经被正确监听。优先检查日志里是否有message_received或session_started这类事件输出。如果没有大概率是配置里没有正确设置输出格式或者二进制版本与 Claude Code 当前的 MCP 协议版本不兼容。还有一个更常见的坑Claude Code 本身会过滤掉部分系统级 MCP 事件尤其是那些不包含用户消息的事件。如果 claude-mem 依赖的是“会话内的所有消息”而 Claude Code 只把用户消息透传给 MCP 服务那么你们看到的行为会是“能存记忆但回忆不准”。我在升级 Claude Code 版本后就踩到这个坑解决办法是主动触发一次带显式记忆指令的对话比如“记住本项目使用 SQLite”然后等几秒再问“之前记录了什么”来验证链路是否通。6.2 记忆库文件越来越大启动变慢默认配置下每一条记忆即使已经过期也只是标记为失效不会彻底清理。运行三个月后我本地的db.sqlite3膨胀到了 280MBMCP 服务每次启动加载索引用了一两秒。处理方法是在配置里打开定期清理或者手动执行一次清理命令claude-mem gc --max-age90d这个命令会把 90 天前的历史记忆删除包括向量记录。如果你不想太激进可以先备份数据库文件跑一次清理后观察两周确认没有误删重要记忆再放心。6.3 为什么有些重要信息没有被记住这个问题我用的排查方法很笨但很有效打开 claude-mem 的“调试模式”它会实时印出“当前消息是否被判定为可记忆”“提取出的记忆条目是什么”这两类日志。运行几个典型场景之后就能清楚地看到是哪一步断了。在我遇到的案例里只有不到三成是因为提取模型能力不够其余都是因为消息本身不够“结构化”。比如“这个逻辑有点问题”这种模糊表达不出意外都会被过滤。所以我的建议是把 claude-mem 当成一个需要协作的对象而不是一个万能录音机。想要它记住就要给它“值得提取”的输入——明确、结构化、自带语境的表达。这不是妥协而是所有基于 LLM 的工具共同的使用哲学。6.4 与多个 MCP 服务竞争上下文窗口如果你跟我一样同时在 Claude Code 里挂了文件系统 MCP、数据库 MCP、claude-mem 等好几个服务上下文窗口的分配会成为一个真问题。claude-mem 默认单轮注入 8 条记忆每条记忆可能带几百字叠加其他 MCP 注入的上下文很快就消耗掉一两万 token。我实测后把MAX_MEMORIES调回 6再配合SIMILARITY_THRESHOLD调高到 0.7整体效果反而更好了——因为上下文里杂质变少Claude 对每条记忆的信任度更高。这里给一个经验公式上下文窗口越紧张越不能贪多。记忆注入不是“越多越好”而是“恰到好处”最好。宁可让一两条关键记忆被放弃也不能让模型在 20 条记忆里大海捞针。6.5 项目级配置没有生效如果你在项目根目录创建了.mcp.json但 claude-mem 始终没有工作检查一下 Claude Code 启动时的工作目录。它必须在你项目根目录下启动而不是在子目录里。如果从 VS Code 的某个文件视图启动终端当前目录可能不是你项目根导致.mcp.json没有被加载。这个问题的排查线索是/mcp列表里完全看不到当前目录的 MCP 服务。7. 我从 claude-mem 里学到的三件事用了 claude-mem 一个多月坦白说它的自动提取能力还没到“零干预”的程度我仍然需要主动说出“这个要记住”甚至偶尔要打开管理面板手动补一条记忆。但即使是这样它也已经把我在项目里的“大脑负担”减轻了一大块。举一个很具体的例子前几天我临时切换去修一个紧急 bug忙了三个小时回来后只需要打开之前的会话说一句“继续那个用户导入功能”claude-mem 已经把此前所有相关决策带回来了。这种体验在过去是做不到的。第一件事是AI 编码工具的上下文不应该只存在于单次会话里。一个工具如果记不住两周前的决定那它就不是一个合格的长期协作者只是一个较强的自动补全。第二件事所有强调“自动”的能力都需要使用者提供合适的输入信号。记忆提取不是黑魔法它靠的是你在对话里的表达是否清晰。第三件事本地优先的存储设计真的重要。claude-mem 的数据全部离线在本地我没有隐私焦虑可以放心地让它记录项目里那些不能公开的架构讨论不用担心数据落到第三方服务手里。最后分享一个小技巧在每个项目里放一个claude-mem-rules.md把你希望 claude-mem 特别留意的关键词和写法写进去配合它的规则匹配机制能显著提升提取准确率。比如写上“凡是出现数据库迁移、鉴权约束、依赖版本这类内容视为高优先级记忆”。这不属于开箱即用的功能但实际调试一次之后回报非常明显。希望这套实践思路能帮你少踩几个坑。
阅读完成 · 觉得有帮助？
