有没有过这种经历用 API 调试了几轮代码好不容易让 Claude 理解了你的项目结构和技术选型结果新开会话一切归零你又要从头开始把上下文喂一遍。我当初折腾 claude-mem 这个项目就是冲着治这个病去的——它本质上是一套给 Claude 的“外挂记忆系统”对话结束之后不是一拍两散而是由系统把该记的信息留在本地存储里下次会话启动时自动检索并注入上下文。这样一来Claude 的行为就从“每句话都当第一次见面”变成了“记得你是熟客”能明显减少重复沟通的成本。如果你平时重度使用 API 接口跑代码评审、做技术问答或者正在搭自己的个人助手这个项目非常值得玩一玩。它会让你重新理解“上下文工程”这件事到底有多大发挥空间。全文我会从需求拆解、架构设计、代码落地、坑位排查四个方面把自己做这个项目时踩过的坑和验证过的方案都过一遍。1. 这个项目到底解决了什么1.1 无状态 API 的困局用过 AI 助手 API 的人都知道模型侧没有任何持久状态。每次调用模型只根据这一次进入的上下文来生成结果不会记得上一轮你说了什么更不会记得昨天你交代过的偏好。这不是缺陷而是这种接口设计的基本约束——无状态换来了接口的简单和可扩展性但代价是开发者必须自己承担“记忆”的工作。很多人多轮任务里反复解释同一个背景本质就是因为这个约束没被处理好。我举一个自己常遇到的场景某个后端项目里我用了一套自定义的目录约定比如控制器都放在 app/controllers服务层写在 domain/services前端对接收到错误码时统一包装成{ code, message }结构。这些约定只要在新的会话里不写进上下文Claude 就完全不记得给出的建议经常和我项目现状对不上。按老办法我需要每次新开会话粘贴一段项目说明几千字就进去了既费 token 又费时间。claude-mem 的思路就是专门解决这类问题。它像人的记忆系统一样分三步走对话结束后抽取关键信息把信息存成结构化记录新会话开始前把相关的记录找回来塞进上下文。通过这个过程让无状态的模型接口体验上更像一个有状态的长期助手。1.2 需要“记住”的信息到底分几类做记忆系统时不能什么都记要先把记忆分区。我实际梳理下来大致分四类第一类是事实型知识包括项目技术栈、目录结构、核心类名、接口地址、环境变量约定这类客观信息。这类信息最稳定一旦记录基本不需要修改是记忆库的地基。第二类是规则型知识包括代码风格、命名习惯、错误码格式、接口设计规范、提交信息格式这类约束条件。模型知道了这些规则产出的内容才跟你的项目风格一致而不是泛泛而谈。第三类是状态型知识也就是项目进行到哪一步了上一轮改完哪个模块当前有没有待办有没有出现阻塞。这类信息时效性强但对连续协作极其重要它决定了你和助手之间能不能无缝接力。第四类是对话摘要说的是某一段长讨论里最终结论是什么、为什么做这个决定。这类信息不追求记录所有过程只求结论。举个例子你和助手讨论了一个小时技术选型最后定了用 MQTT 而不是 HTTP 长轮询那入库的应该是“选型结论MQTT原因是服务端推送频率高、连接数大”而不是把整个讨论过程原样存下来。新手容易犯的错就是把对话原文整个囤下来。看上去像记忆实际是黑历史全集检索噪声极大。我后来只存结构化的抽取结果效果比存原文好得多。1.3 这个方案适合什么场景我的实际经验是它最适合三个场景。第一长期项目维护特别是那种每周都要和助手对接两次、三次的项目记忆可以保证上下文连续不用每次花十几分钟重新交代背景。第二个人 AI 助手你希望助手记住你的名字、称呼习惯、常用工具链、反感什么回复风格这都需要跨会话能力。第三团队内共享一个助手账号做代码问答或文档问答时也需要项目级记忆来对齐大家的使用习惯。反过来如果你只是偶尔做一次两次问答比如查个算法题、写个一次性脚本那完全没有上记忆系统的必要多余的开销反而拖慢响应。做工具先想清楚边界比多写代码重要。2. 核心架构与设计思路拆解2.1 一条完整的记忆闭环我理解的记忆闭环由五个环节组成捕获把当前会话的对话内容抓取到手包括你和 Claude 的来往消息。抽取用大模型能力把对话里的记忆点提炼成结构化记录这一步是整条系统的中枢。存储把结构化记录写入本地数据库并用向量的方式保存语义索引。检索新会话开始时把当前的问题转成向量去做向量检索找出相关记忆。注入把检索到的记忆拼装为一段文本放到 system prompt 或用户消息里再发给模型。有一个生活化的类比我常跟别人讲人的记忆不是直接录下视频再回放而是大脑先抽取要点、归档然后到了需要的时候重建。claude-mem 模仿的就是这套逻辑。你把每次对话当成一条“经历”系统负责提炼成几条“要点”下次要用了再“回忆”出来。这个类比帮我理清了很多设计决策——只要记住“系统不是录像机是归档员”这句话就不会把记忆库做成垃圾场。2.2 存储选型对比存储是整个系统最容易被低估的部分。我最初图省事用了 JSON 文件每条记忆一个对象结构如下{id, content, tags, timestamp}检索方式就是遍历所有文件做关键词匹配。原型阶段还行但记忆量到了几百条之后关键词匹配的准确率明显下降同义改写之后根本匹配不上。于是我把存储换成向量数据库用语义相似度来检索。这里列个简单对比表存储方案上手难度查询能力适合阶段JSON 文件极简只能全量遍历原型验证SQLite简单支持结构化查询但无语义性中小规模结构化记忆向量数据库如 ChromaDB中等语义相似检索支持 Top-K大规模、语义敏感的记忆系统实际选型里我推荐直接用向量库成本没有想象中高。ChromaDB 这类轻量向量库可以本地运行不需要额外的服务器适合个人项目和中小团队。如果规模更大再考虑服务化的向量库但那是后话。2.3 为什么要让 Claude 帮 Claude 记笔记记忆来源于对话但对话原文不适合直接入库。原因有两个一是噪声太多一整轮对话里可能核心信息只有两三个点二是占用空间原文入库存放和检索都会变慢。所以我在抽取环节使用了模型自身的文本理解能力。给它一段对话记录同时附上一条明确的抽取指令让它把关键信息拆成结构化 JSON。这一步本质上是在做信息压缩相当于让秘书看完会议纪要后只留下待办事项和决定。指令模板后面第三章会完整贴出来。抽取指令的设计非常关键。我发现越具体的指令越有效“提取项目背景、技术栈、代码规范、当前进度、决策结论”这些维度的准确性远比笼统的“提取对话要点”要好。模型的任务越明确输出的结构就越稳定下游解析代码也越省事。2.4 检索与注入的策略细节记忆系统的成败更多取决于检索策略。检索太宽乱七八糟的记忆全进来反而干扰模型检索太窄有价值的记忆漏掉系统形同虚设。我采用的方案是把用户当前问题转成向量在记忆库里做余弦相似度搜索选出 top_k 条最相关的再设置一个相似度阈值低于阈值的直接丢弃。阈值这个参数比较微妙我踩过几次坑后总结出一个规律阈值设 0.5 左右时召回率高但噪声大0.7 以上精度高但容易漏日常使用我会在 0.55 到 0.65 之间调具体看应用场景对精度要求高还是对覆盖要求高。把检索到的记忆放进 prompt 也有讲究。我一开始都丢到 user message 里结果发现模型对过时记忆的警惕性不高容易把旧信息当成当前唯一事实直接使用。后来改放到 system prompt 里并且加一句“以下内容是历史记忆可能和当前上下文冲突请以当前信息为准”模型的处理就稳健很多。这个细节改动虽然小但效果提升明显。3. 实操落地与核心环节实现3.1 项目结构与依赖准备我按一个普通 Python 项目来组织下面给出一份可复现的结构和安装命令。依赖上需要几样anthropic 官方 SDK负责调用模型接口chromadb负责向量存取和相似度检索python-dotenv用来管理 API Key 等环境变量一个 embedding 模型负责把文本转成向量目录结构长这样claude-mem/ ├── main.py # 入口处理单条消息往返 ├── memory_store.py # 记忆库封装包括写入、检索、删除 ├── extractor.py # 记忆抽取模块构造抽取指令并解析结果 ├── injector.py # 记忆注入模块拼装上下文 ├── config.py # 阈值、路径等配置 ├── data/ # 本地存储目录 └── .env # API Key 等敏感信息安装依赖用一条命令pip install anthropic chromadb python-dotenv sentence-transformers3.2 记忆抽取指令设计抽取模块是核心它决定记忆库的质量。我把指令模板长这样设计你是一个信息抽取器。下面是用户与 AI 助手的对话记录请提取其中需要长期记住的信息。 要求 1. 只提取客观、稳定、对未来对话有用的信息。 2. 不要提取情绪化表达不要提取临时性寒暄。 3. 对每一条记忆输出 JSON 对象字段包括 id自增、category、content、importance、timestamp。 4. category 取值范围project_background / code_style / progress / decision / user_preference / other 5. 如果没有可提取内容输出空数组。 对话记录 {conversation_text}输出示例[ { id: mem_001, category: project_background, content: 后端项目采用 Python FastAPIORM 使用 SQLAlchemy 2.x, importance: 0.9, timestamp: 2025-01-12T10:30:00Z }, { id: mem_002, category: decision, content: 团队决定错误返回体统一为 {code, message, detail} 结构, importance: 0.8, timestamp: 2025-01-12T10:30:00Z } ]解析响应时有个很实际的坑模型偶尔会输出多余解释或格式不标准。我的做法是在代码里提取 JSON 数组部分做二次解析解析失败就放弃本条对话的抽取不阻塞主流程。稳远比全重要。另外在抽取指令里明确“如果没有可提取内容输出空数组”这句也很管用能显著降低模型乱编内容的概率。3.3 向量存储与检索函数下面是 memory_store.py 的核心片段。我用 ChromaDB 的 Collection 来保存记忆每条记录对应一个文档用本地 embedding 模型做向量化。关于 embedding 方案选择我多说一句如果考虑本地离线运行推荐把 embedding 模型跑成本地的小模型这样每次新对话的向量化不产生网络请求整体延迟更低。我自己的环境里用的是 300M 级别的本地小模型语义效果已经够用。如果追求极致准确率可以用对外部 embedding API 的依赖但会多一次网络往返取舍看你的场景。存储函数的核心逻辑大致是这样import chromadb from chromadb.config import Settings class MemoryStore: def __init__(self, pathdata/memory_db): self.client chromadb.PersistentClient(pathpath) self.collection self.client.get_or_create_collection( nameclaude_memories, metadata{hnsw:space: cosine} ) def add_memory(self, mem_id, content, category, importance, timestamp): embedding embed(content) # 本地 embedding 模型 self.collection.upsert( ids[mem_id], documents[content], metadatas[{ category: category, importance: importance, timestamp: timestamp, }], embeddings[embedding] )检索函数对应如下def search(self, query, top_k5, score_threshold0.55): query_embedding embed(query) results self.collection.query( query_embeddings[query_embedding], n_resultstop_k, include[documents, metadatas, distances] ) hits [] # ChromaDB 默认返回距离cosine 空间里 distance0 时最相似 for i in range(len(results[ids][0])): distance results[distances][0][i] similarity 1 - distance if similarity score_threshold: hits.append({ id: results[ids][0][i], content: results[documents][0][i], metadata: results[metadatas][0][i], similarity: similarity, }) return hits这里有一个关键点ChromaDB 的 distance 在不同距离算法下含义不同。cosine 空间的 distance 范围是 0 到 2相似度换算成 1 - distance。很多人第一次用都会在这里犯迷糊导致阈值判断反了记住这一点能省不少调试时间。3.4 记忆注入上下文注入逻辑是最后一步也是直接影响模型输出的环节。我会把检索到的记忆按固定格式拼装成一段“历史记忆”文本放在 system prompt 里。拼装模板大致如下以下是该用户的历史记忆供你参考。这些记忆来自过往对话可能与当前对话存在冲突。 如果发生冲突请以当前对话中的最新信息为准并在不确定时主动询问。 【项目背景】xxx 【决策记录】xxx 【用户偏好】xxx对应的代码def build_memory_context(memories): if not memories: return lines [] for m in memories: meta m[metadata] category_label { project_background: 项目背景, decision: 决策记录, user_preference: 用户偏好, progress: 进度节点, code_style: 代码规范, other: 其他, }.get(meta[category], 其他) lines.append(f【{category_label}】{m[content]}) context \n.join(lines) return f以下是历史记忆供参考\n{context}\n\n以上是历史记忆。拼接之后的整个请求就变成system prompt 放记忆 当前问题放 user message。之前我提过把记忆放到 system 里并标注冲突处理规则可以显著减少模型盲目采信旧记忆的问题。实际测试里加不加“如果冲突以当前信息为准”这句话模型对旧记忆的信任倾向差别很大加了之后更愿意主动向用户确认而不是自作主张。3.5 参数调优记录给一份我实际跑得比较顺的配置参考top_k 6 score_threshold 0.58 max_memory_items 2000 max_memory_chars 1200几个参数的含义top_k 控制每次注入最多带几条记忆score_threshold 是相似度门槛max_memory_items 是记忆库总条数上限超出后按时间淘汰最旧或按重要性淘汰不重要max_memory_chars 是注入文本的最大字符数防止上下文被记忆占太多反而挤掉当前问题空间。关于注入文本长度我强烈建议做一个硬性限制。如果一句话能说清楚就不要为记忆分配几十行空间。token 资源是有限的记忆不是越多越好而是“相关且精炼”最好。我见过有人 top_k 拉到 20结果一次请求光记忆就占了几千 token当前问题的发挥空间被严重挤压模型回答质量反而下降。4. 常见问题与排查技巧实录4.1 检索到不相关的记忆干扰回复我遇到最多的问题就是在新会话里检索出来的记忆跟当前问题八竿子打不着模型反而被带跑偏。有一次我问某个接口的传参细节系统却把半个月前某次闲聊中记录的“用户喜欢科幻小说”这条记忆带进了上下文模型的回答居然开始发散。排查下来有两个原因。一是 embedding 模型能力有限语义相近但主题不同的文本容易产生较高相似度二是 score_threshold 设得太宽松。解决办法是双管齐下提高阈值到 0.6 左右同时对记忆增加作用域标记也就是每条记忆归属某个项目域检索时只查当前域的集合。作用域隔离这一步我强烈建议加上能直接砍掉大半的跨项目污染。实现上就是在 metadata 里加一个 project_id 字段检索时用 where 条件过滤。4.2 上下文被记忆挤爆token 超限是另一个高频问题。记忆库越来越大后即使只有 top_k 条每条如果都是三五行长文一次灌进上下文也会吃掉很大一块 token。我的解决方式是两层。第一层是单条记忆长度限制抽取阶段就要求模型把每条 content 控制在 50 字以内超长的宁可拆分也不要一条长文。第二层是注入前做全局裁剪max_memory_chars 设置之后按 importance 降序取记忆重要性低的先剪掉。这样在有限的 token 预算里保留的信息优先级最高。实际执行下来单条 50 字以内的要求并不难达成模型很配合。4.3 同一事实记忆互相矛盾记忆系统跑一段时间后必然会出现互相矛盾的情况。比如用户第一次说“我不喜欢代码里出现魔法数字”后来又说“状态码可以直接写死”。两种说法都存进库里检索时同时命中模型就凌乱了。我的做法是引入记忆更新机制。每条记忆存一个来源时间戳在写入时先检索同 category、相似度较高的旧记忆。如果新的表述和旧记忆在语义上非常接近就用新记录覆盖旧记录并保留一条变更历史。如果新旧语义差别很大则作为两条独立记忆共存。这里确实很难自动判断谁对谁错保守策略是最稳妥的。用户也可以在界面上手动标注某条记忆作废我实际用下来手动干预的频率大概是每一到两周一次可控。4.4 调试记忆系统的一些实在建议记忆系统比普通脚本难调试因为问题往往不是“报错”而是“行为不对”。我的调试习惯是给系统开一个 debug 模式在每个请求的日志里打印出当前检索到的记忆列表包括每条记忆的相似度分数。当模型回复不满意时先看日志里到底注入了什么记忆再判断是检索问题还是注入问题。没有这个日志排查起来就是无头苍蝇。另外建议定期查看记忆库内容用最朴实的方式列出全部记忆检查有没有明显的重复项和垃圾记忆。我在实际使用里每个月底会做一次清理对长期不用的记忆先标记降权再过一个月如果依然没有命中就可以删除。这个操作像是给记忆库做一次“搬家整理”长期价值非常大。最后分享一个挺实用的小技巧把特别重要的项目规范手动添加到记忆库里并显式标注 importance1.0、categorycode_style。这样即使它的语义相似度不是最高排序权重也能保证它每次都出现在注入列表里。相当于给系统记忆打了一个“置顶”标签。我个人的体会是claude-mem 这类记忆系统的核心不在代码多巧妙而在对记忆质量和检索策略的控制。做第一次原型很容易做好长期可用需要靠打磨阈值、维护记忆内容和持续清理来解决。后续如果你打算继续扩展可以把记忆从纯文本向量库升级成结构化的项目知识图谱让“记忆”之间产生关联那是另一个有意思的阶段了。
