Claude-Mem 完整教程

项目仓库: thedotmack/claude-mem

---

📝 前言

Claude-Mem 是一个为 Claude Code 打造的持久化记忆系统，它能够自动捕获 Claude 在编码会话中的所有操作，通过 AI 进行压缩，并在未来的会话中注入相关上下文。这使得 Claude 能够保持对项目的持续理解，即使会话结束或重新连接也能保持知识的连贯性。

---

二、核心功能

2.1 持久化记忆系统

Claude-Mem 无缝保留跨会话的上下文：

• 自动捕获工具使用观察
• 生成语义摘要
• 使其对未来会话可用

工作流程： 1. 会话开始时，Claude 自动加载历史记忆 2. 会话中持续捕获关键操作 3. 会话结束时生成摘要并存储 4. 下次会话自动恢复上下文

2.2 渐进式披露 (Progressive Disclosure)

分层记忆检索策略，优化 token 使用：

层级	描述	Token 消耗
搜索	获取紧凑索引和 ID	~50-100 tokens/结果
时间线	获取特定结果周围的时间上下文	中等
完整观察	仅获取筛选后的完整详情	~500-1000 tokens/结果

优势: 通过先筛选再获取详情，实现约 10 倍 的 token 节省。

2.3 搜索工具

Claude-Mem 提供 4 个 MCP 工具 用于智能记忆搜索：

search - 搜索记忆索引

// 搜索记忆索引
search(query="authentication bug", type="bugfix", limit=10)

功能： - 全文查询 - 按类型/日期/项目过滤 - 返回紧凑索引和 ID

timeline - 获取时间上下文

// 获取特定观察周围的时间上下文
timeline(observation_id=123)

功能： - 获取 chronological 上下文 - 了解特定结果周围发生了什么

get_observations - 获取完整观察

// 批量获取完整观察详情
get_observations(ids=[123, 456])

功能： - 通过 ID 获取完整详情 - 始终批量多个 ID 以优化效率

2.4 Web Viewer UI

访问 http://localhost:37777 查看：

• 实时记忆流
• 所有观察记录
• 搜索界面
• 设置面板
• Beta 功能 (如 Endless Mode)

2.5 隐私控制

使用 <private> 标签排除敏感内容：

这是一个普通记录，会被保存

<private>
这个内容不会被保存到记忆系统
</private>

---

三、安装方法

3.1 快速安装 (推荐)

在 Claude Code 终端中运行：

/plugin marketplace add thedotmack/claude-mem

/plugin install claude-mem

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

注意: Claude-Mem 也发布在 npm 上，但 npm install -g claude-mem 仅安装 SDK/库，不会注册插件钩子或设置 worker 服务。如需将 Claude-Mem 作为插件使用，请始终通过上述 /plugin 命令安装。

3.2 OpenClaw Gateway 安装

在 OpenClaw 网关上安装为持久化记忆插件：

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

安装程序处理： - 依赖项 - 插件设置 - AI provider 配置 - Worker 启动 - 可选的实时观察推送 (Telegram, Discord, Slack 等)

3.3 系统要求

• Node.js: 18.0.0 或更高
• Claude Code: 最新版本 (支持插件)
• Bun: JavaScript 运行时和进程管理器 (缺失时自动安装)
• uv: Python 包管理器，用于向量搜索 (缺失时自动安装)
• SQLite 3: 持久化存储 (已打包)

---

四、使用方法

4.1 自动运行

Claude-Mem 全自动运行，无需手动干预：

1. 会话开始: 自动加载历史记忆
2. 会话进行: 自动捕获关键操作
3. 会话结束: 自动生成摘要并存储

4.2 搜索技能

使用 mem-search skill 进行自然语言查询：

# 在 Claude Code 中
使用 mem-search 搜索之前修复的登录 bug

4.3 MCP 工具使用示例

// 步骤 1: 搜索获取索引
search(query="authentication bug", type="bugfix", limit=10)

// 步骤 2: 审查索引，识别相关 ID (如 #123, #456)

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

4.4 Web Viewer 使用

1. 打开浏览器访问 http://localhost:37777
2. 查看实时记忆流
3. 搜索历史记录
4. 配置设置
5. 切换 Beta 功能

---

五、配置

5.1 配置文件位置

~/.claude-mem/settings.json (首次运行自动创建)

5.2 可配置选项

• AI Model: 选择用于摘要的模型
• Worker Port: Web 服务端口 (默认 37777)
• Data Directory: 数据存储目录
• Log Level: 日志级别
• Context Injection: 上下文注入设置

5.3 环境变量

# 设置 API Key
ANTHROPIC_API_KEY=your_api_key

# 设置端口
CMEM_PORT=37777

# 设置数据目录
CMEM_DATA_DIR=~/.claude-mem

---

六、架构详解

6.1 核心组件

1. 5 个生命周期钩子: SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd
2. Smart Install: 缓存依赖检查器
3. Worker Service: HTTP API (端口 37777) + Web Viewer UI
4. SQLite 数据库: 存储会话、观察、摘要
5. mem-search Skill: 自然语言查询 + 渐进式披露
6. Chroma 向量数据库: 混合语义 + 关键词搜索

6.2 数据流

用户会话 → 生命周期钩子 → Worker Service → SQLite/Chroma → 存储
                                                        ↓
新会话 ← 上下文注入 ← 搜索检索 ← Worker Service ← 查询

---

七、最佳实践

7.1 隐私保护

• 使用 <private> 标签保护敏感信息
• 定期清理不需要的记忆
• 配置注入过滤规则

7.2 高效搜索

1. 先使用 search 获取索引
2. 审查结果，筛选相关 ID
3. 使用 get_observations 获取完整详情

7.3 Token 优化

• 利用渐进式披露策略
• 批量获取而非单个获取
• 设置适当的 limit 参数

---

八、相关资源

官方文档

• 官方文档网站
• GitHub 仓库
• 问题反馈

社区

• Discord
• X (Twitter)

相关项目

• Awesome Claude Code - Claude Code 资源精选

---

九、结语

Claude-Mem 为 Claude Code 带来了真正的持久化记忆能力，让 AI 能够在会话之间保持上下文连贯性。通过智能的记忆压缩和渐进式披露策略，它在保持高效的同时提供了强大的历史查询能力。

小贴士: Claude-Mem 最适合处理长期项目的上下文管理。对于一次性任务，使用纯会话模式即可。

---

Happy Memory Coding! 🧠💾