claude-mem：给Claude装上跨会话记忆层，告别金鱼记忆

如果你经常拿Claude做长期项目，大概率经历过这个场景：前天还在聊的服务架构，今天打开新会话，它一脸茫然，你只能把上下文重新粘贴一遍。我把这种状态叫"金鱼记忆"——单次对话里它比谁都聪明，跨会话它就归零。这个痛点，就是 claude-mem 要治的。它是Anthropic开源的一个记忆层工具，直白说就是在Claude外面加一个"笔记本"，把每次对话里值得留下的信息（偏好、决策、项目背景、踩过的坑）自动记下来，下次启动时把相关内容翻出来塞进上下文。这篇文章我会从使用者的角度，把 claude-mem 的机制、部署、接入方式和我在实际项目中踩过的坑一次讲清楚。如果你是靠Claude Code写代码的工程师、长期依赖Claude做研究或写作的人，或者对LLM应用层记忆机制感兴趣，这篇文章应该能帮你省下不少折腾时间。

1. claude-mem到底是什么：给Claude装一层"跨会话的记忆"

1.1 一个真实的痛点：项目干到一半，Claude"失忆"了

我先说个自己的经历。之前做一个RAG知识库项目，第一天和Claude Code敲定了技术栈：FastAPI做服务层、PostgreSQL存元数据、向量库用本地的，连代码目录怎么划分、函数命名风格都对齐了。第二天打开新会话继续写，它完全不记得这些，又给我推荐了一堆别的方案。我只好把前一天的结论重新复制进对话里，占了好几K的上下文，而且稍不注意它还会把"我否定的方案"当成"待选方案"来讨论。

这不是Claude笨，而是它本身的架构决定的：每个新会话都是一张白纸，模型没有开箱即用的跨会话持久存储。手动维护一份"项目备忘"是很多人都在做的事，但这份备忘很快就变成一堆没人想改的过时文档。真正需要的是一个能自动沉淀、能按需召回、还能随时查看和修改的记忆系统，claude-mem就是冲着这个来的。

1.2 它到底做了什么：把一次性对话变成长期资产

claude-mem做的事情可以拆成三层：提取、存储、注入。

提取是指它通过一次LLM调用，把当前对话里的关键信息结构化地"蒸馏"出来——你说了什么需求、做了什么决定、踩了什么坑、偏好什么样的风格；存储是把这些结构化记录落到本地SQLite里；注入是指新会话启动时，它会把和当前场景相关的记忆自动拼进系统提示词，让Claude开局就带着上下文。

和手动复制粘贴相比，最核心的差异是它沉淀下来的不是聊天记录原文，而是经过提炼的结构化记忆。举个例子：你和Claude聊了半小时如何做登录鉴权，最终结论是"用JWT，access token 15分钟过期，refresh token 7天"，claude-mem不会把半小时对话都存下来，它只存那条决策记录，下次开启新会话时，Claude直接就知道"这个项目已经在用JWT方案了"。既保留了上下文，又把上下文压缩到了最小。

我自己的感受是，一旦跑起来，Claude的"失忆焦虑"基本消失了。以前每次新会话都要花几分钟交代背景，现在你直接说"继续把上一个任务做完"，它自己就能从记忆库里把相关项目信息翻出来，这个体验真的值得一试。

1.3 它和Claude自带记忆功能、其他Memory方案的区别

我接触过几种"记忆"实现，很多人会把它们混为一谈。简单梳理一下：

Claude自带的Memory更适合那种轻量的个人偏好记录，但它的记忆是"黑盒"的，你不知道它记住了什么，也没法检索某个具体的决策。手工system prompt又太依赖个人纪律，项目一多就乱。claude-mem站在中间：它有自动提取环节，也有一个你能随时打开来看、搜、删的管理界面，适合把它当成"项目的第二大脑"来用。

2. 核心机制拆解：记忆是怎么被提取、存储和复用的

这一节我尽量把原理讲透。你可以不理解每一行实现代码，但理解了这套流程，后面调参、排错都会顺很多。

2.1 记忆因子：对话里被"蒸馏"出来的六类信息

claude-mem提取信息时不是一股脑记流水账，它把对话拆成几类"记忆因子"（memory factors），每一类单独存储、单独打上时间戳和来源会话。我在实际使用到的版本里，大致能看到这样几类：

这种分门别类的价值在于：召回时按场景取用。比如你要处理一个"登录模块"相关任务，记忆库里关于登录的decision和mistake会比一条普通聊天记录更有参考价值；而preference则适合全局注入，因为你写任何代码都应该优先遵守用户风格习惯。

我实际用过之后意识到，记忆因子的分类本身就是一种压缩。一小时的对话，最终落到SQLite里可能只有几十条精炼记录，而这些记录几乎覆盖了对话里真正有长期价值的信息。如果你希望记忆更"厚"，可以通过配置要求它更频繁地提取、保存更多候选因子，后面配置部分我会给具体参数。

2.2 两条核心链路：提取链路与召回注入链路

claude-mem的运行是两条独立的链路，理解这个很重要。

第一条是提取链路。每次对话结束后（或者间隔一定时长），claude-mem会调用一个LLM，把最近的对话交给它做结构化分析，输出JSON格式的记忆因子。这个过程我理解下来，相当于让一个"书记员"在旁边旁听了你们的对话，然后按表格把关键信息记录下来。你需要为这个"书记员"配置模型，它不一定要和对话主模型一样强，我实测下来用中等规模的模型就能提取出质量合格的结构化记忆。

第二条是召回链路。当你开启一个新会话时，claude-mem会做两件事：一是把用户级偏好（比如语言习惯、常用风格）直接作为固定记忆注入，二是把项目相关的记忆做一次相似度检索，选出一批和当前场景最匹配的记录，按阈值过滤后拼装进系统提示。

这两条链路是异步的：提取发生在对话后，注入发生在对话前。所以你会看到一个现象——刚聊完的对话，立刻开新会话不一定能马上用到刚存的记忆，因为提取可能还没完成。我验证下来，通常等待几秒钟到十几秒再开新会话，沉淀出来的记忆就已经在库里了。

2.3 为什么用TF-IDF而不是向量数据库

这是claude-mem设计里我比较欣赏的一个取舍。它的语义检索底层用的是scikit-learn的TF-IDF加SVD（LSA），而不是很多人想象的向量数据库。

一开始我也觉得奇怪，2025年了怎么还在用这么传统的检索方式？实际跑了一段时间后我理解了：个人级记忆库的规模，撑死了几千条记录，在这种量级下，TF-IDF/LSA的检索效果和速度完全够用，而且它零外部依赖——你不需要额外部署向量数据库服务，pip装完就能跑。作为对比，向量数据库那套要引入embedding模型、要维护向量索引，部署复杂度立刻上一个台阶，对单机个人工具来说明显过重。

这个取舍对普通用户是友好的：你不必为了一个记忆功能去搭一套向量检索基础设施。如果你用的记忆规模特别大，确实可以考虑后续自己迁移到向量库，但对大多数场景，LSA已经能把"相似记忆"捞得挺准了。在CLI里跑claude-mem search验证时，我用几个模糊关键词都能命中之前记下的决策，说明这套轻量方案对个人记忆库是够用的。

3. 本地部署与环境准备：从零跑通整个链路

3.1 两种安装方式：pip包和npm包怎么选

claude-mem提供了两条安装路线，我两条都试过，给你说说差异。

第一条是Python路线：

pip install claude-mem

装完直接就有 claude-mem 命令。我一般先跑一下 claude-mem --help 确认版本和可用命令。这个路线的优点是和Python生态贴合，如果你后续想拿它的包做二次开发，直接 import 就行。

第二条是npm路线：

npm install -g claude-mem

npm包和pip包用的是同一套核心，但如果你主要用Claude Code插件方式接入，走npm会更顺，因为插件机制调用的是全局命令，npm全局安装可以确保命令在PATH里，省去配置软链的麻烦。我自己的建议：只做CLI实验用pip，打算接入Claude Code插件用npm，然后还需要再装一个agent包：

pip install claude-mem-agent

这个包是给MCP接入用的，Claude Desktop那套方式会用到它。别小看这一步，后面配置MCP时如果发现找不到命令，往往就是忘了装agent包。

3.2 初始化、关键配置项与模型选择

装完之后先做初始化：

claude-mem init

init命令会检查环境、创建默认存储目录（Linux/macOS下通常在 ~/.claude-mem），并引导你完成配置。核心要配的有三块：API key、提取模型、存储路径。

API key方面，因为提取链路要调用LLM做结构化蒸馏，你需要有一个可用的推理API访问凭证，比如ANTHROPIC_API_KEY，把它配到环境变量里。输出模型和提取模型可以不同：对话主模型用能力更强的，提取用的模型则可以降一档，控制成本，我用下来到中等规模模型提取质量已经不差。

然后是存储目录。如果你有多个项目，我建议把CLAUDE_MEM_STORE_DIR指向一个统一目录，方便备份。我习惯把它单独放在一个数据目录里，和系统目录分开，这样重装系统也不会误删记忆。

常用环境变量：

export ANTHROPIC_API_KEY="你的key" export CLAUDE_MEM_STORE_DIR="$HOME/.claude-mem" export CLAUDE_MEM_EXTRACTION_MODEL="一个可用的模型名称" export CLAUDE_MEM_MAX_CONTEXT_TOKENS=8000

CLAUDE_MEM_MAX_CONTEXT_TOKENS 这个参数控制注入记忆的最大token量，默认值不高，如果你项目记忆很大，可以往上调，但注意不要挤占主对话的空间。我调过几次后觉得，8000到12000是个比较均衡的区间，注入的记忆太少会丢上下文，太多又浪费token。

3.3 验证安装：跑通第一次记忆提取

配置完成后，我建议不要直接接入工作流，先在命令行里做一次完整验证。

第一步，随便找一个会话记录来测。如果没有现成的，最简单的方式是手动塞一条：

claude-mem remember "我们在FastAPI项目中决定使用JWT鉴权，access token 15分钟过期"

这条命令会把一条记忆直接写入记忆库，先验证写入通路是通的。

第二步，查看记忆是否落库：

claude-mem list

如果能看到那条记录，说明SQLite存储、CLI读取都正常。

第三步，试一下搜索：

claude-mem search "鉴权方案"

如果能搜到刚才那条记录，说明检索链路也是通的。一条龙下来，提取、存储、检索三层就都验证过了。接下来再把它接到真实的Claude对话流程里，让自动提取跑起来，这一步通常不需要额外配置，当你通过插件或MCP接入后，对话本身就喂给了提取链路。

4. 把记忆层接入日常工具链的三种姿势

4.1 通过插件接入Claude Code：最顺滑的方式

我现在主力用的是Claude Code，所以最先试的就是插件方式。claude-mem设计了一套插件机制，你只需要在Claude Code的插件目录里放一个manifest文件，Claude Code启动时就会自动加载它。

具体路径是 ~/.claude/plugins/，我在下面建了一个子目录，把插件配置放进去。manifest文件核心内容大致是这样：

{ "name": "claude-mem", "description": "跨会话记忆层：自动提取、存储、注入对话记忆", "commands": [ { "command": "remember", "callback": "claude-mem remember" } ] }

实际配置中，callback对应的命令就是全局的 claude-mem，插件启动后会注册一些触发行为：新会话开始时注入相关记忆，对话过程中交给提取链路做蒸馏。

插件方式的好处是零感知，你不用每次手动记什么，开个新会话它就自动把项目相关记忆找出来了。我最直观的感受是，连续多天改同一个项目时，Claude Code每次开局都带着"这个项目现在做到哪了"的认知，省掉了我每天写背景摘要的时间。唯一要注意的是，插件会占用少量上下文token去承载记忆注入，我实测默认配置下影响不大，但如果你的会话本身就很长，建议把CLAUDE_MEM_MAX_CONTEXT_TOKENS调低一点。

4.2 通过MCP接入Claude Desktop：给桌面端也补上记忆

如果你主要用Claude Desktop而不是Claude Code，可以走MCP（Model Context Protocol）路线。这需要claude-mem-agent这个包来提供一个MCP server。

配置方式是在Claude Desktop的配置文件里加一段mcpServers配置：

{ "mcpServers": { "claude-mem": { "command": "claude-mem-agent", "args": [] } } }

配置完重启Claude Desktop，出去问一句"你记得我之前说的鉴权方案吗"，如果配置成功，它能直接调起工具从记忆库里检索出答案。这条路线适合那些把Claude当"长期顾问"而不是"写代码搭档"的人——你把项目演进过程中的重要决策都沉淀在记忆库，每次找它聊之前不用重新讲一遍背景。

4.3 CLI与TUI：当记忆库需要人工干预时

自动提取的记忆虽然方便，但不一定总是准确的。当你需要手动查看、修改、清理记忆库时，CLI和TUI就派上用场了。我日常用得最多的几个命令：

claude-mem show # 查看当前会话关联的记忆 claude-mem list # 列出记忆库中所有记忆 claude-mem search "关键词" # 按语义相似度搜索记忆 claude-mem remember "内容" # 手动写入一条记忆 claude-mem forget 记录id # 删除某条记忆 claude-mem dashboard # 启动TUI可视化面板

dashboard是一个终端里的可视化面板，进去之后能看到记忆因子按类型分组，还能直接搜索、筛选。我每周会花五分钟打开dashboard扫一遍，看看有没有错误提取或已经过时的内容，有的话直接删掉。这个"人工巡检"习惯对长期使用质量很重要，不然错误记忆越积越多，后面会被它误导。

5. 我踩过的坑和排查经验

5.1 提取模型没配好，第一次启动就报错

我最早跑的时候，装完包、配好API key，满心期待地聊完一轮对话，结果 claude-mem 日志里一直报模型调用失败。查了一圈发现，问题是提取链路默认调的模型和当前API账号可用的模型不一致——账号A能用，账号B不能，而环境变量指向的是账号B的key。

排查路径是这样：先看 claude-mem status 检查配置，再看日志里具体的模型名称，最后显式把CLAUDE_MEM_EXTRACTION_MODEL设成账号可用的模型。小技巧是，平时低成本调试时可以把提取模型指到本地Ollama，这样跑实验不烧API额度，等要正式用再切回云端模型。踩过这次之后，我每次初始化必做的事就是确认 "提取模型" 和 "API账号权限" 这两件事对上了，避免再白等一轮对话。

5.2 记忆污染：错误提取引发的"幻觉连锁"

这是我在所有坑里觉得最值得警惕的一个。有一次我和Claude聊天时随口说了一句"要不要考虑用消息队列，不过目前阶段其实没必要"，提取链路把这句话的"考虑用消息队列"部分记成了一条decision。结果后来新会话里，Claude开局就认为"项目已决定使用消息队列"，围绕这个假设给了一堆架构建议。

被注入一条错的记忆，比没有记忆更麻烦。因为用户视角会觉得"它为什么突然开始聊这个？"，然后还得反过来纠偏，浪费的时间比当初手动交代背景还多。

我的应对方案有三个：一是发现错误记忆后立即 claude-mem forget 删掉，别等；二是定期开dashboard巡检，尤其关注decision类因子的正确性；三是在对话时尽量明确表达"这是暂定方案/备选方案，不是最终决策"，减少提取链路误判的概率。时间长了你会发现，记忆库的维护本质上是在"过滤噪声"，和写代码一样需要长期清洁。

5.3 相似度阈值调参：太灵敏和太迟钝之间的平衡

claude-mem里给了一些参数控制记忆注入的"灵敏度"，核心是相似度阈值和最大上下文token数。我先试了默认阈值，发现有些相关记忆召回不出来，特别是当项目里有两块功能代码逻辑相近时，它会漏掉其中一块。把阈值调低之后，召回多了，但噪声也上来了，经常把早期过时方案也一起注入，干扰判断。

后来我的做法是：先保持阈值较高跑一段时间，观察哪些场景下"该来的没来"，再小幅下调；同时用CLAUDE_MEM_MAX_CONTEXT_TOKENS限制总注入量。因为当阈值降低导致候选记录变多时，token上限会帮你截断那些排名靠后的记忆，等于加了一个保险。这组参数调完之后效果比较明显，Claude在长周期项目里的"记得"和"精准"都能兼顾到。

5.4 多机同步与隐私问题的取舍

claude-mem默认把记忆库存在本地，这意味着如果你有多台电脑，记忆不会自动同步。我一开始没意识到这个问题，在办公机上积累了一周的决策记录，回家打开笔记本发现它啥也不记得。如果你有多机需求，最简单的方案是把存储目录放到同步网盘里，让多台设备共享同一个路径；但我个人后来不太推荐这个做法，因为记忆库里可能包含敏感代码逻辑和内部决策，放到第三方同步盘有一定隐私暴露风险。

我的方案是：在主力机上保留完整记忆库，其他设备上用只读模式或独立小库，需要时手动 export 再 import。claude-mem的记忆库本质上是SQLite文件，备份和迁移都很轻量，你也可以定期把整个 ~/.claude-mem 打包归档。如果你配合git仓库来做版本管理，记得把包含任何API key的配置排除在外。

使用这几个月下来，我最大的体会是：记忆层作为LLM应用的一部分，它的意义不只是省掉几段重复对话，而是让Claude从一个"无情对话盒"变成了真正参与长期项目的协作者。你需要在前几天克服一个问题——不要信任所有自动提取的记忆，要接受"记忆也需要维护"这个设定。养成了定期巡检、手动修正的习惯后，它回报给你的，是每个新会话开局都自带项目上下文的安心感。如果你正在做长周期项目、或者被"每次都要重新交代一遍"折磨过，建议照着这篇文章的路径把claude-mem跑起来，亲身试一轮，再回来决定要不要留着它。