claude-mem：为Claude打造跨会话持久记忆的开源利器

做个人项目自动化工作流的时候，我一直被一个大问题卡住：和 AI 对话明明聊得好好的，换了个会话就全忘了。前脚刚让它记住我的代码风格偏好，后脚新开一个窗口继续写，它又是一副“初次见面”的样子。后来我在技术社区里翻到claude-mem这个开源项目，试跑了一轮之后感觉思路一下打开了——它解决的正是跨会话记忆持久化这个痛点，不是简单把聊天记录存下来，而是设计了一套自动摘要、分场景存储、按需注入的记忆机制。这篇文章就从我的使用视角出发，完整拆解它的设计思路、安装配置、实际跑起来的流程，以及我在折腾过程中踩过的坑和排查经验。如果你是重度使用 AI 编程助手或想给自己的 AI 工作流加记忆能力的开发者，这篇内容可以直接拿来当上手参考。

1. 项目背景：为什么需要跨会话记忆

1.1 官方会话记忆的局限

用过 Claude 的朋友应该都有这种感觉：同一个对话窗口里，它能记住你前面说过的背景信息，上下文越长表现越好；可一旦关掉窗口、开始一个新会话，之前沉淀下来的偏好、决策、约定基本就归零了。官方产品可能会在会话内部维护一个上下文窗口，但这个窗口的容量有限，而且它本质上是跟着单次会话走的。

对于写代码、做方案、搞内容创作这类经常要跨几天、跨多个任务推进的场景来说，这个限制就很致命。举个例子，我在一个会话里告诉 AI“后端接口一律返回统一的 Result 结构，code/message/data 三段式”，它在这个会话里确实能守规矩；第二天新开会话，它又开始给我返回裸对象。我不得不在每个新会话开头重新把规则打一遍，成本很高，而且容易漏。

1.2 claude-mem 要解决的问题

claude-mem本质上是一个给 Claude 增加持久记忆层的工具。它通过 MCP（Model Context Protocol，模型上下文协议）把记忆能力注入到 Claude 的会话流程中。当你和 Claude 对话时，它会自动把对话内容做摘要、提取关键信息，存到本地数据库里；下次你再跟 AI 对话时，它会根据当前场景检索出相关的历史记忆，作为上下文重新注入给模型。

这样做的直接收益有三个：一是你不必再反复交代背景规则，重要约定能被自动记住；二是记忆是分类存储的，不会像聊天记录倒灌那样把上下文窗口撑爆；三是所有数据都保存在本地，私密性相对可控。

1.3 项目技术架构速览

从实现层面看，claude-mem由几个核心部分组成：

• CLI 工具：提供安装、初始化、记忆查询等命令，通常通过 npm 全局安装。
• MCP Server：以 Model Context Protocol 服务的形式运行，Claude Desktop 或 Claude Code 可以连接它。
• 存储层：目前默认使用 SQLite，把记忆数据、摘要结构化落地到本地文件。
• 记忆管理模块：负责新增记忆、清理过期记忆、按需检索注入。

整个项目是开源发布的，托管在 GitHub 上，协议是 MIT。这意味着你可以直接拿它上生产环境，也可以自己改源码扩展存储逻辑。我后来看它的源码时发现，它的核心思路并不复杂，关键在于“什么时候该记”、“什么时候该注入”这两个触发点设计得比较聪明。

2. 核心机制拆解

2.1 记忆数据的组织方式

claude-mem在本地维护了一个 SQLite 数据库，里面不是简单堆聊天记录，而是把记忆分成了多个维度。站在使用者的角度，我感知比较强的有两类：一类是用户偏好，比如“用户喜欢 Python 类型注解”、“用户要求代码用中文注释”；另一类是项目上下文，比如“当前项目使用 FastAPI + SQLAlchemy”、“用户正在重构订单模块”。

这种分类的价值在于：检索时可以按场景精确命中，避免注入一堆无关信息。它的内部实现里，每条记忆通常还带有时间戳、来源会话、相关关键词等元数据。这些元数据是后面做“相关性排序”的基础，也就是说不是所有记忆在每次对话里都会被搬出来，而是只有跟当前问题相关的才会被选中。

2.2 自动记忆与手动记忆

claude-mem默认会自动处理一部分记忆。它会监听对话内容，在合适的时机生成摘要并存入数据库。这个“合适的时机”，一般是对话中出现了明确的偏好表达、关键决策或者长期约定。

但自动识别总会有漏网之鱼，所以它还有一个手动标签机制。你可以在对话中通过特定指令来显式要求记忆，比如：

@记忆 这个项目的部署流程是：先构建镜像，再执行 migrate，最后滚动更新。

或者用更直接的方式：

记住：接口文档统一维护在 /docs/api.md

Claude 收到这类指令后，会通过 MCP Server 调用记忆写入工具，把这条内容存储下来。手动机制最大的价值是精确性，适合存储那些“必须一字不差”的约定。

2.3 记忆注入机制

记忆写进去之后，怎么在下次对话中生效？这是整个工具的枢钮部分。它的工作流程大致是：

1. Claude 收到用户新消息，开始组织回复。
2. 在生成过程早期，会调用 MCP 工具请求“检索相关记忆”。
3. MCP Server 对用户当前输入做关键词抽取和语义匹配，从 SQLite 中找到候选记忆。
4. 候选记忆经过评分、筛选后，通过系统提示词的形式注入回给 Claude。
5. Claude 把记忆当作背景知识的一部分，结合当前问题生成回答。

这个机制拆开看其实不复杂，但它的巧妙之处在于“按需注入”。如果每次对话都把全部历史塞给模型，上下文窗口很快会被占满，而且无关信息会干扰判断。而按需注入只把当前任务最需要的那几条记忆捞出来，效果更好，也更省 token。

3. 安装与配置

3.1 环境要求

先别急着动手，确认一下基础环境。claude-mem是 Node.js 生态的项目，安装前你需要确保机器上有：

• Node.js 18 及以上版本（我本机用的是 20.x，跑得很稳）
• npm 9 及以上
• 能正常运行的 Claude Desktop 或 Claude Code 环境
• Anthropic API Key（部分功能需要调用接口生成摘要）

检查版本非常简单：

node -v npm -v

如果 Node 版本太老，建议先升级。我最早在一台老机器上跑的时候因为 Node 版本是 16，安装过程报了一堆原生模块编译错误，后来升到 18 就顺畅了。

3.2 安装 CLI

安装过程没有太多花活，全局安装即可：

npm install -g claude-mem

装完之后验证一下：

claude-mem --version

如果看到版本号输出，说明 CLI 已经就绪。这里有个小提示：如果你用的是 nvm 之类的 Node 版本管理工具，全局安装的包会放在当前 Node 版本对应的路径下，切换 Node 版本后可能需要重新安装。

3.3 初始化数据库与 MCP 配置

安装完 CLI 之后，下一步是初始化。运行：

claude-mem init

这个命令会做几件事：创建数据目录（默认在~/.claude-mem/或由系统环境变量指定的位置）、初始化 SQLite 数据库、生成 MCP 配置文件、把配置注册到 Claude Desktop 的配置文件中。

如果你用的是 Claude Desktop，它一般会自动读取claude_desktop_config.json来加载 MCP Server。claude-mem init干的事情就是往这个文件里写入一条 MCP Server 配置。配置内容大致长这样：

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

这个命令的含义很直白：让 Claude Desktop 启动时拉起claude-mem mcp，后者会以 MCP Server 的身份监听来自 Claude 的工具调用。

3.4 与 Claude 客户端对接

配置完成后，需要完全退出并重新打开 Claude Desktop，让 MCP Server 重新加载。重启后，在 Claude Desktop 的输入框旁边或者设置界面里，应该能看到claude-mem已连接的状态。

在 Claude Code 环境中，配置方式略有不同。你需要在项目目录下建立或修改 MCP 配置文件，加入同样的 server 定义。以 Claude Code 为例，它的 MCP 配置一般支持本地命令启动，所以写法基本一致：

claude mcp add claude-mem -- claude-mem mcp

如果这条命令执行成功，后续在 Claude Code 会话里就能直接调用记忆工具了。我知道不少人会在这个环节卡住，主要是路径问题——如果你用 npm 全局安装的路径比较特殊，建议先执行which claude-mem确认可执行文件的实际路径，然后在配置里使用绝对路径，比如：

{ "mcpServers": { "claude-mem": { "command": "/usr/local/bin/claude-mem", "args": ["mcp"] } } }

4. 实操：本地跑起来的完整流程

4.1 用 npx 快速运行

如果你不想全局安装，也可以用 npx 临时跑一下：

npx claude-mem init

这种方式适合先体验一下，不需要污染全局环境。但需要注意，npx 每次运行都会检查并拉取 npm 仓库里的最新版本，如果网络状况不好，首次启动会偏慢。我个人建议正式使用时还是全局安装，尤其在你已经配好了 MCP Server 的情况下，全局安装能确保系统路径稳定指向。

4.2 常用命令详解

claude-mem的命令设计得比较精简，日常使用频率最高的有这几个：

claude-mem list claude-mem search "关键词" claude-mem delete --id 123 claude-mem export claude-mem mcp

• list：列出数据库里已有的记忆条目，方便你确认自动摘要到底存了什么内容。
• search：按关键词检索记忆，这是手动排查问题的利器。比如你感觉 AI 忘记了你之前交代的规则，先search看看记忆到底存没存进去。
• delete：删除指定记忆。有些自动记录的噪点内容，删掉比留着好。
• export：把全部记忆导出成 JSON 文件，适合做备份。
• mcp：启动 MCP Server 进程，这个一般由 Claude Desktop 自动拉起，不需要手动长期运行。

大多数命令都支持--help查看详细参数，不确定的时候先看一眼，踩坑概率会小很多。

4.3 第一次注入记忆验证

跑通整个链路最直观的办法，是做一次“记忆写入 -> 新会话读取”的闭环验证。

第一步，在 Claude Desktop 里随便聊一句能被记住的内容。为了测试，我一般会说：

请记住：所有对外接口的响应时间不能超过 300ms，超时要做熔断处理。

注意我说的是“请记住”，这是触发手动记忆的一种自然表达。Claude 会调用 memory 相关的 MCP 工具，把这句话的核心语义存入数据库。如果我不确定是否存进去了，可以在终端里执行：

claude-mem search "响应时间"

如果看到类似下面的输出，说明记忆已经成功落库：

ID: 1 内容: 所有对外接口的响应时间不能超过 300ms，超时要做熔断处理。 来源会话: 2025-01-12T10:24:03 关键词: 响应时间,超时,熔断

第二步，新开一个会话，直接问：“我之前提过对外接口的响应要求是什么？”如果记忆注入正常，Claude 应该能准确答出“不超过 300ms，超时熔断”这个约定。

整个验证过程不超过五分钟。我第一次跑通这个闭环的时候还是挺兴奋的，因为这意味着 AI 从一个“每次都要重新认识我”的工具，变成了一个“能积累工作约定”的协作者。

5. 数据存储与隐私

5.1 数据存放在哪里

在讲数据之前先说一个关键点：claude-mem的数据默认只保存在本地。默认数据库文件路径一般是~/.claude-mem/memories.db，这是一个 SQLite 文件。你可以直接打开这个目录查看里面的结构，里面有数据库文件、日志文件、配置文件等。

既然是 SQLite，你就能用常规数据库工具去连它。我出于好奇用过sqlite3命令行查看过表结构，记忆相关的表主要有几个字段：id、content、created_at、source_session、keywords。整体设计很轻，不是那种动辄几十张表的重量级系统。

5.2 备份与迁移

因为数据就是文件，备份非常简单。直接把~/.claude-mem/目录整个压缩带走就行。我个人的习惯是每周末跑一次：

cp -r ~/.claude-mem ~/backups/claude-mem-$(date +%Y%m%d)

迁移到新电脑也一样，把整个目录拷贝过去，重新安装claude-mem，然后在配置里指定数据库路径或者直接把目录放到对应的默认位置即可。既然数据是明文 SQLite 文件，迁移之后不需要额外的数据转换。

5.3 隐私注意事项

使用它的隐私边界，我觉得有必要说清楚：记忆内容虽然存在本地，但生成摘要的过程需要调用 Anthropic 的接口来处理对话文本。也就是说，自动记忆功能会把你的对话内容发送给远程大模型服务来做摘要。如果你处理的是敏感代码或客户数据，需要先想清楚能不能接受这个链路。

好在claude-mem提供了关闭自动记忆的选项。你可以只保留手动记忆模式，这样就不会主动把对话内容送去生成摘要，只有你显式要求“记住”的内容才会进入记忆库。这个取舍，建议一开始就做好决定，别等数据出去了再后悔。

6. 常见问题与排查技巧

6.1 命令找不到或权限问题

我在多台机器上配置过，最容易踩的坑就是安装完claude-mem之后，终端提示command not found。原因一般是 npm 全局 bin 路径没有加到系统 PATH 里。排查方法如下：

npm bin -g

这个命令会输出全局 bin 目录。如果发现这个目录不在 PATH 里，你需要手动加一下，比如在~/.zshrc或~/.bashrc中写入：

export PATH="$(npm bin -g):$PATH"

还有一种情况是权限问题。如果你安装时用了sudo，生成的可执行文件可能归属 root，导致当前用户执行受限。我建议不要用 sudo 安装 npm 全局包，维护在当前用户自己的目录下能省掉很多权限烦恼。

6.2 MCP 连接失败

MCP 连接不上是重启后最常出现的问题。症状是 Claude Desktop 里看不到已连接状态，或者对话时提示工具调用失败。

排查顺序我一般是这样：

1. 手动启动 MCP Server 看看能不能正常工作：

   claude-mem mcp

   按 Ctrl+C 退出。
2. 确认配置文件路径正确。Claude Desktop 的配置文件一般在：

   ~/Library/Application Support/Claude/claude_desktop_config.json

   打开后检查mcpServers里claude-mem这一项是否存在。
3. 确认配置里的 command 是否是可执行文件的绝对路径。如果配的是claude-mem，但是 PATH 环境变量在 GUI 环境下没有加载，就会失败。改成绝对路径通常能解决。

另外一个容易被忽视的点是：修改配置后一定要完全退出 Claude Desktop 再重新打开，否则不会重新加载 MCP Server。我一开始只关窗口没退进程，折腾了半天才发现它一直用的是旧配置。

6.3 记忆不生效

“我明明对话了，也有记忆操作，但新会话里它就是不记得”——这类问题我遇到不止一次。排查方向有两个：

第一，确认记忆是否真的写入了数据库。用claude-mem list看数据库里到底有没有内容。如果没有内容，说明自动摘要没触发，或者摘要生成失败。

第二，确认注入机制是否正常。如果数据库里已经有记忆但新会话不生效，大概率是 MCP Server 没有正常回调。这时候可以在对话里直接问 Claude：“你能调用记忆工具吗？”如果它回答不能，说明工具调用链路断了，回到 6.2 排查。

第三，注意相关性问题。即便记忆注入正常，也不是所有历史记忆都会被捞出来。它是有相关性阈值的，如果你的问题和已有记忆的关键词完全不沾边，可能不会被注入。这时候可以试试把问题问得更具体一点，让关键词更接近记忆内容。

6.4 性能与数据库膨胀

用久了之后，数据库会越来越大，尤其自动摘要开启的情况下。SQLite 虽然轻量，但检索速度和数据量有一定关系。我目前的做法是定期清理低价值记忆。

claude-mem本身支持删除单条记忆：

claude-mem delete --id <id>

如果觉得手动删太麻烦，可以先把全部记忆导出做一次整理，清理后再重新导入。导出命令前面提过是claude-mem export，它会生成 JSON 文件。整理好之后，把原数据库文件删除，重新claude-mem init，再按照数据结构导入即可。这个流程虽然有点粗糙，但对于个人使用已经完全够用了。

7. 一些延展使用的思路

7.1 用记忆库沉淀个人规范

我现在把claude-mem当成一个“团队记忆库”在用，只不过这个团队只有我和 AI。我会把常用的代码规范、提交信息风格、命名约定，都通过手动记忆的方式写进去。这样一来，不管开多少个新会话，它的行为都会保持稳定。

这个用法特别适合自由职业者和独立开发者。因为你不一定有团队文档沉淀的习惯，但你和 AI 的协作频率可能非常高。与其写一份文档再每次手动贴给 AI，不如让 AI 自己记住。

7.2 结合项目级记忆做多项目管理

如果你同时维护多个项目，可以借助不同的数据目录来区分记忆。思路是这样的：不同项目用不同的环境变量指定数据路径，这样每个项目都有自己的记忆库。

举个例子：

CLAUDE_MEM_DATA_DIR=/path/to/project-a/.claude-mem claude-mem init CLAUDE_MEM_DATA_DIR=/path/to/project-b/.claude-mem claude-mem init

这样切项目的时候，记忆也是跟着项目走的，不会出现“A 项目的部署约定跑到 B 项目里”的串味问题。这个功能我是在看配置文件时发现的，虽然没有明确写在 README 最显眼的位置，但实测的确有效。

7.3 定期回顾记忆质量

我会每隔一两周跑一次claude-mem list，看看自动记忆到底存了什么东西。这个过程本质上是在做“记忆审计”，把没用的、过期的那几条删掉，把重要的但表述不清的重新记一遍。AI 的记忆和人一样，不是越多越好，而是越准越好。

8. 写在最后的个人体会

从我自己的实际体验来看，claude-mem最打动人的一点，是它把“AI 是否有长期记忆”这个问题从理念层面落到了可操作的工具层面。它的架构并不复杂，没有花哨的分布式存储，没有复杂的推荐算法，核心就是 SQLite 加 MCP 加一点相关性检索，但因为触发点设计合理，实际用起来非常自然。

如果你还在犹豫要不要引入它，我的建议是先按我上面 4.3 的闭环流程跑一遍。整个过程只需要五分钟，你马上能判断它是不是你需要的东西。我个人用下来的感受是，它并不会让单次对话的智能水平有质的飞跃，但对工作流稳定性的提升非常明显。它让 AI 从一个“每次都重新认识你”的陌生人，慢慢变成一个“越来越了解你”的长期搭档。

最后分享一个很小的技巧：使用手动记忆指令时，尽量把关键约束说得具体一点，加一些可量化的指标。比如“所有接口必须做超时熔断”就不如“所有接口响应时间不能超过 300ms，超时必须熔断”有效。记忆的质量直接决定了后续注入的效果，所以在写入那一刻多花十秒钟把话说清楚，后面会帮你省下大把反复解释的时间。