有这样的经历吧每次换新会话或者隔天继续同一个任务第一件事永远是重复上下文“上次咱们聊到哪了”“我之前说过我用 React 和 Tailwind”“那个接口文档再发我一遍”。我一开始觉得这是大模型的通病忍忍就过去了。直到我花了小半个上午把同一个需求背景跟 Claude 交代了第七遍我决定不再忍——开始动手给 Claude 配一个长期记忆层也就是 claude-mem 这个项目的来龙去脉。claude-mem 不是让模型本身“会记忆”的神奇补丁而是一个夹在你和 Claude API 之间的外部记忆桥接工具。它会自动记录每次对话提取其中的偏好、事实、决定存进本地数据库然后在下一次会话发起时把相关的历史信息拼装成一段“记忆提示词”注入到请求里。相当于给 Claude 配了一个随身的备忘笔记本而它本身还是那个聪明的 Claude。这篇文章先讲清楚它要解决的问题再说核心设计、完整部署步骤、实测效果最后给一份我在实际使用中攒下来的避坑清单。想复刻一套外部记忆层的开发者或者重度使用 Claude 做项目协作的朋友这篇都可以直接参考。1. 先搞清楚Claude为什么会“失忆”上下文窗口与会话隔离的本质1.1 上下文窗口是工作台不是记忆力先做个认知校正。Claude 号称有超大上下文窗口几十万 token 能塞下很长的内容。但上下文窗口更像你办公桌上的一张操作台——桌面再大下班关门的时候台面还是会被清空。每次会话结束对话历史就丢掉了模型不保存任何跨会话的状态。模型服务方确实在推进一些记忆类的产品能力但对于自己掌控的工具链、本地私有数据、跨多个产品的统一记忆需求第三方方案仍然大有可为。这里有个常见误解“我给 Claude 发了很长的资料它记住了”——不它只是在当前上下文里暂时“看得到”换一个会话它就忘得干干净净。不仅是网页端通过 API 调用也一样每一次请求都是无状态的上下文靠你主动传入。你传多少它看多少你不传它就当你是新朋友。1.2 记忆缺失的三个典型症状我做 claude-mem 之前认真记录了自己的“失忆症状”。列出来其实很触目惊心场景具体表现时间成本新开会话继续开发任务每次都要重述项目背景、技术栈、当前进度5-10 分钟跨天讨论同一主题上次已经达成的决策再次被推翻或重新讨论反复拉扯、效率极低风格偏好保持不住说好代码用 4 空格加类型注解下次又输出 2 空格逐段修正、极其烦躁这三个症状背后是同一个根因模型本身没有“长期记忆”这个组件。它只有“短期工作记忆”也就是上下文窗口。想要真正解决与其等待模型侧的变化不如在自己的工程链路里补一层外部记忆。这也是 claude-mem 存在的全部理由。1.3 目标外部记忆层不动模型本身所以 claude-mem 的定位从一开始就很明确不动模型、不微调、不改变 Claude 对话能力只做一件事——在会话之间提供一个可靠的外部记忆层。它把记忆拆成三个层次事实记忆项目背景、技术约束、接口文档要点、环境信息。偏好记忆语言风格、代码风格、常用工具链、写作习惯。任务状态记忆进行到哪一步、下一步计划、哪个方案已经被否掉。这个分层直接决定了后面存储与注入的设计。事实记忆是刚性的召回错误会直接误导任务所以可靠性要求最高偏好记忆是柔性的适合作全局注入任务状态记忆时效性最强过了窗口期就该让位给新信息。2. claude-mem核心设计把记忆拆成“能存、能找、能注入”三件事整个项目在技术上可以抽象成一条流水线先记录对话再抽取记忆然后做向量化存储最后在请求前把相关记忆注入到上下文。和大多数人想象的“把所有日志堆起来”完全不同它真正的难点在三个地方。2.1 记录层只记“值得记的”不是流水账最原始的做法是把所有对话日志存起来但这很快会让注入变得又臭又长。我用的方案是抽取式记忆。每次会话结束后对原始对话做一次结构化抽取重点提取四类信息用户明确给出的偏好“以后都用 4 空格缩进”“接口返回统一用 snake_case”。已经达成的决定“数据库选型定为 SQLite不上服务端”“这个方案不采用理由是有迁移成本”。关键事实环境地址、依赖版本、接口名、关键路径。待办状态“下一步是实现用户登录模块”“还有三个 TODO 未处理”。抽取器我最初用纯正则简单可控但识别不出隐式偏好。后来改成“规则初筛加模型精炼”的混合方案先用正则把对话里用户明确陈述的句子捞出来再让模型把这句话压缩成一条规范化的记忆项。折中方案的好处是大部分明显信息走规则只有需要语义理解的部分才调用模型token 成本可控。这一步是决定整个系统上限的地方。记忆抽取得烂后面存储和注入做得再好也没有用。实际经验是“少而精”远比“多而杂”有效一条高质量记忆项的注入价值超过十条流水账。2.2 存储层SQLite为主向量检索为辅存储方案我做过一轮对比方案优点缺点适合场景纯 JSON 文件人类可读、改起来方便大规模检索慢、并发弱记忆量少的个人用SQLite单文件、事务可靠、支持全文检索向量检索需要额外插件个人/小团队主力方案独立向量数据库语义检索强、扩展性好多一个服务要维护团队级、海量记忆我最终选了 SQLite 加轻量向量索引。核心原因单文件部署简单备份就是复制一个文件个人工具的对话量级记忆撑到几万条也不会明显变慢。向量部分用 embedding 模型把记忆内容转成向量存进去检索时算余弦相似度。这个计算量在本地跑完全能接受犯不上为几万条记忆单独部署一个向量数据库服务。每个记忆项在设计上包含这些字段id、类型、内容、来源 session、创建时间、更新时间、访问次数、embedding 向量。这里最关键的是“类型”字段它会在注入阶段起到标签作用让模型快速理解这条记忆属于哪一类。2.3 注入层记忆提示词的组装规则这是 claude-mem 真正出效果的地方。组装不是把所有记忆全塞进去而是做“三类召回”固定记忆跨会话始终要记住的全局偏好每次注入。相关召回根据当前用户问题从向量库里取相似度最高的 N 条。新近事件最近几小时或几天内更新的记忆带时间戳注入。三类召回按优先级从高到低拼装。固定记忆在最前面新近事件在最后面。组装完成的记忆提示词会拼到请求的 system 字段里并明确告诉模型“以下是你已有的相关记忆仅作参考如果与用户当前指令冲突以用户当前指令为准。”光这句话就值得单独讲一下。记忆是历史的快照而用户当前说的话才是最高优先级两者的冲突必须让模型明确知道该听谁的否则旧决策会反复干扰新决策。def build_memory_prompt(user_input: str, profile: MemoryProfile) - str: fixed profile.get_fixed_memories(limit10) relevant profile.recall(user_input, top_kcfg.recall_top_k, thresholdcfg.recall_threshold) recent profile.get_recent(ttl_hourscfg.recent_window_hours) blocks [] if fixed: blocks.append(全局偏好\n render(fixed)) if relevant: blocks.append(历史上相关的决定与事实\n render(relevant)) if recent: blocks.append(近期更新过的事项\n render(recent, with_tsTrue)) if not blocks: return return ( 以下是当前会话之前积累的相关记忆仅作参考若与你得到的当前指令冲突以当前指令为准\n \n\n.join(blocks) )注入量一定要设上限。我默认控制在 2000 token 以内占总上下文预算的一小部分。宁可少注入也不能让记忆内容淹没了用户真正的指令。上个会话讨论到一半的草稿和下个会话真正要执行的任务这两者的优先级完全不一样。3. 本地部署完整脉络从环境准备到首次对话验证3.1 环境与依赖清单我跑的版本基于 Python 3.10只用四个核心依赖anthropic 官方 SDK负责 Claude API 调用。sqlite-vec 或轻量向量索引层负责本地向量检索。pyyaml负责配置解析。一个 embedding 模型服务或本地模型用于把记忆文本转成向量。建议用一个干净的虚拟环境。首次安装时最容易踩的坑是 Python 版本太老3.8 上跑 sqlite-vec 相关特性会有兼容问题。直接从仓库源码方式安装最省事cd claude-mem python -m venv .venv source .venv/bin/activate pip install -e .3.2 配置文件结构与核心参数安装完成后的第一件事是写配置。下面是我跑通使用的核心配置# ~/.claude-mem/config.yaml provider: anthropic model: claude-sonnet-4 memory_dir: ~/.claude-mem session_tags: [dev, writing] recall_top_k: 5 # 相关召回条数 recall_threshold: 0.72 # 相似度阈值低于此值不召回 recent_window_hours: 24 # 新近记忆窗口 fixed_memory_limit: 10 # 全局固定记忆最多几条 prompt_budget_tokens: 2000 # 注入预算上限几个参数值得多说一句。recall_threshold 是关键中的关键调太高每次会话几乎什么都不召回记忆层白做了调太低召回一堆无关内容污染上下文。我建议从 0.7 起步连续测一周再微调。session_tags 用来给不同项目建独立的记忆分区这是避免记忆串味的重要手段。比如开发项目和写作项目各开一个 tag两边记忆互不干扰。prompt_budget_tokens 是注入预算的笼子没有这个上限记忆层早晚会失控。3.3 首次对话验证记忆从无到有设置 API key 后启动交互会话export ANTHROPIC_API_KEYsk-ant-... claude-mem chat --session dev第一轮对话你正常聊告诉它“这个项目用 Python 3.12代码风格统一 4 空格缩进类型标注必写lint 工具用 ruff。”这些句子会被抽取成若干条记忆写入本地库。然后退出会话重新开一个全新会话再问“我记得跟你说过代码风格是什么”如果部署正常claude-mem 会在请求发出前检索到对应记忆并把“项目用 Python 3.12统一 4 空格缩进类型标注必写lint 用 ruff”注入进去。Claude 的回答大概率是把这些原样复述出来并补充一句“根据你之前的约定”。到这里一条最小闭环就跑通了对话→抽取→存储→检索→注入→模型回答。整个链路没有魔法每一步都是可观测的记忆存在哪个文件、加了哪些向量、注入了多少 token全部可以查。4. 实测的一天记忆注入效果、冷启动测试、多会话串联4.1 偏好记忆从“说一次就忘”到“跨天兑现”我连续做了一周测试最稳定的场景是编码风格。第一天告诉它之前的代码仓库用 uv 管理依赖、pytest 跑测试、类型标注严格要求。第二天开新会话直接丢一段“没头没尾”的函数代码让它 review。结果它主动反馈“按你之前的约定这个函数缺少返回类型标注建议补上同时要用 ruff 检查未使用的导入。”这和我没用 claude-mem 时的体验完全不同——以前它不会主动结合历史约定因为根本没有历史可结合。偏好记忆这类全局性、长期性的信息是最适合放进外部记忆层的内容。4.2 项目上下文串联三个会话一次接住最惊喜的是复杂任务的状态衔接。我用三个独立会话做一个功能第一个会话讨论数据库选型结论定了 SQLite 加一个迁移工具。第二个会话里我没有重述背景直接让它写表结构。它正确理解了上下文给出的表结构符合第一个会话中确定的约束。第三个会话改需求它居然记得第二个会话里表结构的设计细节直接在新方案里保留了之前设计的核心字段。整个流程明显比“从零开始”快得多因为不需要每轮重述背景。但也要提醒一点依赖相似度召回不是每次都能命中。如果问题问得太偏我需要在提问时带上一个关键词或者明确说“按上次讨论的 xx”。记忆工具能减轻重复劳动但不是把你变成不用动脑的甩手掌柜。4.3 冷启动与失效实测我专门做了冷启动测试也就是记忆库完全为空时直接使用。结果和不开记忆时的行为完全一致回答不会因为记忆机制变差。这一点很重要说明注入逻辑足够保守空记忆不会制造噪音。测试场景记忆命中注入质量结论偏好问答稳定命中高首选使用场景跨会话任务承接部分命中中提问最好带主题词冷启动空库无命中无行为等价原生 Claude语义近似但不同主题偶发误召回低提高阈值或减少 top_k失效场景主要发生在相似度召回“打偏”的时候。比如我在聊写作风格结果库里的“代码风格”记忆因为相似度不低被召回了造成噪音。解决办法是把记忆类型写好在注入模板里用标签标注来源比如[偏好-代码]、[偏好-写作]。模型看到标签后会做区分不会把两种风格混为一谈。4.4 模型侧已有记忆能力本地记忆层还有必要吗另一个经常被问到的问题是模型服务商自己也在做记忆类能力那本地搭这一层还值不值得我的看法是两者解决的问题有重合但不完全一样。本地方案有几个不可替代的价值数据完全在自己手里记忆文件可导出、可删除、可审查没有平台锁定。可以跨多个产品复用同一套记忆不只是服务于某一个聊天工具。能精细控制注入内容、容量、过期策略甚至做批量清洗和版本管理。如果你只在一个产品里轻量使用模型侧记忆能力也许够用。但只要你对记忆数据的主权、可迁移性、可审查性有要求外部记忆层这条路仍然值得走。很多人低估了“能导出自己的记忆”这件事的价值等对话历史上万条之后你会发现数据自由度比想象中重要得多。5. 跑通之后必须知道的调优与避坑清单跑通最小闭环之后真正的挑战才刚刚开始。这一节的内容全是我自己踩过坑之后总结出来的每一条都对应过一次具体的翻车。5.1 上下文膨胀注入量预算要管死最常见的翻车就是“越记越多上下文被记忆挤爆”。记忆项一旦堆积起来如果全量注入系统提示词会变得很长回答质量不升反降最终整个对话体验比没有记忆层还差。我把注入预算硬性控制在 2000 token并且对固定记忆做数量上限。另一个重要的操作是定期压缩记忆。比如一周跑一次合并任务把多条内容相近的记忆合并成一条摘要而不是无限堆条数。上下文是有限的记忆工具必须学会“增量记忆、存量压缩”。这个原则可以类比整理房间只往柜子里放永远有用的东西过期的资料定期归档。不做定期整理记忆库很快就会变成垃圾堆检索质量直线下滑。5.2 注入顺序与优先级冲突记忆提示词和用户当前指令冲突时永远以当前指令为准。这是我在 system prompt 里明确写死的规则。如果记忆把一条旧决策当成铁律而用户今天已经决定推翻那模型必须响应新指令。为了支持这个逻辑记忆项里应该加一个“状态”字段active、superseded、archived。明确被告知作废的旧决策直接标记为 superseded不再参与召回。不然它会反复跟新指令打架你在新会话里说“不要 SQLite 了换 PostgreSQL”模型却因为记忆里的旧结论一直劝你谨慎。5.3 隐私边界与敏感信息处理这个坑很容易被忽略记忆虽然存在本地但在调用 API 时注入的文本会原样发送给模型服务端。这意味着如果你的记忆里存了密钥、内部地址、客户隐私它们会被送进模型。所以我在写入前会跑一遍脱敏规则凡是匹配 AK/SK、token、身份证号、手机号的模式全部替换成占位符检索注入时再拦截所有含敏感标记的记忆项。本地存储不等于本地推理这个边界一定要清楚。想做本地存储又想完全不出网那就得用本地模型做推理那又是另一套方案了。5.4 进阶给记忆做版本管理和自动日报把 memory_dir 放进 git 是我推荐的第一件事。记忆文件本质上是文本数据库天然适合版本管理。哪天清理规则误删了记忆一个 revert 就回来了。另外一个很实用的心得挂一个定时任务每天会话结束后把当天记忆生成一份“日报摘要”作为固定记忆注入第二天的第一个会话。这等于每天都在给未来的自己留一条高质量笔记而不是让模型去大海捞针。我有段时间高强度使用时靠这个机制让跨天连续开发的感觉接近“无缝衔接”。最后一个经验给每个项目单独开一个 profile让记忆分区管理互不污染。刚开始你觉得一个全局记忆库够用了但项目一多你会发现“上周那个项目的技术细节”和“今天这个项目的技术细节”混在一起有多痛苦。分区配置很简单就是在 config 里多写一行 session_tags但带来的清晰感是质的提升。实际跑了一两周之后我对 claude-mem 这类外部记忆层最大的感受不是“AI 记住了什么”而是“我再也不用当人肉上下文人”。这种体验很难量化但真的很影响连续工作的舒适度。值得提醒的是它不会让模型突然变聪明只是让我们和模型之间少一点重复劳动。如果你也经常被“新会话失忆”折磨可以从最小的一条记忆链路搭起先用一个会话记住一条偏好再慢慢扩展成自己的记忆库。