★ FEATURED ARTICLE 这次我们来看一个比较特别的开发者工具thedotmack / claude-mem。先说结论这是一个专门给 Claude Code 用的长期记忆插件核心思路是让 AI 编程助手在多次会话之间“记得住”项目上下文不靠手工喂资料而是自动沉淀对话历史和关键信息。如果你已经被“每次开新会话 AI 就失忆”这个问题折磨过这个项目值得直接收藏。它最值得关注的几点第一基于 SQLite 做本地持久化不需要额外数据库服务第二以 MCP 服务器方式接入 Claude Code配置一次就能用第三对话内容按项目隔离不会把 A 项目的上下文串到 B 项目第四支持搜索历史记忆、查询时间范围、自动构建项目记忆库后续还可以把记忆导出或接入更多工具链。本文会带你完成理解 claude-mem 的核心结构、下载和安装 MCP 服务、配置 Claude Code 接入记忆插件、测试记忆写入与召回、排查常见故障、以及批量处理和历史记录清理的实践。适合正在用 Claude Code 做实际项目、且对“会话连续性”有硬需求的开发者。1. claude-mem 核心能力速览先把核心规格列出来方便你快速判断是否值得折腾。能力项说明项目类型Claude Code 长期记忆插件 / MCP 记忆服务器核心机制通过 MCP 协议接入 Claude Code使用 SQLite 本地存储对话记忆主要功能自动记忆对话、按项目隔离记忆、跨会话召回、历史搜索、时间范围查询数据存储SQLite 数据库文件存放在本机用户目录依赖环境Node.js、Claude Code CLI、MCP 客户端支持启动方式MCP 服务注册后由 Claude Code 自动拉起是否支持 API支持MCP 工具调用即可读取/写入记忆是否支持批量任务记忆可以批量写入、批量导出、批量清理显存/GPU 要求无纯 CPU 与本地文件操作适合场景Claude Code 长周期项目开发、跨会话知识沉淀、自动维护项目文档这里先说明一个原则下面所有命令和配置都属于“通用接入路径”具体路径、版本号、实际表现以你本机的 Claude Code 版本和 claude-mem 发布版本为准。不要照抄路径后直接认为报错就是项目不行先看日志。为什么这个工具值得关注因为 Claude Code 本身是会话式编程工具每次新会话默认不带历史记忆。你在项目里解决过的问题、约定过的规范、排查过的坑一旦会话关闭就丢了。claude-mem 的定位就是把“会话过程中产生的有价值信息”落盘后续会话直接查。它的工作方式也不复杂当 Claude Code 在会话中调用记忆工具时claude-mem 会把对话摘要、关键决策、代码约定等内容写入 SQLite下次新会话通过 MCP 工具搜索这些记录AI 就能“想起来”。2. 适用场景与使用边界2.1 适合谁用长时间维护同一个代码仓库希望 AI 记住项目背景和技术债。经常在多个项目之间切换需要每个项目独立记忆不被互相污染。团队使用 Claude Code 协作希望沉淀公共技术决策和接口约定。希望减少重复描述项目背景的成本让新会话快速进入工作状态。想把 AI 会话中的要点转成可检索的本地知识库。2.2 能解决什么问题跨会话上下文丢失。每次开新会话都要重新解释项目结构、技术栈、代码风格。历史排查结论无法复用。项目级知识散落在聊天记录里无法搜索和整理。2.3 不适合什么场景需要云端同步和团队共享记忆的场景。claude-mem 默认是本地 SQLite没有内置多人同步机制团队场景需要自己处理文件同步或导出。需要保存敏感信息、密钥、内网地址的场景。记忆库是明文 SQLite 文件本机有读权限的人都能看不要写入凭据。需要大规模非结构化语料入库的场景。它不是通用向量数据库定位是会话记忆不是 RAG 全文检索引擎。对数据隐私有严格合规要求的场景。使用前需要确认哪些信息可以进入本地记忆库。2.4 使用边界与合规提醒claude-mem 会把对话内容写入本地文件默认路径通常在用户主目录下。使用前建议先了解数据存储位置定期清理不需要的旧记录。涉及公司代码、客户信息、内部设计文档时先确认是否有权限将内容写入本地记忆库。不要通过记忆库保存密码、Token、API Key 等敏感凭据也不要保存任何不可公开的隐私信息。如果使用第三方 Claude Code 接入服务注意对方是否有读取本机记忆文件的权限尽量限制 MCP 服务的访问范围。3. claude-mem 环境准备与前置条件在开始之前先确认本机环境是否满足基本要求。这里给出一份通用检查清单按顺序过一遍就好。3.1 环境要求检查项要求操作系统macOS / Linux / Windows 均可但 MCP 服务与 Claude Code 的配置路径不同Node.js建议 18 及以上具体以项目 README 要求为准Claude Code已安装并完成登录能正常启动和对话Git用于拉取项目源码或直接使用 npm 安装SQLite无需单独安装依赖内置 sqlite 模块网络首次安装依赖需要访问 npm registry3.2 检查 node 与 npmnode -v npm -v如果没有安装 Node.js先去官网下载 LTS 版本。Windows 用户注意安装时勾选“Add to PATH”。3.3 检查 Claude Code 是否可用claude --version如果提示找不到命令说明 Claude Code 未安装或未加入 PATH。先完成 Claude Code 的安装和配置再继续。3.4 磁盘空间claude-mem 本身很小主要占空间的是 SQLite 记忆文件和依赖目录。可以预留 500MB 以上空间后续记忆增长后也够用。3.5 确认 MCP 配置入口Claude Code 的 MCP 配置方式在不同版本可能有差异常见入口包括项目级.mcp.json、用户级配置文件、claude mcp add命令。配置前先确认你本机支持哪种方式。claude mcp list如果命令可用说明当前 Claude Code 支持通过 CLI 管理 MCP 服务。如果不可用需要手动修改配置文件。4. 安装部署与启动方式4.1 从 npm 安装 claude-mem如果项目提供了 npm 包最简单的方式是直接安装到本机。npm install -g thedotmack/claude-mem安装后再尝试执行命令确认可用claude-mem --version如果项目只提供源码仓库也可以用 Git 拉取后安装依赖git clone https://github.com/thedotmack/claude-mem.git cd claude-mem npm install npm run build这一步执行完成后项目会生成可执行文件或构建产物。不同版本的结构可能不同以实际仓库 README 为准。4.2 注册 MCP 服务到 Claude Codeclaude-mem 通常以 MCP 服务方式运行。标准做法是把启动命令注册到 Claude Code 的 MCP 配置中。方式一使用 CLI 命令注册如果支持claude mcp add claude-mem -- npx thedotmack/claude-mem方式二手动编辑项目级配置.mcp.json在项目根目录创建.mcp.json内容模板如下{ mcpServers: { claude-mem: { command: npx, args: [thedotmack/claude-mem], env: {} } } }注意.mcp.json是项目级配置只有在该项目目录下启动 Claude Code 才会加载。方式三用户级配置部分 Claude Code 版本支持用户级配置文件路径通常在~/.claude/settings.json把上述mcpServers内容合并到该文件即可。4.3 验证 MCP 服务是否被加载重新启动 Claude Code执行claude mcp list如果输出中包含claude-mem且状态为正常说明加载成功。也可以直接对话测试请查看当前可用的 MCP 工具列表如果 Claude 回复中包含 claude-mem 相关的搜索、写入、查询工具说明接入成功。4.4 启动失败时怎么办检查 npx 是否可用npx --version检查包名是否写错npm view thedotmack/claude-mem version检查 Node 版本是否过低。如果在 Windows PowerShell 下无法直接使用 npx可尝试cmd /c npx ...方式。5. 功能测试与效果验证接入之后最关键的就是验证记忆是否真的生效。下面按功能逐项测试。5.1 测试记忆写入首先在一个会话中给 Claude 明确指令让它把某条关键信息写入记忆。示例对话请记住本项目采用 pnpm workspace 管理依赖服务端使用 Fastify 框架数据库使用 PostgreSQL。这是团队约定的技术选型后续涉及新增依赖时都要遵循。预期结果Claude 调用 claude-mem 的写入工具将这条信息保存到当前项目的记忆库中。你可以查看日志确认工具调用是否成功。判断成功标准没有报错信息并提示已保存。如果你能直接查询 SQLite 文件会看到对应记录。5.2 测试记忆召回开启新会话不重复描述项目背景直接提问我们项目的依赖管理工具是什么预期结果Claude 通过 claude-mem 搜索记忆回复 pnpm workspace。如果回答正确说明记忆写入和召回链路均已打通。5.3 测试按项目隔离记忆在不同目录分别启动 Claude Code在项目 A 写入记忆在项目 B 查询。项目 B 不应检索到项目 A 的记录。这是验证记忆隔离最关键的一步。预期结果项目 B 无法召回项目 A 的记忆。如果不能隔离检查是否配置了全局共享的 SQLite 数据库路径而不是按项目区分。5.4 测试历史搜索在会话中要求 Claude 搜索包含某个关键词的历史记录。示例搜索一下之前关于 ESLint 配置的讨论结果预期结果Claude 返回匹配的历史记忆条目。如果搜索无结果可以尝试更换关键词或先确认记忆确实已写入。5.5 测试时间范围查询部分版本支持时间范围过滤。可以输入查看本周保存的项目决策记录预期结果返回符合时间条件的记忆条目。5.6 验证 SQLite 数据落盘找到 claude-mem 的数据库文件位置。默认情况下常见路径是~/.claude-mem/memory.db用 sqlite3 查看表结构sqlite3 ~/.claude-mem/memory.db .tables如果表结构存在且能查询到数据说明落盘成功。sqlite3 ~/.claude-mem/memory.db SELECT * FROM memories LIMIT 10;注意数据库路径和表名以实际版本为准这里只是通用示例。5.7 功能测试汇总测试项操作预期结果排查方向记忆写入让 Claude 记住项目技术栈保存成功MCP 工具未注册、路径权限记忆召回新会话直接提问正确回答记忆库路径不一致项目隔离双目录分别测试不互相污染数据库路径配置错误历史搜索关键词搜索返回相关记录关键词不匹配落盘验证sqlite3 查询有数据返回数据未写入6. 接口 API 与批量任务claude-mem 本身是 MCP 服务不直接面向外部 HTTP API但它暴露给 Claude Code 的工具集合天然支持批量调用。6.1 MCP 工具调用示例在 Claude Code 对话中Claude 会替我们调用 MCP 工具。常见工具可能包括remember写入一条记忆。recall召回相关记忆。search按关键词搜索记忆。get_recent获取最近记录。clear清理记忆。示例对话请调用记忆工具保存以下内容登录模块使用 JWT Token 认证Token 有效期 2 小时刷新 Token 有效期 7 天。如果 Claude Code 支持直接调用 MCP 工具的路由写法也可以尝试使用 remember 工具保存内容为接口错误码统一格式为 { code, message, data }6.2 批量写入记忆如果你有一批历史信息需要导入记忆库不需要逐条对话。可以在会话中一次性给 Claude 结构化文本让其批量写入。例如请用 remember 工具逐条保存以下项目约定 1. 后端代码使用 TypeScript 2. 环境变量统一放在 .env 文件 3. 所有 API 返回统一包装为 ResponseResult 4. 数据库迁移使用 Prisma预期结果Claude 循环调用工具逐条写入最终提示保存完成。6.3 批量导出记忆如果希望把记忆导出为 JSON 或 Markdown可以直接要求 Claude 读取全部记忆并整理输出。请把所有项目记忆导出为 JSON 格式按照创建时间排序。也可以直接查询 SQLite 文件sqlite3 ~/.claude-mem/memory.db \ .headers on \ .mode json \ SELECT * FROM memories;6.4 批量清理记忆当记忆库膨胀或包含错误信息时可以清理指定范围。请删除所有关于“临时调试日志”的记忆如果工具支持范围删除也可以让 Claude 先搜索再逐条确认删除。6.5 失败重试与日志如果你的接入脚本调用了 claude-mem 的底层工具要注意每次写入前确认当前项目 ID避免写入到错误项目。批量写入失败时查看 Claude Code 输出中的错误信息常见原因是单次工具调用超时或参数格式不正确。SQLite 数据库如果被其他进程锁定会出现写入失败稍后重试即可。7. 资源占用与性能观察claude-mem 不是重负载服务资源占用很低但仍然值得看一眼。7.1 进程资源占用以 MCP 服务方式运行claude-mem 一般只在 Claude Code 会话期间活跃。可以使用系统监控工具观察# macOS / Linux top -o mem | grep claude-mem# Windows PowerShell Get-Process | Where-Object { $_.ProcessName -like *claude-mem* } | Select-Object ProcessName, CPU, WorkingSet预期资源占用内存通常保持在几十到几百 MB 量级具体以本机测试为准。数据库文件大小由记忆条数决定单条记忆通常很小几千条记录也只在 MB 级别。7.2 性能影响因素记忆条目数量越多查询越慢。SQLite 在万级条数内一般无压力。搜索关键词长度短关键词可能匹配大量结果。SQLite 数据库文件是否被压缩或损坏。MCP 服务启动时间首次调用时可能需要加载运行时。7.3 如何降低开销定期清理过期记忆。避免写入大量重复或低价值信息。关闭不需要的 MCP 工具权限减少工具列表加载压力。保持 claude-mem 版本更新旧版本可能存在内存泄漏或查询效率问题。7.4 如何发现记忆库异常如果会话变慢或召回不准检查数据库完整性sqlite3 ~/.claude-mem/memory.db PRAGMA integrity_check;返回ok说明数据文件正常。如果返回错误需要恢复备份或重建记忆库。8. 常见问题与排查方法8.1 排查表问题现象可能原因排查方式解决方案claude mcp list看不到 claude-memMCP 配置未加载检查项目是否在正确目录启动重新配置.mcp.json或运行添加命令启动 Claude Code 时提示 MCP 服务错误npx 无法找到包执行npm view thedotmack/claude-mem重新安装或使用绝对路径新会话无法召回旧记忆数据库路径不一致检查 MCP env 配置统一数据库路径写入记忆时提示权限错误数据目录不可写检查目录权限手动创建目录并授权SQLite 无法打开数据库文件文件损坏或路径错误执行PRAGMA integrity_check恢复备份或重新初始化搜索不到任何结果关键词不匹配或记忆未写入先用SELECT * FROM memories查询调整关键词或补写记忆多项目记忆互相污染配置了全局数据库查看数据库路径是否按项目区分按项目目录初始化单独数据库会话结束后 MCP 进程残留服务未正常退出ps aux | grep claude-mem手动结束残留进程批量写入时中断网络问题或工具调用超时查看 Claude Code 日志分批写入并加日志8.2 依赖安装失败常见错误包括 Node 版本过低、npm 源不可达、包名写错。处理方式npm config get registry如果需要可切换为国内镜像源但注意不要影响其他项目依赖。8.3 模型文件缺失claude-mem 不依赖模型文件但一些从源码构建的版本可能需要npm run build产物。如果构建失败检查.env或配置文件中的路径是否正确。8.4 端口冲突claude-mem 默认不是 HTTP 服务一般不存在端口冲突。但如果你在 MCP 配置中设置了transport: http等远程模式注意端口占用。9. 最佳实践与使用建议9.1 第一次先小范围测试不要第一次就接入大型项目并写入大量记忆。先在一个测试目录跑通写入、召回、清理全流程确认配置稳定后再用于正式项目。9.2 保留一套最小可运行配置记录下你本机能跑通的 MCP 配置内容保存为配置文件。这样换电脑或重装环境时可以快速恢复。# 导出 MCP 配置示例 claude mcp list --json claude-mcp-backup.json9.3 规划记忆内容不是所有对话都值得写入。建议只让 Claude 记录项目技术选型和变更原因。数据库表结构、接口约定、错误码规范。已排查的坑和最终解决方案。团队成员约定的代码风格和 Git 流程。低价值对话临时调试、闲聊、一次性输出不需要保存。9.4 建立定期清理机制记忆库不会自动瘦身。建议每周或每月删除过时的技术决策。清理重复条目。导出重要记忆到项目文档。对数据库做备份。mkdir -p ~/.claude-mem/backups cp ~/.claude-mem/memory.db ~/.claude-mem/backups/memory-$(date %Y%m%d).db9.5 限制敏感信息强烈建议不要在记忆库中保存 Token、密码、私钥、内网地址和个人隐私。如果确实需要记录先确认数据目录权限足够严格并定期检查数据库内容。9.6 注意 Claude Code 版本兼容性不同版本的 Claude Code 对 MCP 协议的支持可能有差异。升级 Claude Code 后建议重新运行一遍写入和召回测试避免协议变化导致功能失效。9.7 批量任务日志与重试如果需要通过脚本批量写入记忆建议给每条记录加上状态标记避免重复写入。sqlite3 ~/.claude-mem/memory.db \ CREATE TABLE IF NOT EXISTS import_log (id INTEGER PRIMARY KEY, content TEXT, status TEXT);这里的表名和字段是示例实际导入时应以 claude-mem 的数据库结构为准。9.8 先确认授权再写入团队资料如果你在团队项目中使用涉及公司内部技术文档、架构方案、客户信息时要确认数据是否允许落到本地 SQLite 文件中。合规问题比技术部署更重要。10. 总结与下一步claude-mem 最值得尝试的点是它把 Claude Code 从“单次会话工具”变成了“带项目记忆的开发助手”。你不需要额外维护向量数据库不需要手动整理文档只要在对话中让 Claude 记住关键约定后续会话就能自动召回。建议你最先验证三个功能记忆写入是否落盘、新会话能否召回、多项目是否隔离。这三个点跑通工具的基本价值就有了。最容易踩的坑有三个一是 MCP 配置写错导致服务不加载二是数据库路径不统一导致记忆无法召回三是往记忆库里写入了敏感信息或大量无用内容时间一长数据膨胀且难以清理。后续可以继续扩展的方向把记忆导出为团队共享文档沉淀到 Git 仓库。结合定时脚本定期清理和压缩记忆库。将 claude-mem 接入 CI/CD 流水线自动沉淀每次构建和部署的决策记录。配合 Claude Code 的自动化任务实现“项目知识自动建档”。建议收藏备用把测试目录的方案跑熟后再迁移到正式项目。下一篇文章可以考虑做一个 claude-mem 与团队项目协同使用的完整配置示例把 MCP 配置、数据库备份、记忆清理流程全部整理成可直接复用的模板。
阅读完成 · 觉得有帮助？
