claude-mem 实战：为 Claude 构建长期记忆系统，解决跨会话上下文重建

1. 从零认识 claude-mem：它到底解决什么问题

第一次看到claude-mem这个名字，很多人会以为它又是一个套壳的对话客户端。其实不是。claude-mem的核心定位是给 Claude 这类大模型补上一块“长期记忆”的拼图——让模型在跨会话、跨项目的场景下，记住你之前告诉过它的偏好、约定、项目背景和踩过的坑，而不是每次开新对话都从一张白纸开始。

我接触这个方向，是因为自己长期用 Claude 做代码辅助和文档整理。用久了就发现一个很痛的点：每次新开一个会话，我都得重新交代一遍“我的项目用 TypeScript 严格模式”“日志统一走 pino”“不要给我写 any”“数据库迁移用 drizzle 而不是 prisma”。这些信息本身不复杂，但重复输入几十次之后，人会非常烦躁，而且一旦漏说，模型给出的代码风格就会跑偏。claude-mem这类工具要解决的，正是这种“上下文反复重建”的浪费。

从关键词claude-mem本身能拆出两个核心语义：一个是Claude，指向以 Claude 为代表的对话式大模型使用场景；另一个是mem，也就是 memory，记忆。合在一起，它描述的是一套围绕 Claude 构建的记忆管理机制。它适合谁？我认为有三类人特别值得关注：第一类是每天高频使用 Claude 写代码、写文档的开发者；第二类是需要模型长期跟踪某个项目背景的产品或运营同学；第三类是想自己动手搭一套本地记忆系统、对 RAG 和向量检索有兴趣的技术爱好者。

需要先说明一点：claude-mem并不是官方内置的某个开关，而更像是一类“记忆层”方案的统称。不同实现思路差别很大，有的走本地文件加检索，有的走向量数据库，有的干脆用结构化的 Markdown 做人工可读的记忆库。下面我会把这类方案的通用设计思路、核心实现细节、实操流程和踩坑经验完整拆开讲，你可以直接照着复现一套属于自己的记忆系统。

2. 记忆系统的整体设计与方案选型

2.1 为什么不能只靠“把历史对话全塞进去”

最朴素的想法是：既然模型有上下文窗口，那我每次把之前所有对话都拼进去不就行了？实测下来这条路走不通，原因有三个。

第一是成本。上下文越长，每次请求消耗的 token 越多，费用是线性甚至超线性上涨的。你不可能为了记住一句“我用 pnpm”，每次都把几万字的聊天记录重新发一遍。

第二是噪声。历史对话里大量内容是寒暄、试错、被否决的方案。这些信息混进去，反而会干扰模型判断，让它把已经废弃的结论当成当前约定。

第三是窗口上限。再大的上下文窗口也有尽头，而一个长期项目的记忆是持续增长的，早晚会溢出。

所以正确的思路不是“全量塞入”，而是“按需检索”：把记忆存到外部，每次对话时只把和当前问题最相关的那几条捞出来，拼进上下文。这就是claude-mem这类方案的基本骨架。

2.2 三种主流实现路线对比

在动手之前，先选路线。我把常见的三种方案整理成表，方便你按自己的情况挑。

我的建议是：先从文件记忆法起步，跑通流程后再升级到混合分层法。一上来就搞向量库，很容易在嵌入模型选型、维度对齐、检索阈值调参上卡住，反而看不到效果。先用最简单的方案验证“记忆确实有用”，再逐步加复杂度，这是我一贯的推进节奏。

2.3 记忆应该分几层

不管走哪条路线，记忆内容本身建议分成三层来管理，这是我在多个项目里验证过比较稳的结构。

• 全局偏好层：跨项目通用的约定，比如“回答用中文”“代码注释用英文”“不要输出 emoji”。这层内容少、变动慢，可以每次全量注入。
• 项目背景层：某个具体项目的技术栈、目录结构、命名规范、依赖版本。这层按项目隔离，切换项目时只加载对应部分。
• 会话临时层：当前这次对话里新产生的结论，比如“刚才决定把接口改成 POST”。这层生命周期短，会话结束时可选择性地沉淀到项目层。

分层的好处是召回时可以做优先级裁剪：全局层永远带上，项目层按当前工作目录匹配，临时层只在同一会话内有效。这样既保证了关键信息不丢，又不会让上下文无限膨胀。

3. 核心细节解析与实操要点

3.1 记忆条目的数据结构设计

记忆系统好不好用，一半取决于数据结构设计。我踩过的最大坑，就是早期把记忆存成一大段自由文本，结果检索时根本没法精确定位。后来改成结构化条目，体验立刻不一样。

一条记忆建议至少包含这几个字段：

{ "id": "mem_20240115_001", "scope": "project", "project": "my-api-service", "type": "preference", "content": "数据库迁移统一使用 drizzle，禁止引入 prisma", "tags": ["database", "migration", "tooling"], "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z", "hit_count": 0, "confidence": 0.9 }

这里几个字段的设计意图值得说明。scope决定这条记忆在什么范围内生效，是全局还是某个项目。type用来区分是偏好、事实还是待办，检索时可以按类型过滤。tags是关键词索引，文件记忆法靠它做匹配，向量法里它也能作为元数据过滤条件。hit_count记录这条记忆被召回多少次，长期没被命中的条目可以考虑归档，避免记忆库无限膨胀。confidence是我后来加的，因为有些结论是模型推测出来的，可信度低，召回时应该降权。

注意：content字段一定要写成完整、自包含的陈述句，不要写成“同上”“见前面”这种依赖上下文的碎片。因为记忆被召回时是脱离原始对话的，碎片化内容会让模型一头雾水。

3.2 写入时机：什么时候该记，什么时候不该记

记忆系统最容易失控的地方，是什么都往里塞。我早期版本就是每轮对话结束自动抽取记忆，结果一周下来存了三百多条，其中一半是“用户说了谢谢”“用户表示同意”这种毫无价值的噪声。

后来我总结了一套写入判断标准，只有满足以下条件之一才写入：

• 明确的偏好声明：用户说“以后都……”“统一用……”“不要……”。
• 项目关键决策：确定了技术选型、接口约定、目录规范。
• 反复出现的纠正：同一个问题用户纠正了两次以上，说明这是稳定预期。
• 显式的记忆指令：用户直接说“记住这个”。

反过来，以下内容坚决不记：寒暄、情绪表达、一次性的临时问题、模型自己的推测（除非用户确认）。

实操上，我建议写入前做一次确认。可以在对话里加一句“我把这条记下来了：xxx，对吗？”，让用户有机会纠正。这个确认动作看起来啰嗦，但能极大提升记忆库的准确率，避免错误记忆被反复召回、越滚越偏。

3.3 召回策略：怎么把对的记忆捞出来

召回是记忆系统的核心。文件记忆法里，最简单的做法是关键词匹配加标签过滤；向量法里，则是把当前问题转成向量，和记忆库做相似度检索。两种方式我都用过，说说各自的调参心得。

关键词匹配的坑在于同义词。用户记忆里写的是“数据库迁移”，当前问题说的是“schema 变更”，字面不匹配就召不回。解决办法是维护一个同义词表，或者干脆在写入时让模型自动生成多个标签。

向量检索的坑在于阈值。相似度阈值设太高，召不回相关记忆；设太低，会捞出一堆似是而非的内容。我的经验是阈值设在 0.75 到 0.82 之间比较稳，具体要看嵌入模型。另外一定要限制召回条数，我一般设 top 5 到 top 8，再多就是噪声了。

还有一个容易被忽略的点：召回结果要排序。我通常按“全局层优先、项目层次之、临时层最后”的顺序拼进上下文，同一层内按相似度或hit_count排序。这样模型看到的信息是有层次的，不会把临时结论误当成长期约定。

3.4 记忆的更新与冲突处理

记忆不是只增不减的。同一个偏好可能被用户改主意，比如“之前说用 pnpm，现在改用 bun 了”。这时候如果两条记忆都在库里，召回时就会打架。

我的处理方式是软删除加版本链。新记忆写入时，先检索是否有同scope、同type、tags高度重叠的旧条目。如果有，把旧条目标记为deprecated，并让新条目通过supersedes字段指向它。召回时只取未废弃的条目。这样既保留了历史，又不会让冲突信息同时出现。

提示：千万不要直接物理删除旧记忆。有时候用户会反悔，说“还是用回原来的方案吧”，这时候历史版本就是救命的。保留版本链的成本很低，收益却很高。

4. 实操过程与核心环节实现

4.1 环境准备与目录结构

下面我以文件记忆法为例，走一遍完整实现。这套方案零外部依赖，用 Python 就能跑，适合先跑通概念。

先建目录结构：

mkdir -p claude-mem/{global,projects,index} touch claude-mem/global/preferences.json touch claude-mem/projects/.gitkeep

目录设计上，global放全局偏好，projects下按项目名建子目录，index放检索用的倒排索引或缓存。每个项目目录里再分background.json（项目背景）和sessions/（会话沉淀）。

4.2 记忆写入模块实现

写入模块的核心逻辑是：接收一条候选记忆，判断是否值得存，去重后落盘。

import json import os from datetime import datetime MEM_ROOT = "claude-mem" def load_json(path): if not os.path.exists(path): return [] with open(path, "r", encoding="utf-8") as f: return json.load(f) def save_json(path, data): os.makedirs(os.path.dirname(path), exist_ok=True) with open(path, "w", encoding="utf-8") as f: json.dump(data, f, ensure_ascii=False, indent=2) def write_memory(scope, project, mem_type, content, tags, confidence=0.9): if scope == "global": path = f"{MEM_ROOT}/global/preferences.json" else: path = f"{MEM_ROOT}/projects/{project}/background.json" memories = load_json(path) # 冲突检测：同类型且标签重叠度高的旧记忆标记为废弃 for m in memories: if m["type"] == mem_type and len(set(m["tags"]) & set(tags)) >= 2: m["deprecated"] = True new_mem = { "id": f"mem_{datetime.now().strftime('%Y%m%d%H%M%S')}", "scope": scope, "project": project, "type": mem_type, "content": content, "tags": tags, "created_at": datetime.now().isoformat(), "hit_count": 0, "confidence": confidence, "deprecated": False } memories.append(new_mem) save_json(path, memories) return new_mem["id"]

这段代码里，冲突检测用的是“标签重叠数大于等于 2”作为判断条件。这个阈值是我调出来的：设成 1 太敏感，稍微沾边就废弃；设成 3 又太迟钝，明显冲突的记忆识别不出来。2 是个比较平衡的值，你可以根据自己的记忆粒度微调。

4.3 记忆召回模块实现

召回模块负责根据当前问题，从记忆库里挑出最相关的条目。

def recall(query, project=None, top_k=6): results = [] # 全局层永远带上 global_mems = load_json(f"{MEM_ROOT}/global/preferences.json") results.extend([m for m in global_mems if not m.get("deprecated")]) # 项目层按标签匹配 if project: proj_mems = load_json(f"{MEM_ROOT}/projects/{project}/background.json") query_terms = set(query.lower().split()) scored = [] for m in proj_mems: if m.get("deprecated"): continue overlap = len(query_terms & set(t.lower() for t in m["tags"])) if overlap > 0: scored.append((overlap * m["confidence"], m)) scored.sort(key=lambda x: x[0], reverse=True) results.extend([m for _, m in scored[:top_k]]) return results def format_for_prompt(memories): lines = ["以下是需要遵守的长期约定："] for m in memories: lines.append(f"- [{m['type']}] {m['content']}") return "\n".join(lines)

召回时全局层无条件带上，是因为全局偏好通常只有几条，成本极低但价值很高。项目层才做相关性筛选。format_for_prompt把记忆拼成一段简洁的提示词，直接塞进系统提示或对话开头即可。

4.4 接入对话流程

把写入和召回接到实际对话里，流程是这样的：

1. 用户发来问题。
2. 调用recall(query, project)拿到相关记忆。
3. 用format_for_prompt拼成提示词，放在系统消息里。
4. 把用户问题和提示词一起发给模型。
5. 模型回答后，判断本轮是否产生了值得记录的内容。
6. 如果有，调用write_memory落盘。

第 5 步的判断可以交给模型自己做，给它一个简单的指令：“如果本轮对话产生了新的长期约定或项目决策，请以 JSON 格式输出，否则输出空。”这样就把记忆抽取自动化了，不用人工干预。

实操心得：第 5 步的自动抽取建议加一道人工确认。我早期全自动跑，结果模型把一些临时讨论也当成决策记了下来，污染了记忆库。后来改成“模型抽取后先展示给用户确认，用户点确认才落盘”，准确率提升非常明显。

5. 常见问题与排查技巧实录

5.1 记忆召回了但模型不遵守

这是最常见的问题。你明明把“不要用 any”召回了，模型还是写了any。原因通常有两个：一是记忆在提示词里的位置太靠后，被长对话稀释了；二是记忆表述太弱，模型没当回事。

解决办法：把记忆放在系统提示的最前面，并且用明确的祈使句表述，比如“禁止使用 any 类型”而不是“用户倾向于不使用 any”。祈使句的约束力明显更强。另外可以在提示词里加一句“以上约定优先级高于本轮对话中的临时要求”，强化权重。

5.2 记忆库越来越大，召回变慢

文件记忆法在条目超过几百条后，全量加载和匹配会变慢。这时候有两个方向：一是给记忆加索引，把tags抽出来建倒排表，检索时先查索引再加载具体条目；二是做归档，把hit_count长期为 0 且超过 90 天的条目移到archive目录，不参与日常召回。

我一般两个都做。倒排索引解决速度问题，归档解决规模问题。归档阈值我设的是“90 天未命中”，这个值可以根据项目节奏调整，快节奏项目可以缩到 30 天。

5.3 不同项目的记忆互相串味

如果你同时维护多个项目，一定要确保召回时严格按项目隔离。我踩过的坑是早期没做隔离，结果 A 项目的“用 MySQL”被召回进了 B 项目，导致 B 项目里模型建议用 MySQL，而 B 实际用的是 PostgreSQL。

隔离的关键是：项目层记忆的路径必须包含项目标识，召回时只加载当前项目目录。全局层可以共享，但全局层里只放真正跨项目通用的内容，比如语言偏好、输出格式，绝不放技术选型。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑是把模型的推测当事实存。有次模型自己推断“你大概想用 Redis 做缓存”，我顺手存了，结果后面每次都被召回，搞得像是我真的决定用 Redis 一样。后来我规定：只有用户明确确认的内容才能写入，模型推测一律不存。

第二个坑是记忆内容太长。早期我喜欢把整段讨论都存进去，结果召回时一条记忆就占几百 token。后来强制要求每条记忆不超过 50 字，逼着自己提炼核心。短记忆不仅省 token，召回精度也更高。

第三个坑是忘了更新。用户改了技术栈，旧记忆没废弃，新记忆又没写，导致模型用的是过时信息。现在我养成了习惯：每次用户说“改成……”“换成……”的时候，立刻触发一次记忆更新，把旧条目标废弃、写新条目。

6. 从文件法升级到混合分层法

跑通文件法之后，如果你觉得关键词匹配不够精准，可以升级到混合分层法。核心改动是在文件存储之上加一层向量索引。

具体做法是：每条记忆写入时，除了落盘 JSON，还把content通过嵌入模型转成向量，存进向量库（本地可以用 faiss 或 chroma）。召回时先用向量检索拿到候选，再用标签做二次过滤，最后按分层优先级排序。

嵌入模型的选择上，我建议用轻量的本地模型，比如 bge-small 这类，几百 MB 就能跑，中文效果也够用。没必要上大模型，记忆检索对嵌入精度的要求没有想象中那么高，速度和成本更重要。

升级过程中要注意向量和原文的一致性。记忆更新时，向量也要同步更新，否则会出现“原文改了但向量还是旧的”这种诡异情况。我的做法是把向量 ID 和记忆 ID 绑定，更新记忆时按 ID 覆盖向量。

混合分层法跑顺之后，召回准确率相比纯关键词能提升一大截，尤其是用户表述和记忆标签用词不一致的场景。代价是多了一个向量库的维护成本，以及嵌入模型首次加载的等待时间。这笔账划不划算，取决于你的记忆规模和使用频率。记忆条目上百、每天高频使用，升级就值；只是偶尔用用，文件法足够了。

最后分享一个我一直在用的小技巧：每周花五分钟翻一遍记忆库，手动删掉明显过时或错误的条目。自动化的冲突检测再聪明，也比不上人眼扫一遍。这五分钟的投入，能省下后面无数次被错误记忆带偏的麻烦。