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 project="my-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 管理，每次修改自动提交。记忆库是你和模型协作的“共同资产”，值得像代码一样对待。
这套东西搭起来大概需要半天到一天，之后每周维护几分钟。换来的是每次会话省下的十几分钟背景沟通，以及模型对你项目越来越深的理解。用上一个月，你就回不去了。
