Claude 记忆管理工具

概述

Claude-Mem 是一个为 Claude Code 构建的持久化记忆压缩系统。它能够在会话之间自动捕获工具调用观测、生成语义摘要，并让未来的会话可以复用这些上下文，使 Claude 即使在会话结束或重连后也能保持对项目的连续认知。

快速开始

通过单条命令即可安装：

npx claude-mem install

安装器会自动完成所有配置，随后在浏览器中弹出登录页面（邮件魔法链接，无需信用卡）。登录后会为账号分配一个记忆密钥，并解锁 claude-mem observer 的 30 天免费试用。试用结束后，记忆功能会自动回退到 Anthropic 套餐，除非另行订阅。登录后可在三种记忆提供者中选择：claude-mem observer、自带的 OpenRouter 或 Gemini 密钥，或 Anthropic 套餐。

若希望跳过登录，可显式传入 --provider 标志、设置 CLAUDE_MEM_ONLINE_OPTIN=false，或在 CI、非交互式 shell 中运行，安装器将不会触发任何账号交互。

支持的其他 IDE 与工具链包括 OpenCode（1.3.4+）、T3 Code、Antigravity CLI、OMP、Pi 原生扩展、DeepSeek Harness 插件，以及 Grok Bot（通过 --ide grok-bot）。其中 Pi 与 DeepSeek Harness 使用 worker 运行时。

也可在 Claude Code 内部的插件市场中安装：

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

注意：直接 npm install -g claude-mem 仅安装 SDK/库，不会注册插件钩子或 worker 服务，请始终通过 npx claude-mem install 或 /plugin 命令安装。

对于 OpenClaw 网关，可使用一行脚本安装：

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

核心特性

• 持久化记忆：上下文跨会话存活
• 渐进式披露：分层检索记忆，并显示 token 成本
• 基于技能的搜索：通过 mem-search 技能查询项目历史
• Web 查看器：启动时打印的 worker URL 提供实时记忆流
• Claude Desktop 技能：可在 Claude Desktop 对话中检索记忆
• 隐私控制：使用 <private> 标签即可排除敏感内容
• 上下文配置：对注入的上下文进行细粒度控制
• 自动运行：无需人工干预
• 引用机制：通过 worker API 用 ID 引用历史观测，或在 Web 查看器中浏览

技术架构

核心组件包含：

1. 生命周期钩子：SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、SessionEnd。每个钩子对应一条 shell-free 命令 claude-mem hook claude-code <event>，由安装器放入 PATH 的小型启动器执行。
2. 智能安装：依赖检查器会缓存结果，钩入 claude --init / --maintenance，以及 npx claude-mem install / repair。
3. Worker 服务：本地 HTTP API，搭配 Web UI 与搜索端点，由 Bun 管理。
4. SQLite 数据库：用于存储会话、观测与摘要。
5. mem-search 技能：通过渐进式披露实现自然语言查询。
6. Chroma 向量数据库：混合语义搜索与关键词搜索。

MCP 搜索工具

Claude-Mem 提供 4 个 MCP 工具，遵循节省 token 的三层工作流：

• search：返回紧凑索引（每条约 50–100 token），支持按类型、日期、项目过滤
• timeline：围绕特定观测获取时间线上下文
• get_observations：仅按 ID 批量获取完整详情（每次约 500–1,000 token）

典型用法：

// 第一步：搜索索引
search(query="authentication bug", type="bugfix", limit=10)
// 第二步：审阅索引，挑选相关 ID（例如 #123、#456）
// 第三步：批量获取详情
get_observations(ids=[123, 456])

通过先过滤再获取详情的模式，可节省约 10 倍 token。

系统要求

• Node.js 20.0.0 或更高版本
• Claude Code 最新版本（需支持插件）
• Bun（缺失时自动安装）
• uv（缺失时自动安装）
• SQLite 3（已捆绑）

配置

设置文件位于 ~/.claude-mem/settings.json，首次运行时会自动创建。可配置 AI 模型、worker 端口、数据目录、日志级别与上下文注入行为。

若希望 SessionStart 上下文包含所有 harness 的观测，可设置 "CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES": "true"，或在查看器设置中启用对应选项。默认值为 "false"，仅注入当前 harness 的观测。

通过 CLAUDE_MEM_MODE 可切换工作流模式与生成观测所使用的语言，模式定义位于 plugin/modes/，语言相关模式遵循 code--[lang] 格式（如 code--zh 表示简体中文）。更改后需重启 Claude Code。

故障排除

遇到问题时，可在 Claude 中描述问题，技能会自动诊断并给出修复建议。Windows 用户若遇到 npm 未识别等错误，需确认 Node.js 与 npm 已安装并加入 PATH；钩子启动器位于 %LOCALAPPDATA%\claude-mem\bin\claude-mem.exe，安装器会自动加入用户 Path。仍有问题时可运行 npx claude-mem doctor。

许可证

采用 Apache License 2.0，理由是持久化的智能体记忆应便于嵌入开发工具、本地代理、MCP 服务器、企业系统、机器人栈与生产级 agent harness 中。ragtime/ 子目录同样遵循 Apache 2.0。