claude-mem：让Claude会话具备长期记忆的开源工具

直接回答：claude-mem 是一个专门给 Claude 会话增加“长期记忆”能力的开源工具。如果你经常用 Claude 的 API 或客户端写代码、做分析、聊需求，大概率遇到过这种场景：上午刚聊完一个项目的技术选型和约束条件，下午开个新会话，它全忘了，你又得把背景信息从头粘贴一遍。claude-mem 解决的就是这个事，它把每次对话里的关键信息自动保存下来，在后续会话中按需调取，相当于给 Claude 配了一个长期记事本。

这篇文章我会从原理到部署，再到日常使用，完整拆解 claude-mem 的工作方式，并结合我自己实际跑了一段时间的经验，把配置参数、踩坑点、目录结构这些细节一次性说清楚。无论你是在本地调 API，还是在使用 Claude 的终端客户端，只要想让会话真正“连续”起来，这篇文章都适用。

1. 为什么需要记忆层：Claude 会话的先天短板

1.1 无状态会话的真实痛点

用过 Claude 的人都有体会，它的单次对话能力很强，但跨会话的“失忆”问题非常明显。默认情况下，每一次会话都是独立的，对话一结束，模型对这次交互的所有上下文就归零了。这不是 Claude 的缺陷，而是大语言模型的基本设计——它本身不维护持久化状态。

但落到实际工作流里，这个特性就很折磨人了。举个例子，我在做一个小工具的前端界面时，第一轮会话里确定了组件库用哪套、配色规范是什么、接口字段命名规则是啥，甚至约定了错误处理统一走某个拦截器。这些信息在当次会话里 Claude 记得清清楚楚，代码生成得也顺。可一旦新建会话继续做下一个模块，它就开始凭“直觉”写代码了，风格和前一轮完全不同，字段命名对不上，样式也跑偏。你只能花大量时间重新描述需求，或者把之前的代码贴给它当参考。

这就是记忆缺失的代价。我身边不少重度用户的做法是维护一个长文本文档，把自己和 Claude 的约定、项目背景、常用命令全写进去，每次会话开始先粘一遍。这种办法能用，但维护成本高，而且随着项目复杂度上升，文档越来越长，最终会超过上下文窗口的有效范围，或者因为内容太多反而干扰了模型对当前任务的判断。

1.2 claude-mem 的核心定位

claude-mem 就是针对上面这个痛点做的。它的核心思路是：把“会话”和“记忆”分开——会话是短期的、一次性的，记忆是长期的、跨会话累积的。工具会在后台自动记录每一次对话的关键内容，按项目或主题归档，在下一次相关会话启动时，把匹配的记忆重新注入到上下文中。

你可以把它理解成一个外挂的“海马体”。模型本身依然不存储任何记忆，但 claude-mem 负责把记忆存放在本地，并在合适的时机“想起来”。这样做有几个直接好处：

第一，不需要改模型，也不需要训练，完全在应用层解决，兼容 Claude 各个版本。第二，记忆存在本地文件系统或数据库中，隐私可控，不会上传到第三方。第三，它不只是一个简单的日志记录器，而是带检索能力的——不是把所有历史都塞进去，而是只提取与当前任务相关的部分。

我在实际使用中把它接到 Claude 的客户端上之后，整个工作流明显顺了。最直观的感受是，跨会话的开发任务不再需要重复交代背景，它知道这个项目叫什么、依赖什么、代码风格怎样，甚至记得我之前说过“后端端口固定用 8080，别乱改”这种细节约定。

2. 记忆系统的工作原理拆解

2.1 记忆的分层结构

claude-mem 的记忆管理并不是“一把梭”式地全量存储，而是分了层级，这样既能保证信息完整，又不会让噪音干扰模型。我梳理了一下，大致是三层结构：

第一层是原始会话记录。每一次和 Claude 的完整交互都会被保留下来，通常按时间和会话 ID 归档到本地。这一层负责“保底”，任何历史信息都不会丢，算是一个完整的操作日志。

第二层是提取出的结构化“记忆卡片”。工具会从原始对话中识别关键信息，归纳成条目。比如用户偏好、项目约束、技术决策、常用命令、命名习惯等。每条记忆都有一个主题标签、一段摘要文本、以及创建时间，方便后续检索。

第三层是长期项目档案。当一个项目积累了足够多的记忆卡片后，claude-mem 会把相关卡片聚合成项目级摘要，代表这个项目当前的整体状态。在新会话开始时，这个摘要会作为系统级上下文注入，让模型快速进入状态。

这样分层设计的好处显而易见。直接用原始日志会带来 token 爆炸的问题——如果一次性把所有历史都塞给模型，上下文窗口根本装不下。而只注入项目摘要，信息密度高、占用少，真正需要细节的时候，再通过检索把相关卡片捞出来。

2.2 关键的上下文检索机制

记忆存储好之后，最关键的问题是怎么在合适的时候把合适的记忆取出来。这也是 claude-mem 和普通日志工具最大的区别。日志只管记，claude-mem 还得管“想”。

我看到的实现思路里，比较主流的是基于关键词和向量语义的双路检索。关键词检索适用于记忆条目里有明确专有名词的场景，比如“项目名”、“端口号”、“库名”，这类信息用精准匹配效率最高。向量语义检索则适合模糊匹配，比如当前会话在聊“登录超时处理”，它能找到曾经记录过的“token 过期策略”相关记忆，即便字面上没有完全重合的词汇。

双路检索的结果会做一次融合排序，按相关度、时间衰减、来源可信度综合打分。时间衰减是个容易忽略但很重要的点——如果一条记忆是三周前记录的，而另一条是昨天的，后者理应优先。但也不能一刀切，因为有些约定是长期有效的，所以 claude-mem 还会根据记忆条目类型区分“长期偏好”和“临时状态”，两者有不同的衰减系数。

这套机制的好处是，注入到上下文里的记忆都是“有用”的，而不是“随机挑几条”。在我的实际测试里，同一轮的 context window 里挤进来的都是直接相关的信息，模型理解当前任务的起点明显高了一大截，很少再出现“我是谁、这个项目是什么”的迷茫状态。

2.3 记忆压缩与长期演进

还有一个必须面对的问题是，随着使用时间拉长，记忆总量会不断膨胀。哪怕检索再精准，项目摘要如果越来越长，最终还是会成为模型上下文的负担。claude-mem 在记忆压缩上有一套自己的策略。

常规做法是定期对同主题的记忆卡片做合并摘要。比如一个项目里关于“数据库选型”的讨论可能出现在多个会话中，早期它用的是 SQLite，后来切换到了 PostgreSQL，这中间还有过几次反复讨论。如果只是简单叠加，最终记忆里会同时存在“用 SQLite”和“用 PostgreSQL”两条矛盾信息，模型真的需要时反而不知道信谁。

所以 claude-mem 的记忆压缩不是简单的文本拼接，而是带“反思”的聚合。它会把同一主题下的历史卡片统一提取出来，生成一份新的、更精炼的摘要，并且对明显的变更决定打上“已废弃”或“已更新”标记。旧的细粒度卡片会被归档，不再参与正常检索，只有项目级摘要继续生效。

我在使用中比较欣赏这个设计，因为它让记忆系统越用越“聪明”，而不是越用越“臃肿”。前几天我看了一眼我的记忆目录，最早几轮会话的原始记录还在，但真正进入上下文的基本都是后来的聚合摘要，信息更新鲜，也更贴合项目当下的真实状态。

3. 部署与接入实操

3.1 安装与初始化

claude-mem 的部署过程不复杂，前提是你的本机已经具备 Python 3.10 以上环境和 Node.js 环境，这主要因为它同时有 Python 后端和一部分终端客户端集成逻辑。安装我建议用虚拟环境，避免污染全局 Python 包。

# 创建并激活虚拟环境 python3 -m venv ~/.venvs/claude-mem source ~/.venvs/claude-mem/bin/activate # 安装主程序 pip install claude-mem # 验证安装结果 claude-mem --version

装完之后别急着用，先做一次初始化。这一步会创建默认配置目录、记忆存储目录，以及生成一个配置文件。初始化命令很简单：

claude-mem init

这个命令会自动创建默认的目录结构，并在终端里打印配置文件的路径。我机器上跑完之后，它的默认记忆根目录是在~/.claude-mem/下面，包括sessions/存放原始会话记录、memory/存放结构化记忆卡片、projects/存放项目级档案，一目了然。

如果你和我一样在不同机器之间同步开发进度，建议把记忆目录软链到网盘目录或者 Git 仓库里，这样换台设备也能延续记忆。我个人是把整个~/.claude-mem目录纳入了一个私有 Git 仓库管理，遇到大改动前先提交一版，相当于给记忆做了个版本控制。

3.2 接入 Claude 客户端的方式

claude-mem 最实用的接入方式是和 Claude 的终端客户端做集成。目前支持两种主要渠道，一种是通过 MCP（Model Context Protocol），另一种是通过 CLI 包装器。

MCP 是现在比较推荐的方式，因为它是标准协议，接入后 Claude 客户端原生就能调用记忆读写能力，不需要额外脚本。在客户端的配置文件里加上 MCP server 配置即可，示例如下：

{ "mcpServers": { "claude-mem": { "command": "claude-mem", "args": ["mcp"], "env": { "CLAUDE_MEM_HOME": "/path/to/.claude-mem" } } } }

配置好之后重启客户端，Claude 就具备了调用记忆工具的权限。你可以直接在对话里问它“我上次说过的关于日志格式的偏好是什么”，它会通过 claude-mem 的检索工具把相关记忆调出来回答你，就像它自己记得一样。

CLI 包装器的方式则更轻量，适合不想动 MCP 配置的人。它会拦截你发给 Claude 的命令，在会话开始前自动把相关记忆注入到 prompt 里，相当于一个透明代理。这种方式的好处是兼容所有 Claude 客户端，缺点是注入的记忆内容你不太好实时干预，一切靠工具的自动判断。

我自己的做法是主用 MCP 方式，因为控制力更强，记忆的读写都是显式的，会话里能聊到就说明工具查到了，没聊到我也可以手动要求它搜索。

3.3 记忆目录的结构

部署完成之后，花点时间了解一下记忆目录的结构，对后续排查问题很有帮助。这是我在实际使用中整理的一个典型目录树：

~/.claude-mem/ ├── config.yaml # 主配置：模型参数、路径、检索策略 ├── sessions/ │ ├── 2025-11-01/ │ │ ├── conv_14b2a9.md # 原始会话记录 │ │ └── metadata.json # 会话元信息（时间、项目、token数） ├── memory/ │ ├── user_preferences.md # 用户级长期偏好 │ ├── project_notes.md # 项目级记忆索引 │ └── cards/ │ ├── 3f8a21.md # 单条记忆卡片 │ └── 9c04d7.md └── projects/ ├── my-tool/ │ └── summary.md # 项目聚合摘要 └── website/ └── summary.md

每个 session 的原始记录是 Markdown 格式，方便人工翻阅，这一点我很喜欢，因为即便 claude-mem 的自动检索失效了，我还能手动打开文件看一眼当时的完整上下文，排查问题也不至于抓瞎。记忆卡片则是结构化的，包含标题、标签、正文摘要、时间戳这些字段，方便程序做检索和排序。

在 config.yaml 里，有几个参数值得重点关注。一个是retrieval.topk，它控制每次最多取回多少条记忆，默认是 5，我建议如果上下文窗口充裕，调到 8 会更稳。另一个是compression.interval_days，控制自动压缩周期，我设的是 7 天一次。还有一个是storage.backend，支持local、sqlite和postgres，默认是local文件存储，适合单机；如果有多机同步需求，可以换到 sqlite 或者 postgres。

4. 核心功能与日常使用指南

4.1 会话摘录与记忆提取命令

claude-mem 的核心能力之一是自动摘录，也就是从一次完整的对话中提取关键记忆。所有客户端会话在结束时，它会自动运行一次提取流程，不需要手动触发。但如果你用的是不支持自动集成的客户端，或者你需要手动处理一批历史会话，CLI 命令同样可以完成。

# 处理最近的 10 个会话 claude-mem extract --limit 10 # 处理某个时间范围 claude-mem extract --since "2025-11-01" --until "2025-11-07" # 只提取指定项目的会话 claude-mem extract --project my-tool

提取完成后，你可以用claude-mem list查看当前记忆库里的所有卡片，每条项目会显示记忆标题、所属项目、创建时间和简短的摘要内容。这相当于给记忆库做了一次体检，能直观看到它记住了哪些东西，哪些重要信息可能漏掉了。

在测试阶段我经常用这个命令校验提取质量。例如我故意在一次会话里提到“把三个重试次数从 5 调到 3，以及把超时时间改成 15 秒”，然后跑完extract之后去查看记忆卡片，看它是否准确记录了这两个具体数值。如果偶尔出现漏记，我会选择把它标记为 high importance 或者手动补一条记忆。

4.2 搜索与复用历史记忆

除了自动注入，claude-mem 还提供了主动搜索能力。有时候你在当前会话里想确认一个历史决定的背景，不需要等到自动检索，直接搜就行。

# 关键词搜索 claude-mem search "数据库连接池" # 按项目过滤 claude-mem search "端口配置" --project my-tool # 列出所有项目档案 claude-mem projects

搜索结果的排序默认按相关度和时间综合计算。实际测试下来，搜具体数值类关键词，比如“超时时间”或者“端口号”，命中精度很高；搜概念类词汇，比如“性能优化”，则需要依赖语义检索，准确率会略有下降，但也能找到方向正确的记忆卡片。

主动搜索在会话里也能做。通过 MCP 集成后，你可以在对话中直接说“查一下我们之前聊过的关于 Redis 缓存策略的记忆”，claude-mem 会把结果拿给 Claude 看。这样即使在新的会话中，也可以无缝衔接旧话题，不需要复制粘贴任何文字。

我实际开发中最常用的场景是这样的：新会话准备动手改某个模块，先输入一句“读取 my-tool 项目的所有未完成事项和约束”，然后 Claude 就会通过工具调起记忆检索，把这之前几个会话里记录的任务列表、注意点、遗留问题都整理出来，相当于一个自动生成的项目简报。我之前靠手写 README 干的事，现在它自己汇总，而且比我写得全。

4.3 遗忘管理与隐私控制

记忆系统还有一个容易被忽略但很重要的功能：遗忘。并不是所有信息都适合长期保留，有时你会希望某些敏感数据不被记录，或者某些旧记忆不再影响之后的会话。

claude-mem 提供了三个层面的控制手段。第一是忽略规则，你可以在配置文件里配置某些路径或者关键词，凡是匹配的内容一律不进记忆库。第二是手动删除，使用claude-mem forget --id <card_id>可以精准删除某条记忆卡片。第三是全库清理，claude-mem wipe会把所有会话记录和记忆卡片清空，恢复到初始化状态。

我在实际使用中有一条经验：敏感信息的控制一定不要事后清理，最好事前配置忽略规则。因为 claude-mem 的原始会话记录存在本地明文，虽然不上传网络，但在共享电脑或者需要备份到 Git 仓库的场景下，明文记录本身就是一个风险点。

我目前的做法是在 config.yaml 里配置了一个正则过滤列表，把密钥类、token 类的内容直接排除在提取范围外。同时记忆目录里的敏感项目我会单独设置特殊权限，确保只有当前用户能读。

关于隐私，再补充一点：claude-mem 默认的存储后端是本地文件，不会把数据发送到任何外部服务。但如果你配置了语义检索功能，部分实现会使用本地向量模型，嵌入计算也在本地完成，因此不会产生数据出网的问题。只有在你自己配置了外部模型 API 的情况下，记忆内容才可能会被发送到模型服务商去做嵌入计算，这个环节需要你自己权衡。

5. 常见问题与排查技巧

5.1 典型故障速查表

部署 claude-mem 和使用过程中，我踩过不少坑。下面是我整理的一些典型问题、可能原因和对应解决方法的速查表，希望帮你少走弯路。

5.2 几条比较隐蔽的避坑经验

除了上面的常规问题，这里再分享几条比较隐蔽的实战经验。第一条是关于会话时长和记忆质量的关系。claude-mem 的提取质量高度依赖对话的完整性，如果你的会话特别短，还没有聊出有效的结论就结束了，提取出来的卡片往往短而无用。我现在的习惯是：每个子任务尽量在一个会话里聊完整，收尾前做一个简单的口头总结——“我们这几个是确定的，这几个待定”——这样 claude-mem 提取出的记忆就有清晰的前置结论，比自动从零散聊天里硬抠摘要强得多。

第二条是关于 token 占用的问题。记忆注入不是免费的，每条检索出的记忆卡片都会占用上下文窗口。如果你用的是长上下文版本还好，如果是小窗口模型，注入 8 条长记忆可能挤占了当前任务的生成空间。我建议在配置 topk 时先保守一点，观察一段时间的对话效果，找到“记忆够用但不拥挤”的平衡点。我现在用 5 条这个默认值，大部分情况下已经够用。

第三条容易被忽略的是多次配置变更后的记忆冲突。如果你某一天改了项目的技术选型，但旧记忆没有被及时标废，新会话里模型可能同时看到新旧两个版本，造成混乱。claude-mem 在压缩时能处理大部分冲突，但它不能主动感知你在外部做的决定。所以我每次在项目里有重大变更时，都会手动跑一次项目关联的压缩或者直接删掉旧记忆卡片，让新记忆从头初始化，避免“记忆打架”。

最后一条是备份策略。记忆库一旦积累久了，价值会非常高，一次误操作或者文件系统损坏，这些记忆就全没了。我现在每天用 cron 任务定期把记忆目录打包备份到项目网盘中，频率不高但足够稳妥。恢复的方法也简单，把备份目录解压回原路径即可，claude-mem 会自动识别已有数据，无缝接续。

我个人真实体验下来，claude-mem 最大的价值不是让你少打字，而是它把“上下文连续”这件事从一次性会话里解放了出来，让跨会话的开发协作真正变成可能。如果你也有那种“重新开一个会话等于重新带一个新人”的感觉，这个工具非常值得在你的工作流里占一个位置。先跑一个星期试试记忆提取质量，再逐步调参数，你会慢慢发现，和 Claude 的配合线变得大不相同。