1. 从零认识 claude-mem它到底解决什么问题第一次看到 claude-mem 这个名字很多人会以为它又是一个“给 AI 加记忆”的玩具项目。但真正用过一段时间之后你会发现它解决的是一个非常具体、非常痛的工程问题如何让 Claude 这类大模型在跨会话、跨项目的长期协作中记住你之前告诉过它的东西而不是每次都从零开始。我自己的使用场景很典型。手上有三四个并行推进的项目每个项目都有自己的技术栈约定、命名规范、目录结构、历史决策。以前每次开新会话我都要花十几分钟把背景重新讲一遍这个项目用的是哪套构建工具、为什么当初放弃了某个方案、某个模块的接口约定是什么。讲完之后模型才开始干活效率极低而且经常讲漏。claude-mem 的核心价值就在这里。它本质上是一套面向 Claude 的持久化记忆层把你在会话中产生的关键信息——项目背景、技术决策、代码约定、个人偏好——抽取出来存到本地然后在后续会话中按需注入回上下文。你可以把它理解成给 Claude 配了一个“外挂笔记本”它自己会记也会自己翻。适合谁来用三类人收益最明显。第一类是长期维护多个项目的独立开发者记忆断层带来的重复沟通成本最高。第二类是把 Claude 当作主力编码助手的人会话频率高记忆复用价值大。第三类是喜欢折腾工具链、愿意花半小时配置换取长期效率的人。如果你只是偶尔问几个问题那确实没必要上这套东西。需要先说明一点claude-mem 这类工具目前生态里实现方式不止一种有基于本地文件存储的有基于向量检索的也有混合方案。下面我讲的这套思路和实操是基于社区里比较主流、我个人实测下来最稳的一种落地方式具体实现细节你可以根据自己的环境调整。2. 整体设计思路为什么是“抽取 检索 注入”三段式2.1 记忆系统的核心矛盾记太多和记太少都难受设计任何记忆系统第一个要回答的问题就是记什么不记什么。如果你把所有对话原封不动全存下来问题很快就会出现。上下文窗口是有限的你不可能每次会话都把过去几百轮对话塞进去。而且大量内容是废话——“好的”“继续”“帮我改一下”——这些对后续毫无价值。反过来如果你只记极少数“精华”又会漏掉很多当时看起来不重要、后来却反复用到的细节。claude-mem 这类工具普遍采用的解法是三段式流水线抽取、检索、注入。这三个阶段各自独立可以分别优化这是它设计上最聪明的地方。抽取阶段会话结束后或进行中用一次轻量的模型调用把对话里的“可复用信息”提炼成结构化条目。检索阶段新会话开始时根据当前任务描述从记忆库里找出最相关的若干条。注入阶段把检索到的记忆以特定格式拼进系统提示或首轮消息里。为什么拆成三段而不是一步到位因为每段的失败模式不一样。抽取错了是信息质量问题检索错了是召回精度问题注入错了是格式和位置问题。分开之后出问题你能快速定位是哪一环而不是面对一个黑盒干瞪眼。2.2 为什么选本地存储而不是云端社区里也有把记忆存到云端的方案但我个人强烈建议优先用本地文件或本地数据库。原因有三条都是踩过坑总结出来的。第一是隐私。你的项目背景、代码约定、甚至一些业务逻辑全都属于敏感信息。存到第三方服务上等于把项目底裤交出去。本地存储没有这个顾虑。第二是可控性。本地存储意味着你可以直接打开文件看里面到底记了什么可以手动删掉记错的内容可以用 git 管理记忆的版本。云端方案你只能通过它提供的接口操作出问题很难干预。第三是速度。本地读写是毫秒级的检索不需要走网络。会话启动时注入记忆这一步对延迟很敏感走网络会明显拖慢体验。提示如果你确实需要多设备同步用 git 仓库或者同步盘来同步本地记忆目录就行没必要为此引入云端服务。2.3 检索策略关键词、向量还是混合检索环节是整套系统里技术含量最高的部分。常见有三种做法检索方式优点缺点适用场景关键词匹配实现简单、零依赖、可解释同义词召回差、中文分词麻烦记忆条目少、术语固定向量检索语义召回强、支持模糊匹配需要嵌入模型、有额外开销记忆条目多、表达多样混合检索兼顾精确与语义实现复杂、需要调权重对召回质量要求高我实测下来的结论是记忆条目在 200 条以内时关键词匹配完全够用别过度设计。超过这个量级再考虑上向量检索。很多教程一上来就让你搭向量库其实对个人用户来说是杀鸡用牛刀维护成本还高。混合检索的权重怎么调一个经验值是关键词命中权重 0.4、向量相似度权重 0.6。但这个不是死的如果你的记忆里术语特别多比如大量 API 名称、函数名关键词权重可以提到 0.5 甚至更高。3. 核心细节拆解记忆条目的结构与抽取逻辑3.1 一条合格的记忆长什么样记忆条目不是随便一段文字它需要结构化。我用的格式是这样的{ id: mem_20240115_001, type: convention, project: my-web-app, content: 该项目所有 API 路由统一放在 src/routes 下文件名用 kebab-case例如 user-profile.ts, tags: [路由, 命名规范, 目录结构], created_at: 2024-01-15T10:30:00Z, confidence: 0.9 }几个字段值得展开说。type用来区分记忆类别常见的有 convention约定、decision决策、preference偏好、fact事实。分类的好处是检索时可以按类型过滤比如写代码时优先召回 convention讨论方案时优先召回 decision。project字段是必须的。如果你同时维护多个项目没有这个字段会导致记忆串味——A 项目的约定被注入到 B 项目的会话里那比没有记忆还糟糕。confidence是抽取时模型给出的置信度。低于 0.6 的条目我建议直接丢弃因为低置信度往往意味着模型在瞎猜注入进去反而误导。tags是给关键词检索用的。抽取时让模型顺便打标签检索时标签命中可以加权。3.2 抽取提示词怎么写才不跑偏抽取质量几乎完全取决于提示词。我前后改了七八版总结出几个关键点。第一明确告诉模型什么该记、什么不该记。不要只说“提取重要信息”太模糊。要给出正反例应该记录 - 项目的技术栈、框架版本、构建工具 - 明确的命名规范、目录约定、代码风格 - 做过的技术决策及其原因例如放弃 Redux 是因为... - 用户明确表达的偏好例如我喜欢函数式写法 不应该记录 - 一次性的调试过程 - 已经被推翻的临时方案 - 寒暄、确认、无信息量的对话 - 模型自己的推测除非用户确认第二要求输出结构化 JSON并给出 schema。这样后续解析不会出错。我一般会在提示词末尾附上完整的字段说明和示例。第三控制单次抽取的条目数量。一次会话抽 3 到 8 条比较合适。太多说明你在硬凑太少说明漏了。如果一次抽出来 20 条大概率是把废话也记进去了。注意抽取用的模型不需要很强用便宜快速的小模型就够。这一步是“信息压缩”不是“深度推理”杀鸡用牛刀纯属浪费。3.3 去重与冲突处理记忆库的“新陈代谢”记忆库用久了必然出现重复和冲突。比如你三个月前记了“用 Jest 做测试”上个月改成了“迁移到 Vitest”如果两条都在检索时就会打架。处理策略分两步。第一步是写入时去重新条目入库前先跟已有条目做相似度比对超过阈值比如 0.85就视为重复选择保留更新的那条或者合并。第二步是定期清理。我一般每两周跑一次清理脚本做三件事删掉 confidence 低于阈值的、合并高度相似的、标记出互相矛盾的条目人工确认。冲突条目的处理要特别小心。不要自动删除旧的而是给旧条目打上superseded_by字段指向新条目检索时默认过滤掉被取代的。这样万一新决策是错的你还能回溯。4. 实操落地从安装到跑通第一条记忆4.1 环境准备与依赖选择先说环境。这套东西对系统要求不高Node.js 18 或者 Python 3.10 都能跑看你熟悉哪个生态。我选的是 Node.js因为跟 Claude 的很多周边工具链衔接更顺。核心依赖就几个一个 HTTP 客户端用来调模型 API一个本地存储方案简单场景用 JSON 文件量大用 SQLite一个 CLI 框架方便封装成命令如果你要上向量检索再加一个嵌入模型客户端和一个向量索引库。但如前所述初期别上。# 初始化项目 mkdir claude-mem cd claude-mem npm init -y npm install better-sqlite3 commander dotenv选 better-sqlite3 而不是 json 文件是因为它同步 API 用起来简单而且支持全文检索后面做关键词匹配很方便。数据量小的时候两者没差别但迁移成本 SQLite 更低。4.2 数据库表结构设计表结构不用复杂两张表就够CREATE TABLE memories ( id TEXT PRIMARY KEY, type TEXT NOT NULL, project TEXT NOT NULL, content TEXT NOT NULL, tags TEXT, confidence REAL DEFAULT 1.0, superseded_by TEXT, created_at TEXT DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE sessions ( id TEXT PRIMARY KEY, project TEXT, started_at TEXT, ended_at TEXT, extracted INTEGER DEFAULT 0 );memories 表存记忆条目sessions 表记录会话用来避免重复抽取同一个会话。tags 存成逗号分隔的字符串就行别急着上关联表等真有复杂查询需求再说。给 project 和 type 建索引检索时能快不少CREATE INDEX idx_project ON memories(project); CREATE INDEX idx_type ON memories(type);4.3 抽取流程的完整实现抽取的触发时机有两种会话结束时手动触发或者定时扫描未抽取的会话。我推荐手动触发为主、定时兜底因为自动抽取容易在会话还没结束时就把半成品记进去。核心逻辑大概是这样async function extractMemories(sessionId, conversation) { const prompt buildExtractionPrompt(conversation); const response await callModel(prompt); const memories parseAndValidate(response); for (const mem of memories) { if (mem.confidence 0.6) continue; if (await isDuplicate(mem)) continue; insertMemory(mem); } }buildExtractionPrompt就是前面说的那段提示词把对话内容拼进去。parseAndValidate要做严格的字段校验模型偶尔会漏字段或者类型不对不校验直接入库后面会炸。isDuplicate的实现初期用简单的字符串相似度就行比如计算两条内容的编辑距离或者 Jaccard 相似度。别一上来就调嵌入模型没必要。4.4 注入环节位置和格式都很讲究注入是最容易被忽视、但影响最大的一环。同样一批记忆注入位置不对效果天差地别。我的经验是把记忆放在系统提示的末尾而不是开头。原因是模型对上下文末尾的内容注意力更强放在末尾能提高记忆被真正“用上”的概率。放在开头的话等模型读到你的实际任务时记忆已经被稀释了。格式上用清晰的分隔和标签project_memory projectmy-web-app 以下是你需要遵守的项目约定和历史决策 [约定] 所有 API 路由统一放在 src/routes 下文件名用 kebab-case [决策] 放弃 Redux 改用 Zustand因为项目状态逻辑简单Redux 样板代码太多 [偏好] 用户偏好函数式写法避免 class 组件 /project_memory用 XML 风格的标签包裹是因为 Claude 对这类结构化标签的识别很稳。每条记忆前面加[类型]前缀方便模型快速判断这条信息的性质。注入条数控制在 5 到 10 条。太少覆盖不全太多会挤占任务本身的上下文。如果检索出来超过 10 条按相关度和 confidence 排序取前 10。5. 常见问题与排查技巧实录5.1 记忆注入了但模型不遵守这是最高频的问题。你明明注入了“用 kebab-case 命名”模型还是给你生成 camelCase。排查思路按顺序来先确认记忆真的注入进去了。打印出发给模型的完整 prompt看看记忆段落是不是在里面。有时候是代码 bug 导致注入失败你以为是模型不听话其实是根本没传。如果确认注入了再看记忆的表述是否足够明确。“命名要规范”这种模糊表述模型没法遵守。“文件名用 kebab-case例如 user-profile.ts”这种带示例的遵守率高得多。抽取时就要注意让模型输出具体、可执行的表述。还不行的话提高记忆在 prompt 里的权重。可以在记忆段落前加一句“以下约定优先级高于你的默认习惯”明确告诉模型这些要覆盖它的默认行为。5.2 记忆库越来越臃肿检索变慢用几个月之后记忆库上千条很正常。这时候检索会明显变慢而且召回质量下降——太多相似条目互相干扰。解决办法是分层管理。把记忆按项目分库检索时只查当前项目的库。跨项目的通用偏好比如“我喜欢简洁的代码风格”单独放一个 global 库每次都注入。再就是定期归档。超过半年没被检索命中的记忆移到归档表不参与常规检索。真需要的时候再手动查。5.3 抽取出来的记忆质量参差不齐这个问题八成出在提示词。我整理了一个排查清单现象可能原因解决方向记了一堆废话提示词没给反例补充“不应该记录”的清单漏掉关键决策提示词没强调决策明确要求记录决策及原因表述太模糊没要求具体化要求带示例、带具体值类型标错类型定义不清给出每种类型的判定标准置信度虚高没让模型自评要求模型对不确定的降分实操心得抽取提示词改完之后别急着全量跑。先拿三五个历史会话做小样本测试人工检查抽取结果确认质量达标再上量。我见过太多人改完提示词直接全量重抽结果把好记忆也覆盖了。5.4 多项目记忆串味这个问题的根源通常是 project 字段没填对或者检索时没按 project 过滤。检查两点抽取时是否正确识别了当前项目可以从工作目录推断检索时 SQL 里有没有WHERE project ?。如果项目之间确实有共享内容别偷懒让它们共用记忆而是显式地在两个项目下各存一份或者放到 global 库。隐式共享是串味的温床。6. 进阶玩法让记忆系统真正长在你身上6.1 记忆的自动衰减与强化不是所有记忆都该永久保留。我的做法是给每条记忆加一个hit_count字段每次被检索命中就加一。定期清理时hit_count 为 0 且超过 90 天的条目降权或归档hit_count 高的条目提升检索优先级。这其实是在模拟人的记忆机制——常用的记得牢不用的慢慢淡忘。实测下来这套衰减机制能让记忆库长期保持“精炼”而不是无限膨胀。6.2 按任务类型切换记忆视图写代码、做架构讨论、写文档这三种场景需要的记忆类型不一样。写代码时 convention 和 preference 最重要做架构讨论时 decision 最重要。可以在注入前根据任务类型做一次过滤。判断任务类型的方法很简单看用户第一句话里的关键词或者让模型快速分类一下。这个小小的过滤能让注入的记忆更精准减少无关信息干扰。6.3 记忆的可视化与手动干预再智能的自动抽取也会有错。所以一定要提供一个简单的查看和编辑界面。不用做得多漂亮一个 CLI 命令能列出、搜索、删除、修改记忆就够了。# 列出当前项目的所有记忆 claude-mem list --project my-web-app # 搜索包含路由的记忆 claude-mem search 路由 # 删除某条记忆 claude-mem delete mem_20240115_001手动干预的价值在于你能及时纠正系统的错误而不是等它把错误记忆反复注入、污染后续所有会话。我一般每周花五分钟扫一眼新增记忆删掉明显不对的。6.4 和其他工具的联动claude-mem 不是孤岛。它可以和你的编辑器、终端、git 钩子联动。比如在 git commit 时触发一次抽取把这次改动涉及的决策记下来或者在编辑器里加个快捷键一键把当前选中的代码约定存成记忆。联动的核心思路是降低记录成本。记忆系统最大的敌人不是技术问题是懒。如果记录一条记忆需要你切窗口、敲命令、填表单你坚持不了两周。把它嵌进你本来就在做的工作流里才能长期用下去。7. 我踩过的几个坑你可以直接绕开第一个坑是过早追求自动化。我一开始想做成全自动——会话结束自动抽取、新会话自动注入、完全不用管。结果自动抽取经常在会话没结束时触发记了一堆半成品自动注入又经常注入不相关的记忆反而干扰。后来改成半自动抽取手动触发、注入自动但可关闭体验立刻好了。自动化不是目的好用才是。第二个坑是记忆条目写得太长。我早期喜欢把一整段决策过程都记下来一条记忆两三百字。结果注入五条就上千字把上下文占满了。后来强制每条记忆控制在 100 字以内只记结论和关键原因细节需要时再问。记忆是索引不是文档。第三个坑是忽视记忆的时效性。技术决策会过时半年前的方案可能早就不适用了。我现在的做法是给每条记忆加一个review_after字段到期提醒我复核。过期的记忆要么更新要么标记失效绝不让它继续误导模型。第四个坑是没有备份。有一次误操作把记忆库删了几个月的积累全没了。从那以后我把记忆目录纳入 git 管理每次修改自动提交。记忆库是你和模型协作的“共同资产”值得像代码一样对待。这套东西搭起来大概需要半天到一天之后每周维护几分钟。换来的是每次会话省下的十几分钟背景沟通以及模型对你项目越来越深的理解。用上一个月你就回不去了。 
长河君 · 2026/10/9 9:12:45 · 阅读 1.2k claude-mem 实战：为 Claude 构建持久化记忆层，解决跨会话上下文丢失
1. 从零认识 claude-mem它到底解决什么问题第一次看到 claude-mem 这个名字很多人会以为它又是一个“给 AI 加记忆”的玩具项目。但真正用过一段时间之后你会发现它解决的是一个非常具体、非常痛的工程问题如何让 Claude 这类大模型在跨会话、跨项目的长期协作中记住你之前告诉过它的东西而不是每次都从零开始。我自己的使用场景很典型。手上有三四个并行推进的项目每个项目都有自己的技术栈约定、命名规范、目录结构、历史决策。以前每次开新会话我都要花十几分钟把背景重新讲一遍这个项目用的是哪套构建工具、为什么当初放弃了某个方案、某个模块的接口约定是什么。讲完之后模型才开始干活效率极低而且经常讲漏。claude-mem 的核心价值就在这里。它本质上是一套面向 Claude 的持久化记忆层把你在会话中产生的关键信息——项目背景、技术决策、代码约定、个人偏好——抽取出来存到本地然后在后续会话中按需注入回上下文。你可以把它理解成给 Claude 配了一个“外挂笔记本”它自己会记也会自己翻。适合谁来用三类人收益最明显。第一类是长期维护多个项目的独立开发者记忆断层带来的重复沟通成本最高。第二类是把 Claude 当作主力编码助手的人会话频率高记忆复用价值大。第三类是喜欢折腾工具链、愿意花半小时配置换取长期效率的人。如果你只是偶尔问几个问题那确实没必要上这套东西。需要先说明一点claude-mem 这类工具目前生态里实现方式不止一种有基于本地文件存储的有基于向量检索的也有混合方案。下面我讲的这套思路和实操是基于社区里比较主流、我个人实测下来最稳的一种落地方式具体实现细节你可以根据自己的环境调整。2. 整体设计思路为什么是“抽取 检索 注入”三段式2.1 记忆系统的核心矛盾记太多和记太少都难受设计任何记忆系统第一个要回答的问题就是记什么不记什么。如果你把所有对话原封不动全存下来问题很快就会出现。上下文窗口是有限的你不可能每次会话都把过去几百轮对话塞进去。而且大量内容是废话——“好的”“继续”“帮我改一下”——这些对后续毫无价值。反过来如果你只记极少数“精华”又会漏掉很多当时看起来不重要、后来却反复用到的细节。claude-mem 这类工具普遍采用的解法是三段式流水线抽取、检索、注入。这三个阶段各自独立可以分别优化这是它设计上最聪明的地方。抽取阶段会话结束后或进行中用一次轻量的模型调用把对话里的“可复用信息”提炼成结构化条目。检索阶段新会话开始时根据当前任务描述从记忆库里找出最相关的若干条。注入阶段把检索到的记忆以特定格式拼进系统提示或首轮消息里。为什么拆成三段而不是一步到位因为每段的失败模式不一样。抽取错了是信息质量问题检索错了是召回精度问题注入错了是格式和位置问题。分开之后出问题你能快速定位是哪一环而不是面对一个黑盒干瞪眼。2.2 为什么选本地存储而不是云端社区里也有把记忆存到云端的方案但我个人强烈建议优先用本地文件或本地数据库。原因有三条都是踩过坑总结出来的。第一是隐私。你的项目背景、代码约定、甚至一些业务逻辑全都属于敏感信息。存到第三方服务上等于把项目底裤交出去。本地存储没有这个顾虑。第二是可控性。本地存储意味着你可以直接打开文件看里面到底记了什么可以手动删掉记错的内容可以用 git 管理记忆的版本。云端方案你只能通过它提供的接口操作出问题很难干预。第三是速度。本地读写是毫秒级的检索不需要走网络。会话启动时注入记忆这一步对延迟很敏感走网络会明显拖慢体验。提示如果你确实需要多设备同步用 git 仓库或者同步盘来同步本地记忆目录就行没必要为此引入云端服务。2.3 检索策略关键词、向量还是混合检索环节是整套系统里技术含量最高的部分。常见有三种做法检索方式优点缺点适用场景关键词匹配实现简单、零依赖、可解释同义词召回差、中文分词麻烦记忆条目少、术语固定向量检索语义召回强、支持模糊匹配需要嵌入模型、有额外开销记忆条目多、表达多样混合检索兼顾精确与语义实现复杂、需要调权重对召回质量要求高我实测下来的结论是记忆条目在 200 条以内时关键词匹配完全够用别过度设计。超过这个量级再考虑上向量检索。很多教程一上来就让你搭向量库其实对个人用户来说是杀鸡用牛刀维护成本还高。混合检索的权重怎么调一个经验值是关键词命中权重 0.4、向量相似度权重 0.6。但这个不是死的如果你的记忆里术语特别多比如大量 API 名称、函数名关键词权重可以提到 0.5 甚至更高。3. 核心细节拆解记忆条目的结构与抽取逻辑3.1 一条合格的记忆长什么样记忆条目不是随便一段文字它需要结构化。我用的格式是这样的{ id: mem_20240115_001, type: convention, project: my-web-app, content: 该项目所有 API 路由统一放在 src/routes 下文件名用 kebab-case例如 user-profile.ts, tags: [路由, 命名规范, 目录结构], created_at: 2024-01-15T10:30:00Z, confidence: 0.9 }几个字段值得展开说。type用来区分记忆类别常见的有 convention约定、decision决策、preference偏好、fact事实。分类的好处是检索时可以按类型过滤比如写代码时优先召回 convention讨论方案时优先召回 decision。project字段是必须的。如果你同时维护多个项目没有这个字段会导致记忆串味——A 项目的约定被注入到 B 项目的会话里那比没有记忆还糟糕。confidence是抽取时模型给出的置信度。低于 0.6 的条目我建议直接丢弃因为低置信度往往意味着模型在瞎猜注入进去反而误导。tags是给关键词检索用的。抽取时让模型顺便打标签检索时标签命中可以加权。3.2 抽取提示词怎么写才不跑偏抽取质量几乎完全取决于提示词。我前后改了七八版总结出几个关键点。第一明确告诉模型什么该记、什么不该记。不要只说“提取重要信息”太模糊。要给出正反例应该记录 - 项目的技术栈、框架版本、构建工具 - 明确的命名规范、目录约定、代码风格 - 做过的技术决策及其原因例如放弃 Redux 是因为... - 用户明确表达的偏好例如我喜欢函数式写法 不应该记录 - 一次性的调试过程 - 已经被推翻的临时方案 - 寒暄、确认、无信息量的对话 - 模型自己的推测除非用户确认第二要求输出结构化 JSON并给出 schema。这样后续解析不会出错。我一般会在提示词末尾附上完整的字段说明和示例。第三控制单次抽取的条目数量。一次会话抽 3 到 8 条比较合适。太多说明你在硬凑太少说明漏了。如果一次抽出来 20 条大概率是把废话也记进去了。注意抽取用的模型不需要很强用便宜快速的小模型就够。这一步是“信息压缩”不是“深度推理”杀鸡用牛刀纯属浪费。3.3 去重与冲突处理记忆库的“新陈代谢”记忆库用久了必然出现重复和冲突。比如你三个月前记了“用 Jest 做测试”上个月改成了“迁移到 Vitest”如果两条都在检索时就会打架。处理策略分两步。第一步是写入时去重新条目入库前先跟已有条目做相似度比对超过阈值比如 0.85就视为重复选择保留更新的那条或者合并。第二步是定期清理。我一般每两周跑一次清理脚本做三件事删掉 confidence 低于阈值的、合并高度相似的、标记出互相矛盾的条目人工确认。冲突条目的处理要特别小心。不要自动删除旧的而是给旧条目打上superseded_by字段指向新条目检索时默认过滤掉被取代的。这样万一新决策是错的你还能回溯。4. 实操落地从安装到跑通第一条记忆4.1 环境准备与依赖选择先说环境。这套东西对系统要求不高Node.js 18 或者 Python 3.10 都能跑看你熟悉哪个生态。我选的是 Node.js因为跟 Claude 的很多周边工具链衔接更顺。核心依赖就几个一个 HTTP 客户端用来调模型 API一个本地存储方案简单场景用 JSON 文件量大用 SQLite一个 CLI 框架方便封装成命令如果你要上向量检索再加一个嵌入模型客户端和一个向量索引库。但如前所述初期别上。# 初始化项目 mkdir claude-mem cd claude-mem npm init -y npm install better-sqlite3 commander dotenv选 better-sqlite3 而不是 json 文件是因为它同步 API 用起来简单而且支持全文检索后面做关键词匹配很方便。数据量小的时候两者没差别但迁移成本 SQLite 更低。4.2 数据库表结构设计表结构不用复杂两张表就够CREATE TABLE memories ( id TEXT PRIMARY KEY, type TEXT NOT NULL, project TEXT NOT NULL, content TEXT NOT NULL, tags TEXT, confidence REAL DEFAULT 1.0, superseded_by TEXT, created_at TEXT DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE sessions ( id TEXT PRIMARY KEY, project TEXT, started_at TEXT, ended_at TEXT, extracted INTEGER DEFAULT 0 );memories 表存记忆条目sessions 表记录会话用来避免重复抽取同一个会话。tags 存成逗号分隔的字符串就行别急着上关联表等真有复杂查询需求再说。给 project 和 type 建索引检索时能快不少CREATE INDEX idx_project ON memories(project); CREATE INDEX idx_type ON memories(type);4.3 抽取流程的完整实现抽取的触发时机有两种会话结束时手动触发或者定时扫描未抽取的会话。我推荐手动触发为主、定时兜底因为自动抽取容易在会话还没结束时就把半成品记进去。核心逻辑大概是这样async function extractMemories(sessionId, conversation) { const prompt buildExtractionPrompt(conversation); const response await callModel(prompt); const memories parseAndValidate(response); for (const mem of memories) { if (mem.confidence 0.6) continue; if (await isDuplicate(mem)) continue; insertMemory(mem); } }buildExtractionPrompt就是前面说的那段提示词把对话内容拼进去。parseAndValidate要做严格的字段校验模型偶尔会漏字段或者类型不对不校验直接入库后面会炸。isDuplicate的实现初期用简单的字符串相似度就行比如计算两条内容的编辑距离或者 Jaccard 相似度。别一上来就调嵌入模型没必要。4.4 注入环节位置和格式都很讲究注入是最容易被忽视、但影响最大的一环。同样一批记忆注入位置不对效果天差地别。我的经验是把记忆放在系统提示的末尾而不是开头。原因是模型对上下文末尾的内容注意力更强放在末尾能提高记忆被真正“用上”的概率。放在开头的话等模型读到你的实际任务时记忆已经被稀释了。格式上用清晰的分隔和标签project_memory projectmy-web-app 以下是你需要遵守的项目约定和历史决策 [约定] 所有 API 路由统一放在 src/routes 下文件名用 kebab-case [决策] 放弃 Redux 改用 Zustand因为项目状态逻辑简单Redux 样板代码太多 [偏好] 用户偏好函数式写法避免 class 组件 /project_memory用 XML 风格的标签包裹是因为 Claude 对这类结构化标签的识别很稳。每条记忆前面加[类型]前缀方便模型快速判断这条信息的性质。注入条数控制在 5 到 10 条。太少覆盖不全太多会挤占任务本身的上下文。如果检索出来超过 10 条按相关度和 confidence 排序取前 10。5. 常见问题与排查技巧实录5.1 记忆注入了但模型不遵守这是最高频的问题。你明明注入了“用 kebab-case 命名”模型还是给你生成 camelCase。排查思路按顺序来先确认记忆真的注入进去了。打印出发给模型的完整 prompt看看记忆段落是不是在里面。有时候是代码 bug 导致注入失败你以为是模型不听话其实是根本没传。如果确认注入了再看记忆的表述是否足够明确。“命名要规范”这种模糊表述模型没法遵守。“文件名用 kebab-case例如 user-profile.ts”这种带示例的遵守率高得多。抽取时就要注意让模型输出具体、可执行的表述。还不行的话提高记忆在 prompt 里的权重。可以在记忆段落前加一句“以下约定优先级高于你的默认习惯”明确告诉模型这些要覆盖它的默认行为。5.2 记忆库越来越臃肿检索变慢用几个月之后记忆库上千条很正常。这时候检索会明显变慢而且召回质量下降——太多相似条目互相干扰。解决办法是分层管理。把记忆按项目分库检索时只查当前项目的库。跨项目的通用偏好比如“我喜欢简洁的代码风格”单独放一个 global 库每次都注入。再就是定期归档。超过半年没被检索命中的记忆移到归档表不参与常规检索。真需要的时候再手动查。5.3 抽取出来的记忆质量参差不齐这个问题八成出在提示词。我整理了一个排查清单现象可能原因解决方向记了一堆废话提示词没给反例补充“不应该记录”的清单漏掉关键决策提示词没强调决策明确要求记录决策及原因表述太模糊没要求具体化要求带示例、带具体值类型标错类型定义不清给出每种类型的判定标准置信度虚高没让模型自评要求模型对不确定的降分实操心得抽取提示词改完之后别急着全量跑。先拿三五个历史会话做小样本测试人工检查抽取结果确认质量达标再上量。我见过太多人改完提示词直接全量重抽结果把好记忆也覆盖了。5.4 多项目记忆串味这个问题的根源通常是 project 字段没填对或者检索时没按 project 过滤。检查两点抽取时是否正确识别了当前项目可以从工作目录推断检索时 SQL 里有没有WHERE project ?。如果项目之间确实有共享内容别偷懒让它们共用记忆而是显式地在两个项目下各存一份或者放到 global 库。隐式共享是串味的温床。6. 进阶玩法让记忆系统真正长在你身上6.1 记忆的自动衰减与强化不是所有记忆都该永久保留。我的做法是给每条记忆加一个hit_count字段每次被检索命中就加一。定期清理时hit_count 为 0 且超过 90 天的条目降权或归档hit_count 高的条目提升检索优先级。这其实是在模拟人的记忆机制——常用的记得牢不用的慢慢淡忘。实测下来这套衰减机制能让记忆库长期保持“精炼”而不是无限膨胀。6.2 按任务类型切换记忆视图写代码、做架构讨论、写文档这三种场景需要的记忆类型不一样。写代码时 convention 和 preference 最重要做架构讨论时 decision 最重要。可以在注入前根据任务类型做一次过滤。判断任务类型的方法很简单看用户第一句话里的关键词或者让模型快速分类一下。这个小小的过滤能让注入的记忆更精准减少无关信息干扰。6.3 记忆的可视化与手动干预再智能的自动抽取也会有错。所以一定要提供一个简单的查看和编辑界面。不用做得多漂亮一个 CLI 命令能列出、搜索、删除、修改记忆就够了。# 列出当前项目的所有记忆 claude-mem list --project my-web-app # 搜索包含路由的记忆 claude-mem search 路由 # 删除某条记忆 claude-mem delete mem_20240115_001手动干预的价值在于你能及时纠正系统的错误而不是等它把错误记忆反复注入、污染后续所有会话。我一般每周花五分钟扫一眼新增记忆删掉明显不对的。6.4 和其他工具的联动claude-mem 不是孤岛。它可以和你的编辑器、终端、git 钩子联动。比如在 git commit 时触发一次抽取把这次改动涉及的决策记下来或者在编辑器里加个快捷键一键把当前选中的代码约定存成记忆。联动的核心思路是降低记录成本。记忆系统最大的敌人不是技术问题是懒。如果记录一条记忆需要你切窗口、敲命令、填表单你坚持不了两周。把它嵌进你本来就在做的工作流里才能长期用下去。7. 我踩过的几个坑你可以直接绕开第一个坑是过早追求自动化。我一开始想做成全自动——会话结束自动抽取、新会话自动注入、完全不用管。结果自动抽取经常在会话没结束时触发记了一堆半成品自动注入又经常注入不相关的记忆反而干扰。后来改成半自动抽取手动触发、注入自动但可关闭体验立刻好了。自动化不是目的好用才是。第二个坑是记忆条目写得太长。我早期喜欢把一整段决策过程都记下来一条记忆两三百字。结果注入五条就上千字把上下文占满了。后来强制每条记忆控制在 100 字以内只记结论和关键原因细节需要时再问。记忆是索引不是文档。第三个坑是忽视记忆的时效性。技术决策会过时半年前的方案可能早就不适用了。我现在的做法是给每条记忆加一个review_after字段到期提醒我复核。过期的记忆要么更新要么标记失效绝不让它继续误导模型。第四个坑是没有备份。有一次误操作把记忆库删了几个月的积累全没了。从那以后我把记忆目录纳入 git 管理每次修改自动提交。记忆库是你和模型协作的“共同资产”值得像代码一样对待。这套东西搭起来大概需要半天到一天之后每周维护几分钟。换来的是每次会话省下的十几分钟背景沟通以及模型对你项目越来越深的理解。用上一个月你就回不去了。