很多搞过 Claude API 的人都有同一种体验单次会话里模型表现得像个聪明同事一旦关掉终端、重开一个 session它就什么都不记得了。尤其是我这段时间在调一个内部知识库问答工具反复在同一个话题上从零开始解释背景最后实在忍不住去找解决方案然后就挖到了claude-mem这个开源项目。claude-mem本质上是一个给 Claude 加“长期记忆”的中间层Python 实现核心思路是把对话历史落盘到 SQLite再在会话开始时把提炼过的记忆注入上下文。它解决的痛点非常直接就是官方 API 的无状态问题适合的人群也很明确用 Claude Code、Claude API 做二次开发被“没有记忆”反复折磨的开发者。这篇文章我不打算复述 README而是把我实际把它跑起来、拆开看它的记忆提取和注入逻辑、以及踩坑排错的过程完整记录下来。1. Claude 的“失忆症”一个值得正视的工程问题1.1 API 的无状态本质先说一个基本事实Claude 本身不具备跨请求记忆。每次调用 API你发过去的 messages 数组模型才会“看得到”下一次请求如果不带上之前的对话它对你这个人、你之前说过什么、你偏好什么格式一概不知。这是 API 架构决定的——为了水平扩展和隔离服务端不会给每个用户维护一份会话上下文。这个设计在工程上是合理的但对使用者来说就非常别扭。你做一个持续多轮的工具总得自己管历史。最简单的做法是把 messages 全量塞回去但这又引出一个新问题上下文窗口是有限的无限堆历史根本不可行。而且按照 token 计费全量历史每次都要重新计费对话一长成本增长肉眼可见。1.2 提示词拼接方案的局限性很多团队的临时方案是“把重要信息写进 system prompt”。比如在 system 里写“用户喜欢简洁回答”“用户是后端工程师”确实有一定的短期效果。但这样做的问题也很明显完全靠人手工维护对话一多就忘静态 prompt 无法根据用户这几次聊了什么动态变化什么都往 prompt 里塞很快 token 就爆了。我见过最极端的做法是把一个月的历史对话全部拼进 messages 里发给 Claude。结果就是开头几千个 token 全是无关紧要的寒暄真正的问题反而排到了后面模型注意力被稀释回答质量直线下降。这个坑让我意识到记忆这件事必须要有“遗忘”和“抽象”的机制不是原封不动地存而是提炼出值得长期保存的信息。1.3 claude-mem 的核心思路claude-mem切入的角度很有意思它不动模型不做向量检索也不搞什么“记忆网络”而是把整件事拆成了四个环节记录把完整会话日志存下来提取用 Claude 自己从日志里提炼“值得记住的事实”存储把提炼结果写入 SQLite注入下次会话开始时把这些记忆拼接进上下文。这个思路最聪明的地方在于它让模型参与“记忆管理”。哪些信息重要哪些可以丢弃不是靠规则硬编码而是交给模型判断。规则只负责存和取判断留给模型。2. claude-mem 记忆闭环拆解日志、提取、存储、注入2.1 四个环节各自做了什么上手之后我先看了它的处理流程。整个闭环大概是这样日志采集它包装了 Claude Code 的启动命令会话结束之后这次会话的原始输出会被捕获并写入日志文件。这个日志是后续所有操作的原材料。记忆提取会话结束后它会调用 Claude 的 API把日志内容丢给模型并附加一套提取指令。模型输出的是一组高度结构化的“记忆片段”每条记忆可能是一个事实、一个偏好、或者一段背景信息。结构化存储提取出来的记忆不是随手记文本而是写入 SQLite 数据库每条记忆会带上元信息比如提取时间、来源会话、记忆类型等。上下文注入下次启动 Claude Code 时它会从数据库里读出当前用户的记忆按照一定的优先级和篇幅限制拼到 system prompt 或者 CLAUDE.md 里让 Claude 在“认识你”的状态下开始新对话。这里有个很关键的点注入不是全量倒入。数据库里的记忆会越来越多如果全部塞进去本质又回到了“无限上下文”的老路。它内部会对记忆做筛选和裁剪只把与当前任务最相关、置信度最高的记忆注入进去。这一点我后面在踩坑部分会再详细说。2.2 SQLite 里到底存了什么花了几分钟翻它的 data 目录结构比我想象中清晰。核心表大致围绕两类实体会话记录和记忆条目。会话记录每次对话的开始时间、结束时间、原始消息数量、token 估算等记忆条目提取出来的结构化事实包含内容字段和标签字段关联表记忆与来源会话的映射方便回溯某条记忆是怎么来的。选择 SQLite 而不是 JSON 文件是有道理的。JSON 文件读写简单但你要做条件查询、按时间排序、去重合并就会非常痛苦。SQLite 随手一条SELECT就能解决而且 Python 标准库自带sqlite3不需要额外引入数据库服务对单机工具来说是最合适的存储方案。2.3 注入不是简单的字符串拼接初次看它的注入逻辑我以为就是把记忆拼成一段文字放进 prompt。实际看完它的模板之后发现没那么简单。它会根据记忆类型生成不同的 prompt 片段比如用户偏好类记忆注入时强调“用户更喜欢的回答方式”项目背景类记忆注入时强调“该项目的基本约束”。这个做法让我想起一个经验模型对上下文格式很敏感。同样一条信息你写成“小明是后端工程师”和写成“当你在回答问题时请注意用户小明是一名后端工程师他的问题可能涉及服务端架构”效果完全不一样。前者是数据后者是行为指令。claude-mem明显是用了后者这种带“行为引导”的注入方式这比简单地堆数据要有效得多。3. 实操把 claude-mem 跑起来并与 Claude Code 打通3.1 安装前的环境准备我是在 macOS 上操作的Python 版本 3.11。安装前先确认几件事有pip并且指向的 Python 版本在 3.9 以上已经有ANTHROPIC_API_KEY环境变量因为记忆提取环节要调用 Claude API本机已经安装了 Claude Code或者至少能调用claude命令。如果你用的是 Windows流程也差不多就是终端命令换成 PowerShell路径处理注意一下用户目录权限问题。我建议后面所有的命令都在同一个 shell 里执行避免环境变量丢失。3.2 安装过程安装用pip直接装pip install claude-mem装完之后检查一下命令是否存在claude-mem --help正常会输出一组子命令包括初始化、启动、清理等。如果提示找不到命令可能是pip装的目录不在PATH里可以用python -m claude_mem --help验证。3.3 初始化与目录结构初始化命令claude-mem init它会在你的用户主目录下创建一个.claude-mem目录里面放数据库文件和配置。我建议初始化之后先看一眼目录ls -la ~/.claude-mem/正常情况下你会看到类似memory.db和config.toml的文件。配置文件可以设置数据库路径、日志保留时间、是否开启 git 备份等。环境变量CLAUDE_MEMORY_PATH也可以用来指定存储目录这个在跑多项目隔离的时候非常好用。3.4 改造启动方式claude-mem最关键的一步是不要直接运行claude而是通过claude-mem来启动。它会做两件事启动 Claude Code同时监控会话输出。实际用法是claude-mem如果你原来习惯给claude传参数可以保证交给claude-mem的参数会被透明转发。自己习惯的命令行参数比如--continue、--model应该能继续用如果发现某一个参数不生效优先看看是不是版本兼容问题。3.5 验证记忆是否生效跑一次完整会话后我做了两步验证会话结束之后用 SQLite 工具查看数据库里是否新增了记忆条目重新启动claude-mem开启新会话直接问“你知道我刚才让你记了什么吗”。如果数据库里有新增记忆但新会话里模型答不上来大概率是注入环节的问题而这个问题的排查逻辑我放在后面的排坑段落里。如果数据库里压根没有新条目那就是提取环节的问题。4. 记忆提取策略谁来决定“什么值得记住”4.1 提取提示词的设计逻辑我一直好奇它是如何让 Claude 从一大段对话日志里提取记忆的。翻到源码里的提取模板之后我发现它设计了一组非常具体的指令核心包括从对话中找出“关于用户本人的事实”找出“用户明确表达过的好恶”找出“用户正在进行的项目的关键背景”忽略寒暄、临时计算、一次性问题每条记忆必须独立成条不能是一段话揉在一起如果信息不确定宁可不提取。这套指令本质上就是在做“信息降噪”。对话里大量内容是无效的比如“你好”“谢谢”“这个报错我再看看”。如果无差别存储记忆库很快就会被垃圾填满模型注入时也无法区分主次。用 Claude 做提取的好处是泛化能力强能识别隐含的、非结构化的用户意图这是规则匹配做不到的。4.2 事实、偏好、项目状态的分层在数据库里我看到记忆条目带了类型标签大致分这几类类型例子注入时优先级用户事实用户是后端工程师主要负责支付系统高表达偏好用户希望代码注释用中文高项目背景项目使用 FastAPI 框架部署在 K8s中会话状态上次聊到性能优化还没结束低分层的好处是注入时可以按优先级做取舍。上下文窗口紧张时优先保“用户事实”和“表达偏好”因为这两类信息对回答质量的影响最大而“会话状态”这种时效性强的记忆过了几天可能就没价值了。4.3 个性化响应的计算我个人的观察是claude-mem的价值不止在于“记住事实”还在于改变模型回答时的姿态。它有一套逻辑会根据记忆内容生成一段“用户画像”描述再把画像注入到 system prompt。画像不是简单堆事实而是用自然语言写成“你正在与一个有X特征的开发者交流他在意Y不喜欢Z”。这种方式比罗列事实清单更符合大模型的理解习惯。模型读人设和读数据用的是不同的处理路径给它一个具象的用户画像它更容易调整语气、详略和术语深度。这一点和写 prompt 时“告诉模型你是谁”是相通的只是现在这个“谁”不用你每次手动写了。5. 实测中踩过的坑记忆失效、上下文爆炸与错误记忆5.1 记忆不生效先查注入再查提取我遇到的第一个问题是数据库里明明有记忆但新会话里的 Claude 完全不像是“记得”的样子。排查链路大概是先确认数据库里确实有记忆条目再确认claude-mem是否用了正确的数据库路径然后看启动日志里有没有注入记录最后看注入的文本是否真正出现在了发给模型的上下文里。我那次的问题出在第二步——我在项目目录里设置了CLAUDE_MEMORY_PATH但启动脚本里用的还是默认路径两条路径指向了不同的数据库文件。查了半天才发现是新旧配置共存导致的路径覆盖问题。这里也提醒大家配置文件和环境变量同时存在时环境变量优先但一定要确认两者指向一致。5.2 上下文爆炸记忆条目随时间膨胀用了两周之后我注意到一个问题开启claude-mem的会话前几轮响应速度明显变慢token 消耗也变高。查询数据库发现记忆条目已经几百条了。这说明注入环节虽然会裁剪但裁剪的力度不够尤其是和高优先级记忆一起注入的画像描述越来越长。解决办法有两个方向定期做记忆清理删除过期、错误、重复的条目调整配置项限制单次注入的记忆条数和总 token 上限。我更推荐两个一起做先让数据库保持干净再让注入逻辑控制篇幅。光靠注入侧压缩提取侧的垃圾还是会在数据库里越积越多。5.3 错误记忆模型记错了怎么办还有个很有意思的问题Claude 在提取记忆时可能出错。我在一次会话里提到“我不太用 Redis”模型提取的记忆却是“用户偏好使用 Redis”另一次我说“这个 bug 可能是缓存导致的”被记成了“项目存在缓存 bug”。这种错误记忆如果被注入到后续会话会产生误导。处理方式我总结了三层第一层会话中直接纠正。如果发现 Claude 的言行基于一条错误记忆明确说“不对我之前说的不是这个意思”新会话中模型可能产生正确的新记忆来覆盖旧记忆。第二层手动清理。用 SQLite 工具直接删掉对应的记忆条目。第三层定期审查。偶尔打开数据库扫一遍记忆条目把可疑内容清掉。说实话第三层最费时间但也是保证长期可用度最重要的一步。任何自动提取系统都不可能 100% 准确记忆这件事必须有个“人工复核”的出口。5.4 数据库异常与恢复还有一次我强制终止终端进程再重启claude-mem时提示数据库被锁或文件损坏。SQLite 对这个场景的处理已经足够好只要定期有备份恢复并不难。我后来做的保护措施有三条开启配置里的 git 自动备份每周手动复制一份 memory.db 到别的目录如果数据库损坏严重直接删除损坏文件从最近的备份恢复。6. 存储层的运维备份、迁移与隐私边界6.1 Git 做记忆的“时间机器”claude-mem支持把数据库导出或备份到 Git 仓库这让我感觉它把记忆当成代码一样管理方向是对的。备份的粒度是“记忆库快照”每次会话后都可以提交一次变更。好处是如果哪次自动提取把记忆库搞乱了你随时可以回滚到之前的 commit。建议把备份仓库放在独立目录不要和业务代码混在一起否则每次 commit 都会被记忆变更刷屏。以及记得给备份仓库配好.gitignore避免日志文件混进版本库。6.2 多项目环境下的数据隔离我同时跑着两个项目一个是内部知识库一个是个人博客助手。两个项目对记忆的需求完全不同如果共用同一个记忆库Claude 就会把博客的偏好带到知识库问答里。claude-mem对这个场景支持得不错通过环境变量指定不同的存储路径即可CLAUDE_MEMORY_PATH/path/to/project_a/memory claude-mem CLAUDE_MEMORY_PATH/path/to/project_b/memory claude-mem我实际用下来感觉“一项目一库”是最高效的形态。项目记忆保持独立提取和注入的上下文也更干净。6.3 隐私与数据安全怎么把握记忆库里面存的是真实对话的提炼结果有可能包含敏感信息。比如我在之前的测试中Claude 把一条包含内部服务地址的信息提取成了记忆如果这份数据库被同步到公共仓库就是一次安全事故。我的建议是记忆库默认只在本地不做云同步。如果确实需要多台机器之间同步优先考虑私有仓库并且对记忆内容定期做敏感信息扫描。系统提示词里也可以加一条“不要提取包含密钥、密码、内部 IP 的内容”虽然不能保证 100% 生效但能显著降低风险。另外删除记忆不等于删除会话日志。会话日志可能还在磁盘上记得按配置里的日志保留策略定期清理。7. 根据我这几周的使用给你几句实话如果让我总结claude-mem的使用体验我的评价是它不是一个装完就完事的插件而是一个需要你参与维护的小系统。安装和接入只占 20% 的精力剩下 80% 花在记忆条目的清洁、注入效果调优、备份恢复策略上。对于刚开始尝试的人我给你的建议是先跑一个低风险的个人项目用两周时间观察记忆注入对回答质量的影响。不要一上来就在生产环境部署因为记忆提取一旦出现系统性偏差纠正成本会很高。有一个小技巧我一直用到现在每隔几天打开数据库用一条 SQL 看一眼近期新增了哪些记忆SELECT content, type, created_at FROM memories ORDER BY created_at DESC LIMIT 20;这个习惯帮我发现了很多模型提取时的隐性偏差。记忆系统的价值取决于里面存的东西是否靠谱这个维护功夫省不了。