thedotmack/claude-mem · 上手攻略

  • 仓库：thedotmack/claude-mem
  • 链接：https://github.com/thedotmack/claude-mem
  • 分类：agent（Agent 记忆持久化）
  • 作者：Tom
  • 更新：2026-07-06

这是什么

claude-mem 是给 AI 编码 Agent 用的跨会话持久记忆系统，解决 AI Agent 的"失忆症"问题：每次开新会话，Agent 对之前做了什么一无所知——之前的 bug 修法、踩过的坑、项目结构，一概重新学起。

它的原理是：在会话过程中自动捕获 Agent 的所有操作、工具调用和观察结果，用 AI 压缩后存入本地数据库（SQLite + Chroma 向量库），下次开新会话时自动注入相关记忆，让 Agent 真正拥有项目连续性。

支持 Claude Code、OpenClaw、Codex、Gemini、Hermes、Copilot、OpenCode 等多种 Agent。（⚠️ Stars：约 8.6 万；搜索结果曾记录 7.4 万，近期在快速增长中。）

解决什么问题

典型场景：连续三天用 Claude Code 构建某个功能，第三天继续时 Agent 已经忘记第一天的架构决策、第二天踩过的坑、哪些 API 调用失败过。Agent 每次都是从零开始。

claude-mem 把这个问题结构化了：它不是简单记录聊天历史，而是把 Agent 的行为和观察结构化为可检索的记忆单元（observations），并通过 3 层递进检索（search → timeline → get_observations）控制 Token 消耗。

快速安装

方式一：npx 一键安装（推荐）

npx claude-mem install

重启 Claude Code，即可在新会话中看到之前会话的记忆。

方式二：Claude Code 插件市场

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

然后重启 Claude Code。

方式三：OpenClaw 集成

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

一键在 OpenClaw 网关上安装，支持配置 AI 提供商、Telegram/Discord/Slack 实时推送等。

方式四：OpenCode

npx claude-mem install --ide opencode

方式五：Antigravity CLI

npx claude-mem install --ide antigravity

详见：Antigravity CLI Setup Guide

核心用法

前提条件

依赖 说明
Node.js 20.0.0+ 运行时
Claude Code（最新版） 需要插件支持
Bun JavaScript 运行时和服务管理器（自动安装）
uv Python 包管理器，向量搜索用（自动安装）
SQLite 3 持久存储（bundled）

⚠️ 注意：npm install -g claude-mem 只装 SDK，不注册插件 Hook 和 Worker 服务。必须用 npx claude-mem install 或 /plugin 命令安装。

安装后的自动行为

安装并重启 Claude Code 后，claude-mem 会在后台自动运行：

  • SessionStart Hook：加载相关记忆
  • PostToolUse Hook：捕获工具使用，生成 observation
  • SessionEnd Hook：压缩本次会话，写入数据库

Web 观测界面

启动后访问 http://localhost:37777 查看记忆流和观测记录。

记忆检索三层流程（Token 高效用法）

// 第1步：搜索索引（轻量，~50-100 tokens/result）
search(query="authentication bug", type="bugfix", limit=10)
// → 返回 compact index with IDs

// 第2步：看时间线上下文（中等）
timeline(observation_id=123)
// → 获取该 observation 前后发生了什么

// 第3步：按 ID 取完整记录（按需，~500-1000 tokens/result）
get_observations(ids=[123, 456])
// → 取回过滤后的完整详情

这个设计让 Agent 可以先广泛搜索再聚焦细节，避免一次性把整个记忆库都塞进 Context。

MCP 工具一览

工具 用途
search 全文搜索 + 过滤（按类型/日期/项目）
timeline 获取某个 observation 的时间上下文
get_observations 按 ID 批量取完整记录

多语言模式

编辑 ~/.claude-mem/settings.json：

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

可用模式包括：code（默认英文）、code--zh（简体中文）、code--ja（日语）等，按 ISO 639-1 语言代码命名。

Beta 功能：Endless Mode

在 http://localhost:37777 → Settings 中可切换到 Beta 频道，开启 Endless Mode（仿生记忆架构，适合超长会话）。详见：Beta Features 文档

配置管理

配置文件：~/.claude-mem/settings.json（首次运行自动创建含默认值的版本）。

可配置项：AI 模型、Worker 端口、数据目录、日志级别、上下文注入规则。

详见：Configuration Guide

典型适用场景

长期项目维护

一个维护超过 3 个月的后端项目，Agent 每次新会话都要重新理解代码结构。claude-mem 让 Agent 记住之前重构了什么、哪里有技术债、哪些依赖升级过。

多 Agent 协作的记忆共享

多个 Agent（Claude Code、Codex、Gemini）可以共用同一份记忆库，让团队级 AI 协作成为可能。

Bug 追踪

每次遇到 Bug 的分析过程都被记录，下次遇到相似错误时 Agent 可以直接检索历史 Observation，而不是重新调试。

知识积累

随着项目推进，claude-mem 积累的 Observation 实际上形成了一个项目专属知识库，包含真实的决策过程和失败教训，比文档更真实。

坑与注意

  1. 全局安装不等于插件安装：如上所述，npm install -g claude-mem 只是 SDK，不是插件。遇到 Hook 不生效，先确认安装方式。

  2. Token 消耗意识：虽然有 3 层检索减少 Token，但大量 Observation 累积后，检索结果仍可能很大。建议定期清理无用 Observation（通过 Web UI http://localhost:37777）。

  3. 隐私标签：支持用标签排除敏感内容（如 #private），但需 Agent 主动打标签使用，不能自动识别。敏感项目注意主动标注。

  4. Chromadb 自托管：向量数据库默认是 Chroma（本地），支持 Docker 部署。v13.1.0 新增 Postgres + BullMQ 的 server-beta 运行时，适合团队场景但需要额外配置。

  5. Bun 依赖：Worker 服务用 Bun 管理，如果本机没有 Bun，首次安装会自动拉取。离线环境可能需要预先安装 Bun。

  6. 中文模式要手动开启：默认是英文，中文模式需在 settings.json 中手动配置 CLAUDE_MEM_MODE: "code--zh"。

与同类对比

工具 定位 优势 不足
claude-mem Agent 跨会话记忆 专为 Agent 设计，3层检索节省Token，Hook自动捕获 依赖特定 Agent，生态限于 Claude 系
claude-code 原生记忆 Agent 内置记忆 无需安装 无法持久化到新会话，功能简单
Ruflo memory Ruflo 框架内置 与 Ruflo 蜂群协作强集成 需安装完整 Ruflo，复杂度高
OpenMemory 通用记忆系统 通用性强 非专为编码 Agent 设计
Notion AI 文档记忆 人类可读，协作友好 Agent 无法自动写入，需要人工整理

claude-mem 是目前最专注编码 Agent 记忆持久化的工具，Hook 自动化程度高，3 层检索设计在 Token 成本意识上领先同类。

一句话推荐结论

如果你每天用 Claude Code 处理超过 30 分钟的项目，装 claude-mem 是最有价值的"升级"——它让 AI Agent 从"每次失忆"变成"真正了解你的项目"，相当于给 Claude Code 配了一个永不遗忘的搭档。