Claude-Mem: Claude Code 的持久化记忆压缩系统

概述

Claude-Mem 是一款专为 Anthropic Claude Code CLI 设计的持久化记忆压缩系统插件。该项目由 Alex Newman（@thedotmack）开发，采用 TypeScript 实现，于 2025 年 8 月首次发布，截至 2026 年 4 月已获得约 59,860 个 GitHub Stars，成为 AI 辅助编程工具领域的重要基础设施组件。

核心定位：自动捕获 Claude Code 编码会话中的工具使用行为，通过 Claude Agent SDK 进行 AI 压缩处理，并将语义化摘要注入后续会话，实现跨会话的上下文连续性。

问题背景与设计动机

核心问题：AI 编程助手的上下文断层

Claude Code 等交互式 AI 编程助手存在一个根本性缺陷——会话记忆的短暂性（Session Ephemeral Nature）。每个新会话均从零状态启动，导致：

问题类型 具体表现
上下文重复阐述 用户需反复解释项目背景、技术栈、编码约定
决策知识流失 已做出的架构决策、设计权衡在会话结束后消失
Bug 修复轨迹断裂 已调试的 Bug 及其根因分析无法延续
编码模式不一致 后续会话可能采用与先前相矛盾的编码风格

解决方案架构

Claude-Mem 采用 “仿生记忆架构”（Biomimetic Memory Architecture）范式：

┌─────────────────────────────────────────────────────────────┐
│  Claude Code 客户端                                          │
│  ├── Hook 系统（5 个生命周期事件）                            │
│  ├── MCP 客户端（搜索工具）                                   │
└─────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│  CLI 层（Bun Runtime）                                       │
│  ├── bun-runner.js（Node→Bun 桥接）                          │
│  ├── hook-command.ts（编排器）                                │
│  ├── handlers/（上下文、会话初始化、观测、摘要、会话结束）      │
└─────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│  Worker Daemon（Express，端口 37777）                        │
│  ├── SessionManager（会话生命周期管理）                        │
│  ├── SDKAgent（Claude Agent SDK 集成）                       │
│  ├── SearchManager（搜索编排）                                │
│  ├── ProcessRegistry（子进程管理）                            │
│  ├── ChromaSync（嵌入向量同步）                               │
└─────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│  存储层                                                      │
│  ├── SQLite（claude-mem.db）—— 结构化数据                    │
│  ├── ChromaDB（chroma.sqlite3）—— 向量嵌入                   │
│  ├── MCP Server（Claude Code 接口）                          │
└─────────────────────────────────────────────────────────────┘

核心技术架构

1. 生命周期 Hook 系统

Claude-Mem 通过 Claude Code 的 Hook 扩展机制介入会话生命周期，实现无侵入式观测。

Hook 事件 处理器 功能描述 超时配置
Setup setup.sh 系统依赖安装检测 300s
SessionStart smart-install.js + context 依赖检查 + Worker 启动 + 上下文注入 60s
UserPromptSubmit session-init 会话注册 + SDK Agent 启动 + 语义注入 60s
PostToolUse observation 工具使用捕获 → 入队 Worker 处理 120s
Stop summarize 会话摘要生成请求 120s
SessionEnd session-complete 会话终止 + 待处理消息清空 30s

Hook 注册配置示例（hooks.json）：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$_R/scripts/smart-install.js\"",
            "timeout": 300
          },
          {
            "type": "command",
            "command": "node \"$_R/scripts/bun-runner.js\" \"$_R/scripts/worker-service.cjs\" start",
            "timeout": 60
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$_R/scripts/bun-runner.js\" \"$_R/scripts/worker-service.cjs\" hook claude-code observation",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

2. Worker Service 架构

Worker Service（src/services/worker-service.ts）是基于 Express 的 HTTP API 服务，监听端口 37777：

  • 异步处理：通过 Bun 管理的后台 Worker 执行 AI 处理任务
  • 消息队列：src/services/queue/ 管理待处理消息的入队、认领、确认流程
  • SSE（Server-Sent Events）：向 Viewer UI 推送实时观测数据
  • 多 Provider 支持：兼容 Claude、Gemini、OpenRouter 等多种 AI 后端

核心会话类型定义：

export interface ActiveSession {
  sessionDbId: number;
  contentSessionId: string;       // 用户 Claude Code 会话 ID
  memorySessionId: string | null; // Memory Agent 会话 ID
  project: string;
  platformSource: string;
  userPrompt: string;
  pendingMessages: PendingMessage[];
  abortController: AbortController;
  conversationHistory: ConversationMessage[];
  currentProvider: 'claude' | 'gemini' | 'openrouter' | null;
  cumulativeInputTokens: number;  // 发现成本追踪
  cumulativeOutputTokens: number;
}

3. 数据库架构（SQLite3）

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

核心数据表
表名 功能 关键字段
sessions 会话追踪 session_id, project, created_at_epoch, source, archive_path
memories 压缩记忆块 session_id, text, title, subtitle, facts, concepts, files_touched
overviews 会话概览 session_id, content, project, origin
diagnostics 系统诊断 session_id, message, severity（info/warn/error）
transcript_events 原始对话数据 session_id, event_index, event_type, raw_json
SDK 集成专用表
表名 功能 关键字段
sdk_sessions SDK 会话映射 content_session_id, memory_session_id, project, status, prompt_counter
observations AI 提取观测 type（decision/bugfix/feature/refactor/discovery/change）, title, facts, concepts, files_read, files_modified
session_summaries 会话总结 request, investigated, learned, completed, next_steps, notes
user_prompts 用户输入历史 content_session_id, prompt_number, prompt_text

4. 观测分类体系

观测记录按语义类型分类，支持细粒度的记忆检索：

type ObservationType = 'decision' | 'bugfix' | 'feature' | 'refactor' | 'discovery' | 'change';

export interface ObservationRecord {
  id: number;
  memory_session_id: string;
  project: string;
  text: string | null;
  type: ObservationType;
  title?: string;
  concept?: string;
  source_files?: string;
  prompt_number?: number;
  discovery_tokens?: number;  // ROI 成本指标
}

5. 向量嵌入与语义搜索（ChromaDB）

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

ChromaDB 用于存储观测记录的向量嵌入，实现：

  • 语义相似性检索：基于向量距离的智能上下文匹配
  • 混合搜索：FTS5 全文检索 + 向量语义检索的复合查询
  • 上下文注入优化：按相关性筛选注入内容，控制 Token 成本

6. 渐进式披露（Progressive Disclosure）

Claude-Mem 采用三层渐进式披露架构，优化 Token 使用效率：

┌─────────────────────────────────────────────────────────────┐
│  第一层：search                                              │
│  功能：返回紧凑索引（含 ID）                                  │
│  Token 成本：~50-100 tokens/result                           │
└─────────────────────────────────────────────────────────────┘
          │ 用户筛选感兴趣的 ID
          ▼
┌─────────────────────────────────────────────────────────────┐
│  第二层：timeline                                            │
│  功能：获取特定观测周围的时序上下文                            │
│  Token 成本：中等                                            │
└─────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│  第三层：get_observations                                     │
│  功能：仅对筛选后的 ID 获取完整详情                            │
│  Token 成本：~500-1,000 tokens/result                        │
└─────────────────────────────────────────────────────────────┘

Token 节省效果：相比直接获取全部详情，该架构实现约 10x Token 节省。

会话 ID 双轨架构

Claude-Mem 维护两种会话 ID 类型以实现跨会话追踪：

ID 类型 标识符 说明
contentSessionId 用户会话 ID Claude Code 对话会话的唯一标识（跨轮次稳定）
memorySessionId SDK 会话 ID Agent SDK 内部会话 ID（用于 Resume 功能）

初始化流程

1. Hook 创建会话
   createSDKSession(contentSessionId, project, prompt)
   Database: content_session_id="user-123", memory_session_id=NULL

2. SDKAgent 启动，检测 hasRealMemorySessionId
   → FALSE（NULL）
   → 不使用 Resume（新建 SDK 会话）

3. 首个 SDK 消息携带 session_id
   ensureMemorySessionIdRegistered(sessionDbId, "sdk-abc123")
   Database: memory_session_id="sdk-abc123"（真实值）

4. 后续轮次可使用 Resume
   → TRUE（同一运行时内的延续性轮次）
   → Resume 参数：{ resume: "sdk-abc123" }

上下文注入机制

Hook 输出格式

SessionStart Hook 通过 hookSpecificOutput.additionalContext 字段向 Claude Code 注入上下文。自 Claude Code 2.1.0 起，该注入为静默模式，不向用户显示。

注入内容示例：

<claude-mem-context>
# Recent Activity

### Oct 25, 2025

| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #2374 | 2:55 PM | ✅ | Marketplace metadata version synchronized to 4.2.11 | ~157 |

### Oct 27, 2025

| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #2757 | 1:23 AM | 🟣 | Released v4.3.3 with Configurable Session Display | ~391 |
</claude-mem-context>

类型图例

符号 含义
✅ 已完成/成功
🔴 Bug 修复
🟣 发布/构建
🔵 调查/信息
🟡 问题-解决方案

隐私控制机制

Claude-Mem 提供 <private> 标签机制，允许用户在输入中标记敏感内容，该内容将被从存储流程中剥离：

<private>敏感信息内容</private>  <!-- 用户级隐私控制 -->

隐私处理发生在 Hook 层（边缘处理），敏感数据不会进入 Worker 或数据库。

MCP 搜索工具

Claude-Mem 通过 MCP（Model Context Protocol）提供四个搜索工具：

工具名 功能 Token 成本
search 全文查询检索，支持类型/日期/项目过滤 ~50-100 tokens/result
timeline 获取特定观测周围的时序上下文 中等
get_observations 按 ID 批量获取观测详情 ~500-1,000 tokens/result

使用示例：

// Step 1: 搜索索引
search(query="authentication bug", type="bugfix", limit=10)

// Step 2: 审阅索引，识别相关 ID（如 #123, #456）

// Step 3: 批量获取详情
get_observations(ids=[123, 456])

容错与降级架构

CLAIM-CONFIRM 消息队列模式

enqueue()           → INSERT status='pending'
claimNextMessage()  → UPDATE status='processing'（原子操作）
confirmProcessed()  → DELETE（成功）
markFailed()        → UPDATE status='failed'（重试 < 3）

自愈机制：处于 'processing' 状态超过 60s 的消息自动重置为 'pending'

Circuit-Breaker 熔断器

Generator 崩溃 → 重试 1（1s）→ 重试 2（2s）→ 重试 3（4s）
  → consecutiveRestarts > 3 → CIRCUIT-BREAKER 触发
  → 停止。避免无限循环。

Graceful Degradation 优雅降级

传输层错误（ECONNREFUSED、timeout、5xx）→ exit 0（永不阻塞 Claude Code）
客户端 Bug（4xx、TypeError、ReferenceError）→ exit 2（阻塞，需修复）

核心原则：Worker 服务不可用永不阻塞用户的 Claude Code 会话。

安装与配置

安装方式

# 标准安装
npx claude-mem install

# Gemini CLI 支持
npx claude-mem install --ide gemini-cli

# OpenCode 支持
npx claude-mem install --ide opencode

# 插件市场安装（Claude Code 内）
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

系统要求

依赖项 版本要求 说明
Node.js ≥ 18.0.0 运行环境
Claude Code 最新版 需支持插件系统
Bun JavaScript Runtime 自动安装
uv Python 包管理器 用于向量搜索（自动安装）
SQLite 3 数据库 内置

配置文件

位置：~/.claude-mem/settings.json

{
  "CLAUDE_MEM_MODE": "code--zh"  // 简体中文模式
}

支持模式：

  • code（默认英文）
  • code--zh（简体中文）
  • code--ja（日语）
  • code--es（西班牙语）
  • 等 ISO 639-1 语言代码

命令行管理

# Worker 服务管理
npm run worker:start    # 启动服务
npm run worker:stop     # 停止服务
npm run worker:restart  # 重启服务
npm run worker:status   # 查看状态

# 队列管理
npm run queue           # 查看待处理队列
npm run queue:process   # 处理待处理项
npm run queue:clear     # 清空失败队列

# Bug 报告
npm run bug-report      # 生成综合 Bug 报告

# Cursor IDE 集成
npm run cursor:install  # 安装至 Cursor
npm run cursor:status   # 查看 Cursor 状态

Web Viewer UI

访问 http://localhost:37777 可查看实时记忆流：

  • 实时观测数据展示
  • 会话历史浏览
  • 搜索功能
  • 设置配置
  • Beta 功能切换（如 Endless Mode）

核心特性汇总

特性 描述
持久化记忆 上下文跨会话存活
渐进式披露 分层记忆检索，Token 成本可视化
技能驱动搜索 通过 mem-search 技能查询项目历史
Web Viewer UI localhost:37777 实时记忆流
隐私控制 <private> 标签排除敏感内容
自动运行 无需手动干预
引用追踪 通过 ID 引用历史观测
多语言支持 中文、日语、西班牙语等
Beta 渠道 Endless Mode 等实验性功能

项目信息

属性 值
版本 v12.1.6
许可证 AGPL-3.0
语言 TypeScript
创建时间 2025-08-31
Stars ~59,860
官方文档 https://docs.claude-mem.ai
GitHub https://github.com/thedotmack/claude-mem
Discord https://discord.com/invite/J4wttp9vDu
X/Twitter https://x.com/Claude_Memory

参考资料

结语

Claude-Mem 代表了 AI 辅助编程工具领域的重要进展——从会话式助手向持久化智能伙伴的范式转变。通过生命周期 Hook、AI 压缩、向量语义检索、渐进式披露等技术的有机结合，该项目有效解决了 AI 编程助手的核心痛点：上下文连续性缺失。

对于追求高效、连贯 AI 编程体验的开发者，Claude-Mem 提供了一套成熟、开源、可扩展的解决方案，值得深入探索与实践。

Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

AI 智能体 OpenClaw 2.6.4 Windows 系统安装与使用全解

avatar AtomGit开源社区
cover

LangChain4j简述与示例

avatar AtomGit开源社区

2026售后服务管理新趋势：AI派工、IoT预测维护将淘汰传统模式？

2026售后管理迈入智能革新期，AI派工与IoT预测维护正重塑行业格局。融合AI智能调度 IoT数据感知，实现故障提前预警、工单自动匹配，替代低效人工模式。构建从被动维修到主动服务的闭环，提升响应效率、降低运维成本，成为企业数字化转型必选路径。

avatar AtomGit开源社区