用过 Claude Code 的朋友应该都有同一个感受单次会话里它聪明得吓人但一旦关掉终端、第二天重新开一个会话它就把昨天跟你讨论过的架构决策、你反复强调的代码风格、甚至你上周刚让它修好的那个 bug 的来龙去脉全忘得一干二净。每次都要重新解释一遍背景这种“金鱼记忆”在项目稍微复杂一点之后就特别折磨人。claude-mem 这个开源项目就是冲着这个问题去的它给 Claude Code 装上了一套长期的记忆系统把对话历史、技术决策、项目偏好这些信息自动提取、结构化、存进本地 SQLite然后在后续会话里按需检索回来。这篇文章我会从原理到实操完整过一遍包括我自己的配置参数和踩过的坑适合所有被 AI 的“失忆”折腾过、想给 Claude 加上长期记忆的开发者。1. 项目整体设计与思路拆解1.1 为什么“记忆”这件事值得单独做一个项目先说个基本事实大语言模型的上下文窗口再大也是“会话级”的关掉会话就清零。虽然你可以用 CLAUDE.md 这类文件手动沉淀一些长期约束但那基本靠人肉维护对话里产生的临时决策、偏好的演变过程、上下文的细节根本不可能靠手工同步。另一方面把所有对话历史一股脑塞进上下文也不是办法成本高、噪音大模型反而抓不住重点。claude-mem 的设计思路是把“记忆”从“上下文”里拆出来单独管理。它的核心做法是每次会话结束后后台自动把这次对话的内容跑一遍 LLM 提取抽取出结构化信息——比如技术决策、代码事实、用户的偏好和指令、项目里出现的概念定义——然后以语义可检索的形式存进 SQLite。下次新会话启动时工具会自动基于当前对话内容跑语义搜索把最相关的历史记忆片段注入到上下文里。这本质上是一个外挂的记忆层让 Claude Code 在会话之间保持连续性和学习能力。这个定位决定了它的几个核心特性本地存储、自动提取、语义检索、工具集成。我当初决定试它而不是自己写脚本就是看中了这四件事它都直接给好了不用我自己折腾。1.2 记忆的分层模型不是把聊天记录存下来而是沉淀“知识”claude-mem 最值得一提的设计是它把记忆分成了五个语义层面。我用了一段时间之后发现这个分层非常关键它决定了后面检索的质量。第一层是conversations会话记录的是会话元数据包括项目、时间、Git 分支等等。这一层相当于档案编号。第二层是messages消息保存实际的对话内容包括工具调用这些细节是其他层次记忆的数据来源。第三层是decisions决策LLM 从对话中提取出的技术选型、方案取舍、排障结论。第四层是user context用户上下文记录你表达过的偏好比如“不要用any”“提交信息用英文”“测试用pytest不用unittest”这类长期有效的指令。第五层是project context项目语义对象包含项目相关的实体、概念、术语定义比如 “PaymentService 是什么、负责什么” 这种。这五层并不是平级的而是有参考关系。决策会引用相关会话用户上下文来自特定消息项目对象也会挂在对应会话下。检索的时候这几层是联合出结果的。换句话说它存的不只是“说过什么”而是“当时为什么这么说、后来定了什么”这正是事后复盘和长期维护最需要的东西。实际用下来的感受是偶尔翻旧账的时候能直接看到当时的决策上下文和依据比自己翻聊天记录高效得多。1.3 为什么存储选 SQLite以及为什么本地优先项目用了 SQLite 而不是 PostgreSQL、MongoDB 之类的重型数据库。这个选择我非常认同。首先定位就是单机工具数据量级即便每天高强度使用 Claude Code撑死也就几十万条消息记录SQLite 毫无压力。其次 SQLite 是单文件数据库备份就是复制一个文件迁移也就是拷走配合claude-mem的数据目录整个记忆库可以随项目带走。第三Python 标准库自带 sqlite3零额外依赖安装部署省心。本地优先这件事在这个项目里不是一个可选项而是隐私底线的考虑。你的对话内容可能包含未发布的架构方案、客户信息、内部代码细节这些数据如果走云端记忆服务等于多了一个第三方知情者。claude-mem 所有数据都留在本机 SQLite 文件里嵌入向量也是本地生成不上传任何东西到外部服务。即便它调用 OpenAI 或者 Ollama 的接口做 LLM 提取和向量化也只是发送当前这一小段内容过去做一次性处理数据库中长期保存的完整记录完全在你的掌控之内。1.4 Embedding 方案选型背后的逻辑说实话这个项目一开始最让我犹豫的就是嵌入模型的选择因为嵌入方案直接决定了语义检索的效果。claude-mem 默认用的是开源模型 Hermes同时支持 OpenAI 的 text-embedding-3-small也支持通过 Ollama 跑本地嵌入模型。默认选 Hermes 而不是 OpenAI核心原因是成本和三方依赖。Hermes 可以通过 Ollama 在本地跑不需要把内容发到 OpenAI零成本、零延迟同时隐私性更好。代价是它依赖 Ollama 在你的机器上常驻如果没装或者没启动自动模式就会跳过嵌入这一步检索效果会退化成纯关键词。如果机器条件允许Hermes 的效果在本地小模型里已经不错但如果你追求极端精准的语义检索或者你已经在用 OpenAI 的 API那换用 text-embedding-3-small 会更稳。我个人的建议是能装 Ollama 就本地跑 Hermes不折腾且没成本如果对话涉及大量专业术语、代码符号那就直接切到 OpenAI 嵌入效果差异在模糊检索场景下还是挺明显的。2. 安装与基础配置实操2.1 安装依赖先装好 backdropclaude-mem 在安装上有个前置依赖跟大多数 Python CLI 工具不一样。它对应的 Claude Code 侧需要一个叫 backdrop 的插件来搭建工具调用通道。这个插件的作用是在 Claude Code 的会话里注册 claude-mem 提供的各个工具比如记忆搜索、记录、遗忘等等让 Claude 在对话中自动/手动调用它们。先说 backdrop 的安装它有两个入口。一是通过 Claude Code 插件系统在终端里执行对应命令添加插件市场然后搜索 backdrop 并安装到项目二是如果安装不上官方文档也给出.claude-plugin的配置方式。我当时在 macOS 上是直接通过市场命令装好的耗时很短装完之后可以在项目目录下确认一下插件是否出现在扩展列表里。装完 backdrop 之后再到 Python 环境里安装 claude-mem 本体pip install claude-mem如果你在 macOS 上遇到系统 Python 权限问题建议用虚拟环境或者直接装到用户目录。装好之后建议顺手确认一下版本避免装到某个奇怪的开发版本claude-mem --version2.2 API Key 与嵌入服务的配置装完包之后不能直接开用因为 claude-mem 做记忆提取和语义检索要调用 LLM 做信息抽取。执行首次命令或者运行初始化流程的时候它会引导你配置 API Key。支持两种途径直接设置环境变量或者把 Key 写进~/.claude-mem/config.toml。我个人更推荐环境变量因为不会不小心把 Key 提交进 Git。如果你打算走 Ollama 本地嵌入路线就需要在配置里把提供方切到 Ollama 并填上 OLLAMA_BASE_URL同时在本地把嵌入模型拉下来。这部分我在后面配置章节会给出完整的config.toml参考。初始化和自检完成后建议跑一次显式构建命令来验证整条链路是否打通它会异步遍历当前项目目录下的claude-md之类对话记录生成记忆库。第一次跑的时候会明显感觉到花了一点时间因为要逐条做 LLM 抽取和向量化。看到控制台输出进度条并且最终没有报错说明链路通了可以进入下一步。2.3 自动记忆模式与手动记忆模式配置好之后你会发现在 Claude Code 的会话里多出了几个新工具名称都带有memories_前缀。这就是 claude-mem 真正发挥作用的地方。Claude 会自己判断什么时候该对这些工具发起调用。为了让你在第一次上手时不至于心里没底它默认跑的是手动模式。也就是说对话过程中 Claude 不会自动写入记忆你得在觉得“这句话以后可能有用”的时候直接告诉它“记住这个”或者“存一下刚才的决定”Claude 就会调用记忆工具把当前内容存进去。这个模式的好处是可控不会把垃圾信息也写进库里适合刚开始用、还在观察效果的朋友。等你用了一段时间觉得提取质量不错就可以切到自动模式或者设置成混合模式。自动模式下Claude 会在对话中习惯性地处理并存储对话内容省去手动干预。但代价是记忆库的噪音会变大比如日常寒暄、无意义的调试过程也可能被提取成“记忆”。我的建议是一开始先手动跑一周然后看看库里沉淀的内容质量再决定要不要开自动。记忆这东西进库容易清洗难。2.4 网页仪表盘直观查看记忆库的方式如果你跟当时的我一样不确定它到底记住了什么可以启动它自带的网页仪表盘看一眼。它本质是一个本地 Web UI用来浏览、检索和管理你的记忆数据对日常检视沉淀结果很有帮助。启动方式很简单安装完成后在终端里执行claude-mem ui默认会跑在 127.0.0.1 的某个端口上浏览器访问之后就能看到历史会话列表、决策时间线、按语义相关的记忆片段等等。仪表盘上可以直接删掉某些不想要的记忆或者标记某条记忆为重点。这个可视化管理面板对于一个长期使用的记忆库来说不算锦上添花而是刚需——因为纯靠命令行检索你很难快速判断这个库长得健不健康。2.5 用 MCP 把记忆带进其他 AI 工具Claude Code 并不是你唯一在用的编码助手。claude-mem 还提供了 MCPModel Context Protocol支持这意味着你可以把它的记忆能力接到其他支持 MCP 的工具里。官方仓库里有一个mcp目录里面包含 JSON 格式的 MCP 配置示例。在 Claude Desktop 或其他 MCP 客户端里加一个服务配置就能让这些工具也具备读取 claude-mem 记忆库的能力。不过要提醒一下MCP 模式目前是偏进阶的玩法配置过程涉及 JSON 路径、服务启动方式等细节新手如果没接触过 MCP 容易卡住。我建议先把 Claude Code 插件模式跑顺了再考虑通过 MCP 扩展。3. 核心原理剖析记忆如何被提取、存储与召回3.1 记忆提取流程从原始对话到结构化条目在你跟 Claude 对话的时候记忆工具捕获到相关消息之后claude-mem 后台的提取流程就开始了。它并不是简单地把这段对话原封不动丢进 SQLite而是调用配置好的 LLM执行一个提炼任务从当前对话里判断哪些内容是长期有价值的信息然后输出为固定结构的 JSON包含类型决策/偏好/项目概念/普通事件、摘要内容、关联会话 ID、当时的 Git 分支等等。这个提取任务通过精心设计的提示词实现模型会收到当前议题相关的对话片段并被要求用简洁的语言概括成记忆条。实际效果是在手动模式下按语义相关性增量存储。比如你在对话里说过一句“Nginx keepalive 超时时间设置为 75 秒是因为后端频繁重启”这条信息就会被 LLM 识别为一个技术决策存成一条带语义向量的决策记录。系统不会为了追求细粒度把所有句子都拆成记忆而是优先保留决策、偏好和项目概念。3.2 语义索引与相似度召回机制这一节是整个项目最硬核的部分也是最值得我们理解原理的地方。存进库里的每一条记忆条目在写入时都会通过嵌入模型生成一个向量。这个向量就是这条记忆在语义空间里的坐标。检索的时候把当前对话的上下文也做一次向量化然后去 SQLite 里找与当前向量余弦相似度最高的那批记忆。SQLite 没有内置向量检索能力所以 claude-mem 选择了在应用层实现召回排序通过绑定机制把待检索的上下文向量与库中条目逐一计算相似度并取 Top-K。这里有两个参数直接影响效果一个是相似度阈值太低会把不相关的旧记忆也召回进来太高则可能导致什么都搜不到另一个是召回的条数上限控制一次最多注入多少条历史记忆。这两个参数在配置文件里都能调默认值对日常项目来说是个不错的起点但如果你发现 Claude 经常被不相关的记忆干扰优先调低召回条数而不是动阈值效果更直接。很多人会担心每次会话都要把所有历史记忆向量跟当前上下文逐一比对项目大了会不会很慢实测下来完全不用担心。几千条记忆的库相似度计算耗时在毫秒级对交互几乎无感知。SQLite 单机处理这种量级的数据绰绰有余。3.3 遗忘机制记忆库的卫生管理长期使用的记忆库会积累大量过时信息尤其项目重构之后旧的技术决策可能不再适用甚至会造成误导。所以 claude-mem 设计了遗忘机制你可以在对话里要求 Claude 删除某条记忆也可以直接通过 CLI 管理遗忘操作。它支持按关键词搜索记忆找出来之后精确删除也支持遗忘指定会话产生的全部记忆适合项目大改版之后做定向清空。除了主动遗忘还有时效性策略。记忆条目会记录捕获时间和最后访问时间CLI 里可以按时间范围列出记忆。如果你有定期清理的习惯建议以月度或者项目里程碑为单位执行一次遗忘操作把过时的决策、废弃的技术栈相关内容清掉保持记忆库精炼。这个习惯我跟身边几个用 claude-mem 的朋友交流过大家都认为遗忘机制才是这个项目长期用不乱的关键如果只进不出再好的检索也会被脏数据拖垮。3.4 与 Claude Code 的集成层级工具、Hook 与上下文注入最后一个值得理解的原理是它跟 Claude Code 的集成方式分三个层面。第一层是工具集成backdrop 插件把memories_*系列函数注册成 Claude Code 的可用工具Claude 在对话中可以自主决定何时调用。第二层是上下文注入在会话开始或者用户提问时背板系统会基于当前对话内容跑一次语义检索把 Top-K 条相关记忆拼装成一条增强消息塞进模型上下文里。这层机制决定了 Claude 能在不主动向你询问的情况下直接“想起”之前的相关决策。第三层是 hook 机制backdrop 作为插件会挂载到 Claude Code 的事件流里在特定生命周期事件触发时执行记忆相关逻辑。三层叠加就形成了自动的、跨会话的记忆增强链路。理解这个集成层级你就知道 claude-mem 不是把记忆文件硬塞给 Claude 让它自己读而是通过工具调用的方式让 Claude 主动参与记忆的读取和写入。Claude 既是记忆的消费者也是生产者。这个双向闭环正是它比简单的文本拼接方案高明的地方。4. 配置文件与运行参数详解4.1 config.toml 的完整结构与每项含义先给一份我实测可用的完整配置然后逐项解释。# ~/.claude-mem/config.toml [core] verbose true debug false auto false # 数据库目录默认位于用户目录下可自定义 history_dir [llm] model gpt-4o-mini api_key_env OPENAI_API_KEY [embedder] provider ollama model hermes ollama_url http://localhost:11434 [search] similarity_threshold 0.25 max_results 5 [context] inject_on_new_session true max_context_memories 5 [cron] # 是否启用定期扫描项目日志以沉淀记忆 enabled true interval_minutes 15先说明配置项不全是我拍的有些是官方仓库里标准的项有些是常用参数在配置文件里的映射。重点说几个我实际调过的参数。auto控制是否开启自动记忆模式。默认false想体验全自动就改成true。我从手动切到自动之后最大的感受是确实方便但库里开始出现一些“我今天修了什么文件”这类过程性内容价值不高。所以如果你对记忆质量要求高我建议保持手动或者开自动但是定期清理。llm分节决定了哪个模型负责提取记忆。官方文档支持多种提供方包括 OpenAI、Anthropic、Ollama。比如你的 Key 存在环境变量ANTHROPIC_API_KEY里那模型可以写claude-sonnet-4-...。如果你没有 Anthropic 账号用 OpenAI 兼容接口也可以有些社区域名还支持本地跑的模拟兼容服务。注意这个模型跟 Claude Code 的模型是独立的claude-mem 只借用它的抽取能力。embedder是嵌入模型配置。provider 可以填openai或者ollama。如果你填了openaimodel就填text-embedding-3-small填ollama时model对应你在本地 Pull 的嵌入模型名称比如hermes。ollama_url默认本地端口一般不用改。这里有个隐藏坑有些版本的 ollama 嵌入模型名是带:latest后缀或者需要指定参数长度的如果搜不到结果先回来看这里是不是写错了。search下的similarity_threshold默认 0.25 是我认为比较合理的值取值范围在 -1 到 1 之间。如果你发现召回的记忆完全不相关就把阈值往 0.4、0.5 上调如果你觉得该召回的东西没召回就往 0.1、0.15 下调。max_results是单次检索最多返回多少条记忆我设过 3 和 10最后固定在 5。太少了信息不够太多了上下文会被无关记忆淹没。4.2 环境变量与密钥管理密钥管理这块值得单独说。claude-mem 支持从环境变量读取 API Key也可以在配置里直接写明文——但除非你确认这台机器只有你自己用否则别这么干。我自己的做法是在 shell 配置文件里导出变量export OPENAI_API_KEYsk-... export OLLAMA_BASE_URLhttp://localhost:11434然后配置文件里只写环境变量名。这样 Key 不落盘万一配置文件被同步到云盘也不会泄露密钥。另外注意 claude-mem 有些版本的日志会打印配置信息如果开了debug true跑完排障记得关掉避免密钥在日志里带上。4.3 CLI 命令速查从检索到遗忘命令行工具除了安装日常用的主要是这几个# 检索记忆按语义相似度排序 claude-mem search 支付模块重构原因 # 列出最近 N 条记忆 claude-mem list --limit 20 # 按会话归档查看 claude-mem conversations # 遗忘指定记忆需要先找到 ID 或关键词 claude-mem forget 关键词 # 启动 Web 仪表盘 claude-mem ui # 显式触发一次记忆构建 claude-mem build # 查看统计信息 claude-mem stats其中claude-mem build在首次接入已有项目时几乎必用它会扫描当前项目目录下已有的对话记录文件并批量构建记忆。另外一个很有用的操作是把当前记忆库导出成 JSON便于备份或者做数据分析。CLI 前面也有--format json这样的参数方便脚本化处理。建议你花 10 分钟把claude-mem --help完整过一遍因为版本更新后命令变化比较多以你本地版本实际输出为准。我文章里这些命令是基于我在用的版本虽然稳定但项目迭代快保不齐你装的新版命令名有小调整。5. 常见问题与排查技巧实录5.1 工具加载失败或根本没有 memories_ 工具这个问题在刚开始用的时候最常遇到。现象是插件装好了包也装了但在 Claude Code 对话里看不到任何memories_开头的工具。排查第一步确认 backdrop 插件真的在当前项目里激活了。Claude Code 的插件是项目级生效的如果你在一个新项目目录里打开会话而插件没有在该目录安装那么自然没有工具。解决方法是执行插件的安装命令把 backdrop 加到当前项目。第二步确认claude-mem安装位置的 Python 环境与 Claude Code 运行环境一致尤其是用了 pyenv 或者虚拟环境的时候容易出现 CLI 装在一个环境里、插件调用的又是另一个环境的情况。第三步检查配置文件有没有语法错误TOML 的缩进和引号问题会导致包加载时直接失败而错误信息有时候不会在 Claude Code 界面里显示。5.2 语义搜索总是搜不到结果库里明明有记忆语义搜索却总是不返回内容这个问题我排查过几次原因基本都是嵌入链路没通。先检查 Ollama 服务是否在运行最简单的验证办法是打开浏览器访问http://localhost:11434能看到 Ollama 的响应文本就说明服务正常。然后确认嵌入模型真的拉下来了命令行执行ollama list看看有没有对应名称。注意配置里的model名称必须跟ollama list输出的名字完全一致大小写、冒号、后缀都必须匹配。如果用的是 OpenAI embedding就用一条简单文本试一下 API 连通性同时留意余额或者限流。还有一点如果你配置里开了自动模式但服务没就绪会话中可能静默跳过嵌入导致记忆条目写入了但没有向量搜索自然召回不到——这种静默失败最坑建议把verbose打开观察日志。5.3 记忆库文件位置与多项目隔离claude-mem 默认的数据目录在用户目录下的.claude-mem/里面包含 SQLite 文件。如果你同时做好几个项目会发现记忆会混在一起。默认设计是全局库当前的对话内容会跟整个库里所有项目的历史记忆一起做检索。这在项目之间差异较大的时候问题不大但如果项目 A 和项目 B 技术栈完全不一样就可能出现跨项目污染。解决办法是通过配置里history_dir或者项目级配置指向不同的数据目录实现项目级记忆隔离。我目前的做法是每接到一个新项目就在项目根目录放一份.claude-mem/config.toml把history_dir指到项目本地。这样各项目的记忆互不串味备份和清理也更干净。5.4 记忆内容质量差提取出来的东西没营养最让我失望的场景是对话里明明讨论了半天架构方案过两天去搜“为什么选 PostgreSQL 而不是 MySQL”结果它召回回来的记忆是“用户今天改了某文件”。这种情况通常是 LLM 提取的指令没有针对性。在手动模式下你可以在让 Claude 记录的时候说得具体一点比如“记住数据库选型定为 PostgreSQL原因是需要 JSONB 和更好的生态支持”。给到提取模型的信息越结构化存下来的记忆就越有干货。在自动模式下如果你发现某类对话总被提取成低质量记忆可以干脆关闭自动改成手动。另外也可以直接用 CLI 的遗忘功能把垃圾条目清掉不要让它们继续污染召回结果。5.5 性能优化建议定期维护与监控记忆库越用越大是必然的虽然目前量级下计算性能没有问题但检索质量会因垃圾记忆变多而下降。我给自己定的维护节奏是每个迭代结束后花几分钟看一眼 Web 仪表盘把过时和无效的条目遗忘掉。另外Claude Code 本身的对话日志在项目里会占空间claude-mem 构建时会扫描这些文件如果你发现某个项目构建特别慢先检查是不是日志文件堆积过多、或者有超大文件。可以把这个时间点记忆构建的效果视为一次归档通过配置调整扫描范围。6. 我的实际体会与这个项目未来的几个方向看到这里你应该已经对 claude-mem 能做什么、怎么做的、坑在哪里有概念了。从我个人的实际体验来说最值回票价的是跨会话的决策回忆能力。以前我复盘一个项目要翻好几个终端的滚动记录现在直接在对话里问“我之前为什么决定用 Vite 不用 Webpack”它能把我当时在对话里表达的原因回忆出来这体验确实很惊艳。这个项目目前还在快速迭代MCP 的接入意味着记忆能力不只是喂给 Claude还可以成为所有 AI 工具的公用记忆底座。我目前保持的使用习惯是重要结论手动让 Claude 存日常对话开自动但每周清一次垃圾条目检索参数用默认没怎么调。如果你刚上手不建议一上来就追求花哨配置先把手动模式跑一个星期看看库里的记忆长什么样再决定开不开自动、要不要换嵌入模型。记忆工具这东西用久了之后你才会发现它改变的不只是工具的智能程度还有你回看项目历史的方式。