用过 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 安装依赖：先装好 backdrop
claude-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 还提供了 MCP（Model 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。如果你填了openai，model就填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_KEY="sk-..." export OLLAMA_BASE_URL="http://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 存，日常对话开自动但每周清一次垃圾条目，检索参数用默认没怎么调。如果你刚上手，不建议一上来就追求花哨配置，先把手动模式跑一个星期，看看库里的记忆长什么样，再决定开不开自动、要不要换嵌入模型。记忆工具这东西，用久了之后你才会发现，它改变的不只是工具的智能程度，还有你回看项目历史的方式。