1. 项目概述与核心定位1.1 这个工具到底解决什么问题claude-mem 是一个围绕 Claude 对话场景构建的记忆持久化与上下文管理方案。它的核心目标很直接让 Claude 在跨会话、跨项目的使用过程中能够记住之前聊过的关键信息而不是每次开新对话都从零开始。如果你日常用 Claude 写代码、做技术方案、整理文档大概率遇到过这个场景昨天跟 Claude 讨论了一套完整的数据库表结构设计今天开新窗口想继续优化结果它完全不记得昨天聊了什么你得把表结构、业务背景、约束条件重新贴一遍。一次两次还能忍天天这么干就是纯粹的效率损耗。claude-mem 要做的就是把这层记忆补上。它的基本工作方式是在本地维护一个结构化的记忆存储层把对话中产生的关键信息项目背景、技术决策、代码片段、待办事项等提取出来按项目或主题分类存储。当你在新会话中提出相关问题时工具会自动检索匹配的记忆条目注入到当前上下文中让 Claude 快速恢复对之前工作的认知。适合谁来用三类人收益最明显一是长期用 Claude 做开发辅助的程序员项目周期长、上下文复杂二是用 Claude 做研究和写作的知识工作者需要跨天甚至跨周持续推进同一主题三是团队协作场景下需要把某个成员的 Claude 对话成果沉淀下来供其他人复用的情况。1.2 为什么不是简单的“复制粘贴历史记录”有人可能会想我直接把之前的对话记录存成文本需要的时候贴进去不就行了这个做法在信息量小的时候可行但有几个硬伤。第一上下文窗口是有限资源。Claude 的上下文窗口虽然不小但你不可能把几十次对话的全部记录都塞进去token 消耗巨大且会稀释当前问题的注意力。claude-mem 的做法是按需检索只把跟当前问题最相关的记忆片段注入而不是全量灌入。第二原始对话记录噪音太大。一次对话里可能聊了五六个话题其中只有一两个跟你当前的问题相关。直接贴原始记录Claude 需要花精力去筛选效果远不如提前提炼好的结构化记忆。第三跨项目隔离。你可能同时推进三个项目每个项目的技术栈和业务逻辑完全不同。如果记忆混在一起A 项目的决策被误用到 B 项目上后果很严重。claude-mem 通过项目维度的隔离机制来避免这个问题。注意记忆的“提炼”环节是整个方案里最需要花心思的部分。提炼质量直接决定了后续检索的准确率后面会详细讲怎么设计提炼规则。2. 核心架构与设计思路拆解2.1 整体架构分层claude-mem 的架构可以拆成四层从下往上依次是存储层负责持久化记忆数据。常见的选择是本地文件系统JSON 或 Markdown 格式或者轻量级数据库SQLite。选本地文件的好处是透明、可版本控制、方便手动编辑选 SQLite 的好处是查询效率高、支持结构化检索。我个人的建议是记忆条目数量在几百条以内用 JSON 文件完全够用超过一千条再考虑上 SQLite。索引层负责给记忆条目建立可检索的索引。最简单的做法是关键词倒排索引复杂一点可以用向量嵌入做语义检索。关键词索引的优点是零依赖、速度快、结果可解释向量检索的优点是能匹配语义相近但用词不同的查询。实际使用中两者结合效果最好——先用关键词做粗筛再用向量做精排。检索层负责根据当前对话内容从索引中找出最相关的记忆条目。这里涉及一个关键决策什么时候触发检索。有两种策略一种是被动的每次用户发消息都检索一次另一种是主动的由用户显式触发比如输入一个特定命令。被动检索体验更流畅但消耗更多计算资源主动检索更可控但需要用户养成习惯。折中方案是首次对话时被动检索一次建立上下文后续由用户按需触发。注入层负责把检索到的记忆条目格式化后拼接到当前对话的上下文中。格式很关键——不能直接把原始 JSON 丢进去需要转成 Claude 容易理解的自然语言描述。通常的做法是加一个前缀说明比如“以下是之前关于本项目的关键决策记录”然后逐条列出。2.2 记忆条目的数据结构设计每条记忆记录需要包含哪些字段这是整个方案的基础设计不好后面全是坑。我的经验是至少要有这几个字段字段名类型说明是否必填idstring唯一标识建议用时间戳随机串是projectstring所属项目标识用于隔离是categorystring分类如 decision/code/todo/context是summarystring一句话摘要检索时主要匹配这个字段是detailstring详细内容检索命中后注入上下文是tagsarray标签列表辅助检索否created_attimestamp创建时间是updated_attimestamp最后更新时间是source_sessionstring来源会话标识方便追溯否category字段的设计特别重要。我试过不分类直接存结果检索时经常把“待办事项”和“技术决策”混在一起返回噪音很大。后来强制分类之后检索准确率明显提升。常用的分类我建议就四五个太多了反而增加维护负担。summary和detail分开设计也是踩过坑之后的经验。一开始我只存一个 content 字段结果检索时要么匹配到摘要但注入的内容太长要么匹配到详细内容但摘要信息丢失。分开之后检索用 summary注入用 detail各司其职。2.3 为什么选择本地优先的方案claude-mem 这类工具数据存储位置有两个选择本地或者云端。我坚定推荐本地优先理由有三。隐私和可控性。你的对话记录里可能包含代码、业务逻辑、甚至一些敏感信息。放在本地数据完全在你自己的掌控之下不用担心第三方服务的隐私政策变化或者数据泄露。零延迟。本地读写没有网络往返检索和注入的延迟可以控制在毫秒级。云端方案即使优化得再好网络抖动也会影响体验。可定制性。本地方案意味着你可以随时手动编辑记忆文件、调整检索规则、甚至写脚本批量处理。云端方案通常只提供有限的 API很多细节你控制不了。当然本地方案也有代价多设备同步需要自己解决。我的做法是用 Git 仓库管理记忆文件换设备时 pull 一下就行。冲突处理也简单记忆条目基本是追加写入很少出现同一时间修改同一条的情况。3. 记忆提炼与检索的实操要点3.1 记忆提炼的触发时机与规则记忆不是越多越好冗余的记忆会拖慢检索速度、降低准确率。关键是要在正确的时机提炼正确的信息。触发时机我建议设三个一是对话结束时用户显式结束或长时间无交互做一次全量提炼二是对话过程中检测到关键决策时比如用户说“就按这个方案来”即时提炼一条三是用户手动触发比如输入/memorize命令。提炼规则是核心。我总结了一个“三问过滤法”这条信息在未来类似场景下还会用到吗如果只是一次性的问答不存。这条信息脱离当前对话上下文后还能独立理解吗如果不能需要补充背景后再存。这条信息跟已有的记忆条目重复吗如果重复更新旧条目而不是新建。具体到内容类型我通常提炼这几类技术决策选了什么方案、为什么选、排除了哪些备选方案代码约定命名规范、目录结构、关键接口定义业务背景项目目标、用户画像、核心流程待办事项未完成的工作、待验证的假设问题记录遇到的坑、排查过程、最终解法实操心得提炼时尽量用陈述句避免疑问句和模糊表述。“数据库用 PostgreSQL”比“数据库可能用 PostgreSQL 吧”好得多。后者在后续检索时会产生歧义。3.2 检索策略的调优检索策略直接决定了记忆功能好不好用。我试过几种方案说一下各自的优劣。纯关键词匹配是最简单的把当前用户消息分词后跟记忆条目的 summary 和 tags 做匹配。优点是快、可解释缺点是同义词和近义词匹配不到。比如用户问“数据库选的什么”记忆里存的是“存储层采用 PostgreSQL”关键词匹配就找不到。向量语义检索能解决同义词问题但需要额外的嵌入模型和向量存储。对于本地方案来说引入嵌入模型会增加不少复杂度。如果你的记忆条目在几百条以内我建议先用关键词匹配配合精心设计的 tags 来弥补语义鸿沟。混合方案是我目前用得最顺的先用关键词做粗筛召回 top 20 条候选然后对这 20 条做一个简单的语义相似度计算可以用轻量级的本地模型精排出 top 5 条注入上下文。这样兼顾了速度和准确率。检索时还有一个容易忽略的点时间衰减。越近的记忆通常越相关。我会在检索评分里加一个时间因子比如最近一周内的记忆权重乘以 1.2一个月前的乘以 0.8。这个调整对提升检索质量帮助很大。3.3 上下文注入的格式设计检索到记忆之后怎么把它们塞进当前对话也是有讲究的。我见过两种极端做法一种是直接把 JSON 丢进去Claude 理解起来费劲另一种是写一大段自然语言说明token 浪费严重。我的做法是用一个简洁的结构化格式类似这样[项目记忆 - 项目名] - [决策] 存储层采用 PostgreSQL原因是需要 JSON 字段支持和全文检索能力 - [约定] API 路由统一用 /api/v1/ 前缀版本号在 URL 中体现 - [待办] 用户认证模块尚未接入计划下周处理这个格式的好处是Claude 能快速识别这是背景信息而非当前问题每条记忆的分类和摘要一目了然token 消耗也可控。前缀[项目记忆 - 项目名]明确告诉 Claude 这些信息的来源和适用范围。注入位置也有讲究。我通常放在用户当前消息之前作为 system 或 context 消息注入。不要放在对话最开头那样会被后续对话淹没也不要放在用户消息之后那样 Claude 可能来不及参考。4. 完整实操流程与配置方法4.1 环境准备与初始化假设你用的是 Node.js 环境Python 环境逻辑类似初始化步骤如下。第一步创建项目目录和记忆存储目录mkdir -p claude-mem/memories cd claude-mem npm init -y第二步安装依赖。核心依赖就两个一个用于文件读写Node 内置的 fs 就够一个用于命令行交互推荐 commander 或 yargsnpm install commander第三步创建记忆存储的初始文件memories/index.json{ version: 1.0, projects: {}, entries: [] }第四步创建配置文件config.json定义检索参数{ maxEntriesPerRetrieval: 5, timeDecayFactor: 0.95, minRelevanceScore: 0.3, categories: [decision, code, todo, context, issue] }这几个参数的含义后面会逐个解释。maxEntriesPerRetrieval控制每次注入的最大记忆条数设太大浪费 token设太小可能漏掉关键信息5 条是我实测下来比较平衡的值。4.2 记忆写入的实现写入逻辑的核心是接收一条原始信息提炼成结构化记忆追加到存储文件。const fs require(fs); const path require(path); const MEMORY_FILE path.join(__dirname, memories, index.json); function loadMemories() { const raw fs.readFileSync(MEMORY_FILE, utf-8); return JSON.parse(raw); } function saveMemories(data) { fs.writeFileSync(MEMORY_FILE, JSON.stringify(data, null, 2), utf-8); } function addMemory({ project, category, summary, detail, tags [] }) { const data loadMemories(); const now new Date().toISOString(); // 去重检查同项目同分类下summary 相似度高的视为重复 const existing data.entries.find(e e.project project e.category category similarity(e.summary, summary) 0.8 ); if (existing) { existing.detail detail; existing.updated_at now; existing.tags [...new Set([...existing.tags, ...tags])]; } else { data.entries.push({ id: ${Date.now()}-${Math.random().toString(36).slice(2, 8)}, project, category, summary, detail, tags, created_at: now, updated_at: now }); } saveMemories(data); }这里的similarity函数可以用简单的编辑距离或者 Jaccard 相似度实现。去重逻辑很重要否则同一个决策被反复记录检索时会返回一堆重复结果。4.3 检索与注入的实现检索的核心是根据当前查询从记忆库中找出最相关的条目。function retrieveMemories(query, project, config) { const data loadMemories(); const queryTokens tokenize(query); const now Date.now(); const scored data.entries .filter(e e.project project) .map(entry { // 关键词匹配得分 const entryTokens tokenize(entry.summary entry.tags.join( )); const keywordScore jaccardSimilarity(queryTokens, entryTokens); // 时间衰减因子 const ageInDays (now - new Date(entry.created_at).getTime()) / 86400000; const timeScore Math.pow(config.timeDecayFactor, ageInDays); // 综合得分 const finalScore keywordScore * 0.7 timeScore * 0.3; return { entry, score: finalScore }; }) .filter(item item.score config.minRelevanceScore) .sort((a, b) b.score - a.score) .slice(0, config.maxEntriesPerRetrieval); return scored.map(item item.entry); }timeDecayFactor设为 0.95 意味着每过一天时间得分乘以 0.95。一个月后时间得分大约是 0.21权重明显下降。这个值可以根据你的使用频率调整——如果你每天都有大量新记忆产生可以设得更低比如 0.9让近期记忆更突出。注入格式化function formatForInjection(memories, projectName) { if (memories.length 0) return ; const lines memories.map(m { const categoryLabel { decision: 决策, code: 约定, todo: 待办, context: 背景, issue: 问题 }[m.category] || m.category; return - [${categoryLabel}] ${m.summary}; }); return [项目记忆 - ${projectName}]\n${lines.join(\n)}; }4.4 与 Claude 对话流程的集成集成方式取决于你用的是 Claude 的哪种接入方式。如果是 API 调用在构造 messages 数组时把格式化后的记忆作为一条独立的 context 消息插入async function chatWithMemory(userMessage, project) { const memories retrieveMemories(userMessage, project, config); const memoryContext formatForInjection(memories, project); const messages []; if (memoryContext) { messages.push({ role: user, content: memoryContext }); messages.push({ role: assistant, content: 已了解项目背景请继续。 }); } messages.push({ role: user, content: userMessage }); // 调用 Claude API... }如果是用 Web 界面可以写一个浏览器插件或者手动把记忆内容粘贴到对话开头。手动方式虽然笨但对于轻度用户来说反而最省事——不需要维护任何代码只需要在开新对话时把记忆文件里的相关内容贴进去。注意注入记忆后加一条 assistant 的确认消息能让 Claude 更好地“进入状态”。我试过不加确认消息直接问问题Claude 有时会把记忆内容当成当前问题的一部分来回答加了确认消息之后这个问题就消失了。5. 常见问题与排查技巧实录5.1 检索结果不相关怎么办这是最常见的问题。表现是明明记忆库里有相关内容但检索出来的都是不相关的条目。排查思路按优先级来先检查 project 字段是否匹配。很多时候是项目标识写错了比如写入时用了my-project检索时用了my_project下划线和连字符不一致导致过滤掉了所有条目。建议在配置里维护一个项目标识列表写入和检索都从这个列表里取。再检查 summary 的措辞。如果 summary 写得太抽象比如“讨论了架构问题”检索时无论用户问什么具体问题都匹配不上。好的 summary 应该包含具体的技术名词和关键决策点比如“确定使用 Redis 做会话缓存TTL 设为 24 小时”。最后调整检索参数。minRelevanceScore设得太高会过滤掉边缘相关的条目设得太低会引入噪音。建议先用 0.3 试如果发现漏检就降到 0.2如果发现噪音多就升到 0.4。5.2 记忆条目膨胀怎么控制用了一段时间之后记忆条目可能从几十条涨到几百条检索效率下降而且很多旧条目已经过时了。我的做法是定期做记忆整理大概每个月一次。整理时做三件事一是合并重复条目。同一个决策在不同时间被记录了多次合并成一条保留最新的 detail。二是归档过时条目。给条目加一个archived字段过时的设为 true检索时默认过滤掉。不要直接删除万一以后需要追溯呢。三是压缩 detail。有些条目的 detail 写得太长把整个对话记录都塞进去了。压缩成关键信息即可详细内容如果需要保留单独存到附件文件里。问题表现可能原因排查方法解决方案检索结果为空project 标识不匹配检查写入和检索的 project 值统一项目标识命名规范检索结果不相关summary 措辞太抽象人工检查命中条目的 summary重写 summary加入具体技术名词检索结果重复去重逻辑失效检查 similarity 阈值降低阈值或改用更严格的去重规则注入后 Claude 理解偏差格式不清晰检查注入内容的格式加分类标签和来源说明记忆条目过多缺乏定期整理统计条目总数和分类分布每月整理一次归档过时条目5.3 多项目并行时的隔离问题同时推进多个项目时最大的风险是记忆串味。A 项目的技术决策被误用到 B 项目上可能导致严重的架构不一致。我的隔离方案是三层防护第一层是 project 字段强制过滤。检索时只返回当前项目的记忆这是硬隔离代码层面保证不会跨项目。第二层是 tags 辅助区分。有些记忆可能跨项目通用比如“代码注释用中文”这种个人偏好可以打上global标签检索时额外把 global 标签的条目也纳入。但这类条目要严格控制数量不超过总条目的 10%。第三层是注入时的显式声明。注入内容里明确写[项目记忆 - 项目名]让 Claude 知道这些记忆的适用范围。如果用户切换了项目但忘记切换记忆库Claude 看到项目名不匹配也会提出疑问。实操心得我习惯在项目根目录放一个.claude-mem-project文件里面就写项目标识。工具启动时自动读取这个文件确定当前项目避免手动指定时写错。5.4 记忆写入的时机把握写早了信息不完整写晚了容易忘。我的经验是分两种场景即时写入适用于明确的决策点。当对话中出现“就这个方案了”“按这个来”“确定用 XX”这类表述时立即提炼一条记忆。这时候信息最新鲜上下文最完整。批量写入适用于对话结束时。把整段对话过一遍提炼出所有值得记录的信息。批量写入的好处是可以做全局去重和分类避免碎片化。两种方式结合使用效果最好。即时写入保证关键信息不丢失批量写入保证记忆库的整洁和完整。6. 进阶优化与扩展思路6.1 记忆的自动过期与刷新不是所有记忆都值得永久保留。技术选型类的记忆可能半年后就需要更新待办事项类的记忆完成后就应该归档。我给每条记忆加了一个ttl字段time to live单位是天。默认值根据分类来定决策类 180 天代码约定类 365 天待办类 30 天背景类 365 天问题类 90 天。检索时自动过滤掉已过期的条目但不过期删除只是标记为expired。过期条目的处理有两种策略一是直接归档不再检索二是触发一次“记忆刷新”——在下次相关对话时提醒用户“这条记忆已过期是否需要更新”。我倾向于后者因为技术决策的过期往往意味着需要重新评估主动提醒比默默归档更有价值。6.2 团队共享记忆的方案个人使用场景下记忆文件放在本地就够了。但团队协作时需要把记忆共享给其他人。最简单的方案是用 Git 仓库管理记忆文件。每个人本地有一份定期 pull 和 push。冲突处理靠 Git 本身因为记忆条目基本是追加写入冲突概率很低。复杂一点的方案是搭一个轻量级的同步服务。可以用一个简单的 HTTP 服务暴露读写接口团队成员通过接口读写记忆。好处是实时同步坏处是需要维护服务。我的建议是团队规模在 5 人以内用 Git 方案完全够用超过 5 人再考虑搭服务。Git 方案还有一个额外好处——记忆的变更历史天然被记录下来谁在什么时候添加了什么记忆一目了然。6.3 与不同 Claude 接入方式的适配claude-mem 的核心逻辑是通用的但跟不同的 Claude 接入方式对接时细节上有差异。API 接入是最灵活的可以在请求构造阶段自由插入记忆内容。需要注意的是 API 的 token 限制注入记忆后要确保总 token 数不超过限制。我的做法是在注入前估算 token 数如果超了就减少注入条数。Web 界面接入需要通过浏览器插件或者手动粘贴。插件方案需要处理页面 DOM 结构变化的问题维护成本较高。手动方案虽然笨但最稳定适合不想折腾的用户。命令行工具接入如果有的话通常支持配置文件或环境变量可以把记忆注入逻辑封装成一个 wrapper 脚本在调用命令行工具之前先检索并注入记忆。不管哪种方式核心原则是一样的在正确的时间注入正确的内容。接入方式只是管道记忆的提炼和检索质量才是决定效果的关键。6.4 记忆质量的自检清单最后分享一个我常用的记忆质量自检清单每次批量整理时过一遍每条记忆的 summary 是否包含至少一个具体的技术名词或决策点同一项目同一分类下是否有重复或高度相似的条目是否有超过 30 天未更新的待办类记忆如果有是完成了还是遗忘了是否有记忆条目的 detail 超过 500 字如果有考虑拆分或压缩。最近一周的检索命中率如何如果低于 50%需要调整检索参数或重写 summary。这个清单看起来简单但坚持执行能显著提升记忆库的整体质量。我自己的记忆库维护了半年多条目数控制在 200 条左右检索命中率稳定在 70% 以上基本能做到“问什么就能找到什么”。这个方案后续还可以往几个方向扩展比如加入记忆的版本对比功能看看某个决策是怎么演变的或者做一个简单的可视化界面直观展示记忆库的结构和分布再或者接入本地的小型语言模型做更精准的语义检索。这些都属于锦上添花核心的记忆提炼和检索逻辑跑通了剩下的都是增量优化。 
长河君 · 2026/10/25 6:45:02 · 阅读 1.2k Claude记忆持久化方案：跨会话上下文管理与检索优化实践
1. 项目概述与核心定位1.1 这个工具到底解决什么问题claude-mem 是一个围绕 Claude 对话场景构建的记忆持久化与上下文管理方案。它的核心目标很直接让 Claude 在跨会话、跨项目的使用过程中能够记住之前聊过的关键信息而不是每次开新对话都从零开始。如果你日常用 Claude 写代码、做技术方案、整理文档大概率遇到过这个场景昨天跟 Claude 讨论了一套完整的数据库表结构设计今天开新窗口想继续优化结果它完全不记得昨天聊了什么你得把表结构、业务背景、约束条件重新贴一遍。一次两次还能忍天天这么干就是纯粹的效率损耗。claude-mem 要做的就是把这层记忆补上。它的基本工作方式是在本地维护一个结构化的记忆存储层把对话中产生的关键信息项目背景、技术决策、代码片段、待办事项等提取出来按项目或主题分类存储。当你在新会话中提出相关问题时工具会自动检索匹配的记忆条目注入到当前上下文中让 Claude 快速恢复对之前工作的认知。适合谁来用三类人收益最明显一是长期用 Claude 做开发辅助的程序员项目周期长、上下文复杂二是用 Claude 做研究和写作的知识工作者需要跨天甚至跨周持续推进同一主题三是团队协作场景下需要把某个成员的 Claude 对话成果沉淀下来供其他人复用的情况。1.2 为什么不是简单的“复制粘贴历史记录”有人可能会想我直接把之前的对话记录存成文本需要的时候贴进去不就行了这个做法在信息量小的时候可行但有几个硬伤。第一上下文窗口是有限资源。Claude 的上下文窗口虽然不小但你不可能把几十次对话的全部记录都塞进去token 消耗巨大且会稀释当前问题的注意力。claude-mem 的做法是按需检索只把跟当前问题最相关的记忆片段注入而不是全量灌入。第二原始对话记录噪音太大。一次对话里可能聊了五六个话题其中只有一两个跟你当前的问题相关。直接贴原始记录Claude 需要花精力去筛选效果远不如提前提炼好的结构化记忆。第三跨项目隔离。你可能同时推进三个项目每个项目的技术栈和业务逻辑完全不同。如果记忆混在一起A 项目的决策被误用到 B 项目上后果很严重。claude-mem 通过项目维度的隔离机制来避免这个问题。注意记忆的“提炼”环节是整个方案里最需要花心思的部分。提炼质量直接决定了后续检索的准确率后面会详细讲怎么设计提炼规则。2. 核心架构与设计思路拆解2.1 整体架构分层claude-mem 的架构可以拆成四层从下往上依次是存储层负责持久化记忆数据。常见的选择是本地文件系统JSON 或 Markdown 格式或者轻量级数据库SQLite。选本地文件的好处是透明、可版本控制、方便手动编辑选 SQLite 的好处是查询效率高、支持结构化检索。我个人的建议是记忆条目数量在几百条以内用 JSON 文件完全够用超过一千条再考虑上 SQLite。索引层负责给记忆条目建立可检索的索引。最简单的做法是关键词倒排索引复杂一点可以用向量嵌入做语义检索。关键词索引的优点是零依赖、速度快、结果可解释向量检索的优点是能匹配语义相近但用词不同的查询。实际使用中两者结合效果最好——先用关键词做粗筛再用向量做精排。检索层负责根据当前对话内容从索引中找出最相关的记忆条目。这里涉及一个关键决策什么时候触发检索。有两种策略一种是被动的每次用户发消息都检索一次另一种是主动的由用户显式触发比如输入一个特定命令。被动检索体验更流畅但消耗更多计算资源主动检索更可控但需要用户养成习惯。折中方案是首次对话时被动检索一次建立上下文后续由用户按需触发。注入层负责把检索到的记忆条目格式化后拼接到当前对话的上下文中。格式很关键——不能直接把原始 JSON 丢进去需要转成 Claude 容易理解的自然语言描述。通常的做法是加一个前缀说明比如“以下是之前关于本项目的关键决策记录”然后逐条列出。2.2 记忆条目的数据结构设计每条记忆记录需要包含哪些字段这是整个方案的基础设计不好后面全是坑。我的经验是至少要有这几个字段字段名类型说明是否必填idstring唯一标识建议用时间戳随机串是projectstring所属项目标识用于隔离是categorystring分类如 decision/code/todo/context是summarystring一句话摘要检索时主要匹配这个字段是detailstring详细内容检索命中后注入上下文是tagsarray标签列表辅助检索否created_attimestamp创建时间是updated_attimestamp最后更新时间是source_sessionstring来源会话标识方便追溯否category字段的设计特别重要。我试过不分类直接存结果检索时经常把“待办事项”和“技术决策”混在一起返回噪音很大。后来强制分类之后检索准确率明显提升。常用的分类我建议就四五个太多了反而增加维护负担。summary和detail分开设计也是踩过坑之后的经验。一开始我只存一个 content 字段结果检索时要么匹配到摘要但注入的内容太长要么匹配到详细内容但摘要信息丢失。分开之后检索用 summary注入用 detail各司其职。2.3 为什么选择本地优先的方案claude-mem 这类工具数据存储位置有两个选择本地或者云端。我坚定推荐本地优先理由有三。隐私和可控性。你的对话记录里可能包含代码、业务逻辑、甚至一些敏感信息。放在本地数据完全在你自己的掌控之下不用担心第三方服务的隐私政策变化或者数据泄露。零延迟。本地读写没有网络往返检索和注入的延迟可以控制在毫秒级。云端方案即使优化得再好网络抖动也会影响体验。可定制性。本地方案意味着你可以随时手动编辑记忆文件、调整检索规则、甚至写脚本批量处理。云端方案通常只提供有限的 API很多细节你控制不了。当然本地方案也有代价多设备同步需要自己解决。我的做法是用 Git 仓库管理记忆文件换设备时 pull 一下就行。冲突处理也简单记忆条目基本是追加写入很少出现同一时间修改同一条的情况。3. 记忆提炼与检索的实操要点3.1 记忆提炼的触发时机与规则记忆不是越多越好冗余的记忆会拖慢检索速度、降低准确率。关键是要在正确的时机提炼正确的信息。触发时机我建议设三个一是对话结束时用户显式结束或长时间无交互做一次全量提炼二是对话过程中检测到关键决策时比如用户说“就按这个方案来”即时提炼一条三是用户手动触发比如输入/memorize命令。提炼规则是核心。我总结了一个“三问过滤法”这条信息在未来类似场景下还会用到吗如果只是一次性的问答不存。这条信息脱离当前对话上下文后还能独立理解吗如果不能需要补充背景后再存。这条信息跟已有的记忆条目重复吗如果重复更新旧条目而不是新建。具体到内容类型我通常提炼这几类技术决策选了什么方案、为什么选、排除了哪些备选方案代码约定命名规范、目录结构、关键接口定义业务背景项目目标、用户画像、核心流程待办事项未完成的工作、待验证的假设问题记录遇到的坑、排查过程、最终解法实操心得提炼时尽量用陈述句避免疑问句和模糊表述。“数据库用 PostgreSQL”比“数据库可能用 PostgreSQL 吧”好得多。后者在后续检索时会产生歧义。3.2 检索策略的调优检索策略直接决定了记忆功能好不好用。我试过几种方案说一下各自的优劣。纯关键词匹配是最简单的把当前用户消息分词后跟记忆条目的 summary 和 tags 做匹配。优点是快、可解释缺点是同义词和近义词匹配不到。比如用户问“数据库选的什么”记忆里存的是“存储层采用 PostgreSQL”关键词匹配就找不到。向量语义检索能解决同义词问题但需要额外的嵌入模型和向量存储。对于本地方案来说引入嵌入模型会增加不少复杂度。如果你的记忆条目在几百条以内我建议先用关键词匹配配合精心设计的 tags 来弥补语义鸿沟。混合方案是我目前用得最顺的先用关键词做粗筛召回 top 20 条候选然后对这 20 条做一个简单的语义相似度计算可以用轻量级的本地模型精排出 top 5 条注入上下文。这样兼顾了速度和准确率。检索时还有一个容易忽略的点时间衰减。越近的记忆通常越相关。我会在检索评分里加一个时间因子比如最近一周内的记忆权重乘以 1.2一个月前的乘以 0.8。这个调整对提升检索质量帮助很大。3.3 上下文注入的格式设计检索到记忆之后怎么把它们塞进当前对话也是有讲究的。我见过两种极端做法一种是直接把 JSON 丢进去Claude 理解起来费劲另一种是写一大段自然语言说明token 浪费严重。我的做法是用一个简洁的结构化格式类似这样[项目记忆 - 项目名] - [决策] 存储层采用 PostgreSQL原因是需要 JSON 字段支持和全文检索能力 - [约定] API 路由统一用 /api/v1/ 前缀版本号在 URL 中体现 - [待办] 用户认证模块尚未接入计划下周处理这个格式的好处是Claude 能快速识别这是背景信息而非当前问题每条记忆的分类和摘要一目了然token 消耗也可控。前缀[项目记忆 - 项目名]明确告诉 Claude 这些信息的来源和适用范围。注入位置也有讲究。我通常放在用户当前消息之前作为 system 或 context 消息注入。不要放在对话最开头那样会被后续对话淹没也不要放在用户消息之后那样 Claude 可能来不及参考。4. 完整实操流程与配置方法4.1 环境准备与初始化假设你用的是 Node.js 环境Python 环境逻辑类似初始化步骤如下。第一步创建项目目录和记忆存储目录mkdir -p claude-mem/memories cd claude-mem npm init -y第二步安装依赖。核心依赖就两个一个用于文件读写Node 内置的 fs 就够一个用于命令行交互推荐 commander 或 yargsnpm install commander第三步创建记忆存储的初始文件memories/index.json{ version: 1.0, projects: {}, entries: [] }第四步创建配置文件config.json定义检索参数{ maxEntriesPerRetrieval: 5, timeDecayFactor: 0.95, minRelevanceScore: 0.3, categories: [decision, code, todo, context, issue] }这几个参数的含义后面会逐个解释。maxEntriesPerRetrieval控制每次注入的最大记忆条数设太大浪费 token设太小可能漏掉关键信息5 条是我实测下来比较平衡的值。4.2 记忆写入的实现写入逻辑的核心是接收一条原始信息提炼成结构化记忆追加到存储文件。const fs require(fs); const path require(path); const MEMORY_FILE path.join(__dirname, memories, index.json); function loadMemories() { const raw fs.readFileSync(MEMORY_FILE, utf-8); return JSON.parse(raw); } function saveMemories(data) { fs.writeFileSync(MEMORY_FILE, JSON.stringify(data, null, 2), utf-8); } function addMemory({ project, category, summary, detail, tags [] }) { const data loadMemories(); const now new Date().toISOString(); // 去重检查同项目同分类下summary 相似度高的视为重复 const existing data.entries.find(e e.project project e.category category similarity(e.summary, summary) 0.8 ); if (existing) { existing.detail detail; existing.updated_at now; existing.tags [...new Set([...existing.tags, ...tags])]; } else { data.entries.push({ id: ${Date.now()}-${Math.random().toString(36).slice(2, 8)}, project, category, summary, detail, tags, created_at: now, updated_at: now }); } saveMemories(data); }这里的similarity函数可以用简单的编辑距离或者 Jaccard 相似度实现。去重逻辑很重要否则同一个决策被反复记录检索时会返回一堆重复结果。4.3 检索与注入的实现检索的核心是根据当前查询从记忆库中找出最相关的条目。function retrieveMemories(query, project, config) { const data loadMemories(); const queryTokens tokenize(query); const now Date.now(); const scored data.entries .filter(e e.project project) .map(entry { // 关键词匹配得分 const entryTokens tokenize(entry.summary entry.tags.join( )); const keywordScore jaccardSimilarity(queryTokens, entryTokens); // 时间衰减因子 const ageInDays (now - new Date(entry.created_at).getTime()) / 86400000; const timeScore Math.pow(config.timeDecayFactor, ageInDays); // 综合得分 const finalScore keywordScore * 0.7 timeScore * 0.3; return { entry, score: finalScore }; }) .filter(item item.score config.minRelevanceScore) .sort((a, b) b.score - a.score) .slice(0, config.maxEntriesPerRetrieval); return scored.map(item item.entry); }timeDecayFactor设为 0.95 意味着每过一天时间得分乘以 0.95。一个月后时间得分大约是 0.21权重明显下降。这个值可以根据你的使用频率调整——如果你每天都有大量新记忆产生可以设得更低比如 0.9让近期记忆更突出。注入格式化function formatForInjection(memories, projectName) { if (memories.length 0) return ; const lines memories.map(m { const categoryLabel { decision: 决策, code: 约定, todo: 待办, context: 背景, issue: 问题 }[m.category] || m.category; return - [${categoryLabel}] ${m.summary}; }); return [项目记忆 - ${projectName}]\n${lines.join(\n)}; }4.4 与 Claude 对话流程的集成集成方式取决于你用的是 Claude 的哪种接入方式。如果是 API 调用在构造 messages 数组时把格式化后的记忆作为一条独立的 context 消息插入async function chatWithMemory(userMessage, project) { const memories retrieveMemories(userMessage, project, config); const memoryContext formatForInjection(memories, project); const messages []; if (memoryContext) { messages.push({ role: user, content: memoryContext }); messages.push({ role: assistant, content: 已了解项目背景请继续。 }); } messages.push({ role: user, content: userMessage }); // 调用 Claude API... }如果是用 Web 界面可以写一个浏览器插件或者手动把记忆内容粘贴到对话开头。手动方式虽然笨但对于轻度用户来说反而最省事——不需要维护任何代码只需要在开新对话时把记忆文件里的相关内容贴进去。注意注入记忆后加一条 assistant 的确认消息能让 Claude 更好地“进入状态”。我试过不加确认消息直接问问题Claude 有时会把记忆内容当成当前问题的一部分来回答加了确认消息之后这个问题就消失了。5. 常见问题与排查技巧实录5.1 检索结果不相关怎么办这是最常见的问题。表现是明明记忆库里有相关内容但检索出来的都是不相关的条目。排查思路按优先级来先检查 project 字段是否匹配。很多时候是项目标识写错了比如写入时用了my-project检索时用了my_project下划线和连字符不一致导致过滤掉了所有条目。建议在配置里维护一个项目标识列表写入和检索都从这个列表里取。再检查 summary 的措辞。如果 summary 写得太抽象比如“讨论了架构问题”检索时无论用户问什么具体问题都匹配不上。好的 summary 应该包含具体的技术名词和关键决策点比如“确定使用 Redis 做会话缓存TTL 设为 24 小时”。最后调整检索参数。minRelevanceScore设得太高会过滤掉边缘相关的条目设得太低会引入噪音。建议先用 0.3 试如果发现漏检就降到 0.2如果发现噪音多就升到 0.4。5.2 记忆条目膨胀怎么控制用了一段时间之后记忆条目可能从几十条涨到几百条检索效率下降而且很多旧条目已经过时了。我的做法是定期做记忆整理大概每个月一次。整理时做三件事一是合并重复条目。同一个决策在不同时间被记录了多次合并成一条保留最新的 detail。二是归档过时条目。给条目加一个archived字段过时的设为 true检索时默认过滤掉。不要直接删除万一以后需要追溯呢。三是压缩 detail。有些条目的 detail 写得太长把整个对话记录都塞进去了。压缩成关键信息即可详细内容如果需要保留单独存到附件文件里。问题表现可能原因排查方法解决方案检索结果为空project 标识不匹配检查写入和检索的 project 值统一项目标识命名规范检索结果不相关summary 措辞太抽象人工检查命中条目的 summary重写 summary加入具体技术名词检索结果重复去重逻辑失效检查 similarity 阈值降低阈值或改用更严格的去重规则注入后 Claude 理解偏差格式不清晰检查注入内容的格式加分类标签和来源说明记忆条目过多缺乏定期整理统计条目总数和分类分布每月整理一次归档过时条目5.3 多项目并行时的隔离问题同时推进多个项目时最大的风险是记忆串味。A 项目的技术决策被误用到 B 项目上可能导致严重的架构不一致。我的隔离方案是三层防护第一层是 project 字段强制过滤。检索时只返回当前项目的记忆这是硬隔离代码层面保证不会跨项目。第二层是 tags 辅助区分。有些记忆可能跨项目通用比如“代码注释用中文”这种个人偏好可以打上global标签检索时额外把 global 标签的条目也纳入。但这类条目要严格控制数量不超过总条目的 10%。第三层是注入时的显式声明。注入内容里明确写[项目记忆 - 项目名]让 Claude 知道这些记忆的适用范围。如果用户切换了项目但忘记切换记忆库Claude 看到项目名不匹配也会提出疑问。实操心得我习惯在项目根目录放一个.claude-mem-project文件里面就写项目标识。工具启动时自动读取这个文件确定当前项目避免手动指定时写错。5.4 记忆写入的时机把握写早了信息不完整写晚了容易忘。我的经验是分两种场景即时写入适用于明确的决策点。当对话中出现“就这个方案了”“按这个来”“确定用 XX”这类表述时立即提炼一条记忆。这时候信息最新鲜上下文最完整。批量写入适用于对话结束时。把整段对话过一遍提炼出所有值得记录的信息。批量写入的好处是可以做全局去重和分类避免碎片化。两种方式结合使用效果最好。即时写入保证关键信息不丢失批量写入保证记忆库的整洁和完整。6. 进阶优化与扩展思路6.1 记忆的自动过期与刷新不是所有记忆都值得永久保留。技术选型类的记忆可能半年后就需要更新待办事项类的记忆完成后就应该归档。我给每条记忆加了一个ttl字段time to live单位是天。默认值根据分类来定决策类 180 天代码约定类 365 天待办类 30 天背景类 365 天问题类 90 天。检索时自动过滤掉已过期的条目但不过期删除只是标记为expired。过期条目的处理有两种策略一是直接归档不再检索二是触发一次“记忆刷新”——在下次相关对话时提醒用户“这条记忆已过期是否需要更新”。我倾向于后者因为技术决策的过期往往意味着需要重新评估主动提醒比默默归档更有价值。6.2 团队共享记忆的方案个人使用场景下记忆文件放在本地就够了。但团队协作时需要把记忆共享给其他人。最简单的方案是用 Git 仓库管理记忆文件。每个人本地有一份定期 pull 和 push。冲突处理靠 Git 本身因为记忆条目基本是追加写入冲突概率很低。复杂一点的方案是搭一个轻量级的同步服务。可以用一个简单的 HTTP 服务暴露读写接口团队成员通过接口读写记忆。好处是实时同步坏处是需要维护服务。我的建议是团队规模在 5 人以内用 Git 方案完全够用超过 5 人再考虑搭服务。Git 方案还有一个额外好处——记忆的变更历史天然被记录下来谁在什么时候添加了什么记忆一目了然。6.3 与不同 Claude 接入方式的适配claude-mem 的核心逻辑是通用的但跟不同的 Claude 接入方式对接时细节上有差异。API 接入是最灵活的可以在请求构造阶段自由插入记忆内容。需要注意的是 API 的 token 限制注入记忆后要确保总 token 数不超过限制。我的做法是在注入前估算 token 数如果超了就减少注入条数。Web 界面接入需要通过浏览器插件或者手动粘贴。插件方案需要处理页面 DOM 结构变化的问题维护成本较高。手动方案虽然笨但最稳定适合不想折腾的用户。命令行工具接入如果有的话通常支持配置文件或环境变量可以把记忆注入逻辑封装成一个 wrapper 脚本在调用命令行工具之前先检索并注入记忆。不管哪种方式核心原则是一样的在正确的时间注入正确的内容。接入方式只是管道记忆的提炼和检索质量才是决定效果的关键。6.4 记忆质量的自检清单最后分享一个我常用的记忆质量自检清单每次批量整理时过一遍每条记忆的 summary 是否包含至少一个具体的技术名词或决策点同一项目同一分类下是否有重复或高度相似的条目是否有超过 30 天未更新的待办类记忆如果有是完成了还是遗忘了是否有记忆条目的 detail 超过 500 字如果有考虑拆分或压缩。最近一周的检索命中率如何如果低于 50%需要调整检索参数或重写 summary。这个清单看起来简单但坚持执行能显著提升记忆库的整体质量。我自己的记忆库维护了半年多条目数控制在 200 条左右检索命中率稳定在 70% 以上基本能做到“问什么就能找到什么”。这个方案后续还可以往几个方向扩展比如加入记忆的版本对比功能看看某个决策是怎么演变的或者做一个简单的可视化界面直观展示记忆库的结构和分布再或者接入本地的小型语言模型做更精准的语义检索。这些都属于锦上添花核心的记忆提炼和检索逻辑跑通了剩下的都是增量优化。