【GitHub】Claude-Mem 深度解析：为 Claude Code 装上"永久记忆脑"

作者前言： 如果你曾经在使用 Claude Code 时感到沮丧------每次新会话都要重新解释项目背景、重复之前的决策、忘记上周修复的 Bug 细节------那么 Claude-Mem 就是为你准备的。这个拥有 17k+ Star 的开源项目，正在重新定义 AI 辅助编程的边界。

[一、为什么需要 Claude-Mem？](#一、为什么需要 Claude-Mem？ "#%E4%B8%80%E4%B8%BA%E4%BB%80%E4%B9%88%E9%9C%80%E8%A6%81-claude-mem")
[二、Claude-Mem 是什么？](#二、Claude-Mem 是什么？ "#%E4%BA%8Cclaude-mem-%E6%98%AF%E4%BB%80%E4%B9%88")
三、核心功能特性详解
四、技术架构深度解析
五、安装与配置完全指南
六、实战场景演示
七、高级功能与最佳实践
[八、与原生 Claude Code 的对比](#八、与原生 Claude Code 的对比 "#%E5%85%AB%E4%B8%8E%E5%8E%9F%E7%94%9F-claude-code-%E7%9A%84%E5%AF%B9%E6%AF%94")
九、总结与展望

一、为什么需要 Claude-Mem？

1.1 AI 的"失忆症"痛点

在使用 Claude Code 进行开发时，你或许遇到过这些场景：

markdown 复制代码

场景一：周一你花了一小时向 Claude 解释项目架构、数据库表结构、
       编码规范。周五再次打开项目，Claude 完全不记得这些上下文。

场景二：上周你和 Claude 一起修复了一个棘手的并发 Bug，
       今天类似问题再次出现，Claude 却无法参考之前的解决方案。

场景三：团队成员用 Claude 完成了一个复杂功能，
       其他成员无法从 Claude 中获得任何关于这个功能的背景知识。

根本问题：Claude Code 的上下文窗口在会话结束后完全清空，无法跨会话保留记忆。

1.2 现有解决方案的局限

方案	局限性
手动维护 CLAUDE.md	需要人工整理，容易过时，无法捕获细节
复制粘贴历史记录	繁琐、不可持续、信息丢失严重
商业记忆服务	价格昂贵、隐私风险、 vendor lock-in

Claude-Mem 的出现，正是为了解决这些痛点。

二、Claude-Mem 是什么？

2.1 项目概览

项目信息	详情
项目名称	claude-mem
开发者	thedotmack
GitHub 地址	github.com/thedotmack/...
官方网站	claude-mem.ai
开源协议	AGPL-3.0
Star 数量	17k+
主要语言	TypeScript/JavaScript
最新版本	v10.3.1（2026年2月）
系统支持	Windows / macOS / Linux

2.2 一句话定义

Claude-Mem 是一个专为 Claude Code 设计的持久化记忆压缩系统，通过自动捕获工具使用观察、生成语义摘要，并将其注入未来会话，实现真正的跨会话上下文连续性。

2.3 核心价值主张

less 复制代码

传统 Claude Code:  [会话1] *** 遗忘 *** [会话2] *** 遗忘 *** [会话3]
                                                         
安装 Claude-Mem:   [会话1] → [记忆存储] → [会话2] → [记忆存储] → [会话3]
                    ↑____________自动注入____________↑

三、核心功能特性详解

3.1 持久化记忆（Persistent Memory）

工作原理：

会话期间，Claude-Mem 通过生命周期钩子自动捕获所有工具调用
会话结束时，AI 自动生成语义摘要
新会话启动时，相关记忆自动注入上下文

效果：

新功能开发时间缩短 40%
新成员上手时间从 3周 → 3天

3.2 渐进式披露（Progressive Disclosure）

这是 Claude-Mem 的核心设计哲学，灵感来自人类记忆的工作方式。

三层检索策略

bash 复制代码

第一层：索引层（轻量级）
├── 观察记录标题
├── 类型标签（bugfix/feature/decision）
├── 时间戳
└── Token 成本：~50-100 tokens/结果

第二层：上下文层（按需加载）
├── 时间线上下文
├── 相关代码片段
└── Token 成本：~200-500 tokens/结果

第三层：完整细节层（精确回忆）
├── 完整的工具输出
├── 原始代码片段
└── Token 成本：~500-1000 tokens/结果

优势：相比传统一次性加载所有上下文，节省约 10倍 Token。

3.3 智能语义搜索

Claude-Mem 提供自然语言搜索能力，无需记住精确的关键词。

搜索示例

javascript 复制代码

// 方式一：自然语言查询（推荐）
"上次我们如何修复了身份验证的 Bug？"
"我们之前关于数据库索引的决策是什么？"
"这个模块之前做过类似的重构吗？"

// 方式二：结构化搜索（精确控制）
search(
  query: "authentication bug",
  type: "bugfix",
  limit: 10
)

// 方式三：时间线查询
timeline(sessionId: "abc-123")

搜索类型支持

搜索类型	说明	示例
概念标签搜索	按主题查找	"关于 API 设计的讨论"
文件引用搜索	按文件查找	"worker-service.ts 的修改记录"
观察类型搜索	按类型筛选	"显示所有 bugfix 记录"
时间线搜索	按会话查看	"上周一的会话内容"

3.4 可视化 Web 管理界面

安装后访问 http://localhost:37777 即可使用。

界面功能

ini 复制代码

┌─────────────────────────────────────────────────────┐
│           Claude-Mem Web Viewer                     │
├─────────────────────────────────────────────────────┤
│ [仪表板] [搜索] [会话] [设置]                       │
│                                                     │
│ 最近记忆:                                           │
│ 🔴 [Critical] 修复了支付接口并发问题 - 2小时前      │
│ 🟤 [Decision] 选择 PostgreSQL 作为主数据库 - 昨天   │
│ 🔵 [Info] 添加了用户注册 API - 3天前               │
│                                                     │
│ 统计信息:                                           │
│ 总观察记录: 1,247                                   │
│ 总会话数: 89                                        │
│ 数据库大小: 45.7 MB                                 │
└─────────────────────────────────────────────────────┘

3.5 隐私保护机制

Claude-Mem 提供多层隐私保护：

隐私标签

html 复制代码

<private>
数据库密码：supersecret123
API 密钥：sk_live_abc123
内部服务器地址：192.168.1.100
</private>

被 <private> 标签包裹的内容不会被记录。

工具过滤配置

json 复制代码

// ~/.claude-mem/settings.json
{
  "skipTools": [
    "ListMcpResourcesTool",
    "SlashCommand", 
    "AskUserQuestion"
  ]
}

配置后，这些工具的执行结果不会被记录。

四、技术架构深度解析

4.1 系统架构图

scss 复制代码

┌─────────────────────────────────────────────────────────────┐
│                     Claude Code 会话                         │
│  (用户输入 → Claude 处理 → 工具调用 → 结果返回)              │
└─────────────────────────────────────────────────────────────┘
                           ↓ 触发
┌─────────────────────────────────────────────────────────────┐
│                  生命周期钩子 (Lifecycle Hooks)               │
│  SessionStart │ UserPromptSubmit │ PostToolUse │ Stop        │
└─────────────────────────────────────────────────────────────┘
                           ↓ 捕获
┌─────────────────────────────────────────────────────────────┐
│                  Worker 服务 (端口 37777)                    │
│  ├── HTTP API 服务器                                       │
│  ├── 观察记录处理器                                         │
│  ├── AI 摘要生成器                                         │
│  └── 搜索索引维护                                           │
└─────────────────────────────────────────────────────────────┘
                           ↓ 存储
┌─────────────────────────────────────────────────────────────┐
│                  双数据库存储系统                             │
│  ┌─────────────┐    ┌─────────────────────────────┐       │
│  │  SQLite DB  │    │   Chroma 向量数据库          │       │
│  │  (结构化)    │    │   (语义搜索)                │       │
│  │  · 观察记录  │    │   · 向量嵌入                │       │
│  │  · 会话信息  │    │   · 语义索引                │       │
│  │  · 摘要      │    │   · 混合搜索                │       │
│  └─────────────┘    └─────────────────────────────┘       │
└─────────────────────────────────────────────────────────────┘
                           ↓ 注入
┌─────────────────────────────────────────────────────────────┐
│               下次会话启动时自动注入上下文                      │
│  "根据您之前的工作，我注意到您正在继续开发..."                 │
└─────────────────────────────────────────────────────────────┘

4.2 五大生命周期钩子详解

钩子名称	触发时机	执行内容	技术实现
SessionStart	Claude Code 启动	启动 Worker 服务，检索最近观察记录，注入相关上下文	调用 `/api/session/start`
UserPromptSubmit	用户发送消息	记录用户原始提示，关联当前会话	写入 SQLite `prompts` 表
PostToolUse	工具执行完成	捕获工具名称、参数、输出、执行时间	JSON 格式存储到 `observations` 表
Stop	Claude 停止任务	生成当前会话的 AI 驱动摘要	调用 Claude API 生成摘要
SessionEnd	会话完全结束	标记会话完成，确保数据持久化	更新会话状态为 `completed`

4.3 双数据库存储设计

SQLite 数据库（结构化存储）

位置：~/.claude-mem/claude-mem.db

核心表结构：

sql 复制代码

-- 会话表
CREATE TABLE sessions (
    id TEXT PRIMARY KEY,
    start_time INTEGER,
    end_time INTEGER,
    summary TEXT,
    project_path TEXT
);

-- 观察记录表（支持全文搜索）
CREATE VIRTUAL TABLE observations USING fts5(
    id,
    session_id,
    tool_name,
    input,
    output,
    timestamp,
    type,
    content='observations_content'
);

-- 摘要表
CREATE TABLE summaries (
    id TEXT PRIMARY KEY,
    session_id TEXT,
    content TEXT,
    model_used TEXT,
    generated_at INTEGER
);

Chroma 向量数据库（语义搜索）

位置：~/.claude-mem/chroma/

功能：

存储观察记录的向量嵌入（embedding）
支持混合语义 + 关键词搜索
根据含义（而非仅关键词）查找相关内容

搜索流程：

css 复制代码

用户查询 → 生成查询向量 → Chroma 相似度搜索 → 返回 Top-K 结果

4.4 AI 压缩引擎

Claude-Mem 使用 AI 模型对原始观察记录进行智能压缩。

压缩策略

scss 复制代码

原始观察记录 (可能 10,000+ tokens)
    ↓ AI 压缩
语义摘要 (约 500-1000 tokens)
    ↓ 提取
关键学习点 (约 100-200 tokens)

观察记录结构

json 复制代码

{
  "id": "obs_abc123",
  "sessionId": "sess_xyz789",
  "toolName": "Edit",
  "input": {
    "filePath": "src/auth.ts",
    "oldString": "...",
    "newString": "..."
  },
  "output": "File edited successfully.",
  "timestamp": 1709875200000,
  "type": "code_change",
  "summary": "修复了身份验证中间件的逻辑错误"
}

五、安装与配置完全指南

5.1 系统要求

依赖项	最低要求	推荐配置
Node.js	18.0.0+	22.x LTS
Claude Code	支持插件的最新版	最新版
Bun 运行时	自动安装	v1.0+
uv (Python)	自动安装	v0.1+
RAM	4GB	8GB+
磁盘空间	100MB	1GB+

5.2 安装方式一：插件市场安装（推荐）

bash 复制代码

# 步骤1：启动 Claude Code
claude

# 步骤2：添加插件市场
/plugin marketplace add thedotmack/claude-mem

# 步骤3：安装插件
/plugin install claude-mem

# 步骤4：重启 Claude Code
# (将自动启动 Worker 服务)

安装后验证：

bash 复制代码

# 检查 Worker 服务是否运行
curl http://localhost:37777/api/health

# 预期输出
{
  "status": "ok",
  "version": "10.3.1",
  "database": "connected"
}

5.3 安装方式二：源码安装（开发者选项）

bash 复制代码

# 克隆仓库
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem

# 安装依赖
npm install

# 构建项目
npm run build

# 启动 Worker 服务
npm run worker:start

# 查看实时日志
npm run worker:logs

5.4 配置详解

配置文件位置

javascript 复制代码

~/.claude-mem/settings.json

完整配置示例

json 复制代码

{
  "provider": "claude",
  "model": "claude-sonnet-4-5-20250929",
  "workerPort": 37777,
  "dataDir": "~/.claude-mem",
  "logLevel": "info",
  "contextObservations": 10,
  "skipTools": [
    "ListMcpResourcesTool",
    "SlashCommand"
  ],
  "privacyTags": ["<private>", "<secret>"],
  "compressionEnabled": true,
  "semanticSearchEnabled": true,
  "autoContextInjection": true
}

配置参数说明

参数	类型	默认值	说明
`provider`	string	"claude"	AI 服务提供商
`model`	string	"claude-sonnet-4-5"	摘要生成使用的模型
`workerPort`	number	37777	Worker 服务端口
`dataDir`	string	"~/.claude-mem"	数据目录
`logLevel`	string	"info"	日志级别 (error/warn/info/debug)
`contextObservations`	number	10	每次注入的观察记录数量
`compressionEnabled`	boolean	true	是否启用 AI 压缩
`semanticSearchEnabled`	boolean	true	是否启用语义搜索

5.5 环境变量配置

bash 复制代码

# 自定义数据目录
export CLAUDEMEM_DATA_DIR="/path/to/custom/dir"

# 自定义 Worker 端口
export CLAUDEMEM_PORT=37778

# 自定义日志级别
export CLAUDEMEM_LOG_LEVEL="debug"

# 指定 AI 提供商
export CLAUDEMEM_AI_PROVIDER="claude"

六、实战场景演示

6.1 场景一：长期项目的上下文连续性

第一次会话：项目初始化

bash 复制代码

$ claude
> 帮我创建一个美发预约系统，需要：
> 1. 用户注册登录（JWT 认证）
> 2. 服务项目管理
> 3. 在线预约功能
> 4. 管理员仪表板

Claude 完成开发后，Claude-Mem 自动记录：

项目架构决策
数据库表结构设计
API 端点定义
关键代码实现

第二次会话：功能扩展（一周后）

bash 复制代码

$ claude
> 早上好！我们之前做了什么项目？

Claude 的回答（由 Claude-Mem 注入的上下文支持）：

bash 复制代码

根据之前的会话记录，我们创建了一个美发预约系统，包括以下模块：
1. 认证模块 (src/auth/) - 使用 JWT 认证
2. 服务管理模块 (src/services/) - 支持 CRUD 操作
3. 预约模块 (src/bookings/) - 支持时间冲突检测
4. 管理员模块 (src/admin/) - 提供仪表板 API

现在您可以继续开发，我会参考之前的架构决策...

6.2 场景二：Bug 修复的历史参考

问题场景

markdown 复制代码

你：这个并发问题之前好像遇到过，当时是怎么解决的？
Claude：(通过 claude-mem 搜索)

根据 2026-02-15 的记录，您之前遇到过类似的并发问题：

问题：支付接口的并发重复扣款
解决方案：
1. 添加数据库行级锁 (SELECT ... FOR UPDATE)
2. 实现幂等性令牌机制
3. 添加 Redis 分布式锁作为二级保护

相关文件：src/payments/processor.ts
提交的修复：commit a1b2c3d

6.3 场景三：团队协作知识共享

Claude-Mem 支持项目级记忆共享。

配置项目级记忆

bash 复制代码

# 在项目根目录创建配置
echo '{
  "claudeMem": {
    "scope": "project",
    "shareWith": ["team-member1", "team-member2"]
  }
}' > .claude-mem.json

效果

makefile 复制代码

开发者A: 完成了用户认证模块的重构
           ↓
Claude-Mem 记录重构决策、新架构、迁移步骤
           ↓
开发者B: (一周后) 需要理解新的认证流程
           ↓
Claude: (通过项目级记忆) 自动提供完整背景

七、高级功能与最佳实践

7.1 无尽模式（Endless Mode）

问题背景

标准 Claude Code 会话的限制：

约 50 次工具调用后达到上下文限制
每个工具输出可能包含 1,000-10,000+ tokens
复杂度：O(N²)（每次响应需重新合成所有历史）

无尽模式的解决方案

ini 复制代码

传统模式:
[工具1输出] → [工具2输出] → [工具3输出] → ... → 上下文溢出

无尽模式:
[工作记忆] ← 压缩 → [存档记忆(磁盘)]
    ↓                        ↓
当前上下文            按需召回

性能对比

指标	标准模式	无尽模式
上下文窗口使用	~100% (50工具后)	~5%
支持的工具体数	~50	~1000+
复杂度	O(N²)	O(N)
观察记录大小	10,000+ tokens	~500 tokens (压缩后)

启用无尽模式

markdown 复制代码

1. 访问 http://localhost:37777
2. 点击 "Settings"
3. 找到 "Endless Mode (Beta)"
4. 切换开关启用

注意：无尽模式目前处于 Beta 阶段，每个工具观察生成可能有 60-90 秒延迟。

7.2 分布式上下文生成

Claude-Mem 集成了 Live Context 系统 ，支持自动生成和维护 CLAUDE.md。

自动生成示例

bash 复制代码

# 在项目根目录运行
> 请帮我生成项目的 CLAUDE.md 文档

Claude-Mem 自动分析：

项目结构
核心依赖
编码规范
构建命令
测试命令

生成标准化的 CLAUDE.md，供所有团队成员使用。

7.3 MCP 工具集成

Claude-Mem 提供 5 个 MCP 工具，遵循三层工作流模式。

工具列表

工具名称	功能	使用场景
`search`	获取紧凑索引	第一步：快速筛选相关记忆
`timeline`	获取时间线上下文	第二步：理解记忆的演变
`get_observations`	获取完整详情	第三步：深入特定记忆
`save_memory`	手动保存重要信息	随时：保存关键决策
`workflow`	查看工作流文档	参考：了解最佳实践

完整使用流程

javascript 复制代码

// 第1步：搜索相关记忆（获取索引）
search(query: "身份验证实现", limit: 10)
// 返回：[{id: 123, title: "JWT 认证实现", type: "feature", time: "2天前"}, ...]

// 第2步：查看时间线（理解上下文）
timeline(sessionId: "sess_xyz")
// 返回：按时间排序的相关观察记录

// 第3步：获取完整详情（深入研究）
get_observations(ids: [123, 456])
// 返回：完整的工具输出、代码片段、决策理由

7.4 实时观察馈送（Live Feed）

Claude-Mem 支持将实时观察记录馈送到团队协作平台。

支持的集成

javascript 复制代码

// Telegram 集成
curl -X POST https://api.telegram.org/bot<TOKEN>/sendMessage \
  -d chat_id=<CHAT_ID> \
  -d text="🔴 [Claude-Mem] 修复了支付并发问题"

// Discord 集成
curl -X POST https://discord.com/api/webhooks/<ID>/<TOKEN> \
  -d content="🟤 [Decision] 选择 PostgreSQL 作为主数据库"

配置实时馈送

json 复制代码

// ~/.claude-mem/settings.json
{
  "liveFeed": {
    "enabled": true,
    "platform": "telegram",
    "webhookUrl": "https://api.telegram.org/bot...",
    "filters": {
      "types": ["bugfix", "decision"],
      "minPriority": "medium"
    }
  }
}

八、与原生 Claude Code 的对比

8.1 功能对比表

功能维度	原生 Claude Code	Claude-Mem
跨会话记忆	❌ 不支持	✅ 自动持久化
语义搜索	❌ 不支持	✅ 混合语义+关键词
上下文注入	⚠️ 仅当前会话	✅ 自动跨会话注入
记忆可视化	❌ 无	✅ Web 查看器
隐私控制	⚠️ 基础	✅ 多层隐私保护
团队协作	❌ 不支持	✅ 项目级记忆共享
Token 优化	⚠️ 手动管理	✅ 渐进式披露
长期项目管理	❌ 困难	✅ 专为长期设计

8.2 性能对比

场景：两周后继续之前的项目

原生 Claude Code：

diff 复制代码

时间成本：
- 重新解释项目背景：15-30分钟
- 回忆之前的决策：10-20分钟  
- 查找之前的代码：5-15分钟
总计：30-65分钟

Token 成本：
- 项目背景文档：~2000 tokens
- 代码解释：~3000 tokens
- 问答交互：~1000 tokens
总计：~6000 tokens

使用 Claude-Mem：

diff 复制代码

时间成本：
- Claude 自动注入上下文：0分钟（后台完成）
- 确认理解：1-2分钟
总计：1-2分钟

Token 成本：
- 压缩后的观察记录：~500 tokens
- 精确召回详情：~1000 tokens (按需)
总计：~500-1500 tokens

效率提升 ：时间节省 95% ，Token 节省 75%。

九、总结与展望

9.1 Claude-Mem 的核心价值

复制代码

┌─────────────────────────────────────────────────┐
│           Claude-Mem 价值三角                   │
├─────────────────────────────────────────────────┤
│                                                 │
│         🧠 持久化记忆                            │
│              ↓                                  │
│    🔍 智能语义搜索 ← → 📊 可视化管理的项目背景                     │
│              ↓                                  │
│         🚀 开发效率提升                          │
│                                                 │
└─────────────────────────────────────────────────┘

9.2 适用场景推荐

用户类型	推荐指数	主要收益
长期项目开发者	⭐⭐⭐⭐⭐	上下文连续性，无需重复解释
开源项目维护者	⭐⭐⭐⭐⭐	历史决策可追溯，Issue 处理更高效
团队协作开发	⭐⭐⭐⭐	知识共享，新成员快速上手
学习新技术的开发者	⭐⭐⭐⭐	学习过程可回溯，知识点关联
短期项目开发者	⭐⭐	收益有限，但未来回顾有帮助

9.3 未来展望

根据项目 Roadmap，Claude-Mem 正在开发以下功能：

多 AI 提供商支持 - 除了 Claude，还将支持 GPT、Gemini 等
更强大的无尽模式 - 降低延迟，支持更复杂的项目
团队协作增强 - 实时协作编辑、冲突解决
AI 驱动的洞察 - 自动识别代码模式、潜在问题
企业级功能 - 权限管理、审计日志、合规工具

9.4 快速上手检查清单

bash 复制代码

✅ 安装 Claude Code 最新版
✅ 运行安装命令：/plugin marketplace add thedotmack/claude-mem
✅ 安装插件：/plugin install claude-mem
✅ 重启 Claude Code
✅ 访问 http://localhost:37777 验证安装
✅ 开始第一个会话，让 Claude-Mem 自动记录
✅ 开启新会话，体验上下文自动注入

参考资料

GitHub 仓库 ：github.com/thedotmack/...
官方网站 ：claude-mem.ai
文档中心 ：docs.claude-mem.ai
Discord 社区 ：discord.gg/claude-mem
相关文章 ：

写在最后：Claude-Mem 正在改变我们与 AI 协作的方式。它不再是一个"健忘"的助手，而是一个能够真正理解你项目历史、延续你思考过程的智能伙伴。如果你每天都在使用 Claude Code 进行开发，Claude-Mem 绝对值得一试。
作者注：本文基于 Claude-Mem v10.3.1 版本撰写，后续版本可能有所变化，请以官方文档为准。

如果本文对你有帮助，欢迎点赞、收藏、关注三连！如有任何问题，欢迎在评论区留言讨论。