claude-mem 这个名字第一次看到的时候我还以为是官方给 Claude 出的什么记忆插件后来才发现是社区开发者 yhyu13 做的一个开源 MCP 服务器。简单说它的作用就是给 Claude Code 装上一套“跨会话记忆”每次你在 Claude Code 里和模型对话它会把会话内容沉淀到本地的 SQLite 数据库标注好项目和会话归属再通过关键词、主题摘要甚至长期记忆LTM的方式在后续的新会话里被重新召回。装上之后最直观的变化就是你不再需要反复跟 Claude 解释“我们之前不是讨论过那个模块吗”它能真的“想起来”。这篇文章是我自己实际用了小几周之后的完整记录从原理拆解到安装步骤、从配置细节到踩坑经验全都写出来。适合正在用 Claude Code 做开发、被上下文丢失烦得不行的朋友也适合对 AI 编程工具怎么做持久化记忆这件事感兴趣的人。我会尽量把底层机制讲清楚但也不会堆术语能让大多数人照着操作就行。1. 为什么需要给 Claude Code 装上“记忆”1.1 会话隔离一次性的上下文是最大的浪费用过 Claude Code 的朋友应该都有同感它确实很强能自己读文件、跑命令、改代码但前提是你得在同一个会话里把事情讲清楚。一旦关掉终端或者新开一个 session它就什么都不记得了。这不是模型的智商问题而是会话边界的限制——每次对话都相当于让一个聪明但失忆的同事重新上岗你必须把所有背景、约定、关键词重新讲一遍。我自己的项目里有很多跨文件的重构比如把一个老的 Python 模块拆成服务、或者调整某个 API 的返回格式。这种任务通常要持续好几个小时中间可能还会穿插查 bug、跑测试、改文档。会话一断下次再开新会话光是重新描述背景就要浪费几百个 token如果项目再大一点我还得手动把相关文件的路径一张张贴给模型效率非常低。更难受的是很多临时结论比如“这个接口字段命名不规范后续要统一加前缀”如果不写进注释或者文档下次就彻底找不回来了。这种“一次性的上下文”其实是很大的浪费。模型明明花了几千个 token 理解项目结果会话一结束这些积累直接归零。这也是 Claude Code 这类 agentic 工具目前最明显的痛点之一。1.2 官方记忆能力的边界Claude 产品本身确实提供了一些记忆能力。比如在 Claude 的网页端或 API 设置里用户可以配置一些个人偏好模型在后续对话里会用上这些偏好。Claude Code 里也有 CLAUDE.md 这种项目记忆文件你可以把项目的结构、代码风格、常用命令写进去让每个新会话自动带上这个背景。但这些方案都有一个共同问题基本靠手动维护。CLAUDE.md 不会自动从你们的对话里提取信息你必须在写文件的时候想好什么该记、什么不该记而且还得定期更新。我在实际项目里经常陷入一个尴尬局面项目刚开始的时候 CLAUDE.md 写得很认真后面代码一改动文档就渐渐失修里面的信息甚至开始误导模型。官方记忆功能也不是为“会话级的历史记录”设计的它更像是给用户提供一个“长期偏好”的载体。你很难指望它自动把“三天前那次会话里我们决定用 pydantic v2 而不是 v1”这种细节记住。开发者真正需要的是一个能自动捕捉对话、自动整理、又能被后续会话主动查询的记忆层——这正是 claude-mem 切入的位置。1.3 claude-mem 的定位和核心思路claude-mem 做的事可以概括成三层记录层通过 MCPModel Context Protocol服务器接入 Claude Code把每一次会话中双方的消息、工具调用等都记录下来存到本地 SQLite 数据库中。整理层定期对结束的会话做总结提取主题、关键词甚至生成“长期记忆”把零散的对话内容变成可以检索的知识点。召回层在后续会话中模型可以通过搜索接口按项目、按关键词、按时间等条件从数据库里找到相关记忆然后把它们作为参考上下文重新注入。这套思路本质上是用一个外部数据库给模型做“外挂记忆”。好处非常明显完全本地、数据结构透明、可以按项目隔离、也可以随时删除或导出不依赖任何云端服务。对于注重隐私、且希望记忆内容可控的开发团队来说这比把对话记录直接丢给第三方更有安全感。2. claude-mem 的工作原理拆解2.1 MCP 服务器与 stdio 通信机制先说一下 MCP。Model Context Protocol 是模型上下文协议本质上是给 AI 应用程序定义一套标准的接口让模型可以调用外部工具、读取外部数据源。Claude Code 里配置的各种 MCP 服务器就是通过这个协议跟 Claude 交互的。claude-mem 就是一个 MCP 服务器。它通过 stdio标准输入输出和 Claude Code 之间走 JSON-RPC 消息。启动时Claude Code 会向服务器发送工具列表请求获得服务器暴露出来的工具能力当模型在对话中决定调用某个记忆相关的工具时请求会被发给服务器服务器操作 SQLite 数据库并返回结果。这种架构的好处是解耦。MCP 服务器不关心上层的 UI 是 Claude Code 还是其他支持 MCP 的客户端只要客户端实现了协议它就能接上。claude-mem 本身也不依赖 Claude 专有 API它只是做好存储和检索至于怎么用这些记忆完全交给模型自己判断。这种“记忆存储和推理分离”的设计我个人比较欣赏因为我们以后换模型、换前端记忆数据完全可以沿用。2.2 本地 SQLite会话、事件与记忆的数据模型claude-mem 把数据存在本地 SQLite 数据库里默认文件位置是~/.claude-mem.db。这个选择很务实SQLite 零配置、单文件、易备份对个人开发者来说再合适不过。相比用 MySQL 或者 RedisSQLite 不需要额外起服务也不会因为系统重启就丢东西。数据库内部大概会包含三类核心表和若干辅助表字段名按版本会有差异我提供一个大致的简化模型方便理解CREATE TABLE sessions ( id TEXT PRIMARY KEY, name TEXT, project_path TEXT, created_at DATETIME, updated_at DATETIME ); CREATE TABLE events ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT REFERENCES sessions(id), role TEXT, content TEXT, ts DATETIME ); CREATE TABLE memories ( id TEXT PRIMARY KEY, session_id TEXT, content TEXT, keywords TEXT, importance REAL, created_at DATETIME );sessions记录了一次会话的基本信息project_path是用来隔离项目的关键字段。events存储了会话中的每一条消息或工具调用相当于给它做了“全文留痕”。memories是提炼出来的长期记忆带有 keywords 和 importance 这样的辅助字段方便做筛选和排序。我每次用claude-mem status看状态时都会顺手用 sqlite3 打开数据库看看 sessions 和 events 的数量有没有增长。如果某个项目会话已经开了很久但 events 一直不涨那多半是 MCP 接入出了问题或者数据库路径被改了。提前熟悉这个模型排查问题会快很多。2.3 长期记忆LTM是怎么生成出来的“长期记忆”是 claude-mem 里比较核心也比较有意思的机制。它不会一开始就把所有对话原封不动当成记忆而是会等会话积累到一定规模之后做一次总结提炼。大致流程是这样的一次会话结束或空闲一段时间后工具会判断当前会话的事件数量是否达到阈值。如果达到阈值它会尝试对这段时间内的对话内容做一次压缩提炼把具体的问题、结论、决策提取成简短的记忆条目。提炼出的记忆会被写入 memories 表并抽取关键词方便后面检索。这个过程相当于让工具自动写“会议纪要”。我在实际使用中感觉它的提炼粒度还是蛮合理的不会把“我改了一行代码”这种琐碎的东西都记下来而是更倾向于记录“决定用 xx 方案解决 xx 问题”这类有复用价值的结论。LTM 的生成依赖本地配置的模型或 LLM 接口。如果模型接口没配好它可能只做关键词提取效果会打折。装完后建议先确认 LTM 是否真的在工作具体方法可以看下一节安装部分的验证流程。2.4 搜索和召回关键词与相似度排序记忆要能被用上检索环节很关键。claude-mem 目前更多是基于关键词和主题匹配类似 TF-IDF 的思路输入一句话它会找出含相关词汇和主题的记忆条目按相关度排序返回。这个方案和真正的向量语义检索相比优点是轻量、离线、几乎零成本缺点是它不一定能理解同义表达。比如你上次记的是“修复登录态失效”这次问的是“token 过期问题”如果没有共同关键词召回效果就会弱一些。实际用下来我发现只要在对话里直接问“我们之前有没有处理过 xxx 问题”带上比较明确的关键词命中率还是不错的。如果第一次搜不到换个说法再搜往往能搜到。对大多数编码场景来说项目里的命名、错误信息、函数名本身就是非常稳定的关键词所以问题没有想象中严重。3. 安装与初始化实操从零到有记忆3.1 安装 MCP 服务器到 Claude Code安装 claude-mem 本质上就是把它的 MCP 服务器注册到 Claude Code。先确认本机有 Node.js 环境而且 npx 命令可以用。然后推荐用 claude mcp add 命令直接注册claude mcp add --scope project -- claude-mem npx yhyu13/claude-mem这个命令会把 claude-mem 以项目级 scope 添加到当前项目的 MCP 配置里。如果希望全局可用把--scope project改成--scope user就行。如果你更习惯直接改配置文件也可以在项目根目录创建或编辑.mcp.json内容类似这样{ mcpServers: { claude-mem: { type: stdio, command: npx, args: [yhyu13/claude-mem] } } }这里面的type必须是stdio表示通过标准输入输出通信。改完配置后重启 Claude Code让它重新加载 MCP 服务器。有个小细节如果是在公司的内网环境npx 首次拉包会比较慢可能还会被 npm registry 的连接问题卡住。建议提前配好 npm 镜像或者把 registry 设置成内网源否则安装过程会显得像卡死了一样。3.2 验证安装status 命令与数据库文件安装完成后先不要急着开始写代码先验证一遍。用下面的命令检查 MCP 服务器有没有被 Claude Code 识别claude mcp list如果输出里有 claude-mem说明工具列表已经注册成功。接下来直接运行claude-mem status这个命令会显示当前记忆库的状态包括数据库路径、会话数量、记忆数量、数据库大小等信息。正常情况下它会输出类似这样的内容Database: /Users/you/.claude-mem.db Sessions: 7 Events: 3421 Memories: 18 Last record: 2025-01-xx 10:12:33看到 sessions 和 events 数量不是 0说明工具已经开始记录了。此时可以再用 sqlite3 打开数据库看看有没有数据落盘sqlite3 ~/.claude-mem.db SELECT count(*) FROM events;我这里提醒一句如果claude-mem status报“database not found”或者显示 0别急着下结论说工具坏了。先确认你当前所在的目录和刚才启动 Claude Code 的目录是不是同一个因为项目级配置是按目录加载的换个目录状态可能就不一样了。3.3 数据文件、日志路径与基本体检方法claude-mem 默认会在用户主目录下生成几个文件。除了~/.claude-mem.db还有一个~/.claude-mem.log日志文件。日志这个细节很容易被忽略但它排查问题非常好用。我常用的体检流程是这样的# 查看日志尾部确认 MCP 服务器启动是否正常 tail -f ~/.claude-mem.log日志里会记录工具调用、数据库连接、LTM 生成等关键动作。如果工具一直不记录数据先看日志里有没有报错比如数据库无法创建、路径不可写之类的基本就能定位问题。还要留意一下数据库文件的体积。我自己的经验是会话用多了之后events 表会膨胀得很快几十个会话之后文件大小可能就上百兆了。这个跟项目复杂度有关属于正常现象。如果完全不在乎历史细节只想要结论性记忆可以定期清理旧的 events只保留 memories文件会瘦很多。4. 核心功能使用让记忆发挥价值4.1 记忆搜索与自动召回claude-mem 最直接的价值就是在新会话里把旧记忆捞回来。使用时不需要专门学什么语法Claude Code 已经能感知到 claude-mem 提供的记忆搜索工具你只要在对话里自然地问就行。比如我会这样说“我们之前是不是处理过数据库连接池被占满的问题帮我从记忆里找一下当时的结论。”这种带明确关键词的提问召回成功率最高。Claude 会调用 claude-mem 的搜索工具返回相关记忆然后结合当前项目上下文继续跟你讨论。如果你想让搜索范围更窄也可以直接问“在 xx 项目下面搜索 xx 关键词”因为 claude-mem 的记忆是按项目隔离的跨项目搜可能会没有结果。我印象最深的一次是在改一个老项目的性能优化时想起了上一次会话里讨论过一个“批量插入太慢改成分批提交 事务合并”的结论但具体参数记不清了。我直接问了一句“上次我们聊的批量插入优化具体怎么做的”结果它把当时的结论、涉及的文件路径、甚至当时的代码片段都捞了出来。那一刻我真的觉得外挂记忆比模型变聪明更实在。4.2 主题汇总与项目档案除了逐条搜索claude-mem 还支持主题类的汇总能力。你可以请求它总结某个项目过去一段时间的会话生成类似“项目纪要”的内容。这在开始一项新任务之前特别有用相当于先让模型读一遍项目历史快速进入状态。我自己习惯在每个迭代周期结束时跑一次汇总然后把结果贴到项目文档里。这样一来即使 claude-mem 的数据库被清理了汇总文档仍然保留着核心决策。很多人只把它当成聊天记录备份工具但我觉得它更像一个自动化的“项目档案生成器”。不过也有一点要注意汇总质量取决于模型的总结能力如果某次总结生成得比较粗糙后续检索出来的记忆可能也会不完整。所以关键项目的核心结论我还是会再做一层人工复核。4.3 会话重命名、导出、导入与删除claude-mem 提供了一些命令行管理能力常用的大概有这些# 查看状态和信息 claude-mem status # 列出会话 claude-mem list # 重命名某个会话方便以后检索 claude-mem rename session-id 订单模块重构 # 导出全部数据备份或迁移用 claude-mem export --format jsonl # 导入数据 claude-mem import backup.jsonl会话重命名是我很推荐的操作。默认生成的会话 ID 都是字符串时间一长根本分不清谁是谁。我每次开始一个比较大的任务前会先按功能给它起个名字比如“支付回调联调”或者“用户权限表设计”后面搜记忆时光凭会话名就能定位到很多信息。导出功能对备份和迁移很有用。默认是 JSONL 格式每行一条记录。我每隔几周会导一次存到自己的备份目录里。反正数据是你自己的多备份不会错。删除功能要谨慎使用。它有作用域限制一般只作用于某个会话或某个项目下的数据。如果你真想清空全部记忆库建议手动备份整个.claude-mem.db文件再操作省得一不小心把自己的历史沉淀连根拔掉。4.4 与内置 CLAUDE.md、官方记忆功能的配合claude-mem 出现之后我和 CLAUDE.md 的分工就变清晰了。CLAUDE.md 用来记录那些“长期稳定”的项目规则比如技术栈、目录结构、代码风格约定。这些信息比较固定适合让模型每次会话都带上。claude-mem 则用来记录那些“动态变化”的过程性知识比如某次 bug 的排查过程、某个模块的临时设计方案。这些信息没必要常驻在上下文里但有必要在需要时能快速找回来。我现在的做法是CLAUDE.md 保持精简只放必须的东西claude-mem 负责把历史经验收着。平时会话就正常用不要因为装了记忆工具就疯狂附加冗余提示词让工具在后台安安静静记录就行。这样两个方案互相补充体感最好。5. 自定义配置与进阶调优5.1 环境变量与数据路径claude-mem 提供了一些环境变量可以对默认行为做定制。我自己最常改的是数据库路径和日志级别。如果你默认目录所在磁盘空间紧张或者想把记忆库归到专门的数据目录可以通过环境变量指定export CLAUDE_MEM_DB_PATH/data/ai/claude-mem.db export CLAUDE_MEM_LOG_LEVELinfo注意环境变量要在启动 Claude Code 之前设置好或者写在 shell 配置里否则 MCP 服务器子进程可能拿不到变量。MCP 服务器是通过 Claude Code 启动的子进程它的环境变量继承自父进程。这一点我踩过一次坑我把变量写在了一个 GUI 启动器的配置里但系统服务里没加结果工具根本读不到自定义路径。5.2 按项目隔离的原理和注意事项claude-mem 的隔离原理不复杂会话记录里有一个 project_path 字段跟当前工作目录绑定。所以你在~/work/project-a里开 Claude Code记录就归到 project-a在~/work/project-b里开记录就归到 project-b。这带来一个好处就是不同项目的记忆不会互相污染。但也有一个坑如果你用符号链接切目录或者通过/tmp下的临时目录启动 Claude Code记录可能会被归到一个新的路径名下导致之前的记忆搜不到。所以我会尽量避免在符号链接路径里启动工具而是用真实路径。还有一点如果你同时在多个终端里开 Claude Code而且都在同一个项目目录下它们的会话记录会同时写到同一个数据库。这个在 SQLite 层面是可以并发的但如果有两个会话同时去写同一行记录偶尔会出现锁定报错。真遇到了不用慌等几秒重试就行SQLite 的锁机制会有它自己的调度方式。5.3 记忆体量增长后的维护策略用了一段时间之后数据库会越来越大反而影响检索效率。这时候可以考虑做一次“记忆压缩”把不再需要的原始事件清理掉只保留长期记忆。我自己的维护节奏是周期操作每周运行claude-mem status确认记录正常增长每个迭代结束跑一次项目汇总导出项目纪要每月导出一份 JSONL 备份顺手清理明显过时的旧会话每季度查看数据库体积如果过大清理 events 只留 memories清理的时候不要直接删数据库文件而是用工具自带的命令。如果非要手动清理 SQLite 表请先备份因为 events 和 memories 之间有外键关联粗暴删除会导致统计和搜索紊乱。6. 常见问题与排查技巧实录6.1 MCP 服务器没注册Claude Code 完全没反应症状配置好了 claude-mem但在 Claude Code 里问它“有没有记忆”它完全一脸茫然没有任何提示。这个多半是 MCP 服务器没有被 Claude Code 加载。先运行claude mcp list看看列表里有没有 claude-mem。如果没有检查.mcp.json的格式特别是 JSON 里逗号和引号是不是写错了。很多人在args里把包名写成了数组而不是字符串这是最常见的低级错误。如果claude mcp list里已经显示有 claude-mem但在会话里仍然没效果就重启 Claude Code 再看。MCP 服务器一般在启动时加载运行中修改配置不会自动生效。6.2 npx 路径不对导致启动失败症状Claude Code 能识别 claude-mem但每次调用工具都报错说找不到命令或进程退出。MCP 服务器由 Claude Code 启动它会继承 Claude Code 的 PATH 环境变量。如果你的 npx 安装在某个用户级目录但 Claude Code 是通过桌面图标或者服务方式启动的PATH 里可能没有那个目录子进程自然找不到 npx。解决方法是把 node 和 npx 的路径显式写进配置里或者设置启动 Claude Code 的 PATH# 先确认 npx 实际路径 which npx # 推荐把输出路径写进 .mcp.json 的 command 字段我自己的做法是直接使用 node 的绝对路径配合npx省得环境变量的问题反复出现。6.3 搜索召回结果为空或很弱症状确认数据在记录status 里 events 也很多但问它“之前有没有遇到过 xxx”时永远返回“没有找到相关记忆”。第一步先排除是不是跨项目了。检查当前目录和产生记忆的目录是否一致如果跨项目检索范围天然不重叠。第二步就是关键词问题。前面说过claude-mem 的关键词匹配对同义表达不敏感你要尽量用当时的原词去问。我通常会切换到数据库里直接查一下sqlite3 ~/.claude-mem.db SELECT content FROM memories WHERE content LIKE %token% LIMIT 5;能看到结果说明数据没问题问题在于召回链路。如果你非要用同义表达可以调低匹配阈值或者尝试在提问时把关键词多列几个。6.4 升级版本后数据库不兼容症状更新了 claude-mem 之后status 显示 DB 文件打开失败或表结构不对。这个属于升级迁移问题。SQLite 的表结构如果改了版本旧库不一定能无缝兼容。遇到这种情况先把旧库备份cp ~/.claude-mem.db ~/.claude-mem.db.bak然后重新初始化和导入。如果工具提供了 self-migration 或者 import 功能用它来导旧数据。备份永远比任何迁移工具可靠。我更推荐的做法是升级前先主动导出一份 JSONL升级后再导入这样最稳。6.5 误删记忆与备份恢复我身边有人手动删除过某个 sessions 记录后来又想找回当时的讨论发现找不回来了。claude-mem 的删除是按记录走的删了 sessions 后关联的 events 和 memories 也会被清理。所以要操作删除之前一定先导出或备份。备份其实非常简单直接复制数据库文件都行因为它可能是 WAL 模式所以我的建议是先用工具导出 JSONL或者用sqlite3 .backup做在线备份sqlite3 ~/.claude-mem.db .backup ./backup-$(date %s).db这种方式比直接复制文件更安全不会因为并发写入导致备份文件损坏。7. 我的实际使用心得与扩展思路7.1 什么样的工作流收益最大从我个人的使用体感来说claude-mem 的收益不是均匀分布的。它最适合那些“长期在同一个项目上反复磨”的场景比如维护老代码、重构大型模块、或者在一个 monorepo 里来回切换任务。这种场景下历史对话里的结论密度很高如果全靠人肉记忆真的会丢东西。反过来如果你只是偶尔开着 Claude Code 写几个一次性脚本每次会话都很短那 claude-mem 的效果不会太明显。因为记忆需要积累会话量不够的时候它能回找的东西自然有限。这个不是工具的问题而是记忆数据的“冷启动”阶段本来就需要时间。我自己现在的工作习惯是每个项目初始化之后顺手把 claude-mem 装好然后用一两个星期积累数据。初步的感受是大概攒到十来个会话之后它的价值就比较明显了。后面基本上是越来越值钱因为你跟模型聊过的每一点有效内容都在变成后续会话可调用的资产。7.2 隐私与数据安全方面的考量这一点我必须单独拎出来说。claude-mem 把全部会话内容明文存在本地 SQLite 里也就是说凡是你在 Claude Code 里说出去的话包括代码片段、项目路径、报错信息都会落盘。如果你是独立开发者这个可能无所谓。但如果在公司环境里就得先确认公司允不允许把内部代码放到外部模型工具里以及允不允许在本地保留这些日志。我建议至少做三件事数据库文件不要放进 Git 仓库加进.gitignore。定期检查数据库文件权限确保只有当前用户可读不要用chmod 777这种危险权限。不要把敏感密钥、生产环境密码直接通过 Claude 对话处理更别指望 claude-mem 主动脱敏。它只是个记忆仓库不是安全审计系统。还有一个容易被忽略的问题当你把 claude-mem 的数据导出成 JSONL 时导出文件也包含了完整的敏感信息。别随手传到公共网盘里这跟把数据库文件丢出去没有本质区别。7.3 后续可以怎么扩展我自己已经开始琢磨一些更进阶的用法。比如把多个项目的 claude-mem 汇总到一起做一个团队级的“经验库”新来的同事接项目之前先跑一遍历史汇总能少踩很多坑。再比如可以写个 cron 定时任务每周自动导出一份 JSONL 并提交到私有仓库这样长期保留项目“记忆变更史”。如果以后工具支持导出成 Markdown 格式我甚至可以直接把这些记忆文档化变成项目 wiki 的一部分。另外一个方向是给记忆加结构化标签。虽然 claude-mem 已经有 keywords 字段但如果能在存记忆时主动给关键词做一次归一化比如“DB”和“数据库”统一成“database”召回效果会好很多。这个可以在导出后写脚本处理成本不高但收益明显。说到底模型本身的能力正在快速提升但对很多实际开发任务来说真正的瓶颈已经不是模型聪明不聪明而是它能不能稳定地记住项目里发生过什么。claude-mem 用最简单的方式把这件事补上这也是我为什么愿意把它写进每台开发机的初始化清单。以后不管换新机器还是开新项目先把记忆层拆好剩下的交给时间就行。