Claude-Mem让你的claude code拥有记忆

给 Claude Code 装上"长期记忆"的持久化记忆系统

目录

• 一、简介
• 二、核心功能
• 三、工作原理
• 四、安装指南
• 五、使用方法
• 六、常见问题
• 七、相关资源

一、简介

什么是 Claude-Mem？

Claude-Mem 是一个 Claude Code 插件，由 Alex Newman (@thedotmack) 开发。它像一个"外挂大脑"一样，为 Claude Code 提供持久化的记忆能力。

解决什么问题？

问题场景 1：跨会话记忆丢失
┌─────────────────────────────────────────────────────────┐
│  会话 A: "帮我修复数据库连接问题"                          │
│    ↓                                                    │
│  关闭 Claude Code                                       │
│    ↓                                                    │
│  会话 B: "上次是怎么修复数据库的？"                       │
│    ❌ Claude: "我没有上次对话的记忆..."                   │
└─────────────────────────────────────────────────────────┘

安装 Claude-Mem 后：
┌─────────────────────────────────────────────────────────┐
│  会话 A: "帮我修复数据库连接问题"                          │
│    ✓ Claude-Mem 自动记录                                │
│    ↓                                                    │
│  关闭 Claude Code                                       │
│    ↓                                                    │
│  会话 B: "上次是怎么修复数据库的？"                       │
│    ✓ Claude: "根据记录，上次我们通过修改..."              │
└─────────────────────────────────────────────────────────┘

核心价值

二、核心功能

2.1 持久化记忆

• 自动保存所有工具调用和操作
• 跨会话保持上下文
• 支持多项目管理

2.2 AI 智能压缩

text
复制
原始数据 (可能很大)
      ↓
   AI 压缩处理
      ↓
精炼摘要 (保留关键信息)

2.3 语义搜索

基于 ChromaDB 向量数据库，支持自然语言搜索：

text
复制
查询: "上次怎么处理登录验证的？"
      ↓
语义匹配 (不只是关键词匹配)
      ↓
返回相关历史记录

2.4 Web 可视化界面

访问 http://localhost:37777 获得：

• 时间线视图
• 搜索和过滤
• 详细记录查看

三、工作原理

3.1 整体架构

mermaid
复制
graph TB
    A[Claude Code] -->|工具调用| B[Hook 系统]
    B -->|捕获事件| C[Claude-Mem Worker]
    C -->|AI 压缩| D[SQLite 存储]
    C -->|向量化| E[ChromaDB]
    C -->|MCP 协议| A
    F[Web UI] -->|HTTP| C

    style A fill:#dda0dd
    style C fill:#87ceeb
    style D fill:#90ee90
    style E fill:#ffa07a
    style F fill:#ffd700

3.2 数据流程

mermaid
复制
sequenceDiagram
    participant User as 用户
    participant Claude as Claude Code
    participant Hook as Claude-Mem Hook
    participant Worker as Worker 服务
    participant DB as 本地数据库

    User->>Claude: 执行操作
    Claude->>Hook: 触发工具调用
    Hook->>Worker: 发送事件数据
    Worker->>Worker: AI 压缩处理
    Worker->>DB: 存储记录
    Worker->>DB: 更新向量索引
    Worker-->>Claude: 确认完成

3.3 组件说明

四、安装指南

4.1 系统要求

4.2 快速安装

步骤 1：添加插件市场

bash
复制
# 没有启动claude在命令行执行
claude plugin marketplace add thedotmack/claude-mem
# 或者在启动claude后执行
/plugin marketplace add thedotmack/claude-mem

步骤 2：安装插件

bash
复制
# 没有启动claude在命令行执行
claude plugin install claude-mem
# 或者启动claude后执行
/plugin install claude-mem

步骤 3：重新打开 Claude Code

安装完后打开 Claude Code，首次启动会自动安装依赖，等待约 30 秒。

4.3在开发或测试中，你可以克隆并从源代码构建

shell
复制
# Clone git仓库
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem

# 安装依赖
npm install

# 构建 hooks 和 worker service
npm run build

# Worker 服务将在首次 Claude Code 会话时自动启动
# 或者手动启动:
npm run worker:start

# 验证服务是否正常
npm run worker:status

4.4 验证安装

bash
复制

#### 4.4.1 检查服务是否运行
lsof -i :37777

#### 4.4.2 自动依赖安装
依赖关系在插件安装过程中会自动安装。SessionStart 钩子还确保每次会话开始时依赖关系都是最新的（这既快速又冪起）。支持Windows、macOS和Linux的跨平台运行。

#### 4.4.3 验证插件安装
检查钩子是否已在Claude代码中配置：
```shell
cat plugin/hooks/hooks.json

4.4.4 数据目录位置

• 数据存储在：~/.claude-mem/
• 数据库：~/.claude-mem/claude-mem.db
• PID文件：~/.claude-mem/.worker.pid
• 移植文件：~/.claude-mem/.worker.port
• 日志：~/.claude-mem/logs/worker-YYYY-MM-DD.log
• 场景：~/.claude-mem/settings.json

4.4.5用环境变量覆盖：

shell
复制
export CLAUDE_MEM_DATA_DIR=/custom/path

4.4.6 检查工人日志

shell
复制
npm run worker:logs

4.4.7 测试上下文检索

shell
复制
npm run test:context

五、使用方法

5.1 Web UI 使用

访问 http://localhost:37777

┌────────────────────────────────────────────────────────────┐
│                      Claude-Mem Web UI                     │
├────────────────────────────────────────────────────────────┤
│  🔍 搜索: [________________]  过滤: [全部 ▼]              │
├────────────────────────────────────────────────────────────┤
│  时间线                                                    │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                            │
│  📅 2026-02-12                                            │
│  ├─ 14:30  修复数据库连接问题                              │
│  ├─ 15:20  添加用户认证功能                                │
│  └─ 16:45  部署到生产环境                                  │
│                                                            │
│  📅 2026-02-11                                            │
│  └─ 10:15  创建新项目                                      │
└────────────────────────────────────────────────────────────┘

5.2 在 Claude Code 中使用

安装后，Claude 会自动获得记忆能力。直接自然提问即可：

你: 我上次是怎么解决那个数据库超时问题的？

Claude: 根据记录，上次我们通过以下方式解决了数据库超时问题：
       1. 将连接池大小从 10 增加到 50
       2. 添加了查询超时设置 (30秒)
       3. 实现了重试机制...

六、常见问题

Q1: 为什么浏览器无法访问 localhost:37777？

A: 服务没有启动。检查并启动服务：

bash
复制
# 检查端口是否被占用
lsof -i :37777
#或者
npm run worker:status
# 启动服务
npm run worker:start

Q2: 安装后首次启动很慢？

A: 正常现象。首次启动需要安装依赖（pm2、better-sqlite3），约需 30 秒。

Q3: 数据存储在哪里？

A: 所有数据存储在本地，默认位置：

bash
复制
~/.claude/plugins/cache/thedotmack/claude-mem/10.0.4(版本不一样这个目录就不同)

不会上传到任何云端服务器。

Q4: 如何清除所有记忆？

A: 停止服务后删除数据目录：

bash
复制
npm run worker:stop
rm -rf ~/.claude/plugins/cache/thedotmack/claude-mem/10.0.4/data/
npm run worker:start

Q5: 支持多台电脑同步吗？

A: 默认不支持（数据在本地）。如需同步，可以自行配置数据目录的云同步方案。

七、相关资源

附录：架构流程图

完整数据流程

mermaid
复制
flowchart TD
    subgraph Input ["输入层"]
        A1[用户输入]
        A2[工具调用]
        A3[代码变更]
    end

    subgraph Process ["处理层"]
        B1[Hook 捕获]
        B2[事件队列]
        B3[AI 压缩]
        B4[向量化]
    end

    subgraph Storage ["存储层"]
        C1[SQLite]
        C2[ChromaDB]
        C3[文件系统]
    end

    subgraph Output ["输出层"]
        D1[Web UI]
        D2[MCP 查询]
        D3[状态栏]
    end

    A1 --> B1
    A2 --> B1
    A3 --> B1
    B1 --> B2
    B2 --> B3
    B2 --> B4
    B3 --> C1
    B4 --> C2
    C1 --> D1
    C2 --> D2
    C1 --> D3

    style Input fill:#e1f5fe
    style Process fill:#fff3e0
    style Storage fill:#e8f5e9
    style Output fill:#f3e5f5

文档版本: 1.0 更新日期: 2026-02-12 适用版本: Claude-Mem 10.0.4