看着昨天的对话记录我脑子里全是“上次那个迁移方案第 6 条细节我们不是讨论过吗”的念头可新会话里的 Claude 完全想不起来这件事。我试过把聊天记录导出、整理、复制粘贴塞回去但窗口一长就乱真正想让它记住的决策反而沉在底部。后来我动手做了一个小工具代号叫 claude-mem本质是一个给 Claude 这类对话模型补“长期记忆”的轻量中间层。它会自动把对话里值得留的东西抽出来沉淀成本地记忆下次打开新会话时先检索、再注入上下文相当于给失忆的顾问配了个每次入场前递小抄的助理。这篇文章把我从零到一实现 claude-mem 的全部过程、关键设计和踩坑记录写清楚。如果你也是那种天天跟模型对话聊方案、写代码、记决策的人又实在受不了“每次都得重新自我介绍”的体验这篇内容应该能直接帮你搭一套可用的记忆侧车不依赖重型数据库也不涉及复杂的平台改造。1. 为什么模型总是“转头就忘”无状态 API 与一次性窗口的真相1.1 一个让我决定动手的典型场景我当时在一个数据迁移项目里白天跟 Claude 梳理了完整的迁移顺序先做 schema 兼容检查再开双写最后灰度切流还在对话里确认了第 6 条检查项的执行细则。晚上合上电脑第二天早上打算继续发现新会话里它问我“你的迁移方案是什么能描述一下吗”。我说“昨天不是谈过吗”它回“我们还没有在本次对话中讨论过这个主题”。这个瞬间非常让人崩溃但冷静下来想这不怪模型笨。每次调用模型 API 时服务端就是无状态的它只能看到你这次请求里携带的文字。你上一个会话里的所有内容都不存在了跟没发生过一样。这就好比去咨询公司每次面谈都是同一个顾问但他没有笔记本你每次都得重新把需求从头讲一遍。我试着把昨天的对话导出后粘贴进新对话第一次是半小时的工作量复制、过滤、压缩成摘要塞进提示词里。第二次还行。第三次就出问题了项目有多个并行方向聊天记录越来越长我把 8000 字的记录全部塞进去模型的注意力被大量琐碎问答分散关键结论反而被淹没了。而且每次重贴都花掉大量 token很不划算。1.2 为什么“全量塞回上下文”是一个错误答案很多人说既然模型没有记忆那我把历史记录都放到提示词里不就得了这个方法在对话次数少、主题单一的早期还能用一旦规模上来就暴露问题。首先是成本。上下文窗口是收费的输入 token 随历史长度线性增长。我做过一次粗略统计一个有 30 轮有效讨论的会话原始记录可能包含 2 万到 3 万个 token每次新对话都重新上传费的不是一点半点。其次是窗口长度的物理限制再大的上下文也有上限等历史超过窗口就得砍砍掉的部分同样等于忘记。最后是信号稀释模型在注意力机制下更关注提示词里靠前和靠后的内容中间大段历史被冲淡反而是真正有用的决定容易被忽略。一句话总结全量回放解决的是“有没有记录”的问题解决不了“哪个记录值得被注意”的问题。1.3 正确思路记忆不是拷贝而是提炼后的可检索索引claude-mem 的核心设计思路从一开始就很明确把“记忆”当成一个独立于对话之外的沉淀层。对话过程中的结论、决策、偏好、待办事项经过提炼和结构化之后变成一条条独立的记忆记录在新对话开始前根据用户当前的目标把相关的那几条记忆检索出来拼进提示词里。这条思路来自我对人类工作方式的类比。一个合格的顾问不会把你三年前说的话一字不差全部复述但他的笔记本上会记着你的目标、你曾经做过的关键选择、你反对过的方案。Claude 缺的正是这样一个笔记本。claude-mem 就是做这个笔记本的。在技术实现上这比想象中轻巧不需要造一个完整的数据库系统不需要上复杂的外部向量服务最核心的三个动作就是“提、存、取”后面我会逐个拆开讲清楚。2. 记忆系统的核心链路一条消息是如何变成长期记忆的2.1 捕获层在对话流的哪个位置安插探针第一个要解决的问题是“对话内容怎么被 claude-mem 看到”。我给出一共有三种接入位置按侵入程度从低到高分别是手动导出、代理转发、插件钩子。手动导出最笨就是靠用户自己把对话内容粘到 claude-mem 里做处理适合初期测试。代理转发比较通用把本来直接发往模型服务商的请求先打到一个本地代理服务这个服务把流量拷贝一份给记忆提取器再原样转发出去。这种方式所有走标准接口的客户端都能用但要做请求加密、协议兼容、流式响应处理复杂度偏高。我最后用的是插件钩子方式也是最推荐的方式。现在很多模型对话工具都支持插件系统或事件订阅你可以在一次对话结束、或者每轮回答完成后直接把消息列表交给 claude-mem 处理。不用改任何网络请求也没有中间层转发带来的延迟和风险。如果连插件机制都没有还可以退回到命令行导入把导出文件扔给 claude-mem 解析。这里有一个经验捕获点不要放在每句话都触发的位置应该在“一轮有意义的问答结束”之后触发否则会存进来大量“好的”“继续”“这个呢”之类的碎片后面存储层会很难受。2.2 结构化提取把对话压成四类“可记忆对象”拿到一段对话后不该原样存储而是需要做一次信息提炼。我给 claude-mem 的提取器定义了四类记忆对象基本覆盖了日常工作中的所有场景decision已经拍板的选择比如“数据库最终选型为 PostgreSQL 12”。fact有客观描述性的信息比如“服务部署在三台容器上总内存 16G”。preference用户的偏好与习惯比如“代码注释用中文提交信息遵循约定式规范”。open-task尚未闭环的待办事项比如“下周需要确认主从同步的延迟监控告警阈值”。这个分类的价值在于检索阶段可以做定向筛选。用户在新对话里问“当时为什么选了 PostgreSQL”系统只需要全局检索 decision 和 fact 两类如果只是做普通闲聊open-task 完全可以不注入。分类还能提高后续冲突检测的效率同样是 decision 类型的两条记录才有资格判断谁覆盖谁。下面是提取器使用的提示词模板实际使用中我要求模型只输出 JSON不要输出任何解释性文字{ instructions: 从以下对话中提取值得长期保留的信息输出 JSON 数组。每条记录包含 type、content、importance、keywords 四个字段。type 取值只能是 decision、fact、preference、open-task 之一。importance 为 1 到 5 的整数5 表示极其关键。keywords 为 2 到 5 个中文关键词。只输出 JSON不要输出其他内容。 }给模型看的实际模板会把上面的 instructions 和对话内容拼在一起并在系统提示词里明确要求“如果一段对话没有值得记录的信息输出空数组”。这个空数组设计后面帮了大忙没有它模型会因为“强制生成”的心理压力而虚构不必要的记忆。2.3 存储层一个前面不用向量数据库的嵌入式方案很多人一听到“记忆检索”就下意识认为得上向量数据库其实在个人使用和中小型项目场景下这属于典型的过度设计。向量数据库确实擅长语义相近内容召回但它有两个问题一是额外引入基础设施维护成本上升二是语义相似不等于“与当前任务相关”经常把相似但不重要的知识也捞出来反而造成干扰。claude-mem 的早期版本只用了一个 JSONL 文件加几行检索代码没有任何数据库进程。每条记忆对象在 JSONL 里是一行结构如下{ id: mem_8d2f1a, type: decision, content: 数据迁移采用双写方案先跑 schema 兼容检查再灰度切流, importance: 4, keywords: [双写, 迁移, 灰度切流], session_id: session-20240612, created_at: 2024-06-12T15:22:3108:00, last_access_at: 2024-06-12T15:22:3108:00, access_count: 0, superseded_by: null }字段里的 importance、keywords、last_access_at、access_count 四个字段是检索和遗忘机制的基础。superseded_by 字段用于处理冲突覆盖后面会细说。JSONL 的追加写入本身支持并发安全多个会话同时往文件末尾写一行操作系统层面不会互相覆盖。查询的时候需要读入全量文件做扫描数据量在几千条以内速度完全可接受。我实测过一万条记忆记录的扫描带排序也就在几十毫秒级对个人场景毫无压力。只有到了几万条以上时再考虑往 SQLite 里迁移也不迟。2.4 检索与注入新会话第一句话之前发生了什么claude-mem 在新会话开始时不是被动等待用户提问而是在用户输入之前先拿到当前会话的目标上下文。这个目标上下文可以是用户在 IDE 里打开的工程文件说明、CLI 里指定的任务参数或者最简单的第一轮用户消息。检索的核心是一个轻量打分公式score 0.7 * semantic_similarity(query, mem) 0.3 * recency_score(mem)semantic_similarity 早期我用的是基于关键词共现的简化版把查询语句和记忆记录分词计算重叠词占比加上 TF-IDF 加权。recency_score 则把创建时间映射到 0 到 1 之间越新的记录得分越高。如果你确实有本地向量模型资源完全可以把 semantic_similarity 替换成向量相似度打分框架不用变。检索完成后claude-mem 会把得分前 5 到 10 条的记忆拼成一个“记忆上下文”块注入到系统提示词的开头部分。这个块长这样子memory-context 基于历史会话以下信息可能与当前任务相关 1. [decision] 数据迁移采用双写方案先跑 schema 兼容检查再灰度切流。 2. [preference] 代码注释使用中文提交信息遵循约定式规范。 /memory-context注意注入位置。我踩过的坑是把它藏在系统提示词末尾发现模型经常忽略放在 prompt 最前面的记忆上下文相当于开场就交代了“你已知的事实”对后续回答的影响最稳定。这个细节直接影响命中率。3. 把 claude-mem 接进日常对话流部署、配置与第一次记忆命中3.1 整体架构一个本地服务加一个会话钩子claude-mem 的运行时分成两个部分。一个是 memory service负责存储、检索、遗忘和维护可以常驻本地也可以被当作命令行工具按需调用另一个是 client hook以插件或包装脚本的形式嵌在对话客户端里负责在合适时机调用 memory service 的接口。两部分通过本地 HTTP 接口通信端口默认用 8123启动命令十分简单直接跑claude-mem serve即可。目录结构也很简洁claude-mem/ ├── claude_mem/ │ ├── __init__.py │ ├── extract.py # 对话结构化提取 │ ├── store.py # JSONL 存储与索引 │ ├── recall.py # 检索打分 │ ├── forget.py # 遗忘与清理 │ └── serve.py # 本地 HTTP 服务 ├── config.json # 用户配置 └── data/ └── memory.jsonl # 记忆记录这套结构的好处是模块边界清楚出了问题能快速定位。提取只负责“产出一条 JSON 记录”存储不关心内容是什么检索只管“按打分返回候选”各自独立调试不要试图做成一个几百行的多合一脚本。3.2 核心配置config.json 里最值得关注的字段我用一个配置文件和 claude-mem 的默认行为解耦。以下是我在实际项目里稳定使用的配置模板{ memory_path: ./data/memory.jsonl, extract_threshold: 3, extract_interval_seconds: 30, top_k: 8, retrieval_mode: hybrid, ignore_prefix: [好的, 继续, 对, 没错, 谢谢], min_content_length: 12, importance_threshold: 2, conflict_check: true, default_incognito: false, prune_days: 90 }extract_threshold 表示一轮对话至少要有 3 条消息才触发提取防止单个问答就被记录。extract_interval_seconds 是提取去重的最小间隔避免用户在短时间内连续追问时重复处理同样的内容。min_content_length 和 importance_threshold 是质量门槛过滤掉太短或太琐碎的内容。ignore_prefix 是前缀过滤像“好的”“继续”这样没有任何信息量的回复直接跳过。有一个容易被忽视但对成本影响很大的配置是 retrieval_mode。它有三个可选值keyword 表示仅用关键词检索hybrid 表示关键词加时间权重vector 表示使用外部向量模型。默认用 hybrid只有在你有稳定可用的本地 embedding 能力时才切换到 vector。3.3 第一次完整调用从新对话到记忆被唤醒为了让第一次接入的读者有一个完整的操作手感我写一个最小可运行的调用流程实际中可以直接落地from claude_mem import MemoryService service MemoryService.from_config(./config.json) # 1. 新会话开始准备注入记忆 query 继续做数据迁移方案重点看第6条检查项 context service.prepare_context(query, top_k5) # 2. 把 context 拼进 system prompt开始对话 system_prompt f 你是我的技术助手。以下是历史记忆中与当前任务相关的信息 {context} 请基于以上信息回答用户问题。如果上面没有你需要的内容请直接说明。 # 3. 对话结束把消息列表传给 service 做提取保存 conversation_messages [ {role: user, content: 第6条检查项的执行步骤是什么}, {role: assistant, content: 第6条检查项分为四步确认源表数据量、...}, ] service.ingest(conversation_messages, session_idsession-20240613)这个流程中ingest 内部会先做前缀过滤和长度过滤再调用提取器最后把符合条件的记忆写入 JSONL。prepare_context 内部对历史记忆做打分排序并把最高分的前若干条组装成可见文本。整个过程不需要手改任何网络请求也不需要理解底层协议细节。我第一次成功跑通的时候新会话里我问“上次迁移方案第 6 条的执行细节是什么”claude-mem 把前一天记录的 open-task 和 decision 两条记忆注入进去模型直接答出了双写方案和第 6 条的检查步骤。那一刻的体验感和手动粘贴历史完全不一样像真的有个笔记本在生效。3.4 CLI 操作不用打开文件也能看到记忆内部记忆侧车不能只顾着自动采集也得给用户留几个手动操作入口。claude-mem 的 CLI 我做得比较简单但每个命令都有明确的适用场景claude-mem serve启动本地服务。claude-mem query 某句话手工检索当前记忆库看哪些记录会命中。claude-mem stats查看记忆总量、类型分布、本周新增数。claude-mem open直接用编辑器打开记忆 JSONL 文件方便人工校对。claude-mem forget session-xxx删除某个对话产生的所有记忆。claude-mem review按周或按月汇总记忆导出一份可阅读的文档。絮叨一句claude-mem query这个命令是调试利器。觉得模型回答不对劲时先用它查一下“该命中的记忆到底命没命中”总比自己猜半天根因要快。4. 记忆质量才是灵魂过滤、冲突、遗忘与隐私边界4.1 让提取器学会克制不是每条消息都值得记住我见过一些记忆工具的通病不管什么对话都往存储里塞结果记忆库变成一个巨大的垃圾场检索出来的东西全是无关紧要的碎碎念。质量把控必须在写入前就做而不是等检索时才后悔。claude-mem 做了一个双重过滤。第一重是硬性规则内容长度小于 12 个字的忽略以 ignore_prefix 开头的忽略连续 30 秒内重复内容的合并。第二重是重要性打分我可以在提示词里要求提取器给每条候选记忆打 1 到 5 分低于 importance_threshold 的不落盘。在工作实践中我发现决策类和偏好类记忆的重要性中位数在 3 到 4事实类容易虚高待办类则波动最大。于是对不同类型设置了不同的准入线比如决策类 2 分以上保存偏好类 3 分以上待办类必须是带有明确动词和对象才保存。这样能显著减小存储体量同时保证检索结果里的“含金量”。4.2 记忆冲突两个相互矛盾的“事实”会毁掉整个上下文记忆最怕的不是遗忘而是自相矛盾。假设第一周记录的是“数据库选型为 MySQL”第二周记录的是“数据库将切换至 PostgreSQL”两条记忆同时存在检索时会把两个都注入上下文模型就会陷入困惑回答变成“既选 MySQL 又选 PostgreSQL”。claude-mem 的解决方式是添加冲突检测环节在写入新记忆前把新记录与同类型、同关键词组的旧记录做一次比对。如果两者明显冲突就给旧记录标记 superseded_by 为新记录 id同时新记录继承旧记录的 keyword 关联性。检索时只返回未被替代的记录废弃记录保留在文件里不会参与后续上下文注入。这种设计比直接删除旧记录更安全因为有时候冲突是用户言语表述差异导致的实际并没错。保留了废弃记录回头检查还能看出推理链直接删了就什么都没了。4.3 遗忘机制长时间不用的记忆应该自然淡出没有遗忘机制的记忆系统最终会沦为垃圾堆。人类大脑的工作机制也是这样频繁回忆的内容被强化长时间不碰的内容逐渐淡出。claude-mem 把这一机制做成了两个层面。第一层是检索侧的老化加权。打分公式里日期越新的记忆权重越高即便内容相关三个月前的一条决策也不会轻易压过最近一周的新决策。第二层是主动清理策略claude-mem 在服务空闲时会扫描记忆文件对满足以下条件的记录做归档处理超过 prune_days默认 90 天未访问、importance 低于 3、access_count 低于 2。这些记录被移到一个 archived.jl 文件里不参与检索但保留可恢复能力。论是系统级老化还是手动归档目的都是让高价值的记忆保持活跃。我通常每周用claude-mem review扫一遍本周记忆顺手清理掉明显失效的条目比月末一次性清理轻松得多。4.4 隐私边界记忆侧车不是越大越全越好记忆能力越强意味着你留在本地的文本越多。claude-mem 的所有记忆都存放在本地不主动上传任何内容到云端这从源头上解决了第三方服务读取隐私的问题。但还要防着另外两个风险一是本机文件被其他进程读取二是敏感会话误入全局记忆。针对第一条我给记忆文件加了可选的加密存储模式写入时用用户提供的密钥做对称加密读取时临时解密。对绝大多数本地使用场景这个措施够了。针对第二条配置文件里有一个 default_incognito 开关。开启后标记为 incognito 的会话产生的对话不会被写入记忆库。我在处理客户敏感数据、账号密码、个人隐私话题时都会主动打开这个模式成本极低却能避免以后检索时不小心把敏感信息带进上下文。所谓边界设计不是一上来就搞复杂权限体系而是先把“什么东西绝对不记录”这条红线画清楚。5. 踩坑实录提取失败、检索跑偏与并发写入的正确调试姿势5.1 提取器偶尔不老实JSON 解析失败的完整排查链路我最初将 claude-mem 接进工作流时遇到最多的报错就是 json.loads 抛异常。表面原因是模型没有按照要求输出纯 JSON而是输出了带 Markdown 代码块包裹的内容或者夹杂了“好的我已提取以下信息”之类的前缀。这种错误看起来很蠢但在流式输出和不同模型版本之间时有发生。我在 extract.py 里做了一个解析兜底函数先剥离 Markdown 围栏再用正则截取第一个 JSON 数组片段最后才交给 json.loadsimport json import re def parse_json_response(text: str) - list: text text.strip() fence_match re.search(r(?:json)?\s*([\s\S]*?), text) if fence_match: text fence_match.group(1).strip() array_match re.search(r(\[.*\]), text, re.S) if not array_match: return [] try: return json.loads(array_match.group(1)) except json.JSONDecodeError: return []这个兜底不算优雅但非常有效。真正重要的经验是永远不要在提示词结尾只写一句“只输出 JSON”要让系统提示词、用户消息示例和负面约束三层配合尽可能不给模型自由发挥的余地。5.2 检索跑偏命中了语义相关但实际无关的旧记忆使用一个月之后我开始遇到第二个典型问题单看关键词检索结果非常相关但放入上下文后模型反而被带偏。比如搜“迁移”就同时命中三年前的机房迁移、上周的数据库迁移、昨天的代码仓库迁移三条内容风格相近手段完全不同。这个问题的根因在于关键词检索天然缺少“场景约束”。我给 claude-mem 补了一个非常简单的约束字段每条记忆在提取时额外记录一个 domain 标签比如 infra、backend、database、frontend。检索时如果当前任务能推断出 domain就只在该 domain 下打分推断不出来时再退回全量检索。domain 推断的逻辑也很朴素从查询语句里检测领域关键词。虽然不够聪明但把三个“迁移”记忆分开绰绰有余。这再次印证了一个判断与其追求语义全文理解不如先把记忆中带结构化标签检索准确性会提升得很明显。5.3 提取成本失控每轮对话都调一次模型token 哗哗地烧把 claude-mem 接入后我起初没太关注 token 成本直到某天统计发现提取消耗的 token 几乎占到对话总消耗的 15%。原因很简单每次 ingest 都调用了完整的大模型做结构化提取而且经常在对话过程中高频率触发。解决方案分三步。第一步是调大 extract_interval_seconds从 10 秒调整到 30 秒把同一批消息的多次触发合并为一次提取。第二步是引入增量哨兵记录每次提取的消息最后一条 ID下次只提取新增部分而不是整个会话从头到尾重新读过。第三步是降低提取模型的规格我让 claude-mem 默认使用一个轻量级的小模型来完成结构化输出而把真正高质量的大模型留给业务对话本身。最终 token 消耗从 15% 降到了 4% 左右记忆提取的质量没有明显下降。对个人使用来说这个优化至关重要因为记忆系统的成本如果不可控再好的功能也没有持续用下去的意义。5.4 并发写导致文件读取异常JSONL 也需要队列有一次我同时开了四个对话窗口它们都在向同一个 memory.jsonl 追加记录追加本身没有互相覆盖但读取端遇到了问题查询时读到一半文件被另一个进程写入行错位导致 json.loads 失败。原因是 JSONL 的“追加原子性”只保证单行级别不保证查询期间的快照一致性。修复方式是在 memory service 里引入一个简单的写入队列所有 ingest 请求先进入内存队列由单个后台线程串行落盘查询端则直接读取当前磁盘文件的快照不做任何写锁竞争。这个改动很小但彻底消除了并发写入导致的脏读问题。对于想在自己的实现里复刻这套方案的人建议至少做三层设计内存队列、单写入线程、读取快照。不要依赖操作系统的文件锁也不要相信“多进程同时 append 不会出错”这种乐观假设。5.5 记忆有效性的评估方法用 20 个问题测命中率最后聊一下怎么评估这套记忆系统到底有没有用。刚做完 claude-mem 时我凭感觉判断“好像有效”但拿不出数据。后来我整理了一套评估方法简单可执行强烈推荐从历史对话中挑选 20 个“后续大概率会被再次问到”的问题比如某个方案的理由、某个待办的状态、某个偏好设定。然后分别在有记忆注入和无记忆注入的情况下让模型依据同一个问题作答再对比答案是否覆盖关键事实点。统计指标就两个关键事实覆盖率和答案稳定性。我跑完 20 题后的数据是无记忆时关键事实覆盖率约为 15%有记忆时提升到 70%。那 15% 主要来自问题本身就把事实说全的场景而差的 30% 来自记忆检索未命中的情况多半是 importance 定低了或者 domain 标签缺失。这套评估方法最大的好处是能定位问题在哪一环而不是笼统地抱怨“模型忘性大”。最后几个私人心得我在把 claude-mem 用成日常习惯之后最大的感受是AI 记忆不是能记越多越好而是该记得住、忘得掉、查得准。费心做结构化和过滤那一刻收益不是马上显现而是当某天你在新对话里提起一个三周前的决定时它张口就来、分毫不差那一刻你会觉得所有踩坑都值了。如果你也要搭类似的东西记得给自己留一个调试用的 query 入口把记忆内部透明出来出了问题能第一时间看到是哪一环节失效而不是对着模型输出猜谜。