Claude-Mem — 持久记忆压缩系统：安装、架构与深度使用指南

G_whang2026-06-14 11:16

1. 概述：为什么需要 Claude-Mem

Claude Code 的天然短板是跨会话遗忘 ------每次新对话从零开始，项目架构、历史决策、已修复的 Bug 全部丢失。claude-mem 是一个专为 Claude Code 设计的持久记忆压缩系统，通过生命周期 Hook 自动捕获工具调用和会话内容，经 AI（Claude Agent SDK）语义压缩后存入本地 SQLite + ChromaDB 向量数据库，为后续会话提供智能上下文注入。

核心数据

指标 数值
GitHub Stars 80,000+（SourcePulse 排名前 0.3%）
Token 节省 3 层渐进检索，相比全量获取节省 50--75%
支持 IDE Claude Code、Cursor、Gemini CLI、OpenCode、OpenClaw
许可协议 AGPL-3.0
最新版本 v13.x（2026 年在持续迭代）

2. 架构总览

复制代码 
┌─────────────────┐                          ┌──────────────────────┐
│   Claude Code   │                          │   Worker Service     │
│                 │   Hooks (5 生命周期)       │   (localhost:37777)  │
│  SessionStart ──┼─────────────────────────►│                      │
│  UserPrompt ────┼─────────────────────────►│  ┌────────────────┐  │
│  PostToolUse ───┼─────────────────────────►│  │  SQLite FTS5   │  │
│  Stop ──────────┼─────────────────────────►│  └────────────────┘  │
│  SessionEnd ────┼─────────────────────────►│  ┌────────────────┐  │
│                 │                          │  │  ChromaDB      │  │
│  MCP Tools ◄────┼──────────────────────────┤  │  (向量检索)     │  │
│  (search,       │   JSON-RPC over stdio    │  └────────────────┘  │
│   timeline,     │                          │  ┌────────────────┐  │
│   get_obs...)   │                          │  │  Web Viewer    │  │
└─────────────────┘                          │  │  (:37777)      │  │
                                              │  └────────────────┘  │
                                              └──────────────────────┘

2.1 核心组件

组件 技术 说明
Worker 服务 Express.js（Bun 运行时） HTTP API 常驻进程，端口 37777
MCP Server Node.js（~312 行轻量封装） 将 MCP 协议调用转为 HTTP 请求
全文检索 SQLite FTS5 关键词精确匹配、结构化过滤
语义检索 ChromaDB 向量数据库 自然语言语义相似度搜索
AI 压缩 Claude Agent SDK 对原始观察记录进行语义压缩和摘要
Web 查看器 内建 UI 实时记忆流、会话回放、时间线浏览

2.2 关键设计决策

  • 渐进式披露：搜索 → 时间线 → 详情，先看索引再获取完整内容，杜绝 Token 浪费。
  • Fire-and-Forget：PostToolUse 和 Stop 钩子异步执行，绝不阻塞 Claude Code 主流程。
  • 本地优先：所有数据存于本地 SQLite + ChromaDB，无外部 API 依赖。
  • 隐私过滤 ：<private> 标签机制 + 自动剥离 API Key/Token。

3. 安装

3.1 方式一：Claude Code 插件市场安装（推荐）

在 Claude Code 中依次执行：

复制代码 
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

安装完成后退出 Claude Code。

3.2 方式二：一键初始化 Worker

在 Windows 终端中执行（必须用 npx，不要全局安装）：

bash 复制代码 
npx claude-mem install

该命令自动完成：

  • 创建 ~/.claude-mem 目录
  • 生成 SQLite 数据库和 ChromaDB 向量存储
  • 在 Claude Code 中注册 5 个生命周期 Hooks
  • 启动 Worker 后台服务（:37777）
  • 生成 MCP 服务器配置

3.3 方式三：Cursor 专用

bash 复制代码 
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem && bun install && bun run build
bun run cursor:setup

4. Worker 管理

Worker 是 claude-mem 的核心常驻服务（Express HTTP API），负责接收观察记录、调用 AI 压缩、响应检索请求。

4.1 查看运行状态

bash 复制代码 
npx claude-mem worker:status

预期输出：running

4.2 启动 Worker

bash 复制代码 
npx claude-mem worker:start

4.3 重启 Worker（完整流程）

bash 复制代码 
# 1. 杀掉旧进程（避免端口占用）
npx claude-mem worker:kill

# 2. 正常启动
npx claude-mem worker:start

# 3. 确认状态为 running
npx claude-mem worker:status

4.4 Web 查看器

Worker 启动后通过浏览器访问：

复制代码 
http://localhost:37777

提供功能：实时记忆流查看、会话历史回放、Observation 时间线浏览、Corpus 语料库管理。

5. 生命周期 Hooks 系统

claude-mem 通过 5 个 Hooks 实现零手动记忆捕获，是系统的核心自动化层。

5.1 Hook 总览

阶段 Hook 事件 触发时机 对应脚本 机制
1 SessionStart 打开 Claude Code worker-service.cjs start → context-hook.js 启动 Worker + 注入历史上下文
2 UserPromptSubmit 用户提交提示词 new-hook.js 创建会话记录、保存原始提示词
3 PostToolUse Claude 调用任意工具后 save-hook.js 捕获工具执行信息，发送给 Worker 做 AI 压缩
4 Stop 用户停止提问 summary-hook.js 生成会话摘要（fire-and-forget）
5 SessionEnd 会话关闭 cleanup-hook.js 标记会话完成、优雅清理

5.2 SessionStart------上下文注入

  1. 启动 Worker 服务（若未运行）
  2. 执行 context-hook.js，等待 Worker 就绪
  3. 调用 GET /api/context/inject?project=<name> 获取历史相关上下文
  4. 通过 hookSpecificOutput.additionalContext 静默注入 Claude Code 上下文
  5. 超时：60s；Claude Code 2.1.0+ 后不再显示用户可见消息

5.3 PostToolUse------自动捕获

  • 匹配器：*（捕获所有工具调用）
  • 排除名单 ：ListMcpResourcesTool、SlashCommand、Skill、TodoWrite、AskUserQuestion 等低价值工具
  • 执行 POST /api/sessions/observations（超时 2s）
  • Fire-and-Forget：不阻塞 Claude 主流程
  • Worker 异步处理：隐私检查 → 记忆标签剥离 → 入队 → AI 压缩

5.4 Stop------摘要生成

  • v12.3.9 重大优化 ：从同步阻塞改为 Fire-and-Forget，消除了约 110 秒的终端阻塞
  • 读取 transcript JSONL，提取最后一条 user/assistant 消息
  • 发送 POST /api/sessions/summarize
  • Worker 端用 SessionCompletionHandler 在钩子关键路径之外完成总结

6. MCP 工具------3 层渐进式检索

这是 claude-mem 检索架构的核心设计：先索引、后时间线、最后详情，强制 Token 高效使用。

6.1 三层工作流（必须遵循）

复制代码 
Layer 1: search(query)         → 获取紧凑索引（ID、标题、日期、类型）
          每个结果 ~50-100 tokens

Layer 2: timeline(anchor=ID)   → 获取指定 Observation 的时间线上下文
          每层 ~100-200 tokens

Layer 3: get_observations(IDs) → 批量获取选定 ID 的完整详情
          每条 ~500-1,000 tokens

6.2 Token 效率对比

方式 操作 Token 消耗
传统 RAG 直接取 20 条完整 Observation 10,000--20,000（90% 浪费）
3 层工作流 索引过滤后取 3 条 2,500--5,000（节省 50--75%）

6.3 MCP 工具详解

工具 用途 参数
search FTS5 + ChromaDB 混合搜索，返回索引 query（必填）、limit、type、concepts、files、dateStart、dateEnd
timeline 以 Observation ID 或搜索词为锚点的时间线 anchor 或 query、depth_before、depth_after
get_observations 批量获取选定 IDs 的完整 Observation ids（必填数组）
build_corpus 从 Observation 历史编译筛选后的语料库 name（必填）、description、type、concepts、files、query
list_corpora 列出所有已构建语料库及其统计 ---
prime_corpus 将语料库载入会话，准备查询 name（必填）
query_corpus 对话式查询已载入的语料库 name（必填）、question（必填）
rebuild_corpus 重建语料库（获取新增 Observation） name（必填）
reprime_corpus 恢复过期语料库会话 name（必填）
observation_add 手动插入一条观察记录 content（必填）、projectId、kind、metadata
observation_context 获取 top-N 相关 Observation 用于上下文注入 query（必填）、limit
observation_record_event 记录 Agent 事件并自动入队生成任务 eventType（必填）、payload
smart_outline tree-sitter AST 解析文件结构骨架 file_path（必填）
smart_search 跨目录发现文件 + 符号 query（必填）、path、max_results
smart_unfold 展开指定符号的完整源码 file_path（必填）、symbol_name（必填）

6.4 Observation 类型体系

搜索和 Timeline 中每条 Observation 携带类型标记：

标记 类型 说明
🔴 bugfix 修复的 Bug 和错误
🟣 feature 新功能实现
🔵 decision 架构/设计决策
🟢 discovery 新发现和洞见
🟠 refactor 代码重构
⚪ change 一般变更
🚨 security_alert 安全告警（高优先级，触发通知）
🔐 security_note 安全注意事项（低优先级）

7. 搜索架构

7.1 混合检索引擎

层级 技术 用途
全文搜索 SQLite FTS5 虚拟表 关键词精确匹配、结构化过滤（type/file/concept/date）
语义搜索 ChromaDB 向量数据库 自然语言查询、语义相似度匹配
混合模式 FTS5 + ChromaDB 协同 RRF 融合排序

7.2 FTS5 虚拟表结构

sql 复制代码 
-- Observation 全文索引
CREATE VIRTUAL TABLE observations_fts USING fts5(
  title, subtitle, narrative, text, facts, concepts,
  content='observations', content_rowid='id'
);

-- 会话摘要全文索引
CREATE VIRTUAL TABLE session_summaries_fts USING fts5(
  request, investigated, learned, completed, next_steps, notes,
  content='session_summaries', content_rowid='id'
);

-- 用户提示词全文索引
CREATE VIRTUAL TABLE user_prompts_fts USING fts5(
  prompt_text,
  content='user_prompts', content_rowid='id'
);

7.3 安全防护

  • 所有 FTS5 查询经过 escapeFTS5Query() 转义，防止 SQL 注入
  • 332 个注入攻击测试覆盖：特殊字符、SQL 关键字、引号转义、布尔操作符

8. Skills------12 个原生技能

安装插件后在 Claude Code 中可用以下指令：

Skill 类型 用途
babysit 监控类 监控/守护任务执行过程
do 执行类 执行多阶段计划
make-plan 规划类 生成分阶段实施计划（Phase 0: 文档发现 → 实施 → 验证）
how-it-works 解释类 解释系统/流程的工作原理
knowledge-agent 知识类 基于历史 Observation 构建可查询的知识代理
learn-codebase 学习类 学习并理解代码库结构和模式
pathfinder 探索类 导航和路径探索
smart-explore 探索类 基于 tree-sitter AST 的 Token 优化代码探索（4--8x Token 节省）
mem-search 检索类 3 层渐进式记忆搜索入口
timeline-report 报告类 以事件/时间为锚点生成时间线报告
version-bump 工具类 自动化版本号管理和变更日志
wowerpoint 展示类 生成演示/可视化输出

8.1 smart-explore------Token 优化的代码探索

工具 用途 Token 消耗
smart_search 跨目录发现文件 + 符号 ~2,000--6,000
smart_outline AST 解析单文件结构骨架 ~1,000--2,000
smart_unfold 展开指定符号完整源码 ~400--2,100

相比传统 Read/Grep/Glob 方式：4--8x Token 节省 （文件理解），11--18x Token 节省（代码库探索）。

支持语言：JavaScript、TypeScript、TSX/JSX、Python、Go、Rust、Ruby、Java、C、C++，以及自定义 tree-sitter 语法。

8.2 Knowledge Agent------历史知识代理

v12.1.0 引入的 Knowledge Corpus 系统：

复制代码 
build_corpus(name, filters) → prime_corpus(name) → query_corpus(name, question)

将历史 Observation 编译为可对话查询的 AI"大脑"，支持：

  • 按类型/概念/文件/日期范围筛选构建
  • 重建以获取新增 Observation
  • 过期会话恢复

9. 配置参考

9.1 Hooks 配置（自动生成于 ~/.claude/settings.json）

json 复制代码 
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear|compact",
        "hooks": [
          { "type": "command", "command": "bun ${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs start", "timeout": 60 },
          { "type": "command", "command": "bun ${CLAUDE_PLUGIN_ROOT}/scripts/context-hook.js", "timeout": 60 }
        ]
      }
    ],
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/new-hook.js", "timeout": 120 }] }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [{ "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/save-hook.js", "timeout": 120 }]
      }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/summary-hook.js", "timeout": 120 }] }
    ],
    "SessionEnd": [
      { "hooks": [{ "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-hook.js", "timeout": 120 }] }
    ]
  }
}

9.2 环境变量

变量 用途 默认值
CLAUDE_MEM_WORKER_PORT Worker 端口 37777
CLAUDE_MEM_WORKER_HOST Worker 主机 localhost
CLAUDE_MEM_CONTEXT_OBSERVATIONS 上下文注入的 Observation 数量 50
CLAUDE_MEM_TELEGRAM_ENABLED Telegram 通知开关 开启（需配置 bot token + chat ID）

10. 数据存储架构

10.1 数据库表

复制代码 
~/.claude-mem/
├── claude-mem.db            # SQLite 主库
│   ├── sessions             # 会话记录
│   ├── observations         # 观察记录（带类型标记）
│   ├── session_summaries    # 会话 AI 摘要
│   ├── user_prompts         # 原始用户提示词
│   ├── observations_fts     # FTS5 全文索引
│   ├── session_summaries_fts
│   └── user_prompts_fts
└── chroma/                  # ChromaDB 向量存储
    └── (embedding vectors)

10.2 隐私保护

  • <private> 标签：在消息中包裹敏感内容，自动排除不被存储
  • 自动剥离：API Key、JWT Token、Secrets 在写入前自动过滤
  • 本地存储：所有数据不离开本机

11. Corpus 语料库系统（v12.1.0+）

将历史 Observation 编译为可查询的 AI"大脑"。

11.1 创建语料库

bash 复制代码 
# 通过 MCP 工具 build_corpus
{
  "name": "bugfixes",
  "description": "所有已修复的 Bug 及其解决方案",
  "type": "bugfix",
  "concepts": "error handling, null safety, race condition",
  "files": "src/auth/,src/database/",
  "dateStart": "2026-01-01",
  "limit": 200
}

11.2 查询流程

复制代码 
prime_corpus("bugfixes") → 将语料库载入会话
query_corpus("bugfixes", "How did we fix the auth race condition?")

11.3 维护

bash 复制代码 
rebuild_corpus("bugfixes")  # 重新搜索，获取新增 Observation
reprime_corpus("bugfixes")  # 刷新过期会话

12. 日常运维命令速查

命令 功能
npx claude-mem install 一键安装：创建目录、生成数据库、注册 Hooks、启动 Worker
npx claude-mem worker:status 查看 Worker 运行状态
npx claude-mem worker:start 启动 Worker 服务
npx claude-mem worker:kill 强制终止 Worker 进程
npx claude-mem worker:restart 重启 Worker 服务
curl http://localhost:37777 访问 Web 查看器

13. 与其他记忆系统对比

维度 Claude-Mem AgentMemory CLAUDE.md
设计定位 Claude Code 原生记忆压缩层 通用多 Agent 记忆引擎 静态上下文文件
捕获方式 5 个生命周期 Hooks，自动化 12 个 Hooks，自动化 手动编辑
检索方式 FTS5 + ChromaDB 混合 BM25 + Vector + Graph（RRF） 全文加载
存储引擎 SQLite + ChromaDB + Bun SQLite + iii-engine 文件系统
外部依赖 ChromaDB（嵌入向量） 零（all-MiniLM-L6-v2 本地） 无
MCP 工具数 15+（含 Corpus/KAG） 53 0
Web 查看器 :37777 :3113 无
Token 节省 50--75%（3 层渐进） 92%（vs 全量上下文） N/A
Skills 12 个 15 个 无
跨 Agent Claude Code、Cursor、Gemini CLI 50+ Agent 独立文件
许可协议 AGPL-3.0 Apache-2.0 N/A
运行环境 Bun Node.js 无

14. 故障排查

问题 解决方案
Worker 未启动 执行 npx claude-mem worker:start 手动启动
端口 37777 被占用 执行 npx claude-mem worker:kill 杀掉旧进程后重启
上下文未注入 检查 Worker 是否 running；查看 context-hook.js 执行日志
Claude Code 退出时卡住 升级至 v12.3.9+（Stop Hook 已改为 Fire-and-Forget）
记忆搜索无结果 确认 Worker 在运行；检查是否有足够会话历史触发压缩
SessionStart Hook 报错 此为已知问题（#1426），冷启动时 Worker 进程可能被误杀；重试即可
npx 版本过旧 安装较新版本：npx claude-mem@latest install
FTS5 查询报错 确保查询字符串已正确转义；避免在搜索中使用未转义的特殊字符

参考资源

相关推荐
黄焖鸡能干四碗2 小时前
软件系统概要设计说明书模版（Word）
大数据·运维·数据库·架构·需求分析
互联网推荐官2 小时前
上海AI Agent智能体开发公司技术选型实录：六条路径、三类架构与真实落地约束
java·人工智能·ai·架构·开发经验·上海
前端不太难2 小时前
GPU 集群调度架构解析
架构·状态模式
Survivor0012 小时前
Codex Harness工程 Skills架构设计原理
ai·架构
@insist1232 小时前
系统架构设计师-嵌入式系统核心概念与关键机制
架构·系统架构·软考·系统架构设计师·软件水平考试
“码”力全开2 小时前
【架构深探】基于Docker与GB28181/RTSP的边缘计算AI视频管理平台：异构算力调度与源码交付实践
人工智能·docker·架构
一切皆是因缘际会2 小时前
LLM温度Temperature底层采样机理
人工智能·机器学习·ai·架构
沪漂阿龙2 小时前
LangChain 系列：Structured Output结构化输出与源码解析
java·人工智能·架构·langchain
happyprince2 小时前
01_verl-项目概览与架构总览
架构·wpf
热门推荐
01HTTP 与 HTTPS 的区别：从原理到实战详解022026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？03【AI】2026 年具身智能模型和世界模型总结042026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？05AI科技热点日报 | 2026年6月1日06《置身钉内》原文-可播放阅读07GitHub 镜像站点08Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析092026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf10AI一周事件 · 2026-06-03 至 2026-06-09