claude-mem：让Claude Code具备长期记忆的跨会话开发助手

如果你最近在用 Claude Code 写项目，大概率碰到过这种情况：同一个工程背景，上个会话刚给它讲清楚，重新开个终端再问，它又一脸懵。Claude Code 本身能力很强，但它的记忆默认是“会话级”的——对话窗口一关，所有上下文就跟格式化了一样归零。claude-mem这个开源项目，就是专门给 Claude Code 补齐“长期记忆”这个短板的。它能在对话中自动记录关键信息，把记忆做语义化存储，并在下次会话启动时自动注入相关上下文，让 Claude 在跨会话、跨天的任务里像“带着工作笔记的老同事”一样连贯地干活。这篇内容适合所有重度依赖 Claude Code 的开发者，尤其是动不动就是多文件改造、长周期迭代、需要频繁切换任务的人。

1. 先搞清楚 claude-mem 解决的是什么问题

1.1 Claude Code 的“失忆症”到底有多疼

用过 Claude Code 的人应该都有体会：单次会话内它可以处理非常复杂的多文件改造，但一旦会话结束，它就什么都不记得了。第二天打开终端继续昨天的需求，你得把项目结构、技术栈、之前讨论的约束条件、甚至刚才改到一半的文件从头再讲一遍。如果项目再大一点、周期再长一点，你会发现大量时间不是在写代码，而是在反复“唤醒”AI 的上下文。

手动粘贴上下文是最常见的补救办法，但这个方法有两个硬伤。第一是成本高，动辄几千字的项目说明要反复整理，而且每次粘贴都会消耗大量 token；第二是精度低，上下文窗口是有限的，你把昨天的背景塞进去，今天的有效注意力就会被打折，甚至出现“前面说了 A 后面又按非 A 处理”的混乱。我见过不少团队最后干脆养成了维护一份CONTEXT.md的习惯，靠人肉补丁来给 AI 续命——这本质上是在用文档管理成本换取 AI 的连续性，治标不治本。

claude-mem的思路跟这些办法完全不一样：它不是在会话开始前手动喂给 AI 一堆背景材料，而是在平时对话中悄悄把关键信息沉淀下来，存到本地，用向量检索的方式在合适的时机自动放回上下文里。说得直白一点，它给 Claude 装了一个“外挂硬盘”，把记忆从会话中剥离出来，实现真正的跨会话持久化。

1.2 claude-mem 的工作方式：给 AI 装一本“工作笔记”

要理解claude-mem做了什么，可以先理解它的整体工作流。它的核心机制可以拆成四步：采集、提炼、存储、召回。每次你和 Claude Code 对话时，claude-mem通过 Claude Code 官方支持的 hooks 机制自动监听交互内容；拿到对话后，再用大模型对内容做摘要提炼，把“用户说了什么”、“助手回复了什么”、“里面有哪些关键决策”整理成结构化记忆；接着将这些记忆向量化，存入本地向量数据库；最后，在下次会话启动时，它会根据当前场景做语义检索，把匹配到的记忆拼装成 system prompt 的一部分注入 Claude 的上下文。

这个模式本质上就是检索增强生成（RAG）在 AI 编程助手场景下的具体应用。你可以把它类比成一个老同事的工作习惯：他不需要记住你入职以来说过的每一句话，但每次开会时他都能准确说出“上次你提到过这个模块要重构”“你之前否决过那个方案”。因为他有随手记笔记的习惯，并且在合适的时机把笔记翻出来用。claude-mem扮演的就是这个角色——它不追求记住全部原始对话，而是抓取对话里真正有长期价值的信息。

想清楚这个逻辑之后，你会发现它跟很多“聊天记录保存工具”有本质区别。聊天记录保存只是把文本堆在硬盘里，容量再大也对 AI 的连续性没有帮助；claude-mem做的是一套完整的记忆管道，从采集到结构化、从向量化到语义召回的每一步，都是为了解决同一个问题：让 AI 在正确的时机想起正确的事。

2. 架构拆解与实现原理：记忆是怎么被存取回来的

2.1 采集层：hooks 在正确的时间点记录对话

claude-mem之所以能自动工作，依赖的是 Claude Code 的 hooks 事件机制。Claude Code 会在会话生命周期的关键节点触发事件，比如会话启动时、用户提交提示时、调用工具时；claude-mem会在这些节点上注册自己的处理逻辑，让事件发生时自动执行一段脚本，把当时的对话内容捕获下来。

具体来说，它主要利用了三个事件节点。SessionStart节点负责在会话初始化时注入历史记忆；UserPromptSubmission节点负责在用户提交提示后记录完整的交互内容，包括用户的提问和 Claude 的回复；PreToolUse节点则用来响应 Claude 调用记忆工具的行为，比如你在对话中主动让它“记住这个决策”，它就能立刻创建一条笔记。hooks 脚本通常会通过本地 HTTP 请求把数据转发给claude-mem的后端服务，由后端完成摘要和入库。

# 安装 hooks 后，可以用 claude-mem 自带命令查看 hook 注册情况 claude-mem hooks list

这里有个很关键的容错设计：hooks 在 Claude Code 中的作用是“监听”而不是“阻断”。也就是说，即使claude-mem后端服务挂了或者向量库写入失败，Claude Code 本身的对话流程不会受影响。我用了一段时间后，还专门试过故意停掉后端服务再正常对话，结果 Claude 完全没感知到异常，顶多是这次会话没有记忆沉淀而已。这种设计非常符合生产环境的可靠性要求——记忆功能应该是锦上添花，绝不能成为对话主流程的绊脚石。

2.2 提炼层：三类摘要让记忆从噪音变成情报

采集层拿到的原始对话往往非常冗长，直接存储会面临两个问题：一是向量化的成本高，二是检索时噪音太大。claude-mem的解决方案是让 LLM 对交互内容先做一轮摘要提炼，再将摘要向量化。它主要生成三类结构性记忆：用户提示摘要、助手响应摘要、关键用户消息摘要。

这三类摘要的定位各有侧重。用户提示摘要记录的是“用户在这次交互中提出了什么要求”；助手响应摘要记录的是“Claude 给出了什么方案、做了什么修改”；关键用户消息摘要则更特殊，它是在用批判性的视角审视用户消息，提取那些可能影响后续决策的信号。举个例子，用户说“这个模块我们用 SQLite 就行，不需要上 PostgreSQL”，这看起来只是一句普通回复，但在批判性摘要里会被标记为一条架构决策，后续任何涉及数据库选型的讨论都应该把它作为重要参考。

把原始对话提炼成结构化摘要还有一个实际问题需要权衡：摘要过程本身要消耗 token。为了控制成本，claude-mem允许你调整摘要粒度，也允许你根据项目需要选择哪些类型的记忆需要重点沉淀。我的建议是，初期可以保持默认配置，跑一段时间之后再根据实际效果动态调整——如果发现摘要太粗、检索结果经常不相关，就把摘要的详细程度调高；如果发现 token 消耗明显上升，就反过来调低。

2.3 存储层：向量数据库与语义检索

完成提炼的摘要会进入向量化阶段。claude-mem支持多种嵌入模型，其中默认方案是通过 Ollama 调用本地的nomic-embed-text模型，生成的向量维度是 768 维；如果你配置了OPENAI_API_KEY，也可以改用 OpenAI 的嵌入模型，比如text-embedding-3-small，向量维度是 1536 维。嵌入模型的选择直接影响的是检索精度和运行成本，本地模型零费用、隐私性好，但精度上通常略逊于付费模型。

向量化后的数据会写入向量数据库。claude-mem默认使用 ChromaDB，数据直接落在本地目录；如果团队共用一个后端，或者数据量特别大，它也有 Qdrant、LanceDB 等选项。向量数据库和普通数据库的最大区别在于它支持相似度检索，也就是所谓的语义搜索——你可以用自然语言去查“我们之前讨论过关于分页方案的决策吗”，它返回的不只是包含“分页”字样的文本，而是语义上最相近的记忆片段。

# 先启动后端，再执行记忆搜索 claude-mem backend start claude-mem memory search "数据库选型时我们有什么约束"

这套检索机制就是记忆系统的核心价值。传统的关键词匹配在代码项目的记忆场景下很难用好，因为同一个意思的表达方式可能千差万别：这次说“分页”，下次可能是“limit offset”，再下次可能直接说“那个列表加载太慢怎么办”。向量检索能把这三句话在语义层面关联起来，这才是“记忆”真正可靠的形态——它不是字面复读机，而是理解了意思的助手。

2.4 召回层：把对的记忆在对的时机塞进上下文

记忆存得再好，如果取不出来就是白搭。claude-mem的召回机制非常巧妙：它不需要你手动搜索再粘贴，而是在会话启动时自动完成。在SessionStart事件触发时，后端会根据当前项目目录和系统提示做一次向量检索，找出最相关的历史记忆，按照设定的数量上限拼装成一段上下文，注入到 Claude 的系统提示中作为额外记忆。

在召回策略上，有几个参数会直接影响效果和成本。一个是单次注入的记忆条数上限，控制了每次会话额外占用的 token 量；一个是相关性阈值，只有相似度超过阈值的记忆才会被注入；还有一个是项目隔离，不同目录下的项目会话会优先检索对应的项目记忆，避免两个项目的上下文互相串台。刚开始用的时候建议保守一点，把注入条数设在 5 到 10 条之间，先感受一下注入的记忆对对话的改造成效，再决定要不要放开。

# 示意：通过 claude-mem config set 调整相关参数 # claude-mem config set MAX_DESCRIPTION_TOKENS 512 # claude-mem config set MEMORY_ROWS 8

召回层设计的巧妙之处在于，注入的记忆就像是给 Claude 的一份“会议纪要预览”，既有之前的技术决策，也有你个人的表达习惯和偏好。久而久之，你会明显感觉到 Claude 的反应不再是“每次都是第一次见面”，它知道你在做什么、做到哪一步了、之前踩过什么坑。这种连续性带来的开发体验提升，是任何手动维护上下文文档的方案都比不了的。

3. 实操部署：从零给 Claude Code 装上记忆

3.1 前置准备：环境和模型

在安装claude-mem之前，先确认本机满足几个前置条件。第一，Python 版本需要在 3.10 以上，因为项目用到了较新的类型注解和异步特性；第二，你本机已经安装并配置好 Claude Code，这个自不必多说；第三，因为默认的嵌入模型依赖 Ollama，建议先把 Ollama 装好，并把服务跑起来。

这里有个容易踩坑的细节：nomic-embed-text这个嵌入模型需要提前下载。我第一次全程默认配置，结果后端第一次尝试向量化时卡了很久，看日志发现是在等待 Ollama 拉模型。提前处理好这一步，后面的安装流程会顺畅得多。

# 启动 Ollama 服务并拉取默认嵌入模型 ollama serve ollama pull nomic-embed-text

如果你不想在本地维护 Ollama，也可以走 OpenAI 嵌入的路线，只需要设置OPENAI_API_KEY环境变量。但两条路线各有取舍：本地模型免费、完全离线、数据不出机器，但检索精度一般；OpenAI 模型精度更高，但每次向量化都会产生 API 调用费用。单机自用推荐 Ollama，团队共享或者对检索精度有更高要求的场景可以考虑后者。

3.2 安装和初始化

安装本身就是一个 pip 命令的事，真正的关键操作都在初始化和配置环节。

# 安装 claude-mem pip install claude-mem # 验证安装 claude-mem --help

安装完成后，执行初始化命令。它会创建~/.claude-mem/目录，里面存放配置文件和向量数据库文件。初始化完成之后，先用claude-mem config show查看默认配置，确认数据库类型、后端端口、嵌入模型来源等关键项，再决定要不要调整。配置没问题就可以启动后端服务了，启动后访问http://localhost:8000的对应接口可以看到健康状态。

# 初始化 claude-mem init # 查看配置 claude-mem config show # 启动本地后端 claude-mem backend start # 查看后端运行状态 claude-mem backend status

起步阶段最容易忽略的是目录归属问题。~/.claude-mem/默认放在用户主目录下，这意味着不同项目会共用同一个记忆库。对于个人独立开发还好，如果你同时维护多个项目，一定要了解项目隔离的配置方式，避免项目 A 的记忆串到项目 B 里去。这点我在后面的问题排查部分会专门展开。

3.3 hooks 安装与验证

后端跑起来只是完成了准备工作，真正让记忆开始流动的是 hooks 安装。hooks 是 Claude Code 的扩展机制，安装完之后，Claude Code 每次会话都会自动调用claude-mem的接口。

# 安装所有 hooks claude-mem hooks install # 查看 hooks 注册状态 claude-mem hooks list

安装完成后，建议先做一轮小范围验证。可以新开一个 Claude Code 会话，随便聊几句项目相关的内容，重点说几个后续容易提到的关键词；然后退出会话，再用claude-mem memory search搜索刚才说的关键词，看能不能搜到对应的记忆记录。如果搜到了，说明从采集到入库的整条链路已经通了。

如果搜索结果是空的，优先检查三件事：后端是否还活着、hooks 是否真的注册到了 Claude Code 的配置文件中、Ollama 服务是否正常。按照我上面列的顺序排查，绝大多数问题都能定位到具体环节。验证通过之后再上手真实项目，成功率会高很多。

3.4 常用配置和参数选择

claude-mem提供了一套标准的配置管理命令，所有的参数都能通过claude-mem config set来调整。这里分享几个在我实际使用中比较影响体验的参数。

记忆注入条数是我最先调整的参数。默认值比较保守，一开始我总觉得 Claude 对旧项目的“回忆”不够明显，把条数调高之后，跨会话连续性立刻提升了一个档次。但注意不要贪多，注入的记忆条数越多，占用的 system prompt 空间就越大，留给实际对话的上下文窗口就越小，对话质量反而可能下降。比较稳的做法是从默认值开始，逐步加量，找到你自己的平衡点。

摘要详细程度也值得关注。如果你经常发现检索出来的记忆片段语义太泛，和当前任务对不上，可以调高摘要 token 上限，让摘要保留更多细节。反之，如果你在意的只是“上个会话聊到哪了”这种粗粒度记忆，降低摘要粒度反而能节省 token 开销，同时降低向量库噪音。

# 示例：调整单条摘要最大 token 数 claude-mem config set MAX_DESCRIPTION_TOKENS 512

还有一个很容易被忽略的点是团队协作场景：claude-mem的数据默认只存在本地，如果你想在团队里共享记忆库，需要把后端部署成共享服务，并让每个成员的客户端指向同一个后端地址。但共享记忆也意味着隐私边界会变得模糊，项目代码里的敏感决策、架构讨论这些内容都会沉淀到共享库里，是否适合放在共享后端，需要团队自己权衡。

4. 实践中的问题排查与避坑实录

4.1 记忆不注入？先查这三个地方

我见过最多的反馈就是“装了 claude-mem 之后感觉没效果”，其实九成九都是链路某个环节断了。排查顺序建议从后端开始。后端服务没有正常运行时，采集、摘要、注入全都无从谈起，所以先执行claude-mem backend status，确认状态是否正常；如果不正常，直接看日志，用claude-mem logs查看最近输出。

后端没问题再看 hooks 是否真的生效。Claude Code 升级之后，hooks 配置有可能会被覆盖或丢失，需要重新执行claude-mem hooks install；你也可以直接打开 Claude Code 的配置文件，确认里面有没有 claude-mem 相关的 hook 注册记录。最后一个容易出问题的地方是 Ollama，如果嵌入模型没有下载完成或者 Ollama 服务没起来，向量化环节会一直失败，表现为日志里有报错，但 Claude 对话没有任何异常。

# 组合排查命令 claude-mem backend status claude-mem logs claude-mem hooks list

还有个容易被忽略的细节：claude-mem默认的配置改动不会热生效，改完配置之后需要重启后端服务。我有一次调了半天参数发现还是老效果，最后想起没重启后端，哭笑不得。改完配置顺手claude-mem backend restart，能省不少排查时间。

4.2 嵌入模型下载慢或 Ollama 连不上

嵌入模型需要从网上下载，首次拉取nomic-embed-text时如果网络状况不理想，几百兆的模型可能会卡很长时间。建议在正式使用前先单独执行ollama pull nomic-embed-text，确认模型已经就位；如果网络确实不稳定，可以配置 Ollama 使用本地的国内镜像源或提前在其他机器下载好模型文件再导入。

Ollama 连接失败的场景也很常遇到。默认情况下claude-mem会走http://localhost:11434访问 Ollama，如果你的 Ollama 不是跑在本机，或者修改过默认端口，就需要在配置中把地址改掉。排查这类问题有个通用方法：先用 curl 确认 Ollama 的接口能不能通，再确认 claude-mem 的配置是否指向了正确的地址，两端一对一比对，很快就能定位。

# 检查 Ollama 服务是否可用 curl http://localhost:11434/api/tags

另外提醒一句，测试阶段不要太依赖生产环境里的真实交互。claude-mem 支持一些手动测试的命令，可以让你在不触发真实 Claude 对话的情况下检查记忆是否正常工作。学会用这些命令做自测，比反复开启新会话验证高效得多。

4.3 记忆串台与数据库膨胀怎么处理

多个项目共用一个记忆库时，记忆串台是最常见的问题。因为向量检索是按语义相似度找最相近的记忆，如果项目 A 和项目 B 都聊过“数据库设计”“缓存策略”这类通用话题，检索结果很容易张冠李戴。解决办法是启用项目隔离的配置，让不同项目使用独立的记忆命名空间。这点建议在初始化时就做好，项目一旦跑起来再调整记忆归属会麻烦得多。

数据库膨胀则是另一个长期问题。向量数据库会随着对话增多不断变大，摘要积累到一定量级后，检索效率和磁盘占用都会上升。claude-mem 提供了清理命令，可以按时间或按类型清理历史记忆。不过清理之前务必备份——我有一次清理时手滑指定了错误的条件，把好几周的会话摘要全删了。备份其实很简单，把~/.claude-mem/目录整个复制一份就行，向量库文件都在里面。

关于记忆过期还有一个主观判断：AI 编程助手的历史记忆不像人的记忆那样“自然遗忘”，旧的技术决策如果不清理，可能在新需求出现时被错误地注入。我的习惯是每个里程碑结束后做一次记忆整理，把已经完成的、不再有参考价值的旧摘要清掉，让记忆库始终保持“近实远虚”的状态。

4.4 常见问题速查表

这张表解决的是“能用”层面的问题，实际运行中还有不少更细的坑。比如有的版本对 Python 版本敏感，升级后需要检查依赖；比如后端端口被占用时，启动命令会静默失败，需要看日志才能发现。这些都是使用过程中逐步积累的经验，遇到一次记录一次，后面就会越来越顺。

回到开头那个问题——一个会话结束就“忘记一切”的 AI 编程助手，到底能不能成为长期协作者？claude-mem的思路给了我一个很明确的答案：可以。它没有试图扩大上下文窗口，也没有让人手动维护项目文档，而是用一条完整的记忆管道，让 Claude 在需要的时候自己找到需要的信息。我第一次体验到“隔两天重新打开项目，Claude 还能接上之前讨论的架构取舍”的时候，心里确实咯噔了一下。当然，它解决的是“记性差”，解决不了“上下文窗口有限”，日常该控制 prompt 规模还是得控制。如果你也在 Cladue Code 上投入了大量时间，装一个claude-mem跑几天，让对话沉淀成真正的项目资产，这个投入绝对值得。