## 项目概述

Claude-Mem 是一个面向 AI 智能体的持久化记忆压缩系统，主要为 Claude Code 设计，也声明可用于 OpenClaw、Codex、Gemini、Hermes、Copilot、OpenCode 等场景。它通过生命周期钩子自动捕获会话中的工具使用情况，生成语义摘要，并在未来会话中注入相关上下文，从而让智能体在会话结束后仍能保持项目知识连续性。项目使用 JavaScript/TypeScript 实现，采用 Apache-2.0 许可证，最新 release 为 v13.15.0。

## 核心功能

- 持久记忆：跨会话保存上下文，使历史信息自动出现在新会话中。
- 渐进式披露（Progressive Disclosure）：分层记忆检索，并显示 token 成本。
- mem-search 技能：用自然语言查询项目历史。
- MCP 搜索工具：提供 `search`、`timeline`、`get_observations` 等工具，文档称通过先过滤再取详情可节省约 10 倍 token。
- Web 查看界面：worker 启动时输出 URL，可实时查看记忆流。
- 隐私控制：使用 `<private>` 标签排除敏感内容。
- 自动运行：无需人工干预。
- 引用与回溯：通过 ID 引用历史观察。
- OpenClaw 网关支持，可安装为 OpenClaw 的持久记忆插件。
- 云同步：可备份记忆到 cmem.ai，worker 在写入时同步。
- 多 IDE/代理支持：Claude Code、OpenCode、Antigravity CLI 等。
- 模式与语言配置：如 `code--zh` 简体中文模式、`code--ja` 日文模式等。

## 适用与不适用场景

适用场景：

- 使用 Claude Code 进行长期项目开发的开发者。
- 希望跨会话保留调试、代码修改、架构决策等上下文的团队。
- 需要从多个代理或 IDE 会话中积累项目记忆的用户。
- 对 token 成本敏感，希望通过分层检索减少上下文开销的场景。

不适用或需谨慎的场景：

- 需要严格企业级安全审计、多租户权限隔离的场景，仓库资料未提供完整安全模型。
- 对本地数据存储位置、向量库资源占用有严格合规要求时，需要自行评估。
- 不希望运行本地 worker、额外依赖 Bun、uv、Chroma 的环境。
- 大规模多用户并发、高可用集群的明确部署方案，仓库资料未提供完整说明。

## 技术架构与依赖

- 生命周期钩子：SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd 等。
- CLI 层：hook-command 事件编排。
- Worker Daemon：本地 HTTP API，包含 Web 查看器、SessionManager、SDKAgent、SearchManager 等。
- 存储层：SQLite（结构化数据）+ Chroma 向量数据库（语义搜索）。
- 搜索架构：全文检索 FTS5 + 向量检索的混合搜索。
- MCP Server：供 Claude Code 等客户端调用记忆搜索工具。
- 系统依赖：Node.js >= 20.0.0、Bun、uv、SQLite 3（内置）、Claude Agent SDK、Chroma。
- 仓库资料未提供完整的依赖版本锁定或资源占用基准。

## 安装与快速开始

默认安装：

```bash
npx claude-mem install
```

为 OpenCode 安装：

```bash
npx claude-mem install --ide opencode
```

为 Antigravity CLI 安装：

```bash
npx claude-mem install --ide antigravity
```

从 Claude Code 插件市场安装：

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

重启 Claude Code 后，先前会话的上下文会自动出现在新会话中。

注意：README 明确说明，`npm install -g claude-mem` 只安装 SDK/库，不会注册插件钩子或启动 worker 服务；应使用 `npx claude-mem install` 或 `/plugin` 命令安装。

OpenClaw 网关安装：

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

Windows 用户若遇到 `npm` 无法识别的问题，需要先安装 Node.js 并确保 npm 已加入 PATH。

## 典型使用方法

- 安装并重启后，历史会话上下文会自动注入新会话。
- 使用自然语言向 Claude 提问，mem-search 技能可查询项目历史。
- MCP 搜索工具推荐三层工作流：先 `search` 获取索引，再 `timeline` 查看时间上下文，最后 `get_observations` 按需获取完整详情。
- 隐私控制：在会话内容中使用 `<private>` 标签标记不希望被记录的信息。
- 模式与语言：编辑 `~/.claude-mem/settings.json`，设置 `"CLAUDE_MEM_MODE": "code--zh"` 后重启 Claude Code。
- 可在 Claude Desktop 会话中通过技能搜索记忆。
- 可通过 worker API 或 Web 查看界面引用历史观察 ID；更详细的 SDK 用法，仓库资料未提供。

## 配置与部署要点

- 配置文件默认位于 `~/.claude-mem/settings.json`，首次运行自动创建。
- 可配置项包括 AI 模型、worker 端口、数据目录、日志级别、上下文注入设置。
- 模式配置：`CLAUDE_MEM_MODE`，内置 `code`、`code--zh`、`code--ja`，语言模式遵循 `code--[lang]` 命名。
- API 鉴权：设置 `CLAUDE_MEM_AUTH_MODE=api-key` 后，需携带 `Authorization: Bearer <key>` 访问受保护端点。
- 可选环境变量：`CLAUDE_MEM_RATE_LIMIT_PER_MIN`、`CLAUDE_MEM_MONTHLY_REQUEST_CAP`、`CLAUDE_MEM_MONTHLY_TOKEN_CAP`、`CLAUDE_MEM_USAGE_METERING` 等，默认不启用。
- Docker 部署：根目录 `docker-compose.yml` 可启动 Claude-Mem Server beta 和 Valkey 侧车，并配置了 `CLAUDE_MEM_AUTH_MODE=api-key`、`CLAUDE_MEM_QUEUE_ENGINE=bullmq`、`CLAUDE_MEM_REDIS_URL=redis://valkey:6379` 等环境变量。
- 发布分支：`main` 为稳定分支并发布到 npm，`core-dev` 和 `community-edge` 为从源码运行的分支。

## 限制、风险与许可证

- 许可证：Apache-2.0。
- 项目需要本地运行 worker，并引入 Bun、uv、SQLite、Chroma 等组件；资源占用与性能基准，仓库资料未提供。
- 插件通过生命周期钩子在 Claude Code 环境中执行脚本，安装第三方插件或脚本需自行评估安全风险。
- 默认本地 worker 可能没有网络鉴权；若暴露到网络，需要配置 API 鉴权或放在代理后。
- 云同步、OpenClaw 网关等涉及第三方服务，需遵守相应服务条款。
- README 还提到第三方发行的 CMEM token 获作者官方认可，作为社区增长催化剂，但这不是本项目功能依赖。
- 关于许可范围的进一步说明见 `docs/license.md` 和 `docs/ip-boundary.md`。
- 数据保留策略、删除保证、完备的安全审计报告，仓库资料未提供。

## 官方链接

- GitHub：https://github.com/thedotmack/claude-mem
- 官方文档：https://docs.claude-mem.ai/
- 最新 Release：https://github.com/thedotmack/claude-mem/releases/tag/v13.15.0
- Discord：https://discord.com/invite/J4wttp9vDu
- 官方 X 账号：https://x.com/Claude_Memory
- 作者：Alex Newman（@thedotmack）

## 信息来源和分析时间

- 信息来源：GitHub 公开仓库 thedotmack/claude-mem，包括 README、docs/ 目录、api.md、architecture-overview.md、session_id_architecture.md、docker.md 等文档，以及最新 release 元数据。
- 仓库地址：https://github.com/thedotmack/claude-mem
- 最新 release：v13.15.0，发布于 2026-08-10T20:35:46Z。
- 分析时间：以该 release 发布时间为参考，未对运行行为做独立验证。