# Claude Mem

> 跨会话持久记忆系统：自动捕获、压缩和检索项目历史上下文，解决AI助手'失忆'问题。当用户说'之前我们做了什么'、'上次怎么解决的'、'记住这个'、'搜索历史记录'、'mem-search'、'查找之前的决策'、'之前修过的bug'时触发此Skill。核心特点：自动捕获无需手动、AI语义压缩、向量+全文检索、渐进式披露、支持敏感内容排除。

- Skill: `gaoqiongxie/claude-mem` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaoqiongxie/claude-mem`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaoqiongxie/claude-mem/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gaoqiongxie (https://skillmd.com/u/gaoqiongxie)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gaoqiongxie/claude-mem

---


> **来源**: [thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) ⭐ 65K+（单周 +12K，GitHub Trending #3）
>
> **发布时间**: 2026-04-29
>
> **理念**: "AI 不应该每次对话都从零开始。记忆是智能的基石。"

# 🧠 Claude 记忆系统

让 AI 记住你们一起做过的一切。跨会话、跨项目、跨时间。

---

## 🎯 核心能力

| 能力 | 说明 |
|------|------|
| **自动捕获** | 无需手动记录，自动保存会话中的关键信息 |
| **AI 压缩** | 将冗长对话压缩为语义摘要，节省存储 |
| **双向检索** | 向量语义搜索 + 全文关键词搜索 |
| **渐进披露** | 按相关性分层注入上下文，控制 Token 成本 |
| **隐私保护** | `<private>` 标签排除敏感内容 |
| **Web 查看器** | 实时查看记忆流（`http://localhost:37777`） |

---

## 🏗️ 技术架构

```
用户对话 → 捕获层 → 压缩层 → 存储层 → 检索层 → 注入层
            ↓         ↓         ↓         ↓         ↓
         钩子系统   Claude    SQLite   Chroma   渐进式
         自动触发   Agent SDK  + FTS5   向量库   披露
```

| 组件 | 技术 | 用途 |
|------|------|------|
| **捕获** | Claude Code Hooks | 会话开始/结束/工具调用时自动触发 |
| **压缩** | Claude Agent SDK | 将观察记录压缩为语义摘要 |
| **结构化存储** | SQLite + FTS5 | 全文搜索、时间线查询 |
| **语义存储** | Chroma | 向量相似度搜索 |
| **查看器** | Web UI | 实时查看和管理记忆 |

---

## 🚀 使用方式

### 方式一：自然语言查询

```
用户：上次我们怎么解决那个登录超时问题的？

→ 自动搜索记忆 → 找到相关 session → 注入上下文

用户：我之前让你记住的 API 设计原则是什么？

→ 语义搜索 "API 设计" → 返回之前确认的决策
```

### 方式二：结构化搜索（mem-search）

```
用户：搜索所有和 "支付" 相关的决策

→ 按类型过滤: decision + 概念: 支付

用户：找一下上周修过的 bug

→ 按时间线 + 类型: bugfix
```

### 方式三：查看时间线

```
用户：这个项目我们做过什么？

→ 按时间线展示所有 session 摘要
   Session 1: 项目初始化 + 架构决策
   Session 2: 用户模块开发 + JWT 方案选择
   Session 3: 支付接口调试 + 超时问题修复
```

---

## 🔍 搜索语法

### 按内容搜索
```
"如何实现缓存"           → 语义搜索
"cache implementation"   → 英文语义搜索
"关键词: Redis"           → 全文搜索
```

### 按类型过滤
| 类型 | 用途 |
|------|------|
| `decision` | 架构决策、技术选型 |
| `bugfix` | 问题修复记录 |
| `feature` | 新功能开发 |
| `refactor` | 重构记录 |
| `discovery` | 新发现、踩坑记录 |

### 按时间范围
```
"上周做的" → 最近 7 天
"上个月"   → 最近 30 天
"2026-04" → 指定月份
```

### 按文件关联
```
"和 auth.js 相关的改动"
"谁修改了这个文件"
```

---

## 📝 记忆记录格式

每次自动捕获的记忆包含：

```json
{
  "id": "obs_123456",
  "session_id": "sess_abc",
  "timestamp": "2026-04-29T10:30:00Z",
  "type": "decision",
  "content": "采用 Redis + Lua 脚本实现分布式锁",
  "context": "用户认证模块的并发控制",
  "files": ["src/auth/lock.js", "config/redis.js"],
  "tags": ["redis", "concurrency", "auth"]
}
```

---

## 🔒 隐私控制

### 排除敏感内容
在对话中使用 `<private>` 标签：

```
用户：我们的数据库密码是 <private>secret123</private>，帮我配置连接

→ 密码不会被记录到记忆中
```

### 手动标记
```
用户：这个信息不要记录 [PRIVATE]

→ 该段对话跳过捕获
```

---

## 🌐 Web 查看器

启动后访问 `http://localhost:37777`：

| 功能 | 说明 |
|------|------|
| **实时流** | 当前会话的记忆捕获实时显示 |
| **搜索** | 全局搜索所有历史记忆 |
| **时间线** | 按 session 查看历史 |
| **管理** | 删除、编辑、标记记忆 |
| **统计** | Token 使用量、存储占用 |

---

## 🆚 与现有记忆方案对比

| | claude-mem | memory-system | memory-bank |
|--|-----------|---------------|-------------|
| **自动化程度** | ⭐⭐⭐ 全自动 | ⭐⭐ 半自动 | ⭐ 手动维护 |
| **存储位置** | 本地 SQLite | 概念性指南 | 项目目录文件 |
| **检索方式** | 向量+全文 | 分类浏览 | 文件读取 |
| **跨项目** | ✅ | ❌ | ❌ |
| **Token 控制** | 渐进式披露 | ❌ | ❌ |
| **隐私保护** | ✅ <private> | ❌ | ❌ |
| **安装复杂度** | 中等（插件） | 低 | 低 |

**最佳实践**：
- `claude-mem` 用于自动捕获和检索项目历史
- `memory-bank` 用于手动维护项目核心文档（ADR、规范）
- `memory-system` 作为概念参考，了解记忆系统设计原理

---

## 💡 使用示例

### 示例1：找回之前的决策
```
用户：之前我们选的是 JWT 还是 Session？

助手：→ 搜索记忆（类型: decision, 关键词: auth）
     找到 2026-04-20 的记录：
     "采用 JWT + Refresh Token 方案，
      原因：无状态、适合微服务、减少 DB 查询"
```

### 示例2：避免重复踩坑
```
用户：这个 MySQL 锁表问题怎么解决？

助手：→ 搜索记忆（类型: bugfix, 关键词: MySQL lock）
     找到之前记录：
     "2026-04-15 遇到过类似问题，
      原因是事务隔离级别设置不当，
      解决方案：改为 READ COMMITTED + 索引优化"
```

### 示例3：项目 onboarding
```
用户：我刚加入这个项目，之前做过什么？

助手：→ 时间线展示所有 session 摘要
     Session 1-5: 项目初始化（技术栈、架构）
     Session 6-12: 核心模块开发
     Session 13-20: 测试和部署
```

---

## ⚙️ 安装说明

### Claude Code 插件
```bash
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
```

### 独立安装
```bash
npx claude-mem install
```

### 配置
```bash
# 查看记忆状态
mem status

# 手动搜索
mem search "Redis 缓存"

# 查看时间线
mem timeline

# 排除目录
mem config exclude_dirs "node_modules,dist,.git"
```

---

## 🔗 相关 Skill

| Skill | 用途 |
|-------|------|
| **memory-system** | 记忆系统设计原理（缓存/Session/消息队列） |
| **memory-bank** | 项目文档化记忆（ADR/规范/模板） |
| **systematic-debugging** | 结合历史记录进行调试 |

---

> "最好的记忆不是记住所有事情，而是在需要的时候想起正确的事情。"