如果你用 Claude Code 写过稍微大一点的代码库肯定体会过那种“每次对话都要重新自我介绍”的崩溃上一次你明明告诉过它“项目用 pnpm别碰 Yarn”“数据库表结构都写在 schema.sql 里”“这个模块是历史遗留尽量别动”结果新开一个会话之后它全部忘光你又得原封不动地交代一遍。碰到更复杂一点的业务光是把背景讲清楚就能耗掉上千 token真正干活的额度反而没剩多少。我把这类问题攒了几个月最后用 claude-mem 把 Claude Code 的跨会话记忆补上了现在它终于像个体面的长期协作伙伴而不是每次见面都互加微信的陌生人。claude-mem 本质上是一个跑在本地、以 SQLite 为存储核心的长期记忆服务它通过 MCPModel Context Protocol接口接入 Claude Code。每次对话过程中它会自动抽取关键信息比如你的技术选型、架构决策、常用命令、代码风格偏好等下一个会话开启时再把这些相关记忆拉回来放进上下文里。换句话说它给 Claude Code 装了一个“动态的 CLAUDE.md”而且不需要你自己维护。这篇文章我会把它的整体设计、核心模块、安装配置、还有我实际使用中踩到的坑完整地过一次。适合正在用 Claude Code 做真实项目、被“会话失忆”和 token 浪费折磨的开发者参考。1. 先说说我为什么做 claude-mem1.1 会话失忆是效率黑洞Claude Code 这类 Agent 型工具默认是“一锤子买卖”式的对话模型每个会话独立任务做完上下文清空。这对一次性编程任务是没问题的但真实项目恰恰是一连串有因果关系的长跑。你前三个小时刚确定了“订单模块统一走 order_service 中间层”第四个小时报了个 bug新会话里的 Claude 却可能重新发明一套直接连数据库的方案。如果这份记忆还要靠你手动整理那这个工具就失去了“让你省心”的意义。我在团队里观察过重度用户平均每天会开十几次会话每次开场都在重复项目背景、依赖关系、代码位置。按 2000 token 算一天光重复自我介绍就烧掉两万到三万 token一个月下来是六十万 token 的纯浪费。这不是用量问题是架构问题——工具本身缺少“跨会话状态”。1.2 我想要的记忆能力和它的边界做 claude-mem 之前我给自己列了需求清单第一记忆必须本地存储不能把项目内部的命名、路径、接口设计这些敏感信息丢给外部服务第二记录和读取都要全自动我不可能每次手动告诉它“记住这句话”第三检索要足够准别在上下文里硬塞一堆无关内容第四所有记忆要可查询、可删除毕竟 AI 记错的东西比不记更可怕。也有过更“聪明”的设想比如直接给 Claude 挂一个大模型做长期上下文压缩或者用 embedding 把整个代码库都向量化。这些方案不是不好而是太重了。我这个项目要的是“轻、快、够用”SQLite 负责结构化存储关键词加上简单的语义匹配负责召回每个项目独立记忆互不污染。事实证明这个组合在绝大多数开发场景下已经足够。1.3 这工具到底适合谁先说结论它最适合两类人。一类是重度 Claude Code 用户每天要处理多个跨会话任务痛点非常明显另一类是微服务或大仓库项目的维护者项目上下文复杂到“一段 CLAUDE.md 根本讲不完”。如果你只是偶尔拿 Claude Code 写个脚本、改个小 bug那这个工具的收益不大反而会多一层 MCP 服务要维护。我也想说清楚它的边界claude-mem 不是要让 AI 记住你的银行卡密码也不是给所有对话做长期大模型微调。它管的是“可外显、可校准、可清除”的项目记忆和用户偏好这点理解到位了后续的功能取舍才会顺。2. 记忆方案的整体设计2.1 先把记忆拆成三层我第一版设计非常粗暴把所有历史对话原文存下来每次启动全量塞给 Claude。结果不需要测试也知道第一次对话就把上下文撑爆而且大量重复信息还会干扰判断导致模型回答更加飘。后来我把记忆按照“能不能直接复述、需不需要聚合”拆成了三层。第一层是偏好类记忆比如“代码缩进用 2 空格”“提交信息按 conventional commits 写”“测试不要 mock 掉 Redis”。这类信息短小、独立、复用频率极高直接原样存储就行。第二层是事实类记忆比如“用户服务监听 50051 端口”“支付回调地址在 config/payment.toml”“项目使用 turborepo 管理 monorepo”。这类信息也是原样存储但需要经常更新。第三层是结论类记忆比如“把消息队列切换成 RabbitMQ因为 Kafka 太重”“不要在订单查询里 join 用户表性能太差”。这类信息由前两个小时的对话推论得出不能简单记录一句话需要把“上下文、结论、原因”打包保存否则以后只记得结论忘了它为什么成立。三层分开存储查询权重也不同偏好类每次会话都加载事实类按项目加载结论类则靠当前对话主题触发检索。这种设计很像我们写代码时区分配置文件、业务常量和运行期数据思路相同只是换了个场景。2.2 为什么选定 SQLite 而不是 JSON 文件很多人第一反应是记忆量不大用个 JSON 文件不就完了我在原型阶段确实先用了 JSON而且跑了两个星期直到几次写坏文件之后才彻底放弃。原因是 Agent 工具的执行并发度比你想的高Claude Code 在处理任务时会同时发起多个工具调用如果多个写操作同时落到同一个 JSON 文件上极容易互相覆盖最后文件里只剩半条记录。SQLite 天生处理并发写WAL 模式下读写不互斥单文件存储又方便迁移备份还自带 SQL 查询能力。我用一张记忆表就解决了 JSON 时代的三个问题并发写冲突、脏数据覆盖、查询没索引。如果你把 claude-mem 的数据目录放在 Dropbox 或 iCloud 同步盘里SQLite 还能保证同步过程中文件不会被半个写入状态污染。经历过一次数据文件损坏后你会对单文件方案有心理阴影SQLite 算是帮我找回了安全感。2.3 向量检索与关键词检索的取舍一开始我也认真考虑过引入 sqlite-vec 或直接外挂一个向量数据库每次对话前把所有记忆 embedding 一遍再做语义检索。“语义匹配”听起来高级但在这个场景里有个致命问题开发记忆里的术语高度专一比如“service层”“DTO”“pnpm-lock.yaml”关键词几乎能精确命中。你不需要理解“职责分离原则”和“分层架构”之间的语义相似度只需要把“项目用分层架构”这条丢进上下文就行。所以我最终选择了“关键词为主、子串匹配为辅、标签组合过滤”的检索策略把记忆文本分词用 LIKE 和 FTS5 索引做匹配再按项目维度过滤。这样检索延迟可以压到毫秒级而且完全不需要维护 embedding 模型的更新成本。只有当记忆数量超过几千条、关键词召回开始漏结果时我才会考虑加向量维度目前来说没有必要。3. 核心模块拆解3.1 对话截获与信息抽取claude-mem 要自动从对话里抽信息首先要能“看到”对话内容。我实现的方式是在 MCP 服务里注册一个轻量的历史钩子通过 Claude Code 的会话事件流拿到消息文本但自己不保存完整原文只抽结果。这么做也是隐私考量长期保存原始对话太敏感保存抽出来的结构化记忆已经足够。信息抽取我用的是 Claude 自己来完成——这在 claude-mem 里叫“记忆提炼器”。它读一段对话窗口输出一个 JSON 数组每条包含 category、content、project、confidence 这几个字段。比如你随口说了一句“以后接口返回统一用 ApiResponse 包一层不要直接吐 Map”提炼器就会把它归类为 preferencecontent 保留这句话confidence 标记为 0.9。抽取任务发起时机也很讲究我放在一次对话结束或上下文即将被截断时触发此时该聊的信息已经聊完提炼器能看到相对完整的上下文记忆质量明显更高。有个细节值得提不是所有句子都值得记。如果 Claude 把“用户说谢谢”也存成记忆那数据库很快就脏了。所以提炼器还有一个 filter只保留三类内容——包含明确指令的、包含项目专属名词的、以及包含因果逻辑的句子。过滤不掉的低频噪音则靠置信度阈值和人工删除兜底。3.2 记忆写入与去重合并sampling 会把抽取出的记忆条目一批批写入 SQLite但直接写入肯定不行因为同一个信息会跨会话反复出现。举个例子你今天说“用 pnpm”明天又会说“记住我们用 pnpm”如果原样存两条检索出来的记忆列表里就有两个几乎一样的条目既浪费 token也让模型困惑。我设计了一个权重叠加机制写入前先按 project category content_hash 做查重。如果已经存在就把 hit_count 加一、更新最后确认时间并且 content 保持不变——因为反复出现的说法往往是最准确的长期约定。如果 content 相似但不完全相同再走一层“合并规则”把新的补充信息接在旧内容后面。比如之前记的是“前端构建用 pnpm”新一条是“monorepo 根目录用 pnpm 安装依赖”两条合并后就是更完整的版本。只有当内容差异较大时才真正新增一条记录。这里有个取舍合并可以避免记忆碎片化但也可能把两条本来不相干的信息搅在一起。我的经验是合并条件要保守相似度低于 0.7 宁可不合留给后续检索时通过 top_k 统一召回也别在写入阶段破坏原意。3.3 MCP 检索接口设计记忆写入得再好检索不出来也白搭。claude-mem 对外暴露了两个 MCP 工具一个是 get_relevant_memories负责在会话启动时拉取记忆注入上下文另一个是 manual_remember允许你手动告诉它“这条必须记”。前者是自动流程的核心后者是我为自己保留的“手动保险丝”。get_relevant_memories 的入参很简单query当前任务描述、project_key、limit、min_confidence。内部先按 project_key 硬过滤再对 query 做词法切分用每个 token 去匹配记忆的 content 和 tags。返回结果按 hit_count 降序、last_checked_at 升序排列保证高频记忆优先太久没确认过的记忆排在最后。limit 默认是 5我实验下来这个数字最合适太少不够覆盖上下文太多则挤占本来就紧张的 token 预算。我还在接口里加了一个 skip_greeting 开关。开启后会话开始时工具返回记忆但 Claude 不在回复里主动复述这些记忆只在回答里“默认它们已经成立”。这能让记忆悄悄生效而不是每次开场都上演一段“好的我已经记住了”的废话表演用户体验差别非常大。4. 从零到一安装与配置实录4.1 环境准备与安装我用的是 macOS Node.js步骤如下。首先确保 Node 版本在 18 以上然后安装 claude-mem 本体npm install -g claude-mem claude-mem --version如果安装顺利你会看到版本号。Claude Code 这边需要自己先装好版本最好保持最新因为 MCP client 的配置路径在不同版本里略有差异。装完之后验证一下 MCP 协议配置是否生效我习惯先跑一条诊断命令:claude mcp list如果列表为空不用慌说明还没有注册任何 MCP server下一步手动把 claude-mem 加进去就行。实操经验如果你在 Linux 服务器上跑无头模式记得先设置环境变量CLAUDE_MEM_DB_PATH否则它会写到当前用户目录下的默认路径不同 shell 用户之间容易互相踩数据库。4.2 把 claude-mem 接入 Claude Code接入方式取决于你对 MCP 的熟悉程度。最省事的命令是claude mcp add claude-mem -- npx claude-mem serve这会注册名称为 claude-mem 的 MCP serverClaude Code 每次启动时都会拉起来。想用全局项目隔离的话可以把它安装在 scope 下claude mcp add claude-mem --scope project -- npx claude-mem serve加完后再跑claude mcp list你应该能看到 claude-mem 出现在列表里并且状态是 connected。如果你偏好手写配置文件也完全没问题。Claude Code 会读取.mcp.json中的配置填入这样一段即可{ mcpServers: { claude-mem: { command: npx, args: [claude-mem, serve], env: { CLAUDE_MEM_DB_PATH: /your/workdir/claude-mem.db, CLAUDE_MEM_PROJECT_KEY: my-backend-service } } } }这里有个关键CLAUDE_MEM_PROJECT_KEY如果设置了那么所有记忆都会归到这个 key 下适合单项目仓库如果不设置claude-mem 会尝试根据当前工作目录自动推断项目名。多仓库开发时建议显式设置避免两个同名目录把记忆串一起。4.3 初始化数据库与第一轮记忆入库启动 MCP server 后claude-mem 会自动完成数据库初始化不需要手动建表。如果你想确认表结构可以打开~/.claude-mem/claude-mem.db或者你自定义的路径sqlite3 ~/.claude-mem/claude-mem.db .schema你会看到一张核心的 memories 表大致包含这些字段字段说明id自增主键project_key项目隔离键categorypreference / fact / conclusioncontent记忆文本tags逗号分隔的标签词用于检索hit_count被命中的次数confidence抽取置信度created_at首次写入时间last_updated_at最近更新时间初始化完成后正常开启一个 Claude Code 会话随便聊几句项目相关的内容并且明确说出一条偏好。结束对话后查一眼hit_count和content确认记忆已经写入。如果你发现会话结束很久了还没数据入库多半是记忆提炼器没有被触发可以先手动调一下写接口再排查事件流采集。5. 实操中常踩的坑与排查技巧5.1 反复记同一个偏好怎么办很多用户遇到的第一个困惑就是同一个偏好被记了十几遍。原因通常是提炼器每次抽取都生成新 hash而查重逻辑没命中。我排查下来常见的坑是 content 里拼接了动态信息比如“项目根目录是 /Users/me/work/demo 目录”路径一旦变化hash 就不一样。解决办法是写入前做一次“动态槽位归一化”把绝对路径、日期、时间戳这类高频变化信息替换成占位符再算 hash存储时保留原始文本查询时用原始格式匹配。另外每次会话结束后定时任务会把同一 project 下相似度高于阈值的记忆做一轮 merge把 hit_count 合并到最新一条这也减少了冗余。如果你遇到 merge 效果不理想可以先调低相似度阈值或者直接手动删掉低置信度的旧条目。5.2 检索回来的记忆占满上下文怎么办记忆一旦增多检索接口单次返回的内容也会膨胀尤其是在 top_k 和 max_tokens 都拉满的情况下。这个问题需要从两个方向控制。第一个是检索侧limit 不要超过 5每条记忆返回前先用句子裁剪只保留主语、谓语和关键宾语那些“我觉得”“大概可能”之类的连接词全部扔掉。第二个是注入侧把返回的记忆合并成一段结构化的“项目约定摘要”而不是让每一条记忆单独占据一个 block这样 token 占用会少很多。我自己设的经验值是“每条记忆压缩到 50 token 以内一个会话最多注入 10 条压缩记忆”。超过这个上限就说明项目约定太多建议你自己额外整理一份精简版 CLAUDE.md把最高频的约定写死claude-mem 负责补充动态信息。两条路并行上下文永远不会失控。5.3 项目之间记忆串味多项目开发时最担心的事情就是记忆漏到别的项目里。如果你发现当前项目里出现了上一个项目的技术偏好先检查 CLAUDE_MEM_PROJECT_KEY 是否在每个仓库里都设置了。如果你用的是.mcp.json它的作用范围可能比你想象的大很多开发者把配置文件放在了 home 目录下结果所有项目共用同一个 key。正确做法是每个仓库放各自的.mcp.json或者利用--scope project参数按目录注册。还有一个小坑如果你把 Claude Code 的自动探测目录打开它可能把相邻文件夹也纳入同一个 workspace导致 project_key 推断失效。我的经验是项目启动命令里显式传入 project key别依赖自动推断尤其在同一台机器上维护多个仓库时。顺便提一句清除串味记忆的命令非常有价值claude mem delete --project other-project --category all定期清理“临时方案”“先这样写”类低质量的记录既能节省空间也能提升检索精准度。我通常每周做一次“记忆审计”把不想要的东西直接删掉效果比调整算法参数更立竿见影。5.4 数据库文件膨胀与损坏处理SQLite 用一段时间后体积变大是正常现象因为每次更新会生成新版本记录旧版本还在占用空间。我观察到的规律是一个活跃项目跑三周数据库大约在 20 MB 到 50 MB 之间这个量级完全无感。一旦超过 100 MB就开始影响检索性能了虽然不至于卡死但明显变慢。处理办法很简单定时执行一次 VACUUMsqlite3 /path/to/claude-mem.db VACUUM;至于损坏我在强杀进程时碰到过一次打开数据库直接报错。恢复思路是先用.recover命令把可读部分导出成新库sqlite3 /path/to/claude-mem.db .recover | sqlite3 /tmp/restored.db恢复完成后可以重新指向新库路径。经过多次实践我现在的兜底策略是写个 cron 任务每晚用 sqlite3 的 backup API 做一次热备而不是直接拷贝数据库文件。热备在写入期间也能得到一致性快照非常重要。6. 一些值得养成的使用习惯工具是死的用法是活的。claude-mem 用得顺手之后回顾了一下有几个习惯让我收益最大。第一在对话中主动给关键结论加“记忆锚点”。过去我会随口说“这个接口要加超时”现在会把话说全“记住order 服务的查询接口超时时间统一设为 3 秒因为上游数据库有时会抖动。”加上了“记住”两个字提炼器捕获到偏好类指令的概率就更高记忆质量也明显更好。第二定期看一眼记忆库。claude-mem 提供了 list 命令可以直接按类别浏览我把它当成项目知识库的管理后台看到过期的记不起来的内容就顺手删掉。第三把 claude-mem 和版本库里的 CLAUDE.md 做分工CLAUDE.md 只写稳定不变的架构约定claude-mem 管动态演进的技术决策和偏好互相补充而不是互相替代。从设计到落地最后一个感受是给 AI 工具做记忆最重要的不是“存得多”而是“存得准、取得到、删得掉”。claude-mem 本质上是个极简的本地记忆层但它补齐了 Claude Code 在跨会话场景里最关键的一环。如果你也长期被会话失忆困扰我建议从一个小项目开始试起先让它跑起来再用一两周时间校准提炼和检索的参数你很快会体会到“它记得我”和“它能帮我想起来”之间的巨大差别。