thedotmack / claude-mem

thedotmack/claude-mem

open_in_new前往仓库

为每个代理提供跨会话的持久上下文——捕获代理在会话中的所有操作，通过AI压缩，并将相关上下文注入未来会话。支持Claude Code、OpenClaw、Codex、Gemini、Hermes、Copilot、OpenCode等。

项目概览

项目概述

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。
  • 仓库资料未提供完整的依赖版本锁定或资源占用基准。

安装与快速开始

默认安装：

npx claude-mem install

为 OpenCode 安装：

npx claude-mem install --ide opencode

为 Antigravity CLI 安装：

npx claude-mem install --ide antigravity

从 Claude Code 插件市场安装：

/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 网关安装：

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 公开仓库 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 发布时间为参考，未对运行行为做独立验证。