这次我们来看 thedotmack 开源的 claude-mem。如果你经常用 Claude Code 做代码维护、多轮任务改造或者接续式开发大概会遇到同一个问题新开会话之后Claude 完全不记得上一轮说过什么项目背景又要重新描述一遍。claude-mem 解决的就是这个痛点。它是一个给 Claude Code 提供长期记忆的 MCP 服务把会话中的关键信息持久化到本地记忆库并在后续对话中自动检索、自动注入相关背景。这个项目最值得关注的点有三个第一它不需要 GPU普通开发机就能跑和显存、CUDA 基本无关第二它通过 MCP 协议与 Claude Code 集成不需要改 Claude Code 本身的代码第三它支持按项目隔离记忆项目之间不会串味。本文会带大家完成从安装、初始化、注册 MCP 服务、写入记忆、新会话检索到记忆内容查看和问题排查的完整流程。如果你正在用 Claude Code 处理长周期任务或者想让团队新成员快速恢复项目上下文这篇可以直接收藏。1. claude-mem 核心能力速览能力项说明项目类型Claude Code 长期记忆增强工具 / MCP 服务开源来源GitHub 仓库 thedotmack / claude-mem核心功能会话记忆持久化、项目级记忆、全局记忆、历史语义检索运行环境需要 Node.js 环境通过 npm / npx 启动硬件门槛无 GPU 要求普通开发机即可运行支持平台macOS / Linux / Windows以官方 README 标注为准启动方式CLI 初始化 Claude Code MCP 注册对外接口以 MCP 工具形式暴露给 Claude Code批量任务支持历史记录批量导入导出具体命令看项目文档适合场景多会话开发、项目背景记忆、代码仓库上下文恢复从核心定位看它不处理图像、不跑大模型推理也不是一个生成工具它是一个“上下文管理中间件”。它连接 Claude Code 和本地记忆存储属于工程向的效率工具所以显存、CUDA、显卡这些词在它身上都不适用。更值得关注的是 Node 环境、MCP 协议配置、记忆写入与检索的稳定性。2. 适用场景与使用边界2.1 适合谁claude-mem 适合下面几类人每天用 Claude Code 处理多个分支任务希望每个任务都有连续上下文的开发者。在一个大型代码仓库里做跨模块改造不想每次重述项目结构和技术栈的工程师。团队协作场景下新成员上手项目时希望得到历史决策记录的团队。写技术文档、批量整理代码注释需要反复引用项目背景的内容生产者。本质上只要你的工作流是“Claude Code 多个会话”claude-mem 就值得试。2.2 能解决什么问题最直接的价值是省掉重复的背景说明。以前每次开新会话都要把“项目用的什么框架、数据库是什么、启动命令是什么、当前进度到哪一步”重新发一遍。有了 claude-mem这些信息会在会话开始时被自动检索出来Claude 会直接基于记忆回答。第二个价值是项目交接。开发者离开项目几周再回来或者换同事接手既往会话中的关键决定也不会丢检索一下就能恢复上下文。第三个价值是减少多轮任务中的低级错误。很多长任务做到后面Claude 会把前面的细节忘掉版本号、路径、命名规则都可能搞混。记忆注入后这类错误会明显减少。2.3 不适合什么场景不适合把它当作通用数据库用。它是为“对话上下文”设计的不是为结构化业务数据设计的。如果要把订单、用户表、配置项管起来直接用数据库更合适。也不适合用来保存超大文本。记忆库体积膨胀之后检索速度会下降成本也会增加。保持记忆内容短、结构化才能发挥它的优势。另外如果你完全不用 Claude Code也不打算接入 MCP 客户端那这个项目对你没有直接用处。它的能力是绑定在 Claude Code 会话里的不是独立的知识库产品。2.4 安全与合规边界这一点必须强调claude-mem 会把对话关键信息写入本机文件凡是写进记忆库的内容都会被后续会话重新读取。所以有几个红线不要把 Access Key、Secret、数据库密码、云厂商凭证写进记忆。不要在记忆里写入未公开的业务数据、用户隐私数据。处理客户项目时确认客户是否允许使用带持久记忆的 AI 辅助工具。团队共用开发机时注意记忆库对同一机器的其他用户是否可读。记忆是双刃剑省事的前提是内容干净。敏感信息一旦入库就会被反复使用扩散面会比普通日志更大。使用前最好先约定哪些内容可记忆哪些内容永远不进记忆库。3. 环境准备与前置条件3.1 运行环境清单检查项要求操作系统macOS / Linux / Windows以项目 README 为准Node.js建议 18 或更高版本npmNode.js 自带注意镜像源稳定性Claude Code已安装并完成命令行登录MCP 能力当前 Claude Code 版本支持 MCP 工具注册磁盘空间记忆库为文本型数据早期占用很小安装前先确认环境node -v npm -v claude --version如果node或npm不存在先去安装 Node.js。Windows 环境建议用官方安装包或 wingetmacOS 可以用 HomebrewLinux 可以用 nvm 管理版本避免系统级权限问题。3.2 了解 MCP 的启动方式claude-mem 是以 MCP Server 形式运行的。MCP 的全称是 Model Context Protocol作用是让 AI 客户端能调用外部工具。Claude Code 通过 MCP 启动 claude-mem然后 claude-mem 把记忆工具暴露给 Claude 调用。这个架构意味着不需要单独开一个常驻 Web 服务窗口。claude-mem 会在 Claude Code 需要的时候自动启动。工具列表由 MCP 协议自动同步不需要手动告诉 Claude“你有记忆工具”。所以环境准备里最重要的是 Node.js 可用以及 Claude Code 能正常启动 MCP 服务。3.3 注意事项npm 镜像源会直接影响首次安装速度。如果npx拉包很慢可以考虑使用国内 npm 镜像或者直接用全局安装方式把包装到本地。后续章节会分别给出命令。另外Windows 环境建议使用 PowerShell 或 Windows Terminal 执行命令避免 cmd 的编码和路径问题。如果安装后 CLI 命令找不到请检查 npm 全局 bin 目录是否加入了 PATH。4. 安装部署与启动方式4.1 安装 claude-mem CLI最直接的安装方式是通过 npm 全局安装npm install -g thedotmack/claude-mem安装完成后验证版本claude-mem --version如果安装过程中报权限错误常见原因是 npm 全局目录写入权限不足。Linux 和 macOS 可以使用 nvm 重新安装 Node.jsWindows 建议用官方安装包修复权限不建议直接用 root 绕过权限检查。安装完成后还需要确认 CLI 能正常读取配置目录。运行一次帮助命令即可claude-mem --help如果能看到子命令列表说明 CLI 已经可用。4.2 初始化记忆库初始化这一步会创建本地记忆库结构同时生成默认配置。在项目目录执行claude-mem init从实际部署经验看初始化过程通常会做三件事在本地创建记忆存储目录。生成 claude-mem 的配置文件。输出下一步集成到 Claude Code 的提示信息。初始化成功后不要急着动手写记忆先检查一下是否生成了配置文件。如果没有生成说明当前目录可能存在权限问题或者 CLI 版本与预期不一致。此时先解决版本和目录权限问题再进入下一步。4.3 注册 MCP 服务到 Claude CodeClaude Code 注册 MCP 服务有两种方式命令行注册和配置文件注册。命令行方式直接执行claude mcp add claude-mem -- npx -y thedotmack/claude-mem这条命令的意思是把 claude-mem 注册为 Claude Code 的一个 MCP 服务启动命令是npx -y thedotmack/claude-mem。配置文件方式在项目根目录创建.mcp.json{ mcpServers: { claude-mem: { command: npx, args: [-y, thedotmack/claude-mem] } } }两种方式效果相同。区别在于命令行方式会写入 Claude Code 的用户级配置而.mcp.json会随项目目录提交适合团队协作统一配置。如果你已经把 claude-mem 全局安装也可以把 command 换成claude-mem减少 npx 启动时的解析时间{ mcpServers: { claude-mem: { command: claude-mem, args: [] } } }注意这里需要替换成你本机实际的全局命令路径Windows 下可能是claude-mem.cmd。不确定时先用 npx 方式保证能跑通。4.4 确认服务状态注册完成后列出当前 MCP 服务claude mcp list如果 claude-mem 显示为已连接说明 MCP 注册成功。这时候打开一个 Claude Code 会话输入/mcp应该也能看到 claude-mem 及其工具列表。如果状态显示 disconnected不要急着改配置。先检查 npm 包是否安装成功再手动执行一次启动命令npx -y thedotmack/claude-mem能启动说明包没问题不能启动说明 Node 环境或包安装有问题按报错信息逐步排查。5. 功能测试与效果验证5.1 第一轮会话写入记忆找一个有代表性的项目目录比如一个真实的代码仓库打开 Claude Code。然后告诉 Claude 需要记录的项目背景。示例指令请记住本项目的前端使用 React 18后端使用 FastAPI数据库使用 PostgreSQL。常用启动命令是 make dev。接下来正常进行工作对话让 Claude 处理几个问题。比如让它解释当前目录的模块结构或者让它按记忆中的技术栈给出启动建议。这个过程会触发记忆写入。判断写入成功的标准是Claude 在后续回答中能主动使用这些背景信息并且不再向你重复确认技术栈。5.2 新会话检索记忆这是整个工具最核心的验证点。退出当前会话重新打开 Claude Code保持同一个项目目录然后直接提问这个项目的技术栈和常用启动命令是什么判断成功的标准Claude 能直接回答 React 18、FastAPI、PostgreSQL、make dev。回答时不需要你说“我之前告诉过你”。如果项目里有多个模块Claude 能结合记忆和当前目录给出更完整的上下文。如果命中说明记忆写入、持久化和检索链路都正常。如果没命中优先检查当前工作目录是否和写入记忆时一致因为项目级记忆往往绑定项目路径。5.3 用 CLI 检查记忆内容除了让 Claude 回答还可以通过 CLI 直接查看记忆库内容。具体子命令以claude-mem --help为准通常包含查看、搜索、删除、重置这几类操作。先看命令帮助claude-mem --help再尝试查看当前项目记忆claude-mem view或者按关键词搜索claude-mem search FastAPI如果搜索能返回 React、FastAPI 这类关键词记录说明记忆库文件已经被正确写入。这一步的价值在于不依赖 Claude 的对话表现可以直接确认底层数据是否存在方便区分“记忆没写入”和“检索不到”两个问题。5.4 失败时的判断方向测试时如果出现问题先按现象分类现象优先排查方向Claude 说没有 claude-mem 工具MCP 注册失败检查claude mcp listClaude 有工具但查不到记忆当前项目目录不对或记忆作用域不匹配CLI 能查到记忆但 Claude 查不到记忆检索工具调用失败看 MCP 日志写入很慢或卡住记忆库文件过大或 npx 拉包超时先用命令行把现象分开数据层是否正常工具层是否正常。这两条线分开排查比反复问 Claude 要快得多。6. 接口 API 与记忆操作6.1 MCP 工具接口claude-mem 不对外暴露 HTTP 端口它暴露的是 MCP 工具。Claude Code 在需要记忆时会自动调用这些工具不需要手工传参。对使用者来说工具调用过程是透明的。你只需要告诉 Claude“记住什么”“查什么背景”Claude 自己决定调用哪个工具。如果你要在自己的程序里集成 claude-mem可以通过官方的 MCP SDK 连接同一个服务。以 TypeScript 为例标准连接代码模板如下import { Client } from modelcontextprotocol/sdk/client/index.js; import { StdioClientTransport } from modelcontextprotocol/sdk/client/stdio.js; const transport new StdioClientTransport({ command: npx, args: [-y, thedotmack/claude-mem] }); const client new Client({ name: my-client, version: 0.1.0 }); await client.connect(transport);连接之后就可以列出 claude-mem 暴露的工具const tools await client.listTools(); console.log(tools);这个模板适用于任何 MCP 服务不局限于 claude-mem。实际工具名和参数要以服务端返回为准。6.2 批量导入历史记忆如果你已经有一批历史对话记录希望一次性导入先确认项目 README 是否提供 import 命令。如果有一般流程是先整理成约定格式再执行批量导入。这里给一个通用模板需要按实际项目命令替换claude-mem import ./history/*.md --project demo批量导入前要注意三件事文本内容要清洗不要把日志、临时输出一起导进去。每条记忆尽量短小保证后续检索命中率。导入前做好备份避免错误数据污染既有记忆库。6.3 防止误用的简单策略接口能力越强越要控制内容边界。建议在记忆中显式加上排除规则比如告诉 Claude 不要把包含密钥、token、密码的内容写入记忆不要记忆任何包含密钥、密码、access token 的内容只记录技术决策和项目结构。这样的指令会显著降低敏感信息入库的概率。不要以为工具会自动过滤过滤规则需要你自己设定。7. 资源占用与性能观察7.1 怎么观察状态claude-mem 是一个 Node 进程不常驻后台而是由 Claude Code 按需拉起。想看它是否在运行可以开一个 Claude Code 会话然后在另一个终端执行ps aux | grep -i claude-memmacOS 和 Linux 下能看到 Node 进程即为正常。Windows 下可以用任务管理器查看 node 进程。7.2 影响性能的因素claude-mem 的负载不在显卡上而在三个方面第一npm 启动速度。通过npx -y启动时每次都要先解析包如果本地没有缓存甚至要现场拉包。这个阶段最容易感觉到卡顿。解决方式是改成全局安装然后在 MCP 配置里把 command 指向全局命令。第二记忆库体积。记忆条目少时写入和检索几乎是瞬时完成的。记忆库膨胀后语义检索和全文检索的耗时都会上升。建议定期清理过期记忆或者按项目维度分批管理。第三记忆条目粒度。如果你把一整段代码或长文档存成一条记忆后续检索命中时这些大块内容会占用大量上下文空间间接影响 Claude 的回答质量。记忆粒度越细检索效率越高。7.3 降低资源占用的实操建议使用全局 npm 安装减少 npx 解析开销。同一时间只保留必要的 MCP 服务不相关的服务不要挂在 Claude Code 配置里。定期执行清理命令删除过期项目记忆。写记忆时让 Claude 使用简洁摘要不要原文复制大段日志。如果你更在意开发机负载建议把 claude-mem 和主项目代码分开放在不同目录减少无关文件被扫描的概率。但这个并不绝对具体依赖版本和项目文档为准。8. 常见问题与排查方法问题现象可能原因排查方式解决方案claude mcp list显示 disconnected包未安装或命令路径错误手动运行npx -y thedotmack/claude-mem重新安装 npm 包修复 PATHClaude 说没有 claude-mem 工具MCP 注册未生效输入/mcp查看工具列表重启 Claude Code重新执行claude mcp add新会话查不到记忆当前项目目录与写入时不一致用 CLI 查看记忆库路径回到原项目目录或调整记忆作用域CLI 有记录但 Claude 查不到检索工具调用失败查看 MCP 日志和 stderr 输出手动运行启动命令确认无报错npx 启动非常慢首次拉包或网络源不稳定观察 npx 下载过程改为全局安装减少解析开销记忆内容混乱导入格式不规范查看导入日志清洗文本后重新导入记忆库路径不清楚配置未初始化运行claude-mem --help查看路径重新执行claude-mem init遇到问题时第一步永远是看命令行输出不要反复在对话里试探。CLI 能跑通说明基础安装没问题MCP 能连上说明配置没问题只有 CLI 和 MCP 都正常才能再去判断记忆内容本身的质量问题。9. 最佳实践与使用建议9.1 按项目隔离记忆项目级记忆是最推荐的使用方式。每个项目目录绑定自己的记忆库不互相干扰。全局记忆只放通用知识比如你常用的代码规范、命名习惯、工具链偏好。这样既能减少检索噪音也能避免项目 A 的信息污染项目 B 的上下文。9.2 记忆指令要显式不要指望 Claude 把所有对话都自动记住。更好的做法是在关键节点显式要求记录例如请记住当前的决策日志系统统一使用 JSON 格式错误码范围从 40000 开始。这样做的好处是记忆内容可控不会把无关对话也写进库。项目进行到阶段性的节点可以定期整理一份“当前状态摘要”让 Claude 记录相当于给项目拍快照。9.3 敏感信息不进库在团队和商业项目中使用时先在项目说明里约定密钥、凭证、个人隐私、未公开数据一律不进记忆库。如果记忆库里已经混入了敏感信息尽快删除对应记录并检查是否有人通过会话读取过这些内容。9.4 定期维护记忆库记忆库维护和工作区清理一样重要。项目结束后可以清理该项目的历史记忆长期项目则按月检查一次。建议维护节奏每周检查一次记忆质量删除无用条目。每月做一次批量清理归档过期项目。版本升级前备份记忆库目录。9.5 接口访问控制如果多人共用一台开发机或者通过共享配置接入 MCP 服务要限制 claude-mem 记忆库的文件系统权限避免未授权用户读取历史记忆。开发机上不要直接设置 777 权限按用户和用户组隔离更稳妥。10. 总结与下一步claude-mem 最值得尝试的是它把“会话记忆”从一个模糊需求变成了可落地的本地工具。你不用换掉 Claude Code不用注册额外服务只要装一个 Node 包、注册一个 MCP 服务就可以在下一个会话里看到记忆效果。第一步建议先跑最小验证在单个项目目录写入三条技术栈记忆然后开新会话直接检索。这个流程十分钟内能完成比读任何文档都快。最容易踩的坑是 MCP 注册成功但项目目录不对导致记忆写入了另一个作用域。遇到查不到记忆的情况先确认当前工作目录不要急着重装软件。后续可以继续扩展的方向包括把 claude-mem 接入自己团队的授权流程与敏感信息过滤规则把它和多项目工作流结合形成固定的项目交接模板也可以在个人使用过程中总结一套适合自己的记忆指令风格。建议收藏备用下次遇到“Claude 又失忆”的时候这个工具能直接派上用场。 
长河君 · 2026/10/9 10:33:41 · 阅读 1.2k claude-mem：为 Claude Code 提供长期记忆的 MCP 服务，告别会话失忆
这次我们来看 thedotmack 开源的 claude-mem。如果你经常用 Claude Code 做代码维护、多轮任务改造或者接续式开发大概会遇到同一个问题新开会话之后Claude 完全不记得上一轮说过什么项目背景又要重新描述一遍。claude-mem 解决的就是这个痛点。它是一个给 Claude Code 提供长期记忆的 MCP 服务把会话中的关键信息持久化到本地记忆库并在后续对话中自动检索、自动注入相关背景。这个项目最值得关注的点有三个第一它不需要 GPU普通开发机就能跑和显存、CUDA 基本无关第二它通过 MCP 协议与 Claude Code 集成不需要改 Claude Code 本身的代码第三它支持按项目隔离记忆项目之间不会串味。本文会带大家完成从安装、初始化、注册 MCP 服务、写入记忆、新会话检索到记忆内容查看和问题排查的完整流程。如果你正在用 Claude Code 处理长周期任务或者想让团队新成员快速恢复项目上下文这篇可以直接收藏。1. claude-mem 核心能力速览能力项说明项目类型Claude Code 长期记忆增强工具 / MCP 服务开源来源GitHub 仓库 thedotmack / claude-mem核心功能会话记忆持久化、项目级记忆、全局记忆、历史语义检索运行环境需要 Node.js 环境通过 npm / npx 启动硬件门槛无 GPU 要求普通开发机即可运行支持平台macOS / Linux / Windows以官方 README 标注为准启动方式CLI 初始化 Claude Code MCP 注册对外接口以 MCP 工具形式暴露给 Claude Code批量任务支持历史记录批量导入导出具体命令看项目文档适合场景多会话开发、项目背景记忆、代码仓库上下文恢复从核心定位看它不处理图像、不跑大模型推理也不是一个生成工具它是一个“上下文管理中间件”。它连接 Claude Code 和本地记忆存储属于工程向的效率工具所以显存、CUDA、显卡这些词在它身上都不适用。更值得关注的是 Node 环境、MCP 协议配置、记忆写入与检索的稳定性。2. 适用场景与使用边界2.1 适合谁claude-mem 适合下面几类人每天用 Claude Code 处理多个分支任务希望每个任务都有连续上下文的开发者。在一个大型代码仓库里做跨模块改造不想每次重述项目结构和技术栈的工程师。团队协作场景下新成员上手项目时希望得到历史决策记录的团队。写技术文档、批量整理代码注释需要反复引用项目背景的内容生产者。本质上只要你的工作流是“Claude Code 多个会话”claude-mem 就值得试。2.2 能解决什么问题最直接的价值是省掉重复的背景说明。以前每次开新会话都要把“项目用的什么框架、数据库是什么、启动命令是什么、当前进度到哪一步”重新发一遍。有了 claude-mem这些信息会在会话开始时被自动检索出来Claude 会直接基于记忆回答。第二个价值是项目交接。开发者离开项目几周再回来或者换同事接手既往会话中的关键决定也不会丢检索一下就能恢复上下文。第三个价值是减少多轮任务中的低级错误。很多长任务做到后面Claude 会把前面的细节忘掉版本号、路径、命名规则都可能搞混。记忆注入后这类错误会明显减少。2.3 不适合什么场景不适合把它当作通用数据库用。它是为“对话上下文”设计的不是为结构化业务数据设计的。如果要把订单、用户表、配置项管起来直接用数据库更合适。也不适合用来保存超大文本。记忆库体积膨胀之后检索速度会下降成本也会增加。保持记忆内容短、结构化才能发挥它的优势。另外如果你完全不用 Claude Code也不打算接入 MCP 客户端那这个项目对你没有直接用处。它的能力是绑定在 Claude Code 会话里的不是独立的知识库产品。2.4 安全与合规边界这一点必须强调claude-mem 会把对话关键信息写入本机文件凡是写进记忆库的内容都会被后续会话重新读取。所以有几个红线不要把 Access Key、Secret、数据库密码、云厂商凭证写进记忆。不要在记忆里写入未公开的业务数据、用户隐私数据。处理客户项目时确认客户是否允许使用带持久记忆的 AI 辅助工具。团队共用开发机时注意记忆库对同一机器的其他用户是否可读。记忆是双刃剑省事的前提是内容干净。敏感信息一旦入库就会被反复使用扩散面会比普通日志更大。使用前最好先约定哪些内容可记忆哪些内容永远不进记忆库。3. 环境准备与前置条件3.1 运行环境清单检查项要求操作系统macOS / Linux / Windows以项目 README 为准Node.js建议 18 或更高版本npmNode.js 自带注意镜像源稳定性Claude Code已安装并完成命令行登录MCP 能力当前 Claude Code 版本支持 MCP 工具注册磁盘空间记忆库为文本型数据早期占用很小安装前先确认环境node -v npm -v claude --version如果node或npm不存在先去安装 Node.js。Windows 环境建议用官方安装包或 wingetmacOS 可以用 HomebrewLinux 可以用 nvm 管理版本避免系统级权限问题。3.2 了解 MCP 的启动方式claude-mem 是以 MCP Server 形式运行的。MCP 的全称是 Model Context Protocol作用是让 AI 客户端能调用外部工具。Claude Code 通过 MCP 启动 claude-mem然后 claude-mem 把记忆工具暴露给 Claude 调用。这个架构意味着不需要单独开一个常驻 Web 服务窗口。claude-mem 会在 Claude Code 需要的时候自动启动。工具列表由 MCP 协议自动同步不需要手动告诉 Claude“你有记忆工具”。所以环境准备里最重要的是 Node.js 可用以及 Claude Code 能正常启动 MCP 服务。3.3 注意事项npm 镜像源会直接影响首次安装速度。如果npx拉包很慢可以考虑使用国内 npm 镜像或者直接用全局安装方式把包装到本地。后续章节会分别给出命令。另外Windows 环境建议使用 PowerShell 或 Windows Terminal 执行命令避免 cmd 的编码和路径问题。如果安装后 CLI 命令找不到请检查 npm 全局 bin 目录是否加入了 PATH。4. 安装部署与启动方式4.1 安装 claude-mem CLI最直接的安装方式是通过 npm 全局安装npm install -g thedotmack/claude-mem安装完成后验证版本claude-mem --version如果安装过程中报权限错误常见原因是 npm 全局目录写入权限不足。Linux 和 macOS 可以使用 nvm 重新安装 Node.jsWindows 建议用官方安装包修复权限不建议直接用 root 绕过权限检查。安装完成后还需要确认 CLI 能正常读取配置目录。运行一次帮助命令即可claude-mem --help如果能看到子命令列表说明 CLI 已经可用。4.2 初始化记忆库初始化这一步会创建本地记忆库结构同时生成默认配置。在项目目录执行claude-mem init从实际部署经验看初始化过程通常会做三件事在本地创建记忆存储目录。生成 claude-mem 的配置文件。输出下一步集成到 Claude Code 的提示信息。初始化成功后不要急着动手写记忆先检查一下是否生成了配置文件。如果没有生成说明当前目录可能存在权限问题或者 CLI 版本与预期不一致。此时先解决版本和目录权限问题再进入下一步。4.3 注册 MCP 服务到 Claude CodeClaude Code 注册 MCP 服务有两种方式命令行注册和配置文件注册。命令行方式直接执行claude mcp add claude-mem -- npx -y thedotmack/claude-mem这条命令的意思是把 claude-mem 注册为 Claude Code 的一个 MCP 服务启动命令是npx -y thedotmack/claude-mem。配置文件方式在项目根目录创建.mcp.json{ mcpServers: { claude-mem: { command: npx, args: [-y, thedotmack/claude-mem] } } }两种方式效果相同。区别在于命令行方式会写入 Claude Code 的用户级配置而.mcp.json会随项目目录提交适合团队协作统一配置。如果你已经把 claude-mem 全局安装也可以把 command 换成claude-mem减少 npx 启动时的解析时间{ mcpServers: { claude-mem: { command: claude-mem, args: [] } } }注意这里需要替换成你本机实际的全局命令路径Windows 下可能是claude-mem.cmd。不确定时先用 npx 方式保证能跑通。4.4 确认服务状态注册完成后列出当前 MCP 服务claude mcp list如果 claude-mem 显示为已连接说明 MCP 注册成功。这时候打开一个 Claude Code 会话输入/mcp应该也能看到 claude-mem 及其工具列表。如果状态显示 disconnected不要急着改配置。先检查 npm 包是否安装成功再手动执行一次启动命令npx -y thedotmack/claude-mem能启动说明包没问题不能启动说明 Node 环境或包安装有问题按报错信息逐步排查。5. 功能测试与效果验证5.1 第一轮会话写入记忆找一个有代表性的项目目录比如一个真实的代码仓库打开 Claude Code。然后告诉 Claude 需要记录的项目背景。示例指令请记住本项目的前端使用 React 18后端使用 FastAPI数据库使用 PostgreSQL。常用启动命令是 make dev。接下来正常进行工作对话让 Claude 处理几个问题。比如让它解释当前目录的模块结构或者让它按记忆中的技术栈给出启动建议。这个过程会触发记忆写入。判断写入成功的标准是Claude 在后续回答中能主动使用这些背景信息并且不再向你重复确认技术栈。5.2 新会话检索记忆这是整个工具最核心的验证点。退出当前会话重新打开 Claude Code保持同一个项目目录然后直接提问这个项目的技术栈和常用启动命令是什么判断成功的标准Claude 能直接回答 React 18、FastAPI、PostgreSQL、make dev。回答时不需要你说“我之前告诉过你”。如果项目里有多个模块Claude 能结合记忆和当前目录给出更完整的上下文。如果命中说明记忆写入、持久化和检索链路都正常。如果没命中优先检查当前工作目录是否和写入记忆时一致因为项目级记忆往往绑定项目路径。5.3 用 CLI 检查记忆内容除了让 Claude 回答还可以通过 CLI 直接查看记忆库内容。具体子命令以claude-mem --help为准通常包含查看、搜索、删除、重置这几类操作。先看命令帮助claude-mem --help再尝试查看当前项目记忆claude-mem view或者按关键词搜索claude-mem search FastAPI如果搜索能返回 React、FastAPI 这类关键词记录说明记忆库文件已经被正确写入。这一步的价值在于不依赖 Claude 的对话表现可以直接确认底层数据是否存在方便区分“记忆没写入”和“检索不到”两个问题。5.4 失败时的判断方向测试时如果出现问题先按现象分类现象优先排查方向Claude 说没有 claude-mem 工具MCP 注册失败检查claude mcp listClaude 有工具但查不到记忆当前项目目录不对或记忆作用域不匹配CLI 能查到记忆但 Claude 查不到记忆检索工具调用失败看 MCP 日志写入很慢或卡住记忆库文件过大或 npx 拉包超时先用命令行把现象分开数据层是否正常工具层是否正常。这两条线分开排查比反复问 Claude 要快得多。6. 接口 API 与记忆操作6.1 MCP 工具接口claude-mem 不对外暴露 HTTP 端口它暴露的是 MCP 工具。Claude Code 在需要记忆时会自动调用这些工具不需要手工传参。对使用者来说工具调用过程是透明的。你只需要告诉 Claude“记住什么”“查什么背景”Claude 自己决定调用哪个工具。如果你要在自己的程序里集成 claude-mem可以通过官方的 MCP SDK 连接同一个服务。以 TypeScript 为例标准连接代码模板如下import { Client } from modelcontextprotocol/sdk/client/index.js; import { StdioClientTransport } from modelcontextprotocol/sdk/client/stdio.js; const transport new StdioClientTransport({ command: npx, args: [-y, thedotmack/claude-mem] }); const client new Client({ name: my-client, version: 0.1.0 }); await client.connect(transport);连接之后就可以列出 claude-mem 暴露的工具const tools await client.listTools(); console.log(tools);这个模板适用于任何 MCP 服务不局限于 claude-mem。实际工具名和参数要以服务端返回为准。6.2 批量导入历史记忆如果你已经有一批历史对话记录希望一次性导入先确认项目 README 是否提供 import 命令。如果有一般流程是先整理成约定格式再执行批量导入。这里给一个通用模板需要按实际项目命令替换claude-mem import ./history/*.md --project demo批量导入前要注意三件事文本内容要清洗不要把日志、临时输出一起导进去。每条记忆尽量短小保证后续检索命中率。导入前做好备份避免错误数据污染既有记忆库。6.3 防止误用的简单策略接口能力越强越要控制内容边界。建议在记忆中显式加上排除规则比如告诉 Claude 不要把包含密钥、token、密码的内容写入记忆不要记忆任何包含密钥、密码、access token 的内容只记录技术决策和项目结构。这样的指令会显著降低敏感信息入库的概率。不要以为工具会自动过滤过滤规则需要你自己设定。7. 资源占用与性能观察7.1 怎么观察状态claude-mem 是一个 Node 进程不常驻后台而是由 Claude Code 按需拉起。想看它是否在运行可以开一个 Claude Code 会话然后在另一个终端执行ps aux | grep -i claude-memmacOS 和 Linux 下能看到 Node 进程即为正常。Windows 下可以用任务管理器查看 node 进程。7.2 影响性能的因素claude-mem 的负载不在显卡上而在三个方面第一npm 启动速度。通过npx -y启动时每次都要先解析包如果本地没有缓存甚至要现场拉包。这个阶段最容易感觉到卡顿。解决方式是改成全局安装然后在 MCP 配置里把 command 指向全局命令。第二记忆库体积。记忆条目少时写入和检索几乎是瞬时完成的。记忆库膨胀后语义检索和全文检索的耗时都会上升。建议定期清理过期记忆或者按项目维度分批管理。第三记忆条目粒度。如果你把一整段代码或长文档存成一条记忆后续检索命中时这些大块内容会占用大量上下文空间间接影响 Claude 的回答质量。记忆粒度越细检索效率越高。7.3 降低资源占用的实操建议使用全局 npm 安装减少 npx 解析开销。同一时间只保留必要的 MCP 服务不相关的服务不要挂在 Claude Code 配置里。定期执行清理命令删除过期项目记忆。写记忆时让 Claude 使用简洁摘要不要原文复制大段日志。如果你更在意开发机负载建议把 claude-mem 和主项目代码分开放在不同目录减少无关文件被扫描的概率。但这个并不绝对具体依赖版本和项目文档为准。8. 常见问题与排查方法问题现象可能原因排查方式解决方案claude mcp list显示 disconnected包未安装或命令路径错误手动运行npx -y thedotmack/claude-mem重新安装 npm 包修复 PATHClaude 说没有 claude-mem 工具MCP 注册未生效输入/mcp查看工具列表重启 Claude Code重新执行claude mcp add新会话查不到记忆当前项目目录与写入时不一致用 CLI 查看记忆库路径回到原项目目录或调整记忆作用域CLI 有记录但 Claude 查不到检索工具调用失败查看 MCP 日志和 stderr 输出手动运行启动命令确认无报错npx 启动非常慢首次拉包或网络源不稳定观察 npx 下载过程改为全局安装减少解析开销记忆内容混乱导入格式不规范查看导入日志清洗文本后重新导入记忆库路径不清楚配置未初始化运行claude-mem --help查看路径重新执行claude-mem init遇到问题时第一步永远是看命令行输出不要反复在对话里试探。CLI 能跑通说明基础安装没问题MCP 能连上说明配置没问题只有 CLI 和 MCP 都正常才能再去判断记忆内容本身的质量问题。9. 最佳实践与使用建议9.1 按项目隔离记忆项目级记忆是最推荐的使用方式。每个项目目录绑定自己的记忆库不互相干扰。全局记忆只放通用知识比如你常用的代码规范、命名习惯、工具链偏好。这样既能减少检索噪音也能避免项目 A 的信息污染项目 B 的上下文。9.2 记忆指令要显式不要指望 Claude 把所有对话都自动记住。更好的做法是在关键节点显式要求记录例如请记住当前的决策日志系统统一使用 JSON 格式错误码范围从 40000 开始。这样做的好处是记忆内容可控不会把无关对话也写进库。项目进行到阶段性的节点可以定期整理一份“当前状态摘要”让 Claude 记录相当于给项目拍快照。9.3 敏感信息不进库在团队和商业项目中使用时先在项目说明里约定密钥、凭证、个人隐私、未公开数据一律不进记忆库。如果记忆库里已经混入了敏感信息尽快删除对应记录并检查是否有人通过会话读取过这些内容。9.4 定期维护记忆库记忆库维护和工作区清理一样重要。项目结束后可以清理该项目的历史记忆长期项目则按月检查一次。建议维护节奏每周检查一次记忆质量删除无用条目。每月做一次批量清理归档过期项目。版本升级前备份记忆库目录。9.5 接口访问控制如果多人共用一台开发机或者通过共享配置接入 MCP 服务要限制 claude-mem 记忆库的文件系统权限避免未授权用户读取历史记忆。开发机上不要直接设置 777 权限按用户和用户组隔离更稳妥。10. 总结与下一步claude-mem 最值得尝试的是它把“会话记忆”从一个模糊需求变成了可落地的本地工具。你不用换掉 Claude Code不用注册额外服务只要装一个 Node 包、注册一个 MCP 服务就可以在下一个会话里看到记忆效果。第一步建议先跑最小验证在单个项目目录写入三条技术栈记忆然后开新会话直接检索。这个流程十分钟内能完成比读任何文档都快。最容易踩的坑是 MCP 注册成功但项目目录不对导致记忆写入了另一个作用域。遇到查不到记忆的情况先确认当前工作目录不要急着重装软件。后续可以继续扩展的方向包括把 claude-mem 接入自己团队的授权流程与敏感信息过滤规则把它和多项目工作流结合形成固定的项目交接模板也可以在个人使用过程中总结一套适合自己的记忆指令风格。建议收藏备用下次遇到“Claude 又失忆”的时候这个工具能直接派上用场。