claude-mem 是我最近在折腾的一个项目名字就是字面意思给 Claude 补上一块长期记忆。起因特别简单我用 Claude 做日常知识管理和代码辅助的时候发现同样的问题每次都要重新解释一遍。比如上周让它帮我看过某个项目的目录结构这周再问它它完全不记得了。这不是模型笨而是架构如此。大模型的上下文窗口只是在一次会话内部临时保存信息会话结束一切归零。claude-mem 想做的事情就是把这部分会蒸发的内容变成可以持久化、可以检索、可以自动注回对话里的“外挂记忆”。这个项目适合谁我觉得三类人最需要一是重度使用 Claude API 做工具的开发者二是正在搭 Agent 应用、希望智能体能记住用户偏好和项目状态的团队三是想给自己搞一个“第二大脑”但不想手动复制粘贴历史记录的人。后面我会把整个设计思路、踩坑过程、最小可复现的代码都写出来。如果你觉得“记忆”就是“把聊天记录存下来”那可能误会更深了。下面先聊聊我为什么会觉得这个问题值得专门做一个项目。1. 项目背后的真实需求大模型会话记忆的痛点1.1 上下文窗口不是记忆很多人在聊大模型记忆时容易把“上下文窗口”和“记忆”混在一起。上下文窗口类似一个临时的会议白板模型能看到的全部内容都写在这块白板上。白板足够大几百页纸都能贴上去但会议结束白板会被擦掉。Claude 的 API 本身就是无状态的你发一个请求它返回一个响应这中间没有任何“上次聊过什么”的概念。即便你在请求里带上历史记录那也只是你手动把白板重新画了一遍。所以长期记忆本质上是一个外部存储问题。你需要一个数据库把对话里的关键信息抽出来下次对话前再根据当前问题把相关记忆重新摆回白板。听起来不难但真正做起来会发现难的点在于“抽什么”“存成什么样”“怎么保证下次一定找得到”以及“怎么不让记忆把上下文窗口撑爆”。claude-mem 这个项目的核心就是把这一套流程自动化。我最早尝试过一个很蠢的方案每次对话结束后把整段对话追加到一个本地 Markdown 文件里下一次请求时把 Markdown 全文塞进 system prompt。结果用了不到一周就崩了因为文件越来越长请求越来越贵而且模型经常被无关历史干扰甚至出现“回答你今天中午吃的什么”从旧日志里翻出三天前的天气情况这种荒诞结果。1.2 现有“手工记忆”方案有多痛当时的替代方案不外乎三种第一种是手工维护一份“关于我”的文档让模型每次先读它第二种是每次对话都手动把关键信息粘贴进去第三种是干脆不用记忆每次从零开始解释背景。这三种我都试过各有各的痛点。手工维护文档最核心的问题是不及时。你在对话中产生的新偏好比如“以后所有代码注释都用中文”“这个项目不要用 Redis改用 PostgreSQL”你很难做到当场更新文档。一旦忘了模型下次就会继续按旧偏好执行。手动粘贴则非常考验人你根本不知道哪些信息该粘。粘少了模型记不住粘多了又刷掉真正重要的内容。而且人会有路径依赖同一个信息可能被以不同说法反复粘进去最后 system prompt 里全是冗余。不做记忆就更直接每个新会话都是一次“重新做人”。尤其是做 Agent 类应用用户可能连续几天都在处理同一个复杂任务如果 Agent 记不住上一个会话已经做到哪一步整个任务的连续性就完全断了。所以 claude-mem 的设计目标很明确自动从对话中提取值得记住的内容结构化存储然后在需要时把最相关的记忆拼回上下文。它不是聊天记录存档而是一个记忆管理系统。2. claude-mem 的核心设计记忆要能自动沉淀2.1 记忆抽取让模型自己归纳要记什么第一步要解决“该记什么”的问题。常规做法是拿规则做关键词抽取比如出现“我叫”就提取名字出现“不要用”就提取偏好。但真实对话里的信息远没有那么规整用户可能说的是“我觉得这个方案不太好换掉吧”规则就很难判断这是情绪还是决策。我采用的是让 Claude 自己抽取记忆。具体来说每次对话结束后我会把最近几轮对话历史单独发给模型用一个固定 prompt 要求它输出结构化 JSON。这个 prompt 的大致意思是从这段对话里提取四类信息——事实、偏好、任务状态、代码约定并给出置信度评分。这背后的直觉是模型理解语义的能力远强于规则引擎它能区分“今天天气不错”这种一次性闲聊和“我已经把认证模块改成 JWT 了”这种需要长期保留的项目状态。它还能对信息做归一化比如用户某次说“你以后别叫我王总喊老王就行”模型能意识到这是偏好并把它整理成“对用户的称呼老王”。这里有个很关键的细节抽取完成后我不会把全部结果都写入记忆库而是先做一次过滤。置信度低于某个阈值的信息直接丢弃某些明显只跟当前事物相关的临场信息比如“现在几点了”的答案也不应该进入长期记忆。这个过滤规则简单但能避免很多记忆污染。2.2 记忆存储向量库和关系表各干各的记忆抽取出来之后怎么存一开始我图省事想把所有内容都塞进一个 SQLite 表。后来发现不行。原因很简单记忆的检索方式分两种一种是精确匹配一种是语义匹配。比如用户名字“老王”项目路径“/home/wang/projects/auth”这类信息适合用关系表存储字段清晰查询时可以精确等于。但“用户对这个项目很有感情希望保留原有接口风格”这种描述性记忆就没有哪个字段能精确匹配只能靠语义搜索。 所以 claude-mem 的存储层用了双轨制一个 SQLite 数据库存结构化事实一个轻量向量数据库存语义化记忆片段。向量数据库的选择上我用的是 Chroma。主要原因是它轻量、不需要单独起服务可以嵌入式运行非常适合个人工具和小型团队内部应用。如果以后数据量真的到了百万级再迁移到专门的向量库也不迟接口差异不大。结构化表这边我设计了几个核心字段记忆 ID、类型、内容、命名空间、创建时间、更新时间、来源会话 ID、置信度。其中“命名空间”特别重要后面会单独讲。2.3 记忆注入在有限的上下文里挑最相关的记忆存进去还不够关键是下次对话时怎么把它取回来。取回的难点不在于“能把所有记忆都塞回去”而在于“只塞最需要的那些”。我一开始做过一个反面样例把所有记忆按时间倒序把最近的 20 条全部拼进 system prompt。结果模型反而被大量无关记忆干扰。比如用户今天在做后端调试记忆库里却躺着上周三讨论前端配色方案的内容模型居然会尝试把配色建议应用在后端日志里非常离谱。后来我把注入流程改成了“召回-排序-裁剪”三步。第一步根据当前用户问题做一个向量查询把语义相关的记忆候选捞出来。第二步把候选按相关度、时间新鲜度、置信度综合排序。第三步设置一个 token 预算比如 3000 token从上往下往 prompt 里加加满为止超出的先不放。这里有个经验数据一条记忆平均大概 100 到 300 token3000 token 预算大约能容纳 10 到 30 条。如果遇到真正需要大量背景信息的场景比如让助手继续上一个大型重构任务可以临时把预算提高到 8000但尽量别超过总上下文的一半。因为模型还要留空间给当前问题和推理过程。3. 从零实现一个最小可用的 claude-mem3.1 环境准备与项目结构真正动手写的时候我没有一上来就做完整框架而是先搭了一个最小可用版本。环境方面需要 Python 3.10 以上因为后面用到了新的类型语法。依赖安装了四个核心库anthropic、chromadb、sqlalchemy、pydantic。项目结构很简单claude-mem/ ├── mem/ │ ├── __init__.py │ ├── models.py │ ├── store.py │ ├── extract.py │ └── inject.py ├── cli.py └── config.yamlmodels.py 放数据模型store.py 负责读写 SQLite 和向量库extract.py 负责调用 Claude 抽取记忆inject.py 负责把记忆拼回 system prompt。cli.py 做命令行入口。这样分层的好处是每个模块的职责单一后面替换某一个实现不会牵连到其他部分。3.2 数据模型与写入流程在 store.py 里我先定义了结构化记忆的模型from sqlalchemy import create_engine, Column, String, Float, Integer, DateTime, Text from sqlalchemy.ext.declarative import declarative_base from datetime import datetime Base declarative_base() class MemoryItem(Base): __tablename__ memory_items id Column(Integer, primary_keyTrue) namespace Column(String(64), indexTrue) memory_type Column(String(32), indexTrue) # fact / preference / task / code content Column(Text) confidence Column(Float, default0.8) source_session Column(String(128)) created_at Column(DateTime, defaultdatetime.utcnow) updated_at Column(DateTime, defaultdatetime.utcnow, onupdatedatetime.utcnow)写入流程是先检查是否已有相同命名空间下高度相似的内容有的话就更新没有才新插入。这步看似简单但对于避免重复记忆至关重要。向量库这边我用 Chroma 存语义记忆时也保留了同一个 memory_id 作为关联键。这样关系表和向量库就能一一对起来删除或更新时可以联动处理。3.3 挂到 Claude 的调用链路上为了让 Claude 能使用记忆我写了一个简单的包装函数。核心逻辑是在每次真正调用 model 之前先根据用户输入去记忆库查询把结果注入 system prompt在模型返回之后再异步地把这段对话交给抽取模块处理沉淀新记忆。def chat_with_memory(user_message: str, user_id: str default): ns user_id context_memories query_relevant_memories(user_message, namespacens) system_prompt build_system_prompt(context_memories) response call_claude(system_prompt, user_message) # 异步抽取记忆避免阻塞用户 extract_and_save(user_message, response, namespacens) return response这个流程里最有争议的点是抽取应该放在响应后同步做还是异步做。我最终选择了异步。因为抽取本身也是一次 Claude 调用耗时可能跟主回答一样长如果放在主流程里用户会明显感到延迟。异步放在后台即使用户马上关闭程序记忆也会在退出前通过队列尽量写完。build_system_prompt 函数会做 token 估算。我没有用很高精度的 tokenizer而是采用一个近似方法中文字符大约 1.5 到 2 个 token英文单词大约 1 到 1.5 个 token。按保守估算给每条记忆分配 200 token给整个记忆区分配 3000 token。3.4 日常操作命令行交互怎么设计光有 Python API 还不够日常使用还是命令行最顺手。我加了一个 cli.py支持几个子命令python cli.py ask 当前数据库配置是什么 python cli.py add 用户偏好所有接口返回 JSON 格式 python cli.py search 数据库 python cli.py stats python cli.py drop --namespace testask 命令会走完整的记忆注入流程add 命令则允许手动添加一条记忆search 用来验证召回效果stats 输出当前各类型记忆数量。手动添加很必要因为不是所有值得记的信息都一定出现在对话里用户可能会有意识地沉淀一些自己的背景。4. 方案选型实录哪些坑我在项目里踩过4.1 记忆库里不能只放向量这个坑我印象特别深。最初我天真地以为向量数据库能解决所有检索问题于是把所有记忆统一转成 embedding 存进去。结果在使用过程中遇到一个典型的翻车场景用户问“这个项目数据库怎么连”向量召回返回了一条“之前项目用过 Redis连接地址是 xxx”但没有任何一条记忆提到当前项目已经改用 PostgreSQL。因为“数据库”和“Redis”语义上相关向量检索就把旧项目的记忆拉出来了但事实完全错了。后来我意识到长期记忆里的信息分两种一种是客观事实适合精确匹配一种是语义描述适合模糊召回。混合检索是必须的。现在的做法是凡是能结构化成字段的比如项目名、端口号、技术栈选型、用户称呼都放进 SQLite 关系表通过精确查询拿凡是长段落的决策原因、讨论过程、写作风格才放进向量库。在 query 阶段我会同时跑两个查询关系表里精确过滤向量库做语义搜索然后把两边的结果合并去重。合并时优先保留精确匹配的命中再按相关度补充向量命中。这套混合方案的召回质量比单纯用向量库高了一大截。4.2 新旧记忆冲突怎么处理记忆是动态的用户会改主意项目也会调整方向。如果旧记忆和新记忆同时存在模型就会精神分裂。我处理冲突的原则很简单时间戳大的优先置信度高的优先但两者冲突时时间优先。具体实现时每次写入新记忆前我会先按内容和命名空间做一次相似度搜索。如果找到相似度超过 0.85 的旧记忆就判断为“同一主题的更新”直接用新内容覆盖旧内容同时保留一个更新时间。如果相似度在 0.6 到 0.85 之间则说明可能相关但不是同一件事我会选择插入新记忆不覆盖旧的。这个阈值是我反复试出来的。阈值设太高比如 0.95几乎没有记忆会被覆盖旧信息和新信息容易共存设太低比如 0.5又容易误伤把“用户喜欢偏激进的接口命名”和“用户喜欢激进的配色”当成同一件事。0.85 是个相对合理的平衡点适合大多数个人知识库场景。4.3 成本、延迟与上下文窗口的平衡长期记忆看起来很美但每一步都要花钱。抽取记忆需要额外调用一次 Claude向量化需要调用 embedding 模型如果把记忆注入和主对话再做一次合并总延迟会比普通对话高出不少。所以我在设计里明确分了轻重缓急。用户主动等待的只有主对话。记忆抽取走后台异步不参与关键路径。向量化现在用的是本地轻量模型虽然效果不如商业 embedding API但对个人项目足够。我测试过本地向量化一条几百字的记忆耗时大概几十毫秒完全不必为此引入额外网络依赖。上下文窗口的控制上我在 config.yaml 里暴露了两个参数max_memory_token 和 min_recall_score。默认值分别是 3000 和 0.65。调高 min_recall_score 会减少召回的噪声但也可能漏掉潜在相关记忆调低则容易引入干扰。如果发现模型被无关记忆带偏先检查这个阈值是否太低。4.4 多用户多项目隔离别忘掉做 claude-mem 的前几天我只用一个命名空间数据全是自己的没出问题。直到我把它分享给朋友用才发现如果不做隔离所有人的记忆会混在一起。A 用户说“我对海鲜过敏”B 用户问“附近有什么好吃的”可能出现 A 的过敏信息被召回并被错误地当成 B 的偏好。解决办法就是前面提到的 namespace 字段。每次读写记忆时必须在查询条件里带上 namespace。我一般用 user_id project_name 组合作为命名空间比如 “wang:blog-system”这样既能区分用户又能区分项目。这个隔离不仅要写在应用层还要体现在向量库里。Chroma 支持按 metadata 过滤我在每条向量写入时都添加了 namespace metadata查询时用 where 参数强制过滤。这一步不能省否则迟早会出事故。5. 常见问题排查与优化技巧5.1 高频问题速查表这里整理一下我在使用和调试 claude-mem 过程中遇到的典型问题以及对应的处理方案。现象可能原因处理方式对话里出现旧项目的信息向量召回没有按 namespace 过滤检查 Chroma 查询的 where 条件是否包含 namespace记忆库里重复内容很多写入前没有做相似度去重比对 embedding 相似度超过 0.85 优先覆盖更新模型回答被无关记忆干扰min_recall_score 设得太低调高阈值同时检查召回排序逻辑上下文超长报错max_memory_token 超过限制显式降低 max_memory_token优先保留高相关度记忆后台抽取任务经常失败网络抖动或接口并发限制增加重试机制使用指数退避一条记忆改了旧版本还在更新时没有同步删除向量库旧向量根据 memory_id 联动删除旧向量再插入新向量5.2 记忆库的“可视化”调试法调试记忆系统最痛苦的事情是“黑盒”。你不知道模型到底看到了哪些记忆也就不知道该从哪个方向排查。所以我给 claude-mem 加了一个 debug 模式在正常的 ask 请求里把注入后的 system prompt 完整打出来。打开 debug 后你可以直接看到模型面前站着哪些记忆它们的相关度排序是多少被截断的记忆有哪些。这个信息比任何日志都有用。我甚至有两次发现所谓“模型回答错误”根本和记忆无关是 prompt 里夹杂了一条置信度极低、相关度却很靠前的旧记忆那条记忆还是之前测试时偶然存进去的。可视化还有一个用途统计每个类型的记忆占比。如果你发现 preference 类型占了 80%那说明抽取 prompt 里对偏好类信息的引导过于强烈需要调整抽取 prompt 的平衡。记忆库的结构应该尽量贴合实际使用场景而不是模型天然的抽取倾向。5.3 把性能做上去的几个小改动claude-mem 一开始的性能并不好主要体现在对话延迟上。虽然抽取是异步的但主对话前的记忆查询是同步的而且关系表查询和向量查询串行执行两者加一起需要几百毫秒到一秒。优化手段有三个。第一把向量查询和关系表查询改成并行执行Python 里用 ThreadPoolExecutor 就能做到总耗时按最慢的那个算。第二对热点记忆加一层缓存比如用户在连续十几轮里反复问同一个项目状态时不需要每次都重新查询向量库直接命中缓存。缓存的失效策略用简单的最后访问时间即可。第三延迟加载 embedding 模型第一次调用才加载避免每次启动 CLI 都白等几十毫秒。这三个改动做完记忆查询的延迟从接近一秒降到了两三百毫秒。对大多数应用来说这个量级已经不太能被感知了。6. 后续还可以怎么玩6.1 从个人记忆扩展到团队知识库单用户的 claude-mem 跑顺之后我第一个想到的扩展方向是团队共享记忆。比如团队里接入同一个 Claude 机器人每个成员提问时机器人可以共享项目级别的事实信息但用户偏好保持隔离。这其实不需要改太多逻辑只需要把 namespace 分成两层项目级和用户级项目级记忆对所有成员可见用户级记忆只对本人可见。这里要特别说明团队共享记忆会放大记忆污染的危害。一个人说错的信息可能被整个团队当成事实。所以团队场景下置信度阈值要调得更高并且要加上“谁写入的”这个来源字段。我曾经在内部小范围试过发现如果没有来源记录用户很难信任机器人的回答因为不知道它依据的是哪条记忆这条记忆是谁提供的。6.2 给 Agent 装上“跨会话执行”的能力claude-mem 其实很适合嵌入到 Agent 框架里。Agent 经常需要分多步完成一个任务如果每一步都重新开一个会话那它就会丢失“目前已经做到第几步”的状态。把任务状态作为记忆存下来下次会话开始时自动读取Agent 就能像人一样“回来接着干”。比如代码重构助手用户第一会话让它识别项目中所有硬编码的数据库连接字符串它记录下了十几个位置第二会话用户又说“顺便把连接池也统一改一下”助手如果记得之前的扫描结果就能直接基于这些信息展开而不是重新扫描一次。这种连续性对实际工作流的价值非常大。6.3 我自己的实际体会和下一步计划跑了一段时间之后我对长期记忆这件事最深的体会是真正难的不是“存下来”而是“想清楚什么时候该忘掉”。如果只管存、不管删记忆库迟早被过期信息填满甚至污染模型的判断。我现在计划给 claude-mem 加一个定期清理机制对超过 90 天且置信度低于 0.7 的记忆做归档对用户主动标记为“废弃”的记忆直接删除。长期记忆系统应该像人的记忆一样有沉淀也有遗忘只留下那些真正经得起时间考验的信息。如果你也在做类似的事情我建议从最小版本开始先跑通抽取、存储、召回、注入这条链路再考虑复杂的数据结构和分布式方案。把时间花在实际对话的调优上比在设计完美架构上推演更有价值。