1. 项目概述与核心定位1.1 这个工具到底解决什么问题claude-mem这个项目从名字拆开看就是两个部分claude和mem。mem是 memory 的缩写直译过来就是“记忆”。所以这个项目的核心目标非常明确——给 Claude 这类大语言模型加上一层持久化的记忆能力。如果你用过 Claude 的对话界面应该有一个很直接的体感每次开一个新会话它就像失忆了一样完全不记得你上次跟它聊过什么。你上次告诉它“我用的技术栈是 Python FastAPI PostgreSQL”下次再问它问题它还是会默认你什么背景都没有。这种体验在短对话里还能忍但一旦你把它当成日常开发助手、写作助手或者知识管理工具来用每次都要重新交代背景效率损耗就非常大了。claude-mem要做的就是这件事把对话中产生的关键信息抽取出来存到一个可以持久化的地方然后在后续的对话中自动把这些记忆注入到上下文里。这样 Claude 就能“记住”你之前告诉它的偏好、项目背景、技术选型、命名习惯等等。1.2 适合哪些人上手这个项目不是给纯小白用的它需要你对命令行、Node.js 或者 Python 环境有一定了解。具体来说以下几类人会比较适合重度 Claude 用户每天都要跟 Claude 来回几十轮对话反复交代同样的背景信息已经让你烦了。独立开发者 / 小团队没有资源去搭建复杂的 RAG 系统但希望有一个轻量级的记忆层来辅助日常开发。AI 应用开发者想研究“记忆注入”这个方向是怎么落地的想拿一个现成的实现来参考或者二次开发。知识管理爱好者想把跟 AI 的对话沉淀成可检索、可复用的知识库而不是聊完就丢。如果你只是偶尔问 Claude 一两个问题那这个项目对你的价值不大。但如果你已经把 Claude 当成了日常工作流的一部分那它值得你花时间研究一下。1.3 核心关键词拆解围绕claude-mem这个标题有几个关键词需要先理清楚关键词含义在项目中的角色Memory记忆指持久化的对话信息核心功能整个项目围绕它展开Context Injection上下文注入把记忆塞回对话实现手段决定记忆怎么被用起来Embedding向量化把文本转成向量检索环节的关键技术Persistence持久化数据存到磁盘或数据库保证记忆不丢失Retrieval检索从记忆库中找到相关内容决定注入哪些记忆这几个词基本覆盖了claude-mem的完整链路抽取 → 存储 → 检索 → 注入。后面我会按这个链路逐层拆开讲。2. 整体架构设计与思路拆解2.1 为什么不做成微调很多人第一反应是让模型记住东西直接微调不就行了这个思路在理论上成立但在实际场景里有几个硬伤。第一微调的成本太高。每次新增一点记忆就要重新跑一遍训练时间成本和算力成本都不划算。第二微调会改变模型本身的权重容易导致灾难性遗忘——学了新的忘了旧的。第三微调后的模型是静态的你没法在运行时动态地增删改记忆。claude-mem选择的是另一条路不改模型改上下文。模型本身不动但在每次请求的时候动态地把相关记忆拼接到 prompt 里。这样做的好处是记忆可以随时增删改实时生效不消耗训练资源记忆的内容和来源可追溯可以针对不同的对话场景注入不同的记忆这个思路本质上就是 RAGRetrieval-Augmented Generation的一个变体只不过 RAG 通常面向文档库而claude-mem面向的是对话历史。2.2 记忆的分层设计一个容易被忽略的点是记忆不是铁板一块。claude-mem在设计上把记忆分成了几个层次不同层次的记忆有不同的生命周期和注入策略。第一层会话级记忆Session Memory这是最细粒度的记忆记录的是当前这次对话里发生的事。比如你刚才说“这个函数改名叫fetchUserData”那在当前会话的后续对话里Claude 应该知道这个改名。会话级记忆通常存在内存里会话结束就丢弃。第二层项目级记忆Project Memory这一层记录的是跟某个具体项目相关的信息。比如你告诉 Claude“我这个项目用的是 pnpm 而不是 npm”这条信息应该在整个项目的生命周期内都有效。项目级记忆需要持久化到磁盘通常按项目路径或者项目 ID 来组织。第三层用户级记忆User Memory这是最顶层的记忆记录的是跨项目的个人偏好。比如“我习惯用 4 个空格缩进”“我讨厌用any类型”“回复我的时候不要用 emoji”。这些偏好跟具体项目无关应该在任何对话里都生效。分层的好处是注入的时候可以按优先级组合用户级记忆永远注入项目级记忆按当前项目注入会话级记忆按当前会话注入。这样既保证了记忆的覆盖面又避免了把所有记忆一股脑塞进去导致上下文爆炸。2.3 存储选型为什么是 SQLite 向量索引存储这块claude-mem走的是一个很务实的路线SQLite 存结构化数据向量索引存语义检索。为什么不用纯向量数据库因为记忆不只是用来做语义检索的。你还需要按时间排序、按项目过滤、按类型筛选、做去重、做更新。这些操作用 SQL 来做非常自然用纯向量库反而别扭。为什么不用纯关系数据库因为记忆检索的核心场景是“找到跟当前对话最相关的几条记忆”这是语义相似度问题不是精确匹配问题。SQL 的LIKE查询搞不定这个。所以最终的方案是两者结合SQLite 存记忆的元数据内容、时间、项目、类型、来源同时存一个向量字段或者单独存一个向量索引文件。检索的时候先用 SQL 做粗筛比如限定当前项目、限定最近 30 天再用向量相似度做精排。这个方案的好处是单文件数据库部署简单不需要额外起服务支持事务记忆的增删改有原子性保证向量检索可以用sqlite-vec这类扩展也可以外挂一个轻量级的向量索引备份和迁移就是拷贝一个文件的事2.4 记忆抽取的策略选择记忆从哪来这是整个项目里最需要拿捏的部分。抽得太少记忆库是空的注入没东西可用抽得太多噪音太大注入进去反而干扰模型。claude-mem采用的是混合抽取策略显式标记抽取用户在对话里用特定格式标记的内容比如#remember或者!mem直接抽出来存。这种方式准确率最高但依赖用户主动标记。规则抽取用正则或者关键词匹配来识别可能的记忆点。比如出现“我用的是”“我们项目”“以后都”“记住”这类词的时候触发抽取。这种方式覆盖面广但会有误报。模型抽取让 Claude 自己在对话结束时总结“这次对话里有哪些值得记住的信息”返回一个结构化列表。这种方式最智能但会额外消耗 token。实际运行的时候这三种策略是叠加使用的。显式标记优先级最高规则抽取作为补充模型抽取作为兜底。抽取出来的记忆会经过一轮去重和合并再写入存储。3. 核心细节解析与实操要点3.1 记忆的数据结构设计一条记忆在存储里长什么样直接决定了后续检索和注入的效率。claude-mem里一条记忆的典型结构包含以下字段{ id: mem_20250115_001, content: 用户的项目使用 pnpm 作为包管理器不用 npm 或 yarn, type: preference, scope: project, project_id: my-fastapi-app, source: explicit, created_at: 2025-01-15T10:30:00Z, updated_at: 2025-01-15T10:30:00Z, embedding: [0.023, -0.041, ...], access_count: 12, last_accessed_at: 2025-01-20T08:15:00Z, confidence: 0.95 }几个关键字段值得展开说type记忆的类型。常见的有preference偏好、fact事实、decision决策、context背景。不同类型的记忆在注入时的措辞可以不一样。比如preference类型的记忆注入时可以说“用户偏好xxx”decision类型的可以说“之前已决定xxx”。scope记忆的作用域。对应前面说的三层session、project、user。检索的时候按 scope 过滤。confidence置信度。显式标记的记忆置信度是 1.0规则抽取的可能只有 0.6模型抽取的在 0.7 到 0.9 之间。低置信度的记忆在注入时可以加一个“可能”的前缀或者干脆不注入。access_count 和 last_accessed_at这两个字段用来做记忆的“热度”排序。一条记忆被检索得越频繁、最近被访问得越近说明它越重要。在向量相似度接近的情况下优先注入热度高的记忆。3.2 向量化的实操细节向量化这块claude-mem默认用的是轻量级的 embedding 模型比如all-MiniLM-L6-v2或者bge-small-zh。为什么不用大模型因为记忆检索对精度的要求没有文档检索那么高小模型完全够用而且速度快、资源占用低。实操的时候有几个点需要注意第一embedding 的维度要和索引匹配。all-MiniLM-L6-v2输出 384 维bge-small-zh也是 384 维text-embedding-3-small是 1536 维。你选了什么模型索引就要按对应的维度建。维度不匹配是最常见的报错来源。第二中文记忆要用中文模型。如果你主要用中文跟 Claude 对话那 embedding 模型一定要选支持中文的。用纯英文模型去编码中文相似度计算会非常不准。bge-small-zh或者text-embedding-3-small都是不错的选择。第三embedding 要缓存。同一条记忆不需要反复计算 embedding。写入的时候算一次存到数据库里后续检索直接用。如果记忆内容更新了才需要重新计算。第四批量计算比单条计算快得多。如果你一次性要写入几十条记忆不要循环单条调用 embedding 接口要攒成一批一起算。批量计算的吞吐量通常是单条的 5 到 10 倍。3.3 检索策略的调优检索是决定记忆质量的关键环节。claude-mem的检索流程大致是这样的拿当前对话的最后几轮内容拼成一个查询文本对查询文本做 embedding在向量索引里找 top-K 条最相似的记忆用 SQL 过滤掉不符合 scope 条件的记忆按相似度、热度、置信度做一个综合排序取 top-N 条注入到上下文这里面有几个参数需要调K 值初筛取多少条。太小了可能漏掉相关记忆太大了精排压力大。一般设 20 到 50 之间比较合适。N 值最终注入多少条。这个直接决定了注入的 token 量。一般设 3 到 8 条。超过 10 条的话注入的内容可能比用户当前的问题还长反而干扰模型。相似度阈值低于某个相似度的记忆直接丢弃。这个阈值一般设 0.3 到 0.5 之间。设太低会注入不相关的记忆设太高会漏掉相关但表述不同的记忆。时间衰减越老的记忆权重越低。可以用一个简单的指数衰减函数比如weight exp(-age_days / 30)30 天前的记忆权重降到 0.37。提示检索参数没有万能值需要根据你的实际使用情况调。建议先跑一段时间把检索日志打出来人工看看注入的记忆是否相关再针对性调整。3.4 注入格式的设计记忆检索出来了怎么塞进 prompt 里也是有讲究的。claude-mem的注入格式大致是这样的[Memory Context] The following are remembered facts and preferences from previous conversations: 1. [preference] 用户的项目使用 pnpm 作为包管理器 2. [decision] 数据库选型已确定为 PostgreSQL 16 3. [fact] 用户的主力语言是 Python 3.12 Please take these into account when responding. [End Memory Context]这个格式有几个设计考量用明确的分隔符把记忆区和用户问题区分开避免模型把记忆当成用户问题的一部分每条记忆前面标注类型帮助模型理解这条记忆的性质结尾加一句“请考虑这些信息”明确告诉模型要用这些记忆记忆按重要性排序最重要的放最前面注入位置也很关键。记忆应该放在 system prompt 之后、用户问题之前。放在 system prompt 里容易被模型当成固定指令放在用户问题之后又太晚了。4. 实操过程与核心环节实现4.1 环境准备与依赖安装假设你用的是 Node.js 环境claude-mem的初始化流程大致如下# 克隆项目 git clone https://github.com/your-org/claude-mem.git cd claude-mem # 安装依赖 npm install # 初始化数据库 npm run db:init # 配置环境变量 cp .env.example .env.env文件里需要配置几个关键项# 数据库路径 CLAUDE_MEM_DB_PATH./data/memory.db # Embedding 模型 CLAUDE_MEM_EMBEDDING_MODELbge-small-zh CLAUDE_MEM_EMBEDDING_DIM384 # 检索参数 CLAUDE_MEM_TOP_K30 CLAUDE_MEM_TOP_N5 CLAUDE_MEM_SIMILARITY_THRESHOLD0.35 # 记忆抽取开关 CLAUDE_MEM_EXTRACT_EXPLICITtrue CLAUDE_MEM_EXTRACT_RULEtrue CLAUDE_MEM_EXTRACT_MODELfalse这里有几个点需要说明为什么默认关掉模型抽取因为模型抽取每次都要额外调一次 Claude成本高、延迟大。建议先用显式标记和规则抽取跑一段时间等记忆库有一定积累了再考虑开模型抽取。embedding 模型怎么选如果你的对话主要是中文选bge-small-zh如果是中英混合选text-embedding-3-small如果追求极致轻量选all-MiniLM-L6-v2。维度一定要跟CLAUDE_MEM_EMBEDDING_DIM对上。数据库路径用相对路径还是绝对路径建议用绝对路径避免因为工作目录变化导致找不到数据库。4.2 记忆写入的完整流程记忆写入分三步抽取、去重、存储。第一步抽取显式标记抽取最简单就是扫一遍对话内容找#remember或者!mem标记的段落。规则抽取需要维护一个触发词列表const TRIGGER_PATTERNS [ /我用的是(.)/, /我们项目(.)/, /以后都(.)/, /记住(.)/, /不要用(.)/, /偏好(.)/ ];匹配到触发词之后把触发词后面的内容作为候选记忆。这里要注意规则抽取很容易误报。比如“我用的是一把锤子”这种日常对话也会被抽出来。所以规则抽取出来的记忆置信度要设低一点比如 0.6。第二步去重去重分两种精确去重和语义去重。精确去重就是内容完全一样或者高度相似的直接合并。可以用编辑距离或者 Jaccard 相似度来判断。语义去重就是算 embedding 的余弦相似度超过 0.9 的认为是同一条记忆合并或者更新。去重的时候要注意保留最新的那条。比如用户先说“我用 npm”后来说“我改用 pnpm 了”这两条记忆语义上高度相似应该保留后一条把前一条标记为过期。第三步存储存储就是往 SQLite 里写一条记录同时更新向量索引。这里要注意事务写 SQLite 和写向量索引要么都成功要么都失败不能一个成功一个失败。async function storeMemory(memory) { const embedding await computeEmbedding(memory.content); const tx db.transaction(() { db.prepare( INSERT INTO memories (id, content, type, scope, project_id, source, confidence, embedding, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) ).run( memory.id, memory.content, memory.type, memory.scope, memory.project_id, memory.source, memory.confidence, JSON.stringify(embedding), new Date().toISOString() ); vectorIndex.add(memory.id, embedding); }); tx(); }4.3 记忆检索的完整流程检索的入口是当前对话的上下文。具体来说取最近 3 到 5 轮对话的内容拼成一个查询文本。function buildQuery(recentMessages) { return recentMessages .slice(-5) .map(m m.content) .join(\n); }然后对查询文本做 embedding在向量索引里找 top-Kasync function retrieveMemories(query, options) { const queryEmbedding await computeEmbedding(query); // 向量检索 const candidates vectorIndex.search(queryEmbedding, options.topK); // SQL 过滤 const filtered candidates.filter(c { const mem db.prepare(SELECT * FROM memories WHERE id ?).get(c.id); if (!mem) return false; if (mem.scope session mem.session_id ! options.sessionId) return false; if (mem.scope project mem.project_id ! options.projectId) return false; return true; }); // 综合排序 const scored filtered.map(c { const mem db.prepare(SELECT * FROM memories WHERE id ?).get(c.id); const similarity c.score; const recency Math.exp(-daysSince(mem.created_at) / 30); const heat Math.log(mem.access_count 1) / 10; const confidence mem.confidence; return { ...mem, finalScore: similarity * 0.6 recency * 0.2 heat * 0.1 confidence * 0.1 }; }); scored.sort((a, b) b.finalScore - a.finalScore); return scored .filter(m m.finalScore options.similarityThreshold) .slice(0, options.topN); }这个排序公式里相似度占 60% 权重时间新鲜度占 20%热度占 10%置信度占 10%。这个权重分配不是固定的你可以根据自己的场景调。如果你更看重记忆的准确性可以把置信度权重调高如果你更看重时效性可以把时间权重调高。4.4 注入到 Claude 请求检索出来的记忆最终要拼接到发给 Claude 的请求里。假设你用的是 Anthropic 的 API请求体大致是这样的async function callClaude(userMessage, memories) { const memoryContext memories.length 0 ? [Memory Context]\n${memories.map((m, i) ${i 1}. [${m.type}] ${m.content} ).join(\n)}\n[End Memory Context]\n\n : ; const response await anthropic.messages.create({ model: claude-sonnet-4-20250514, max_tokens: 4096, system: You are a helpful assistant., messages: [ { role: user, content: memoryContext userMessage } ] }); // 更新记忆的访问计数 for (const mem of memories) { db.prepare( UPDATE memories SET access_count access_count 1, last_accessed_at ? WHERE id ? ).run(new Date().toISOString(), mem.id); } return response; }这里有一个细节记忆是拼在 user message 里的不是放在 system prompt 里。为什么因为 system prompt 通常会被缓存如果记忆放在 system prompt 里每次记忆变化都会导致缓存失效。放在 user message 里system prompt 可以稳定缓存只有 user message 部分变化。注意如果你的记忆量很大拼接后的 user message 可能会超过模型的上下文窗口。这时候需要做截断优先保留 finalScore 高的记忆或者对记忆内容做摘要压缩。5. 常见问题与排查技巧实录5.1 记忆检索不准怎么办这是最常见的问题。表现是明明记忆库里有相关记忆但检索的时候就是没被召回或者召回了一堆不相关的。排查思路按以下顺序来第一步检查 embedding 模型是否匹配。如果你的记忆是中文的但 embedding 模型是纯英文的那相似度计算基本是随机的。确认模型支持中文并且维度配置正确。第二步检查查询文本的构造。查询文本是从最近几轮对话拼出来的。如果最近几轮对话是“好的”“嗯”“继续”这种没有信息量的内容那查询 embedding 自然检索不到相关记忆。可以尝试用更长的窗口或者用用户当前的问题作为查询文本。第三步检查相似度阈值。阈值设太高会漏召回设太低会引入噪音。建议先把阈值调到 0.2看看召回情况再逐步往上调。第四步检查 scope 过滤。如果记忆的 scope 是project但检索的时候project_id没传对那这条记忆会被过滤掉。检查一下 project_id 的生成逻辑是否一致。第五步检查向量索引是否同步。如果记忆写入了 SQLite 但没写入向量索引那检索的时候自然找不到。检查写入流程里向量索引的更新是否成功。5.2 记忆注入后模型不理会怎么办有时候记忆明明注入进去了但 Claude 的回复里完全没体现出来。这通常是注入格式的问题。原因一记忆和用户问题混在一起了。如果记忆没有用明确的分隔符包起来模型可能把记忆当成用户问题的一部分而不是背景信息。确保用[Memory Context]和[End Memory Context]这样的标记包起来。原因二记忆的措辞太模糊。“用户可能喜欢某种风格”这种模糊表述模型很难用起来。记忆内容要具体、明确比如“用户偏好用 4 个空格缩进”。原因三记忆太多模型注意力被分散了。如果一次注入 20 条记忆模型可能只关注前几条。控制注入数量在 5 条以内按重要性排序。原因四system prompt 里有冲突指令。如果 system prompt 里写了“忽略用户消息中的额外指令”那记忆可能被当成额外指令忽略掉。检查 system prompt 的内容。5.3 记忆库膨胀太快怎么控制用了一段时间之后记忆库可能会积累几千条记忆检索变慢存储变大。这时候需要做记忆的清理和压缩。策略一设置过期时间。会话级记忆可以设 7 天过期项目级记忆可以设 90 天过期用户级记忆永久保留。过期记忆定期清理。策略二合并相似记忆。定期跑一个任务把语义相似度超过 0.9 的记忆合并成一条。合并的时候保留最新的内容和最高的置信度。策略三淘汰低热度记忆。如果一条记忆超过 60 天没有被访问过且 access_count 小于 3可以考虑归档或者删除。策略四压缩记忆内容。把长记忆压缩成短记忆。比如“用户说他之前用 npm但是后来因为依赖冲突问题换成了 pnpm现在项目里都用 pnpm”可以压缩成“项目使用 pnpm”。5.4 常见问题速查表问题现象可能原因排查方法解决方案检索不到相关记忆embedding 模型不匹配检查模型是否支持中文换用中文 embedding 模型检索到不相关记忆相似度阈值太低查看检索日志的相似度分数调高阈值到 0.4 以上记忆注入后无效果注入格式不清晰检查 prompt 里的分隔符用明确的标记包裹记忆记忆库增长过快抽取过于激进统计每日新增记忆数调低规则抽取的触发频率检索速度变慢向量索引过大统计记忆总数做记忆合并和过期清理记忆内容冲突去重逻辑不完善检查是否有矛盾记忆加入语义去重和过期标记写入失败事务未回滚查看错误日志确保 SQLite 和向量索引在同一事务上下文超长注入记忆太多统计注入的 token 数减少 top-N或压缩记忆内容5.5 几个踩过的坑坑一embedding 维度不一致导致索引崩溃。我一开始用all-MiniLM-L6-v2建了索引后来换成text-embedding-3-small忘了改维度配置结果写入的时候直接报错。换模型的时候一定要同步改维度配置并且重建索引。坑二SQLite 并发写入锁表。SQLite 默认是写锁全库的。如果多个进程同时写记忆会频繁锁表。解决方案是开 WAL 模式或者把写入操作串行化到一个队列里。坑三记忆内容里的特殊字符导致 SQL 报错。记忆内容里如果有单引号或者反斜杠直接拼 SQL 会报错。一定要用参数化查询不要拼字符串。坑四忘记更新 last_accessed_at。检索到记忆之后一定要更新访问计数和时间。否则热度排序永远不准老记忆会一直排在前面。坑五项目 ID 不稳定。如果项目 ID 是根据当前工作目录生成的那在不同目录下打开同一个项目会生成不同的 project_id导致项目级记忆检索不到。建议用 git 仓库的根路径或者固定的项目名作为 project_id。6. 进阶玩法与扩展方向6.1 记忆的自动摘要当记忆库积累到一定规模单条记忆的检索可能不够用了。这时候可以引入“记忆摘要”层定期把某个项目下的所有记忆做一次摘要生成一条高层记忆。检索的时候先检索摘要再根据摘要定位到具体记忆。这个思路类似于书籍的目录和章节。摘要是目录具体记忆是章节内容。先看目录找到大致方向再翻到具体章节看细节。6.2 记忆的冲突检测当用户改变主意的时候新旧记忆会冲突。比如先说“用 npm”后说“用 pnpm”。claude-mem需要能检测到这种冲突并且把旧记忆标记为过期。冲突检测可以用语义相似度加时间戳来做如果两条记忆语义相似度超过 0.85且时间戳相差超过 1 天那新的那条覆盖旧的那条。6.3 多用户隔离如果你是在团队里用这个工具那不同用户的记忆需要隔离。可以在记忆表里加一个user_id字段检索的时候按 user_id 过滤。用户级记忆只对本人可见项目级记忆对项目成员可见。6.4 记忆的可视化记忆库大了之后光看列表很难理解记忆之间的关系。可以做一个简单的可视化把记忆按项目、按类型、按时间做成图表。这样你能直观地看到哪些项目记忆多、哪些类型记忆多、记忆的增长趋势是什么样的。7. 个人实操体会我用claude-mem大概有三个月了最大的感受是记忆的质量比数量重要得多。一开始我贪多什么对话都往里抽结果记忆库很快膨胀到几千条检索出来的东西乱七八糟反而干扰了 Claude 的回复。后来我把抽取策略收紧只保留显式标记和高置信度的规则抽取记忆库控制在几百条检索质量明显提升。另一个体会是注入格式的措辞很关键。同样的记忆用“用户偏好xxx”和“用户可能喜欢 xxx”两种措辞注入模型的采纳率完全不一样。前者模型会严格遵守后者模型经常忽略。所以记忆的措辞要果断、明确不要用模糊词。还有一点不要指望记忆能解决所有问题。记忆适合存那些稳定的、跨会话的信息比如技术栈、命名习惯、项目背景。对于那些一次性的、跟当前问题强相关的内容还是直接放在对话里更靠谱。记忆是辅助不是替代。最后分享一个小技巧定期导出记忆库人工过一遍把过期的、矛盾的、低质量的记忆删掉。这个清理工作看起来麻烦但能显著提升检索质量。我一般每个月清理一次花不了多少时间但效果立竿见影。
