1. 这个东西到底是干嘛的
如果你重度使用 Claude Code 维护项目，迟早会遇到一个让人抓狂的场景：今天下午刚和 AI 敲定后端用 FastAPI、数据库直接用 Postgres、任务队列走 Redis，还专门在项目里建了个agents/目录放各个子 agent 的 prompt；第二天早上重新打开终端，Claude 跟完全失忆了一样，又把同样的架构问题从头问一遍。你会觉得它很蠢，其实它不蠢，只是每次会话启动时上下文都是全新的，昨天那些对话并没有自动带过来。
claude-mem 这个开源命令行工具，解决的就是这个"跨会话记忆断层"。它的核心思路是给 Claude Code、Cursor 这类终端 Agent 加一个持久记忆层，把之前几轮对话里已经形成的决策、代码约定、技术选型沉淀下来，下次开新会话时自动喂给模型。这样一来，AI 不再需要你每天把背景故事重新讲一遍，它会带着项目上下文直接进入工作状态。
它适合谁？我把话说白一点。
- 你要是偶尔让 Claude 写个排序函数、生成一段正则，那真用不上这工具，手动粘贴上下文就够了。
- 你如果每天开着 Claude Code 维护同一个仓库，项目里有大量隐含约定、已经被讨论过好几轮的架构决策，那装了它之后体验是质变。
- 你再要是玩多 Agent 协作，希望不同角色的 agent 共享一套项目记忆，它通过多 profile 天然支持这种场景。
我自己用了大概两周之后，最直观的感受是：日常需要手动复制粘贴给 AI 的"项目背景"少了一半以上。它记下的内容当然不可能全准，需要偶尔人工纠偏，但总体是笔划算的买卖。下面我把它的原理、安装、日常命令和踩坑实录完整写一遍。
1.1 为什么 Claude 会“失忆”
先把技术成因说清楚，不然你会误以为这工具在做什么黑魔法。大语言模型的上下文窗口是有限的，每次会话开始，模型能看到的内容只有系统提示词、你这次输入的内容，以及对话过程中逐步累积的消息。它没有任何"开机自启的硬盘"，不会自动读取昨天存在磁盘某处的笔记。Claude Code 这类工具能记住项目结构，是因为它实时跑了文件系统的 tool call，但对话层面的历史决策，它并不会主动翻出来。
有人会说，Claude Code 的会话不是可以--resume继续吗？确实能，但你总不能每次工作都顺着昨天的会话尾巴往下聊。会话之间会有新需求、新改动、新分支，而项目顶层的"宪法性约定"——比如目录结构怎么摆、错误处理用什么风格、依赖走哪个私有源——这些内容应该独立于某段会话而存在。claude-mem 做的事就是把这类约定从会话历史里剥离出来，单独存成一份结构化记忆，而不是让你每次都去翻阅 JSONL 会话日志。
1.2 和笔记、文档方案的区别
有人第一反应是：我写个CONVENTIONS.md不也一样？我试过，它能解决问题的一部分，但有几个很致命的弱点。
第一，文档是静态的。你得记得去改，还得记得让 Claude 去读。项目忙起来的时候，谁会专门去维护一份给 AI 看的宪法文件？反正我没有这个自律。
第二，文档是全局的。一个 50 万行的成熟仓库和一个刚初始化的 demo 项目共用同一套约定，粒度完全不对。你要在文档里区分"哪些规则适用于哪个项目"，做着做着文档就成了一团浆糊。
第三，文档没有时间线。上次推翻的方案、两周前弃用的库，这些内容在文档里只会被默默覆盖，你根本不知道 Claude 现在的某个决定是基于哪条历史记忆。claude-mem 的做法更接近"日志驱动的记忆"：它是从真实交互历史里长出来的，每条记忆自带时间戳、会话 ID 和来源，你能回溯，能被搜索，也能随时删掉某条不靠谱的结论。
2. 核心原理与数据模型
2.1 记忆从哪来：会话尾部的“结论富矿”
用过 Claude 写代码的人应该都有体会：一场超过半小时的长会话，越到后面越容易出现类似"那我们就用 Pydantic v2 吧""统一走utils/validators.py这个入口""以后公共方法都放lib/不要放utils/"这样的句子。这些在对话当时只是决策流的一部分，但隔一天再看，它们就是整个项目最重要的约束。
claude-mem 在自动记忆方面，依赖的主要信号正是这种"尾部结论"。它会去读取 Claude Code 产生的会话记录，也就是~/.claude/projects下那堆 JSONL 文件，把最近一段交互作为候选区，从中抽取看起来像结论、约定、事实的句子。这层实现本质上不是多高深的 NLP，而是一套启发式规则加轻量过滤：太短不收，纯情绪化表述不收，连续追问过程不收，但带"我们决定""统一用""以后别再用"这类决策色彩的表述，很容易被收进去。
这里有个前提你得知道：自动识别不可能是 100% 准确的。所以它的设计哲学是"先收进来，再人工裁决"。你不满意某条记忆，直接 forget 掉；它漏掉的，你手动 remember 补上。按我自己这几周的体验，自动识别的准确率大概七到八成，可以接受，剩下的手动兜底。
2.2 数据躺在哪：SQLite 与多 profile
记忆默认存在~/.claude-mem/memories.db，就是一个 SQLite 文件。项目选 SQLite 而不是扁平 JSON，是个非常实际的决定：查询、去重、按时间排序、按关键字过滤，SQL 的灵活性比每次全文件扫描强得多。数据库模型也简单，核心就是memories表，每条记录包含内容、创建时间、所属会话 ID、profile 名称、来源类型这几个字段，你完全可以把它当成一个"带时间戳的轻量笔记库"来看待。
多 profile 是它容易被忽略但非常好用的功能。你可以给不同场景建独立的记忆空间，比如主项目用default，小玩具项目用sandbox，个人学习笔记单独开一个。启动时通过环境变量或命令行参数切换 profile，各空间互不污染。这样做的价值在于：你不想让一个实验性项目的临时决策，污染你主力项目里那些已经沉淀好的稳定约定。
要说明的是，SQLite 是本地文件存储，所以读取速度非常快。每次新会话注入记忆时，实际耗时可忽略不计，不存在"装了这个工具，终端变卡"的问题。
2.3 记忆怎么被召回：MCP 工具与提示词注入
claude-mem 提供两种召回路径，我建议两个都开。
第一种是作为 MCP 服务器存在。MCP 你可以粗暴理解为 AI 世界的 USB 接口，任何支持 MCP 的客户端都能通过同一套协议调用外部工具。claude-mem 以 MCP 工具的形式把自己的能力暴露给 Claude：获取最新记忆、搜索记忆、保存记忆、删除记忆。Agent 在会话中遇到具体的记忆需求时，会主动调用这些工具。比如说模型发现自己需要确认"分页参数之前是怎么定的"，它会去调search-memories搜一把。
第二种是把最近几条记忆直接拼进系统提示词里。这个方案我很喜欢。相比"等模型想起来去搜"，注入是零延迟的前置加载，代价是只能容纳少量内容。我实测下来，注入最近三条核心记忆 + 按需搜索的组合最舒服：开场就有上下文，具体问题再深挖。
3. 安装与三分钟接入
3.1 安装 claude-mem
安装这块倒是很简单。它是个 Python 包，最省事的路径是走 PyPI：
pip install claude-mem如果你机器上 Python 环境比较乱，也可以考虑用pipx装成独立 CLI，避免和系统 Python 包互相污染：
pipx install claude-mem装完可以先验证版本：
claude-mem --version能正常输出版本号，说明核心 CLI 已经可用了。如果你想玩最新特性，项目 README 上一般也会给curl安装脚本的路径，不过我自己的习惯是稳定版走 pip，追求新功能才去拉源码。
3.2 配置 MCP 服务器：Claude Code 实测
要让 Claude Code 真正用上 claude-mem，核心是注册 MCP 服务器。Claude Code 的配置文件位置在~/.claude/settings.json，你需要在里面的mcpServers字段里注册一条记录：
{ "mcpServers": { "claude-mem": { "command": "claude-mem", "args": ["mcp", "--transport", "stdio"] } } }保存后重启 Claude Code，让它重新加载 MCP 配置。加载成功的话，你会在会话里看到它把最近几条记忆作为开场上下文带进来，或者你可以在对话里直接问 Claude："你有哪些记忆工具可以用？"它应该能列出搜索、获取、删除之类的能力。
这里有个细节：--transport stdio是终端本地客户端用的，Claude Desktop 和 Claude Code 这类本地跑 MCP 的场景基本都是 stdio。远程 HTTP 模式一般用于自定义 Agent 或容器化场景，日常开发用不上，我也不建议一上来就折腾 HTTP。
3.3 其他客户端的接法：Cursor 与 Claude Desktop
Cursor 的接法和 Claude Code 大同小异。新版 Cursor 支持项目级 MCP 配置，在项目根目录建一个.cursor/mcp.json：
{ "mcpServers": { "claude-mem": { "command": "claude-mem", "args": ["mcp"] } } }Claude Desktop 则要写进它的配置文件，macOS 上路径是~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上在%AppData%\Claude\下。配置块同样是注册一个名为claude-mem的服务器，写法和上面一致。
接完这些客户端之后有个共同点：所有 MCP 工具调用的数据都走本地进程，不会经过云端转发。这一点对看重代码私密性的团队尤其重要，后面我会专门展开。
4. 日常使用与命令手册
4.1 核心命令速查
我把自己真正高频用的命令整理成了一张表。注意不同版本可能有细微改动，以你本地claude-mem --help为准，但下面这批命令在这几周里我基本每天都在用：
| 命令 | 作用 |
|---|---|
claude-mem | 显示最近记忆的快速摘要，没有子命令时的默认入口 |
claude-mem latest-memories | 取最近三条记忆，适合作为每日开工前的快照 |
claude-mem recent-memories | 按时间倒序列出所有记忆，可以带数量限制 |
claude-mem search "关键词" | 做全文模糊搜索，返回命中的记忆 |
claude-mem remember "内容" | 手动写一条记忆，适合自动识别漏掉的场景 |
claude-mem forget <id> | 按记忆 ID 删除一条记录 |
claude-mem sessions | 查看历史会话列表，回看某次会话产生的记忆 |
claude-mem status | 查看当前数据库路径、profile、MCP 状态 |
先说latest-memories。我每天开工第一件事就是跑一遍这个命令，目的是确认 claude-mem 昨晚自动存了什么，快速扫一眼有没有明显抽风记下来的垃圾。如果有，就地 forget；如果缺了什么关键结论，顺手 remember 补上。这种"开工前清点记忆"的习惯，比等模型把错误记忆带进对话再纠正要省事得多。
search命令是处理"突然想不起来之前怎么定的"这种场景的最好工具。比如我恍惚记得上周和 Claude 讨论过日志格式，但忘了结论是 JSON 还是纯文本，直接跑：
claude-mem search "日志格式"它会直接把命中条目连同时间戳打出来，几秒钟定位。
4.2 手动写入与遗忘：别把记忆库变成垃圾场
自动识别不是万能的，所以手动写记忆的能力很重要。举个例子，有次我敲定了一个很关键的决定："所有外部 API 请求必须通过clients/http.py统一封装，禁止在业务代码里直接 import requests。"当时对话尾部有大量细节内容，结果自动抽取没有把它单独提炼出来。我没有纠结，直接手动补了一条：
claude-mem remember "所有外部 API 请求必须通过 clients/http.py 统一封装，禁止业务代码直接 import requests"这条记忆当天下午就被新会话的 Claude 用上了，它写新模块的时候一开始确实想直接 import requests，然后自动报错，自己调用了记忆工具查出这条约定，老老实实改走统一封装。这个场景是我觉得整个工具最值钱的地方：约定被固化下来，并持续约束后续代码生成行为。
反过来，记忆库最怕的是只进不出。我见过有人装了 claude-mem 之后完全不清理，数据库里堆了几百条模棱两可的废话，最后注入提示词的有效信息密度反而下降。我的建议是每周花两分钟做一次"记忆瘦身"：recent-memories全量扫一遍，凡是过期的、被推翻的、描述太模糊的，统统 forget。记忆这事儿，少而精永远好过多而杂。
删除单条记忆用forget加上 ID：
claude-mem forget 37ID 可以通过recent-memories或search的输出看到。需要说明的是，这不代表彻底抹掉历史——它只从记忆表里移除，Claude Code 自己的会话 JSONL 日志仍然存在原始记录。但就模型每次召回的上下文而言，这条记忆已经不可见了。
4.3 从旧会话里恢复记忆：claude-mem 的隐藏价值
除了自动和手动两种写入方式，claude-mem 还有一个我最近才经常用的场景：旧会话补档。某次会话过后，你发现有些结论当时没触发自动记忆，而手动补又嫌麻烦，其实可以直接从历史会话里再挖一遍。配合sessions命令找到目标会话，再针对性地用搜索调用找出相关结论，写成记忆补录进去。相当于给记忆库做二次捕捞。
以我自己的使用习惯，这类"补档"往往发生在项目大改之后。比如重构完目录结构，我会回头检查最近三天的会话里有没有已经被推翻的旧目录约定，有的话立刻 forget 掉，免得旧规则和新结构混淆在同一个记忆库里。
5. 常见问题与排查实录
5.1 MCP 连不上：先分清是路径问题还是注册问题
我见过太多人在这里卡住。现象是 Claude Code 里报了 MCP 连接错误，或者工具列表里压根看不到 claude-mem 提供的功能。排查第一步，先在终端手动跑一遍：
claude-mem mcp --transport stdio如果这个命令直接报命令不存在或者 Python 模块找不到，那就不是配置问题，是claude-mem压根不在 Claude Code 子进程能拿到的 PATH 里。这种情况在 macOS 上尤其常见——你可能把 Python 包装进了用户目录，但 Claude Code 是从 GUI 环境启动的，PATH 和你终端里的不一样。
解决办法一是用绝对路径注册，比如command写"/usr/local/bin/claude-mem"或者"$(which claude-mem)"展开后的完整路径；二是把 MCP 注册命令的 args 里加上--config指向配置文件，减少环境依赖。这个问题折腾我半小时，最后就是用绝对路径解决的。
5.2 记忆一直为空：先检查会话日志来源
另一个高频问题是：配置一切正常，但claude-mem跑出来就是没有记忆。这时候要查它的数据来源。claude-mem 自动记忆依赖 Claude Code 的本地会话日志，如果你用的是 Cursor 等其他客户端，会话日志的路径和格式可能不同，自动记忆阶段采集不到东西，自然为空。
我的建议是，不要只依赖自动记忆。先手动remember几条，验证数据库写入和召回链路是否通，如果手动写的能正常被搜到，那说明整个链路没毛病，缺的只是自动采集源。当前要么切换成手动为主的工作流，要么针对你使用的客户端去查它是否兼容。从产品现状来看，Claude Code 的兼容性是最成熟的，其他客户端建议以手动记忆为主、自动为辅。
5.3 数据库膨胀与备份恢复
SQLite 文件用久了会膨胀，这是所有日志型数据库的通病。不过 claude-mem 的体量通常很小——就算一天记 20 条，一条算 200 字节，一年也就一两 MB，完全不用担心。真正需要关心的是备份。我本地用 macOS 自带的 Time Machine，所以~/.claude-mem/目录会自动进入备份，如果你没有整机备份习惯，建议隔段时间手动把整个目录打包：
tar -czf claude-mem-backup.tar.gz ~/.claude-mem恢复也很简单，把memories.db放回原路径即可。这个文件是自包含的，不存在跨机器迁移后找不到外部依赖的问题。
6. 安全与隐私边界
6.1 数据到底存哪、怎么传输
这个问题我每次推荐工具都会被问。claude-mem 的记忆数据存在你的本地磁盘，就是这个~/.claude-mem/memories.db文件。MCP 通信走的是本地进程间管道，不是云端 API，也就是说，你的代码决策、技术约定这些东西不会因为装了它就被传到一个第三方的服务器上。它和那些把上下文发到云端做索引的服务有本质区别。
但要说完全没有风险也不客观。第一，如果你用 HTTP 传输模式跑远程 MCP，那么记忆内容会走网络，传输通道的 TLS 配置需要你自己把关。第二，memories.db本身是明文存储的 SQLite 文件，谁拿到了磁盘权限，谁就能直接读里面所有记忆。第三，你会通过提示词把记忆注入给模型，而这些提示词在某些产品里可能被用于模型训练或质量评估，这不是 claude-mem 能控制的，取决于你用的客户端本身的数据策略。
6.2 需要注意的坑：别把密钥和隐私写进记忆
我的实操建议是：不要在记忆里保存任何密钥、Token、数据库连接串。理由不用多说，这是明文文件，而且每次都会被自动拼进系统提示词，暴露面比普通笔记大得多。我在用 Cluade Code 时，密钥一律走.env和环境变量，claude-mem 记忆里只保存"如何访问"的约定，比如"配置项在.env的DB_PASSWORD字段"，而不是密码本身。
此外，公司代码仓库如果涉及未公开的业务逻辑，使用这类记忆工具前最好跟团队确认。虽然数据在本地，但如果你使用的客户端本身存在遥测上报，或者你把记忆通过提示词注入给了云端模型，那这些内容本质上是进入了模型服务商的处理链路。这个风险不是 claude-mem 引入的，但你得心里有数。
6.3 关于记忆"污染"的几点经验
最后分享几条我这段时间踩坑踩出来的经验。
第一，记忆库里最危险的是"过期的架构决策"。一个项目从单体拆成微服务的过程中，会有大量旧约定被推翻。你如果不及时 forget，新会话的模型会同时读到"所有模块都放app/目录"和"模块拆分到各个 services"两条冲突记忆，然后一脸懵。我的解法是：每次架构调整完成后，立刻做一次记忆清理，把被推翻的旧约定全部删掉或者更新成新版本。
第二，有些记忆需要带约束条件。比如"全项目用 pytest"是条好记忆，但"不要用 pytest"这种负向表述容易让模型过度解读。我现在的习惯是，写记忆时尽量用正向、可执行的表述，少用"禁止""不要"开头，除非真的没别的说法。模型对这些指令的遵循能力没那么强，表述越具体、越像对代码的实际约束，效果越好。
第三，别想着把 claude-mem 变成一个万能知识库。它的定位是轻量记忆层，不是 Notion。你把长篇需求文档、接口设计说明书塞进去，效果只会更差。核心结论、风格约定、技术选型这些"一句话能说清"的东西才适合进记忆库，大段内容请继续放 README 或文档，然后在记忆里存一个文档路径让模型去读。这样两者的优势才能互补。
以我个人这几周的体验来看，claude-mem 最有价值的地方不是省下了多少复制粘贴，而是让 AI 真正开始具备"项目感"。它会在你忘记交代背景的情况下，主动用之前定好的约定去约束新代码；当你改完一个模块，它也能帮你把这次决策沉淀下来，不用你反复说同样的上下文。当然，它不能替代人的判断，自动记忆偶尔会抽风，需要定期打理。但只要你适应了"开工前看一眼、每周清一次"这个节奏，它确实能让终端里的 AI 更像一个真正跟了你半年的队友，而不是每次见面都重新自我介绍的路人。
