用过 Claude 或者 Claude Code 的朋友应该都经历过同一个尴尬场景上午还跟它聊得好好的下午换台电脑或者新开一个会话它就完全不记得之前讨论过的项目背景、代码规范和你的偏好了。你只能把同样的背景信息重新粘贴一遍有时候一天要重复好几轮。这个痛点非常真实而claude-mem这个开源项目就是专门解决这个问题的。claude-mem是一个基于 MCPModel Context Protocol协议的记忆增强工具它的核心功能就是给无状态的 Claude 加装长期记忆。它会自动把对话中值得记住的信息用户偏好、项目背景、关键决策、代码约定等写入本地 SQLite 数据库并在后续对话中按需检索注入给 Claude。通俗点说就像给 Claude 配了一个随身笔记本聊过的东西不会白聊。这个工具非常适合重度使用 Claude 的开发者、技术写作者以及任何需要在多会话中维持上下文一致性的场景。这篇文章我会从设计思路、安装配置、实操过程到踩坑记录完整拆解claude-mem目前的表现。无论你是刚听说 MCP 的新手还是已经在折腾 Claude 自定义配置的老玩家按着这篇文章走半小时内就能把记忆功能跑起来。1. 项目整体设计与思路拆解1.1 无状态 AI 的痛点与claude-mem的价值先回到一个基础问题为什么 Claude 会失忆目前的大语言模型本质上是无状态的。每一次对话请求都需要把完整的上下文拼进 prompt 里发给模型模型本身并不保留任何记忆。Claude 官方提供的 Project Knowledge 和自定义 instructions本质上也是用户手动把资料塞进上下文的工具并没有自动化的回忆能力。一旦会话关闭、上下文超长截断或者切换了对话窗口那些藏在历史里的信息就彻底丢了。claude-mem的价值恰恰在这里。它用外部存储SQLite 数据库作为记忆的容器利用 MCP 协议与 Claude 双向通信。Claude 在对话过程中会主动调用工具记录重要信息下次对话时又会自动查询相关的历史记忆把结果作为上下文的一部分带进来。整个过程不需要用户手动搬运材料时间越长积累的记忆越多Claude表现出的智力在特定领域内就越高。这个思路的本质是把模型能记住多少的问题转化为外部数据库能不能高效存取的问题。模型能力不够的部分用工程手段来补这其实是目前 AI 应用层一个非常务实的做法。1.2 架构选型为什么是 MCP SQLiteclaude-mem的技术选型很值得聊。它没有做成浏览器插件也不是一个独立 GUI而是选择以 MCP server 的方式存在。MCP 目前是 Anthropic 主推的标准化协议Claude Desktop 和 Claude Code 都原生支持 MCP 服务器的接入相当于给 AI 提供了一个标准化的工具插口。存储层选 SQLite 更是相当务实。对于个人级别的记忆数据量几千条到几万条记录SQLite 的读写性能完全不是瓶颈单文件部署、零运维、跨平台拷贝方便还能直接用 DuckDB 或 SQLite Browser 之类的工具做查询分析。相比之下如果引入 Postgres 或者向量数据库虽然后续扩展性更强但光环境搭建这步就能劝退大部分普通用户。值得特别提一句的是claude-mem的记忆并不是简单的把全文日志存下来而是通过结构化分表来管理。用户信息、事实陈述、偏好习惯、项目决策、代际偏好等分别存储和检索这比一股脑的 chat history 要精确得多。具体实现细节我在第三节展开。1.3 适合谁用能解决什么问题如果你属于下面几类人群中的一种claude-mem非常值得一试深度使用 Claude Code 的开发者。跨会话维护项目上下文是刚需尤其是多模块开发、跨天推进时Claude 能自动记住之前定的 API 方案和代码约定节省大量重复沟通成本。用 Claude 做写作、研究或知识管理的朋友。对话中提到的生平细节、文献偏好、观点立场都会被记下来后续写作对话的连贯性会有质的提升。对数据隐私有要求的用户。所有记忆都存储在本地数据库里不会上传到第三方服务器这点比云端记忆方案让人放心得多。反过来如果只是偶尔用一次 Claude 聊天、问点一次性问题不加记忆问题也不大。这个工具带来的增益是越用越明显的初始阶段感知可能并不强烈。2. 核心细节解析与实操要点2.1 环境准备与安装步骤在实际动手前先把前提条件列清楚。claude-mem需要 Node.js 环境目前推荐的版本是 Node 18 及以上。如果你的系统里已经装过 npm 或者其他 Node 工具链一般都能满足要求。测一下版本号node -v npm -v我在 macOSApple Silicon和 Ubuntu 22.04 上都跑过过程一致Windows 理论上也可以通过 WSL 跑但建议优先用 WSL原生 PowerShell 环境下 MCP 的路径拼接容易出幺蛾子。claude-mem的安装方式主要分两种npm 全局安装或者克隆仓库本地构建。对大多数人来说npm 全局安装最省事npm install -g thedotmack/claude-mem安装完成后敲一下claude-mem --version确认能正常运行。如果提示命令找不到多半是全局 bin 路径没进 PATH检查下npm prefix -g把对应的 bin 目录加进~/.zshrc或~/.bashrc。这个虽然是小问题但遇到的人真不少我刚开始装的时候也是卡在最后一步。如果你更想控制源码版本或者想改点内部逻辑那就走源码构建git clone https://github.com/thedotmack/claude-mem.git cd claude-mem npm install npm run build构建产物在dist目录下后续配置 MCP 时直接指向构建出来的入口文件即可。2.2 配置文件与 MCP 接入安装完成之后最关键的一步是把claude-mem注册成 MCP 服务器。不同的客户端配置方式稍有差别。Claude Code的配置路径是项目级的在项目根目录建一个.mcp.json文件然后按下面这个格式填{ mcpServers: { claude-mem: { command: claude-mem, args: [--transport, stdio] } } }Claude Desktop则是编辑claude_desktop_config.json位置一般在# macOS ~/Library/Application Support/Claude/claude_desktop_config.json # Windows %APPDATA%\Claude\claude_desktop_config.json填入相同的 JSON 配置即可。配置完成后重启 Claude Desktop然后在界面上看 MCP 服务器状态是否显示已连接。如果显示红色错误多半是 command 路径没找到。解决方式是在配置里直接写绝对路径比如{ mcpServers: { claude-mem: { command: /usr/local/bin/claude-mem, args: [--transport, stdio] } } }路径不确定的话用终端执行which claude-mem看一下就知道。从我个人体验来说在 Claude Code 里接入比在 Desktop 里顺手。Claude Code 本身就是命令行工具调试链路更透明日志输出直接打在终端里出了问题方便定位。2.3 数据库结构与记忆格式装好之后claude-mem会在你系统目录下创建数据文件夹。macOS/Linux 下默认位置是~/.claude-mem/ ├── memories.db # 主数据库文件 └── config.json # 用户配置文件数据库的核心表结构大致如下我 prisma 看了一遍源码直观理解起来非常清晰memories表主记忆表字段包括id、type、content、metadata、timestamp等。type字段用来区分记忆类型。tags表记忆标签体系支持建立多对多关系。sources表记录每条记忆的来源会话和项目方便追溯。embeddings表为每条记忆生成文本向量在检索阶段做相似度匹配。记忆的type分类我觉得很有参考意义常见的有类型含义USER_PREFERENCE用户偏好命名习惯、格式要求、工具链选择FACT事实性信息项目技术栈、架构决策、外部依赖TASK_STATUS任务进度功能开发到一半、遗留问题CODING_STYLE代码风格约定缩进、命名规范、框架约定每一条记忆都会附带observed_at时间戳和source字段这样就算后续记忆发生冲突也能根据时间线和来源判断哪条记录更可信。这个设计细节在长期使用中特别管用——Claude 偶尔会记录两条矛盾的偏好有来源追溯才好做收敛。3. 实操过程与核心功能实现3.1 首次对话记忆是怎么自动产生的安装配置完成后我建议你先别急着堆复杂任务用一个测试项目完整走一遍闭环。我当时建了一个假装在开发一个小型记账应用的临时目录然后跟 Claude Code 开始对话。第一轮对话里我故意说了几类信息项目用的技术栈是 FastAPI React、数据库打算用 PostgreSQL、代码风格上偏好双引号和末尾分号、当前阶段正在设计用户表。这些信息在普通对话里聊完就散了但接入claude-mem之后Claude 会在对话过程中自动判断哪些信息值得记忆并调用记忆工具的saveMemory方法写入数据库。这个自动判断的机制很有意思。不是说用户每句话都会被存下来而是 Claude 通过一个内置的信息筛选prompt判定某条内容是否具备长期复用价值。像今天天气不错这种废话不会被记录而这个项目我们决定用 monorepo 架构这种会影响后续决策的信息一定会入库。你可以通过claude-mem --query命令行工具验证一下记忆是否写入成功claude-mem --query tech stack正常情况下会返回刚才对话中提到的 FastAPI、React、PostgreSQL 等技术栈信息。看到这一步基本上说明整个链路已经通了。3.2 手动操作记忆的管理与检索如果说自动记忆是工具的主干那手动管理能力就是它的精细化触手。claude-mem的命令行接口提供了几个非常实用的操作显式添加记忆。自动判断再聪明也有漏网之鱼。当你明确希望 Claude 记住某条信息时直接跟它说请记住我们团队约定所有 API 返回格式都用{code, data, message}结构它会通过工具调用把这条信息写入记忆库。查看全部记忆。如果想回顾目前到底积累了多少记忆跑一下claude-mem --show输出会按时间倒序列出所有记忆记录每条都带 ID、类型、内容、来源会话和时间戳。这个功能在感觉 Claude 最近好像没有记住新东西的时候特别有用能快速定位是不是自动记忆的环节出了故障。记忆搜索。除了让 Claude 在对话中自动检索记忆你也可以手动验证记忆库里的内容是否完整claude-mem --search project architecture这条命令会对存储的文本做相似度匹配返回与查询语义相关的记忆条目。我实测下来搜索质量在个人项目这个数据量级下相当够用不太需要额外接 Embedding API。3.3 让 Claude 在后续对话中自动调用记忆记忆写入是基础真正体现mem价值的是对话时的自动检索。在 Claude Code 里随便新开一个会话直接问它我们计划用什么数据库 如果没有claude-mem它大概率会一脸茫然接入之后它会先调用记忆工具执行searchMemories(database)然后把检索到的PostgreSQL作为参考信息再给出回答。这个先检索、再生成的流程本质上就是目前业界提的 RAGRetrieval-Augmented Generation范式。但claude-mem做得好的一点在于它的上下文注入是有取舍的不是把整个数据库内容全塞进 prompt而是只注入与当前问题语义相关的记忆片段严格控制 token 消耗。我做过多轮实测在积累了大约 200 条记忆的情况下普通对话的 token 增量大概在 300~800 之间基本无感。也就是说记忆功能带来的上下文增益成本非常可控不会出现对话越久越烧钱的情况。3.4 记忆的去重、冲突处理与遗忘机制记忆系统运行时间久了一定会产生重复或冲突的记录。比如周一你告诉 Claude代码用 4 空格缩进周三又说算了用 2 空格吧——两条记忆都存在该听谁的claude-mem处理这个问题靠的是时间和上下文权重。每条记忆都有timestamp当 Claude 检索时命中冲突内容它会优先采信时间更新的记录。同时在saveMemory时会做一轮相似度比对完全重复的内容会直接合并或忽略。我建议你也可以养成定期清理的习惯claude-mem --delete id可以直接删除指定记忆一个月跑一次保留真正有价值的内容就好。这类主动性遗忘的功能设计得不是很深但对于目前的适用场景来说已经足够了。真正需要复杂遗忘曲线和记忆消退机制的话那就是另一个量级的产品了。4. 常见问题与排查技巧实录4.1 典型故障速查表好用的工具该踩的坑一样也不少。下面这张表是我在实际安装和使用过程中遇到的典型问题按照从高到低的发生频率排列症状可能原因解决办法MCP 服务器连接失败显示红色错误claude-mem命令不在 PATH 中在配置中使用绝对路径/usr/local/bin/claude-mem对话中 Claude 完全不提记忆MCP 工具未被自动调用或提示词未触发手动触发请搜索你的记忆库找一下关于...的信息记忆写入失败提示 database is locked多个进程同时访问 SQLite 数据库检查是否有其他会话在使用同一数据库WAL 模式可能存在锁竞争关闭多余会话claude-mem --query返回空数据库路径不在默认位置查看配置确认DB_PATH是否被修改或直接用--db path指定安装后命令不存在npm 全局 bin 目录未加入 PATH执行npm prefix -g并添加对应 bin 目录到 shell 配置文件其中 database is locked 这个问题我遇到得最多。原因是我习惯同时开多个终端窗口跑不同的 Claude Code 会话而claude-mem默认的 SQLite 策略在并发写时偶尔会锁库。我现在的做法是尽量控制同时活跃的会话数最多两个基本就不会撞锁了。如果你确实需要大量并发会话可以考虑改一下数据库的 journal 模式为 WAL有助于改善这个情况。4.2 隐私与安全注意事项用claude-mem之前隐私边界一定要想明白。所有记忆都存本地确实比云服务安全但一旦数据库文件被上传到公共仓库或者发给别人等于把核心隐私直接暴露。以下几个点是我会特别留意的默认数据库路径不要改保持~/.claude-mem/就好。很多人图省事会把数据库放在项目目录里一不留神就提交到 git 仓库了。如果一定要放项目里记得把*.db加进.gitignore。敏感信息需要过滤。密码、Token、密钥这类内容虽然 Claude 不太会主动记忆但你还是应该养成习惯不直接在对话中暴露如数据库密码之类的敏感信息。这不是claude-mem的问题而是所有 AI 工具使用的通用准则。定期备份数据库。claude-mem虽然稳定但手工备份不要省。直接把~/.claude-mem/memories.db拷贝到指定备份目录即可恢复也就是一条复制命令的事。4.3 高级使用技巧与后续扩展思路等基础流程跑顺了之后可以试一试下面几个我实际用下来体验不错的高级玩法场景一多项目隔离。现在官方版本默认用一套数据库存储全部记忆多个项目容易互相污染。我自己的做法是为不同项目配置不同的--db路径通过 Claude Code 的项目级配置指向不同的数据库文件。这样 A 项目的技术方案不会串到 B 项目里记忆之间的干扰会小很多。场景二结合自定义 instructions 使用。claude-mem只是给了 Claude 检索记忆的能力但在对话中何时检索、检索什么其实还可以通过 instructions 进一步优化。例如在系统提示词中加一条当你需要回答涉及项目背景或历史决策的问题时请先调用记忆搜索工具再进行分析。 这个组合方式能让记忆的调用率明显变高思考链路也更稳定。场景三写自动化工具读取记忆库。很多朋友看到memories.db里面的结构化数据就有想法完全可以写一些脚本做二次分析。比如跑个 Python 脚本统计一下本周积累了哪些类型的记忆看一下项目进度在时间线中的推进情况。这类玩法基于 SQLite 太方便了自由度很高后续也大概率会进化出更丰富的可视化方案。写在最后的一点个人体会claude-mem给我最大的感受是它把 AI 从每次都像第一次见面的状态里拉了出来让对话变得有连续性、有积累感这在持续工作流里带来的效率提升是实实在在的。你可以把它当成一个网络黑盒它不一定每次都完美——偶尔会有记忆检索不到、偶尔会存了无关内容——但整体上能解决那些手动搬运上下文带来的绝大多数重复劳动。我在实际用了两三周之后最明显的体验是跨天继续一个项目时重新回到会话里直接说接着昨天的进度推进Claude 就已经知道昨天讨论到哪个功能、踩过哪些坑、代码风格是什么这种连贯感确实有点上瘾。如果你也在为 AI 对话的失忆头疼花半个小时把claude-mem装起来大概率不会后悔。