claude-mem：让Claude Code拥有跨会话持久记忆的开源插件

你是不是也有这样的烦恼？

每天用 Claude Code 写代码，前一个会话里刚讨论完架构方案、修完一个棘手的 bug，关掉终端再开一个新的——Claude 全忘了。你得重新解释项目背景、重新描述那个 bug 的来龙去脉、重新告诉它你用了什么技术栈。这种"失忆"不仅浪费时间，更让人恼火：明明刚才还聊得好好的，怎么一转眼就形同陌路？更惨的是，你花了半天让 Claude 理解了一套复杂的业务逻辑，结果第二天它又从零开始。如果你经常和 Claude Code 配合干活，这种痛感一定深有体会。尤其是在做长期项目的时候，每天重复解释上下文简直是在浪费生命。

claude-mem 是什么？

claude-mem 是一个专为 Claude Code 设计的持久化记忆压缩系统插件——它自动捕获你在编码会话中的一切操作，用 AI 压缩成语义摘要，并在未来的新会话中智能注入相关上下文。简单说：让 Claude 拥有"记忆力"，跨会话也不会失忆。

这个项目在 GitHub 上已经收获了 57.9K 星，单日新增 2,305 星，足见社区对它的认可程度。当前最新版本为 v12.1.5，项目由 Alex Newman（@thedotmack）开发维护，采用 AGPL-3.0 开源协议。它已经被收录到 awesome-claude-code 列表中，是 Claude Code 生态中最为热门的插件之一。

核心功能一览

• 🧠 持久化记忆：上下文跨会话保存，新会话自动加载历史上下文，再也不用重复解释项目背景和技术选型
• 📊 渐进式披露：分层检索记忆，先给索引（约50-100 token），再按需加载详情，节省约10倍 token 消耗，不用每次都全量注入
• 🔍 技能搜索（mem-search）：用自然语言查询项目历史，比如"上次我们怎么修的那个认证bug？"，Claude 自动调用
• 🖥️ Web 查看器：浏览器打开 http://localhost:37777，实时查看记忆数据流，可视化浏览所有历史观察，还能切换版本
• 💻 Claude Desktop 技能：从 Claude Desktop 对话中直接搜索记忆库，无需切换到 Claude Code
• 🔒 隐私控制：用 <private> 标签包裹敏感内容，该部分不会被记录到记忆库，保护你的密码和密钥
• ⚙️ 上下文配置：精细控制哪些上下文被注入新会话，包括模式、语言、注入层级、数据目录等
• 🤖 全自动运行：无需手动操作，装完即忘，五个生命周期钩子会在正确时机自动触发
• 🔗 引用系统：每个观察都有唯一ID，可以在 http://localhost:37777/api/observation/{id} 查看详情并溯源
• 🧪 Beta 渠道：尝鲜"无尽模式"（Endless Mode）等实验性功能，适合需要超长会话的场景

安装步骤（手把手教程）

前置条件

在安装 claude-mem 之前，请确保你的系统满足以下要求：

检查 Node.js 版本

首先确认你的 Node.js 版本不低于 18.0.0：

node -v

如果版本低于 18.0.0，需要先升级 Node.js。推荐从 https://nodejs.org 下载最新 LTS 版本。如果你用的是 macOS，也可以用 Homebrew 升级：

brew install node@22

Linux 用户使用包管理器安装：

# Ubuntu / Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# CentOS / RHEL
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo yum install -y nodejs

Windows 用户直接从官网下载安装包即可。

方法一：npx 一键安装（推荐，最简单）

这是最主流的安装方式，一条命令搞定：

npx claude-mem install

安装脚本会自动完成以下工作：

1. 检测并安装 Bun 运行时（如果系统里没有的话）
2. 检测并安装 uv Python 包管理器（用于向量搜索功能）
3. 注册 5 个生命周期钩子（SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd）
4. 启动 Worker 服务（监听端口 37777）
5. 初始化 SQLite 数据库和 Chroma 向量数据库

整个安装过程通常只需要几十秒。安装完成后，重启 Claude Code 即可生效。

macOS / Linux 用户

直接在终端执行：

npx claude-mem install

如果你使用 Homebrew 安装的 Node.js，但 npx 命令找不到，先确认 Node.js 在 PATH 中：

which node
which npx

如果找不到，可能需要重新链接：

brew link node

或者直接重装 Node.js：

brew reinstall node

Windows 用户

在 PowerShell 或 CMD 中执行同样命令：

npx claude-mem install

如果提示 npm : The term 'npm' is not recognized，说明 Node.js 没有加入系统 PATH。请按以下步骤操作：

1. 从 https://nodejs.org 下载最新 LTS 版本安装
2. 安装时务必勾选 "Add to PATH" 选项
3. 重启终端（这步很重要，重启后 PATH 才能生效）
4. 打开新的 PowerShell 窗口，验证安装：node -v 和 npm -v
5. 再次运行 npx claude-mem install

方法二：Claude Code 插件市场安装

如果你已经在 Claude Code 会话中，可以直接用插件命令安装：

/plugin marketplace add thedotmack/claude-mem

/plugin install claude-mem

安装完重启 Claude Code 即可。这种方式不需要离开 Claude Code 环境，更加便捷。

方法三：Gemini CLI 安装

如果你使用 Google 的 Gemini CLI 而非 Claude Code，claude-mem 同样支持：

npx claude-mem install --ide gemini-cli

安装器会自动检测 ~/.gemini 目录并完成配置。重启 Gemini CLI 后生效。

方法四：OpenCode 安装

如果你使用 OpenCode 开发工具：

npx claude-mem install --ide opencode

安装器会自动识别 OpenCode 的配置目录并完成所有设置。

方法五：OpenClaw Gateway 安装

对于 OpenClaw 网关用户，有专门的一键安装脚本：

curl -fsSL https://install.cmem.ai/openclaw.sh | bash

这个安装器不仅处理插件本身，还自动配置 AI 供应商、启动 Worker 服务，甚至可以设置实时推送到 Telegram、Discord、Slack 等平台，功能非常全面。

重要注意事项

千万不要用 npm install -g claude-mem！这条命令只安装 SDK/库，不会注册插件钩子、不会启动 Worker 服务。务必使用 npx claude-mem install 或上面提到的插件命令来安装，否则记忆功能无法正常工作。

使用方法

基础用法：装完即用，全自动

安装完 claude-mem 后，你什么都不用做。它会自动在每个会话的关键节点工作：

1. 会话开始时（SessionStart）：自动加载与当前项目相关的历史上下文，Claude 会"想起"之前做过什么
2. 你输入提示时（UserPromptSubmit）：记录你的请求和意图
3. Claude 使用工具后（PostToolUse）：捕获工具调用结果作为"观察"，比如读取了哪个文件、执行了什么命令
4. 会话结束时（SessionEnd）：压缩整个会话内容为语义摘要，存入数据库供未来使用

下一次你开新会话，Claude 自动获取之前的上下文——就像它从未"失忆过"。你再也不用每次开头都说"我们之前在做XXX项目，用了YYY技术栈……"。

进阶用法一：搜索项目历史

你可以在对话中用自然语言查询历史记忆。Claude 会自动调用 mem-search 技能。举例：

• "上次会话我们做了什么？"
• "我们之前修过这个 bug 吗？"
• "之前是怎么实现认证功能的？"
• "worker-service.ts 这个文件之前做过什么改动？"
• "最近这个项目有什么进展？"

背后是一个三层工作流，非常高效：

这样做的好处是：不需要一开始就加载所有历史，而是逐步筛选、按需深入——平均节省约 10 倍的 token 开销。对于需要控制成本的开发者来说，这一点至关重要。

搜索操作类型详解

claude-mem 支持 10 种搜索操作，覆盖几乎所有你需要的查询场景：

1. 搜索观察：跨所有观察全文搜索，最常用的搜索方式
2. 搜索会话：跨会话摘要全文搜索，适合找某个会话的整体信息
3. 搜索提示：搜索原始用户请求，回溯你之前问过什么
4. 按概念搜索：按概念标签查找（如"发现"、"问题-解决方案"、"模式"等）
5. 按文件搜索：查找引用特定文件的所有观察，追踪文件变更历史
6. 按类型搜索：按类型查找（决策、bug修复、功能、重构、发现、更改）
7. 最近上下文：获取项目最近的会话上下文，快速了解最新进展
8. 时间线：获取特定时间点前后的上下文时间线
9. 按查询的时间线：搜索观察并获取最佳匹配周围的时间线上下文
10. API 帮助：获取搜索 API 文档，了解如何更精确地查询

手动调用 MCP 工具示例

如果你需要精确控制搜索，可以直接调用 MCP 工具：

// 步骤1：搜索索引，找到相关观察的 ID
search(query="认证bug", type="bugfix", limit=10)

// 步骤2：审视返回的索引结果，标记感兴趣的 ID（比如 #123, #456）

// 步骤3：获取完整详情
get_observations(ids=[123, 456])

进阶用法二：Web 查看器可视化浏览

浏览器打开 http://localhost:37777，你会看到一个功能完整的 Web 界面，可以：

• 实时查看当前会话的记忆流，观察 claude-mem 记录了什么
• 浏览所有历史观察记录，按时间倒序排列
• 按类型、时间、项目等维度过滤
• 在设置页面切换稳定版/Beta 渠道
• 查看每个观察的详细信息和引用链

这个 Web 查看器对于调试和理解 claude-mem 的行为非常有用，尤其在刚安装的时候，建议打开看看它是如何捕获和压缩上下文的。

进阶用法三：隐私保护

如果你在对话中涉及密码、密钥等敏感信息，用 <private> 标签包裹：

我的数据库密码是 <private>my_secret_password</private>

被 <private> 包裹的内容不会被记录到记忆库中，保证隐私安全。这个功能对于需要在对话中传递凭证但又不希望被持久化保存的场景非常实用。

进阶用法四：中文模式配置

claude-mem 默认用英文记录观察和生成摘要。如果你希望用中文，编辑设置文件：

# macOS / Linux
nano ~/.claude-mem/settings.json

# Windows
notepad %USERPROFILE%\.claude-mem\settings.json

将 CLAUDEMEMMODE 改为 code--zh：

{
  "CLAUDE_MEM_MODE": "code--zh"
}

修改后重启 Claude Code 生效。这样 claude-mem 生成的所有观察和摘要都会用中文书写，阅读体验更好。

查看所有可用模式：

ls ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/

其他语言模式格式为 code--[语言代码]，比如 code--ja（日语）、code--es（西班牙语）等。这种内置的多语言支持意味着你不需要额外安装语言包。

实际场景举例

同类工具对比

核心优势总结：claude-mem 不是简单的"记忆存储"，而是一套完整的上下文工程系统——从自动捕获、AI 压缩、智能检索到按需注入，每个环节都做了深度优化。尤其是渐进式披露设计和 Chroma 向量数据库的引入，让它在 token 效率上远超同类方案。传统方案要么全量注入导致浪费，要么只存不压缩导致上下文窗口被撑满，而 claude-mem 的三层工作流设计巧妙地平衡了上下文完整性和 token 经济性。

系统架构简析

了解架构有助于你更好地配置和排错。claude-mem 由以下核心组件构成：

┌─────────────────────────────────────────────┐
│                Claude Code                    │
│  ┌──────────┐  ┌──────────────┐              │
│  │ Lifecycle │  │  MCP Search  │              │
│  │  Hooksx5 │  │  Tools x4   │              │
│  └─────┬────┘  └──────┬───────┘              │
│        │               │                      │
└────────┼───────────────┼──────────────────────┘
         │               │
         ▼               ▼
┌─────────────────────────────────────────────┐
│           Worker Service (Bun)               │
│       Port 37777 · 10 Search Endpoints       │
│  ┌─────────┐  ┌───────────┐  ┌───────────┐ │
│  │ SQLite  │  │  Chroma   │  │  Web UI   │ │
│  │ Database│  │  Vector DB│  │  Viewer   │ │
│  └─────────┘  └───────────┘  └───────────┘ │
└─────────────────────────────────────────────┘

下面是各组件的作用详解：

• 5 个生命周期钩子：SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd——在会话的关键节点自动触发，无需你手动调用。另有一个"智能安装"预钩子脚本，负责在首次运行时检测和安装所有依赖。
• Worker 服务：运行在 Bun 上的 HTTP API，端口 37777，提供 Web 查看器和 10 个搜索端点。Bun 作为进程管理器保障其稳定运行。
• SQLite 数据库：存储会话、观察、摘要的持久化数据，使用 FTS5 全文搜索扩展。数据文件默认存放在 ~/.claude-mem/ 目录下。
• Chroma 向量数据库：混合语义 + 关键词搜索，是 claude-mem 智能检索能力的核心。它不仅能匹配关键词，还能理解语义关联，找到"意思相近"的历史记录。
• MCP 搜索工具：提供 search、timeline、get_observations 三个 MCP 工具，Claude 可以通过这些工具与 Worker 服务交互。

这套架构的设计哲学是"渐进式披露"——不是一股脑把所有历史都塞给 Claude，而是先给索引，再按需深入。这与传统上下文管理方案形成了鲜明对比。

常见问题排查

安装后没有生效？

1. 确认已经重启了 Claude Code（这一步最常被遗忘）
2. 检查 Worker 服务是否在运行：浏览器访问 http://localhost:37777
3. 如果端口被占用，编辑 ~/.claude-mem/settings.json 修改端口
4. 检查日志文件是否有报错信息

想生成 Bug 报告？

如果你遇到了问题，可以用自带的 Bug 报告生成器：

cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report

会自动生成一份包含系统环境、版本信息和日志的诊断报告，方便提交到 GitHub Issues。

Windows 上 npm 命令找不到？

确保 Node.js 安装时勾选了 "Add to PATH"，并重启终端。如果还不行，尝试完全卸载 Node.js 后重新安装。

想尝鲜 Endless Mode？

打开 http://localhost:37777，进入 Settings 页面，切换到 Beta 渠道。Endless Mode 是一种仿生记忆架构，适用于超长会话场景——类似人类的短期记忆和长期记忆的协同工作方式。

如何完全卸载？

如果你想卸载 claude-mem，可以执行：

npx claude-mem uninstall

这会移除所有钩子注册和配置文件，数据库文件需要手动删除：

rm -rf ~/.claude-mem

小结

claude-mem 用一套精巧的自动化系统解决了 AI 编程助手的"失忆"难题——自动捕获、AI 压缩、智能检索、按需注入，你只需一条 npx claude-mem install 命令，之后再也不用担心上下文丢失。无论是日常迭代开发还是长期维护项目，它都能显著提升你和 Claude 的协作效率。对于重度使用 Claude Code 的开发者来说，这是一个必备插件。

项目地址：https://github.com/thedotmack/claude-mem

官方文档：https://docs.claude-mem.ai/

Discord 社区：https://discord.com/invite/J4wttp9vDu

作者 X/Twitter：https://x.com/Claude_Memory