claude-mem

为 AI Agent 提供跨会话持久记忆，自动捕获每轮交互中的工具调用和观察结果，用 LLM 压缩为语义摘要并在新会话中注入相关上下文。亮点在于支持 Claude Code、Gemini CLI、OpenCode 等多种 Agent 框架，通过 MCP 搜索工具和 Web UI 实现渐进式上下文检索，大幅提升 Agent 在长期项目中的连续性和效率。

README

🇨🇳 中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇵🇹 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 构建的持久化记忆压缩系统。

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

Claude-Mem 自动捕捉工具使用观察记录，生成语义摘要，并在未来的会话中提供访问，从而无缝地在会话之间保留上下文。这使得 Claude 能够在会话结束后或重新连接后，仍然保持对项目的知识连续性。

快速开始

使用一条命令安装：

npx claude-mem install

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

npx claude-mem install --ide gemini-cli

或为 OpenCode 安装：

npx claude-mem install --ide opencode

或从 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/库 —— 它不会注册插件钩子或设置 worker 服务。请始终通过 npx claude-mem install 或上面的 /plugin 命令安装。

🦞 OpenClaw 网关

在 OpenClaw 网关上以单条命令安装 claude-mem 作为持久化记忆插件：

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

安装程序会处理依赖、插件设置、AI 提供商配置、worker 启动以及可选的实时观察数据推送至 Telegram、Discord、Slack 等。详情请参阅 OpenClaw 集成指南。

关键特性：

🧠 持久化记忆 - 跨会话保留上下文
📊 渐进式披露 - 分层的记忆检索，附带 token 成本提示
🔍 基于技能的搜索 - 使用 mem-search 技能查询项目历史
🖥️ Web 查看器 UI - 在 http://localhost:37777 实时查看记忆流
💻 Claude Desktop 技能 - 从 Claude Desktop 对话中搜索记忆
🔒 隐私控制 - 使用 <private> 标签排除敏感内容
⚙️ 上下文配置 - 精细控制注入哪些上下文
🤖 自动运行 - 无需手动干预
🔗 引用 - 使用 ID 引用过去的观察记录（通过 http://localhost:37777/api/observation/{id} 访问，或在 http://localhost:37777 的 Web 查看器中查看全部）
🧪 Beta 频道 - 通过版本切换尝试实验性功能，如无尽模式

文档

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

入门指南

安装指南 - 快速开始与高级安装
Gemini CLI 设置 - 专门针对 Google Gemini CLI 集成的指南
使用指南 - Claude-Mem 如何自动工作
搜索工具 - 用自然语言查询项目历史
Beta 功能 - 尝试无尽模式等实验性功能

最佳实践

上下文工程 - AI 代理上下文优化原理
渐进式披露 - Claude-Mem 上下文启动策略背后的理念

架构

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

配置与开发

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

工作原理

核心组件：

5 个生命周期钩子 - SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd（共 6 个钩子脚本）
智能安装 - 缓存依赖检查器（预钩子脚本，非生命周期钩子）
Worker 服务 - 在端口 37777 上提供 HTTP API，附带 Web 查看器 UI 和 10 个搜索端点，由 Bun 管理
SQLite 数据库 - 存储会话、观察记录、摘要
mem-search 技能 - 支持渐进式披露的自然语言查询
Chroma 向量数据库 - 混合语义 + 关键词搜索，实现智能上下文检索

详情请参阅架构概述。

MCP 搜索工具

Claude-Mem 通过 4 个 MCP 工具 提供智能记忆搜索，遵循 token 高效的 3 层工作流模式：

3 层工作流：

search - 获取包含 ID 的紧凑索引（约 50-100 tokens/结果）
timeline - 获取感兴趣结果周围的时间线上下文
get_observations - 仅获取筛选后的 ID 的完整详情（约 500-1,000 tokens/结果）

工作原理：

Claude 使用 MCP 工具搜索你的记忆
从 search 开始获取结果索引
使用 timeline 查看特定观察记录周围的状况
使用 get_observations 获取相关 ID 的完整详情
通过先过滤再获取详情，节省约 10 倍 token

可用的 MCP 工具：

search - 使用全文查询搜索记忆索引，支持按类型/日期/项目过滤
timeline - 获取特定观察记录或查询周围的时间线上下文
get_observations - 按 ID 获取完整的观察记录详情（始终批量传入多个 ID）

使用示例：

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

// 第 2 步：审查索引，找出相关 ID（例如 #123、#456）

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

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

Beta 功能

Claude-Mem 提供了一个 beta 频道，包含实验性功能，如 无尽模式（用于延长会话的仿生记忆架构）。可在 Web 查看器 UI（http://localhost:37777 → 设置）中切换稳定版和 beta 版。

有关无尽模式及如何尝试的详细信息，请参阅 Beta 功能文档。

系统要求

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 模型、worker 端口、数据目录、日志级别和上下文注入设置。

有关所有可用设置和示例，请参阅**配置指南**。

模式与语言配置

Claude-Mem 支持通过 CLAUDE_MEM_MODE 设置切换多种工作流模式和语言。

此选项同时控制：

工作流行为（例如 code、chill、investigation）
生成观察记录时使用的语言

如何配置

编辑设置文件 ~/.claude-mem/settings.json：

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

模式定义在 plugin/modes/ 目录中。要本地查看所有可用模式：

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

可用模式

模式	描述
`code`	默认英文模式
`code--zh`	简体中文模式
`code--ja`	日文模式

语言特定模式遵循 code--[lang] 格式，其中 [lang] 是 ISO 639-1 语言代码（例如 zh 代表中文，ja 代表日文，es 代表西班牙语）。

注意：code--zh（简体中文）已内置 —— 无需额外安装或更新插件。

更改模式后

重启 Claude Code 以应用新的模式配置。

开发

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

故障排除

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

有关常见问题和解决方案，请参阅 故障排除指南。

Bug 报告

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

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

贡献

欢迎贡献！请：

Fork 本仓库
创建功能分支
进行更改并编写测试
更新文档
提交 Pull Request

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

许可证

Claude-Mem 采用 Apache License 2.0 许可证。

我们选择 Apache-2.0 是因为持久的代理记忆应易于嵌入开发者工具、本地代理、MCP 服务器、企业系统、机器人栈以及生产级代理框架中。

完整细节请参见 LICENSE 文件。有关许可范围和开源/商业边界，请参见 docs/license.md 和 docs/ip-boundary.md。

关于 Ragtime 的说明：ragtime/ 目录采用 Apache License 2.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 是由第三方在未经 Claude-Mem 事先同意的情况下创建的 Solana 代币，但已获得 Claude-Mem 创建者（Alex Newman，@thedotmack）的官方认可。该代币作为社区增长的催化剂，以及为最需要的开发者和知识工作者提供实时代理数据的载体。$CMEM：2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS

开源项目thedotmack2026-05-26原文

打开互动版