🇨🇳 中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇵🇹 Português • 🇧🇷 Português • 🇰🇷 한국어 • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇮🇱 עברית • 🇸🇦 العربية • 🇷🇺 Русский • 🇵🇱 Polski • 🇨🇿 Čeština • 🇳🇱 Nederlands • 🇹🇷 Türkçe • 🇺🇦 Українська • 🇻🇳 Tiếng Việt • 🇵🇭 Tagalog • 🇮🇩 Indonesia • 🇹🇭 ไทย • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇷🇴 Română • 🇸🇪 Svenska • 🇮🇹 Italiano • 🇬🇷 Ελληνικά • 🇭🇺 Magyar • 🇫🇮 Suomi • 🇩🇰 Dansk • 🇳🇴 Norsk

专为Claude Code打造的持久化内存压缩系统。

快速入门 • 工作原理 • 搜索工具 • 文档 • 配置 • 故障排除 • 许可证

Claude-Mem 通过自动捕获工具使用记录、生成语义摘要，并将其提供给后续会话，从而在不同会话之间无缝保留上下文。这使得 Claude 即使在会话结束或重新连接后，仍能保持对项目的知识连续性。

---

快速入门

只需一条命令即可安装：

npx claude-mem install

或者为 Gemini CLI 安装（会自动检测 ~/.gemini）：

npx claude-mem install --ide gemini-cli

也可以从 Claude Code 内的插件市场安装：

/plugin marketplace add thedotmack/claude-mem

/plugin install claude-mem

重启 Claude Code 或 Gemini CLI。之前会话的上下文将自动出现在新会话中。

注意： Claude-Mem 也已发布在 npm 上，但运行 npm install -g claude-mem 只会安装 SDK/库 — 它不会注册插件钩子或设置工作服务。请务必通过 npx claude-mem install 或上述 /plugin 命令进行安装。

🦞 OpenClaw 网关

只需一条命令，即可在 OpenClaw 网关上将 claude-mem 作为持久化内存插件安装：

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

安装程序会自动处理依赖项、插件设置、AI 提供商配置、工作进程启动，以及可选的实时观测信息推送至 Telegram、Discord、Slack 等平台。详细信息请参阅 OpenClaw 集成指南。

主要特性：

• 🧠 持久化内存 - 上下文可在不同会话间持续保留
• 📊 渐进式披露 - 分层内存检索，同时显示 token 费用
• 🔍 基于技能的搜索 - 使用 mem-search 技能查询项目历史
• 🖥️ Web 查看器界面 - 实时内存流，访问地址为 http://localhost:37777
• 💻 Claude Desktop 技能 - 可从 Claude Desktop 对话中直接搜索内存
• 🔒 隐私控制 - 使用 <private> 标签排除敏感内容的存储
• ⚙️ 上下文配置 - 细粒度控制注入哪些上下文
• 🤖 自动运行 - 无需手动干预
• 🔗 引用 - 通过 ID 引用过往观测记录（可通过 http://localhost:37777/api/observation/{id} 访问，或在 Web 查看器 http://localhost:37777 中查看全部）
• 🧪 测试通道 - 通过版本切换尝试实验性功能，如无限模式

---

文档

📚 查看完整文档 - 官方网站浏览

入门指南

• 安装指南 - 快速入门与高级安装
• Gemini CLI 设置 - 专门针对 Google Gemini CLI 集成的指南
• 使用指南 - Claude-Mem 的自动化工作原理
• 搜索工具 - 用自然语言查询项目历史
• 测试功能 - 尝试实验性功能，如无限模式

最佳实践

• 上下文工程 - AI 代理上下文优化原则
• 渐进式披露 - Claude-Mem 上下文预热策略的理念

架构

• 概述 - 系统组件与数据流
• 架构演进 - 从 v3 到 v5 的发展历程
• 钩子架构 - Claude-Mem 如何使用生命周期钩子
• 钩子参考 - 7 个钩子脚本详解
• 工作进程服务 - HTTP API 与 Bun 运维管理
• 数据库 - SQLite 模式与 FTS5 搜索
• 搜索架构 - 结合 Chroma 向量数据库的混合搜索

配置与开发

• 配置 - 环境变量与设置
• 开发 - 构建、测试、贡献代码
• 故障排除 - 常见问题及解决方案

---

工作原理

核心组件：

1. 5 个生命周期钩子 - 会话开始、用户提问提交、工具使用后、停止、会话结束（6 个钩子脚本）
2. 智能安装 - 缓存依赖检查器（前置钩子脚本，非生命周期钩子）
3. 工作进程服务 - 在端口 37777 上提供 HTTP API 和 Web 查看器界面，包含 10 个搜索接口，由 Bun 管理
4. SQLite 数据库 - 存储会话、观测记录和摘要
5. mem-search 技能 - 基于自然语言的渐进式披露查询
6. Chroma 向量数据库 - 混合语义与关键词搜索，实现智能化上下文检索

详情请参阅 架构概述。

---

MCP 搜索工具

Claude-Mem 提供智能记忆搜索功能，通过 4 种 MCP 工具，遵循一种节省 token 的 3 层工作流程：

3 层工作流程：

1. search - 获取紧凑的索引，包含观测 ID（每次结果约 50–100 个 token）
2. timeline - 获取围绕感兴趣结果的时间线上下文
3. get_observations - 仅对筛选出的 ID 获取完整细节（每次结果约 500–1,000 个 token）

工作方式：

• Claude 使用 MCP 工具搜索您的记忆
• 首先使用 search 获取结果索引
• 再用 timeline 查看特定观测或查询周边发生的情况
• 最后使用 get_observations 获取相关 ID 的完整细节
• 节省约 10 倍 token，因为会在获取详细信息前先进行过滤

可用的 MCP 工具：

1. search - 使用全文查询搜索记忆索引，并按类型、日期、项目等条件筛选
2. timeline - 获取特定观测或查询周边的时间线上下文
3. get_observations - 根据 ID 获取完整的观测记录（始终批量处理多个 ID）

使用示例：

// 第一步：搜索索引
search(query="authentication bug", type="bugfix", limit=10)

// 第二步：审查索引，确定相关 ID（例如 #123、#456）

// 第三步：获取详细信息
get_observations(ids=[123, 456])

更多详细示例请参阅 搜索工具指南。

---

测试功能

Claude-Mem 提供一个 测试通道，包含实验性功能，如 无限模式（仿生记忆架构，适用于长时间会话）。您可以通过 Web 查看器界面 http://localhost:37777 → 设置，在稳定版和测试版之间切换。

有关无限模式及其使用方法，请参阅 测试功能文档。

---

系统要求

• Node.js：18.0.0 或更高版本
• Claude Code：最新版本，支持插件
• Bun：JavaScript 运行时与进程管理器（若缺失则自动安装）
• uv：用于向量搜索的 Python 包管理器（若缺失则自动安装）
• SQLite 3：用于持久化存储（已打包附带）

---

Windows 设置说明

如果您遇到类似以下错误：

npm : The term 'npm' is not recognized as the name of a cmdlet

请确保已安装 Node.js 和 npm，并将其添加到系统 PATH 中。请从 https://nodejs.org 下载最新版 Node.js 安装程序，安装完成后重启终端。

---

配置

设置文件位于 ~/.claude-mem/settings.json（首次运行时会自动生成默认配置）。您可以在此配置 AI 模型、工作进程端口、数据目录、日志级别以及上下文注入设置。

所有可用设置及示例请参阅 配置指南。

---

开发

有关构建说明、测试和贡献流程，请参阅 开发指南。

---

故障排除

如果遇到问题，请向 Claude 描述问题，故障排除技能将自动诊断并提供修复方案。

常见问题及解决方案请参阅 故障排除指南。

---

Bug 报告

使用自动化生成器创建全面的 bug 报告：

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

贡献

欢迎贡献！请按照以下步骤操作：

1. 分支仓库
2. 创建功能分支
3. 在进行更改的同时编写测试
4. 更新文档
5. 提交拉取请求

有关贡献流程，请参阅 开发指南。

---

许可证

本项目采用 GNU Affero 通用公共许可证 v3.0（AGPL-3.0）许可。

版权所有 © 2025 Alex Newman (@thedotmack)。保留所有权利。

完整详情请参阅 LICENSE 文件。

这意味着：

• 您可以自由地使用、修改和分发此软件。
• 如果您对其进行修改并在网络服务器上部署，则必须公开您的源代码。
• 衍生作品也必须以 AGPL-3.0 许可证授权。
• 本软件不提供任何担保。

关于 Ragtime 的说明：ragtime/ 目录单独采用 PolyForm 非商业许可证 1.0.0 许可。详细信息请参阅 ragtime/LICENSE。

---

支持

• 文档：docs/
• 问题：GitHub Issues
• 仓库：github.com/thedotmack/claude-mem
• 官方 X 账号：@Claude_Memory
• 官方 Discord：加入 Discord
• 作者：Alex Newman (@thedotmack)

---

基于 Claude Agent SDK 构建 | 由 Claude Code 提供支持 | 使用 TypeScript 打造

---

关于 $CMEM？

$CMEM 是一种 Solana 代币，由第三方在未经 Claude-Mem 事先同意的情况下创建，但已被 Claude-Mem 的创建者 Alex Newman（@thedotmack）正式认可。该代币旨在作为社区增长的催化剂，并为最需要实时代理数据的开发者和知识工作者提供数据渠道。$CMEM：2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS

Claude-Mem 快速上手指南

Claude-Mem 是一个专为 Claude Code 和 Gemini CLI 设计的持久化记忆压缩系统。它能自动捕获工具使用观察、生成语义摘要，并在会话结束后保留上下文，让 AI 在重新连接时依然“记得”之前的项目状态。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (WSL)
• Node.js: 版本 >= 18.0.0
• 目标工具: 已安装并配置好 Claude Code 或 Gemini CLI
• 网络环境: 能够访问 npm registry 及 GitHub（如需加速，请自行配置国内镜像源）

注意: 虽然该工具发布在 npm 上，但不要直接使用 npm install -g 安装全局包，那样只会安装 SDK 库而不会注册插件钩子或启动工作服务。请务必使用下方的 npx 命令进行安装。

安装步骤

根据你的使用场景，选择以下任一命令进行一键安装：

1. 为 Claude Code 安装（推荐）

这是最常用的安装方式，会自动检测并配置环境：

npx claude-mem install

2. 为 Gemini CLI 安装

如果你主要使用 Google 的 Gemini CLI，工具会自动检测 ~/.gemini 目录并进行适配：

npx claude-mem install --ide gemini-cli

3. 通过插件市场安装

如果你已经在运行 Claude Code，也可以直接在交互式界面中执行：

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

4. OpenClaw 网关安装（可选）

如果你在使用 OpenClaw 网关，可以使用专用脚本安装：

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

安装完成后：请重启你的 Claude Code 或 Gemini CLI 终端会话。此前会话的上下文将自动出现在新会话中。

基本使用

安装完成后，Claude-Mem 将以全自动模式运行，无需手动干预。它会在后台执行以下操作：

1. 自动捕获：记录工具调用和关键对话节点。
2. 智能摘要：生成语义化的记忆摘要。
3. 上下文注入：在新会话开始时，自动将相关历史记忆注入给 AI。

核心功能体验

1. 查看实时记忆流

安装后，本地会启动一个 Web 服务，你可以随时在浏览器中查看当前的记忆流和观察记录：

• 访问地址：http://localhost:37777
• 功能：查看实时记忆、搜索历史记录、管理配置。

2. 使用自然语言搜索记忆

在对话中，你可以直接让 Claude 搜索过去的记忆。底层通过 mem-search 技能和 MCP 工具实现高效的三层检索：

示例对话：

用户: "帮我查一下上次我们是怎么解决那个认证 bug 的？"

Claude (自动调用工具):

1. 执行 search(query="authentication bug") 获取索引。
2. 发现相关 ID (例如 #123, #456)。
3. 执行 get_observations(ids=[123, 456]) 获取详细上下文。
4. 基于检索到的详细信息回答你的问题。

3. 隐私控制

如果某些内容不适合存储，你可以在对话中使用 <private> 标签，Claude-Mem 会自动排除这些内容：

<private>
这里是一些敏感的 API 密钥或个人信息，不会被存入记忆库。
</private>

4. 进阶：切换测试版功能

如果你想尝试“无尽模式 (Endless Mode)"等实验性功能：

1. 打开 Web viewer: http://localhost:37777
2. 进入 Settings (设置)
3. 在版本通道中切换至 Beta。

---

更多详细架构说明和高级配置，请访问官方文档：https://docs.claude-mem.ai/