企业官网建设流程全解析

这次我们来看一个比较特别的开发者工具：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 版本和 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 环境要求

3.2 检查 node 与 npm

node -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 Code

claude-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 功能测试汇总

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 排查表

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.json

9.3 规划记忆内容

不是所有对话都值得写入。建议只让 Claude 记录：

• 项目技术选型和变更原因。
• 数据库表结构、接口约定、错误码规范。
• 已排查的坑和最终解决方案。
• 团队成员约定的代码风格和 Git 流程。

低价值对话（临时调试、闲聊、一次性输出）不需要保存。

9.4 建立定期清理机制

记忆库不会自动瘦身。建议每周或每月：

• 删除过时的技术决策。
• 清理重复条目。
• 导出重要记忆到项目文档。
• 对数据库做备份。

mkdir -p ~/.claude-mem/backups cp ~/.claude-mem/memory.db ~/.claude-mem/backups/memory-$(date +%Y%m%d).db

9.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 配置、数据库备份、记忆清理流程全部整理成可直接复用的模板。