Claude-Mem: 为 Claude Code 构建持久化记忆系统

“Never Start from Zero” —— 让 AI 编程助手拥有跨会话的记忆能力

1. 为什么需要 Claude-Mem？

为了解决多轮交互中的上下文丢失问题，Claude Code 官方引入了基于本地纯文本的原生记忆机制。然而，在复杂的长期工程实践中，开发者们常常会疑问：既然有了原生支持，为什么还需要引入 Claude-Mem 这样更为庞大的插件系统？

1.1 Claude Code 的原生记忆机制

正如我之前在 《Claude Code 源码解析：基于 Markdown 文件的持久化记忆机制》 一文中所剖析的，Claude Code 官方选择了一条极简且内聚的纯文本工程化路线。其原生系统完全基于本地的 Markdown 文件，通过巧妙的个人与团队双层目录架构，实现了对话上下文与规则知识的长效留存。

在这个机制下，为了避免每次会话加载全量文件导致 Token 消耗过大，原生系统采用了“轻量级索引 + 结构化实体文件”的解耦模式。大语言模型在初始化时仅读取轻量级索引，当判定某一记忆条目与当前任务相关时，再主动去检索并读取具体的 .md 实体文件内容。同时，系统结合后台的 AutoDream 防劣化机制来自动合并和沉淀临时日志。这种架构的优势在于部署门槛极低，非常适合用来存储类似于“团队代码规范”、“数据库连接配置”这样相对静态且全局的规则型知识（Rule/Knowledge）。

1.2 原生记忆的局限性

尽管原生系统的“纯文本 + 目录索引”架构简单直接，但在面对需要持续跟进的海量动态上下文时，其性能与扩展性瓶颈也随之暴露：

  • Token 消耗与污染风险：由于直接读取完整的 Markdown 实体文件，当项目记忆（如排查日志、试错过程）膨胀时，大模型需要吞吐大量冗余的非结构化文本，极易导致昂贵的 Token 浪费和上下文污染。
  • 检索精准度单一：原生系统依赖模型自身去扫描纯文本索引，检索维度十分单一。在面对“仅查找最近三天的 Bug 修复记录”这种包含特定时间范围和动作类型的精确过滤查询时，显得无能为力。
  • 性能与资源竞争：在处理大体积记忆的自动固化（如 AutoDream 压缩过程）时，可能会与终端主进程产生资源竞争，影响实时对话的流畅度。

1.3 Claude-Mem 的破局与互补

为了突破上述瓶颈，Claude-Mem 放弃了纯文本方案，转而构建了基于 SQLite 关系型数据库 + Chroma 向量数据库 的现代检索架构。

  • 多维精准检索：借助双引擎架构，Claude-Mem 能够实现按时间、操作类型（Feature/Bugfix）、关键字以及高维语义特征的精准过滤。
  • 渐进式按需加载：通过定制的 MCP 工具（如 search、timeline、get_observations），单次记忆加载的 Token 消耗被严格控制在极低水平（节省高达 96%）。
  • 完全的异步解耦：将计算密集的 AI 特征压缩完全剥离到独立的 Bun Worker 后台进程中，确保了前端终端交互的绝对丝滑。

事实上，Claude-Mem 并非要替代原生记忆，而是对大模型长效记忆体系的高级扩展。如果说原生记忆是静态的“规则库”，那么 Claude-Mem 则是记录“尝试过哪些修复手段”、“架构如何一步步演进”等动态经验型时间线（Experience/Timeline）的无冕之王。

2. 什么是 Claude-Mem？

为了弥补原生记忆在动态上下文追踪上的短板，Claude-Mem 引入了基于 SQLite 与 Chroma 向量引擎的双层持久化机制。该系统不仅突破了上下文截断的瓶颈，更能将零散的调试经验转化为高度结构化的连续性知识资产，赋予大模型跨会话的工程演进记忆。

2.1 Claude Code 的失忆症问题

尽管 Claude Code 的原生记忆解决了部分静态规则的留存问题，但在面对高频动态的长期工程演进时，大模型仍然会遭遇“失忆症”。这意味着如果不引入更重的特征压缩组件，每当开启一个新终端，此前艰难排查出的报错根因与深层逻辑假设仍会丢失，迫使大模型陷入重复推理的低效循环。

2.2 真实场景的重复代价

记忆的缺失直接导致开发流程陷入高昂的“重试成本（Retry Penalty）”。在排查深层缺陷或重构跨模块逻辑时，这种局限性尤为致命。以下方一个历时两周的排查场景为例，我们可以清晰地看到因上下文丢失而引发的重复劳动瓶颈：

时间 事件 结果
Day 1 调试了一个棘手的认证问题 ✅ 问题解决
Day 7 遇到类似问题 ❌ Claude 不记得之前的解决方案
Day 14 又遇到相同问题 ❌ 重新调查

为彻底解决上述痛点，Claude-Mem 构建了一条完全解耦的后台记忆管道。系统通过实时捕获前端工具的调用流，并在后台执行基于大模型的语义压缩，最终实现了关键技术决策在多会话间的无缝注入与继承：

┌─────────────────────────────────────────────────────────────┐
│                     Claude-Mem 工作流程                      │
│                                                             │
│   Session 1          Session 2          Session 3           │
│   ┌─────────┐       ┌─────────┐       ┌─────────┐           │
│   │ 工作     │ ───▶  │ 记忆注入 │ ───▶  │ 持续积累  │           │
│   │ 观察     │       │ 继续工作 │       │ 越来越聪明│           │
│   └─────────┘       └─────────┘       └─────────┘           │
│        ↓                  ↑                                 │
│   ┌─────────┐       ┌─────────┐                             │
│   │ AI压缩   │ ───▶  │ 存储    │                             │
│   │ 结构化   │       │ SQLite  │                             │
│   └─────────┘       └─────────┘                             │
└─────────────────────────────────────────────────────────────┘

2.3 项目概述

作为一个非侵入式的开源扩展插件，Claude-Mem 致力于在不改变终端开发者现有习惯的前提下，赋予底层大模型跨会话的知识存取能力。项目的核心设计哲学为“强大但隐形（Powerful yet Invisible）”——开发者无需下发任何额外的记忆存储指令，便能感受到大语言模型在伴随项目演进而“越发聪明”。

项目数据（截至 2026 年 4 月）：

指标 数值
GitHub Stars 2.8k+
当前版本 v10.6.3
支持语言 28 种语言文档翻译
License AGPL-3.0

2.4 核心特性

Claude-Mem 针对复杂工程的长期记忆需求，在数据采集、特征压缩与可视化管理层面构建了完整的工具链，以确保上下文的高效流转。

特性 描述
🧠 持久化记忆 上下文在会话间保留，打破单次对话边界
📊 渐进式披露 分层记忆检索，极致优化 Token 消耗
🔍 MCP 搜索工具 允许通过自然语言直接查询项目历史
🌐 Web 查看器 UI 提供实时的记忆流可视化大屏 (http://localhost:37777)
📁 Folder Context 自动生成项目级别的 CLAUDE.md 上下文文件
🔒 隐私控制 支持通过 <private> 标签物理隔离敏感内容
🤖 全自动运行 挂载后完全在后台静默运行，无需人工干预

2.5 系统要求

系统的平稳运行依赖于特定版本的底层环境与核心中间件支持，确保数据处理的高效与安全。使用前需确保环境满足以下条件：

  • Node.js：18.0.0 或更高版本。
  • Claude Code：支持插件功能的最新版本。
  • Bun：作为 JavaScript 运行时和进程管理器（若缺失会自动安装）。
  • SQLite 3：用于持久化存储（已内置捆绑）。

3. Claude-Mem 是如何工作的？

为了实现无缝上下文继承与零散经验固化，Claude-Mem 依托前端拦截、多模态存储与 AI 语义压缩三大支柱，构建了一条全自动的记忆处理管道。这种非阻塞架构不仅保障了终端响应的实时性，还为大模型提供了高度结构化的历史认知。

3.1 核心架构概览

通过解耦数据流与控制流，系统构建了一条从终端交互到后台持久化的非阻塞数据处理管道。该设计确保了用户的高频操作与后台的大模型数据压缩完全剥离，互不干扰：

┌─────────────────────────────────────────────────────────────────┐
│                    Claude Code Session                          │
│   User → Claude → Tools (Read, Edit, Write, Bash)               │
│                      ↓                                          │
│                PostToolUse Hook                                 │
│                (queues observation)                             │
└─────────────────────────────────────────────────────────────────┘
                       ↓ SQLite queue
┌─────────────────────────────────────────────────────────────────┐
│                    SDK WORKER PROCESS                           │
│   ONE streaming session per Claude Code session                 │
│   AsyncIterable<UserMessage>                                    │
│     → Yields observations from queue                            │
│     → SDK compresses via AI                                     │
│     → Stores in database                                        │
└─────────────────────────────────────────────────────────────────┘
                       ↓ SQLite storage
┌─────────────────────────────────────────────────────────────────┐
│                      NEXT SESSION                               │
│   SessionStart Hook                                             │
│     → Queries database                                          │
│     → Returns progressive disclosure index                      │
│     → Agent fetches details via MCP                             │
└─────────────────────────────────────────────────────────────────┘

3.2 五大生命周期钩子

通过深度切入 Claude Code 的运行生命周期（Hooks），系统能够在不侵入其内部核心逻辑的前提下，精准拦截并捕获各个关键节点的上下文快照。

钩子 触发时机 功能
SessionStart 会话开始时 注入之前会话的上下文索引
UserPromptSubmit 用户提交提示词前 初始化会话跟踪，保存用户输入
PostToolUse 工具执行后 拦截并捕获工具使用观察数据
Stop/Summary 会话中途或中断时 生成阶段性会话摘要
SessionEnd 会话结束时 优雅清理资源，确保 Worker 完成处理落盘

3.3 异步 Worker 服务

为了承接高并发、高吞吐量的记忆压缩与语义检索请求，系统引入了独立于主终端进程的常驻 Worker 服务。该服务基于 Bun 运行时（支持崩溃自动重启与全平台兼容），并集成了 Claude Agent SDK，专职处理大模型的推理与计算密集型任务。

核心端点包括：

端点 HTTP 方法 功能说明
/health GET 检查后台服务健康状态
/sessions POST 初始化并创建新的记忆会话
/observations POST 接收并入队新的观察数据
/stream GET 提供基于 SSE 的实时记忆流更新
/api/search GET 提供对外的记忆检索接口

3.4 分层存储引擎

多模态的记忆特性要求底层存储必须兼顾精确的结构化查询与模糊的非结构化语义检索。Claude-Mem 为此构建了基于关系型数据库与向量引擎协同的立体存储网络。

┌─────────────────────────────────────────────────┐
│                 SQLite Database                 │
│  - sdk_sessions: 记录 SDK 会话元数据              │
│  - observations: 存放压缩后的结构化观察             │
│  - session_summaries: 保存会话的提炼摘要           │
│  - pending_messages: 持久化后台工作队列            │
└─────────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────┐
│              FTS5 全文搜索                       │
│  - observations_fts: 观察数据的全文索引            │
│  - session_summaries_fts: 摘要数据的全文索引       │
└─────────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────┐
│             Chroma 向量数据库（可选）              │
│  - 存储语义搜索嵌入向量                            │
│  - 提供高维相似度检索能力                           │
└─────────────────────────────────────────────────┘

3.5 从原始输出到结构化知识

面对极其繁杂的系统调用与工具执行日志，Claude-Mem 巧妙借助了大模型的自然语言理解（NLU）能力，将零散、低信噪比的原始终端输出提炼为高密度的结构化领域知识，实现了高达 10:1 到 100:1 的惊人压缩率。

底层 SQLite 数据库通过 ObservationRow 数据模型，将这些提炼后的高价值资产进行持久化存储：

// 定义 SQLite 数据库中结构化观察记录的数据模型
interface ObservationRow {
  id: number;
  memory_session_id: string;
  project: string;
  type: "decision" | "bugfix" | "feature" | "refactor" | "discovery" | "change";
  title: string | null;
  subtitle: string | null;
  narrative: string | null;
  facts: string | null; // JSON 数组格式
  concepts: string | null; // JSON 数组格式
  files_read: string | null; // JSON 数组格式
  files_modified: string | null; // JSON 数组格式
  discovery_tokens: number; // 用于计算 ROI 的指标
  created_at: string;
  created_at_epoch: number;
}

3.6 Agent SDK 深度集成

为了确保记忆压缩与抽取过程的高效与连贯，后台 Worker 维护了一个持久存活的 SDK Agent 实例，专职负责异步队列中数据的循环流转处理。

通过异步流式生成器持续拉取挂起的观察记录，Worker 服务能源源不断地将最新的终端上下文喂给大模型进行语义压缩：

// 异步生成器：持续向 SDK 会话中流式输入用户的观察数据
async function* messageGenerator(): AsyncIterable<UserMessage> {
  // 1. 初始化系统角色与记忆压缩 Prompt
  yield {
    role: "user",
    content: "You are a memory assistant...",
  };

  // 2. 维持长连接，不断轮询并处理队列中的新观察数据
  while (session.status === "active") {
    const observations = await pollQueue();
    for (const obs of observations) {
      yield {
        role: "user",
        content: formatObservation(obs), // 格式化并提交给大模型
      };
    }
    await sleep(1000); // 避免 CPU 空转，控制拉取频率
  }
}

相比于传统的单次请求模式，这种单一长会话设计不仅降低了系统开销，还大幅提升了语义提炼的连贯性：

核心优势 具体说明
SDK 维护对话状态 保证了压缩时的上下文连贯性，避免语义断层。
上下文自然累积 系统内部自动流转，无需开发者手动管理状态。
更少的 API 调用 减少了握手和系统 Prompt 消耗，显著降低运行成本。
自然的多轮流程 贴合大模型原生交互模式，整体提炼效率更高。

4. 如何高效检索与利用记忆？

为了在有限的 Token 窗口内最大化上下文价值，系统开创性地结合了三层加载策略与标准化的 Model Context Protocol (MCP) 检索接口。

4.1 破解上下文污染

全量加载历史数据的简单粗暴策略会导致严重的 Token 浪费与注意力涣散，这是早期记忆系统面临的共同难题。在 Claude-Mem 的早期版本中，直接加载所有历史记录导致了灾难性的上下文污染：

SessionStart 加载了：
- 150 次文件读取操作
- 80 次 grep 搜索
- 45 次 bash 命令
- 总计：约 35,000 tokens
- 与当前任务相关的：约 500 tokens (1.4%)

大量无关信息不仅消耗了昂贵的 API 额度，还严重降低了 Claude 聚焦当前任务的效率。

4.2 解决方案：三层工作流

为了破解上下文超载的困局，系统开创性地引入了由浅入深的三层记忆唤醒机制，实现了按需加载和精准滴灌。

┌─────────────────────────────────────────────────────────────────┐
│                    3-LAYER WORKFLOW                             │
│                                                                 │
│  Layer 1: search → Get index with IDs (~50-100 tokens/result)   │
│                      ↓                                          │
│  Layer 2: timeline → Get chronological context                  │
│                      ↓                                          │
│  Layer 3: get_observations → Fetch full details (~500-1000 tks) │
└─────────────────────────────────────────────────────────────────┘

该机制将检索过程解耦为索引定位、时序还原与详情拉取三个阶段，各层职责与成本控制如下：

层级 解决的问题 消耗成本
Layer 1 (索引) 回答“存在什么历史记录？” 约 50-100 tokens/结果
Layer 2 (时间线) 回答“事件的上下文和时序是什么？” 动态可变，取决于查询深度
Layer 3 (详情) 回答“具体的技术细节是什么？” 约 500-1000 tokens/结果

4.3 Token 效率提升

通过严格的数据对比可以直观地看到，渐进式披露策略在节省计算资源和提升信息信噪比方面展现出的巨大优势。

方法 使用的 Token 数量 内容相关性
传统全量加载 ~25,000 8%
渐进式披露 ~1,100 100%

此项架构创新直接为单次会话节省了高达 96% 的上下文窗口，极大提升了系统的可用性。

4.4 MCP 工具与工作流指引

系统向大模型暴露了一组标准化的 MCP 接口。为确保大模型能像查阅本地知识库一样灵活追溯开发细节，Agent 必须遵循以下标准化的接口调用顺序，严禁越级拉取详情：

3-LAYER WORKFLOW (ALWAYS FOLLOW):
1. search(query) → Get index with IDs (~50-100 tokens/result)
2. timeline(anchor=ID) → Get context around interesting results
3. get_observations([IDs]) → Fetch full details ONLY for filtered IDs
NEVER fetch full details without filtering first. 10x token savings.

4.5 第一层：搜索索引

作为记忆唤醒的第一步，搜索工具负责在全局范围内快速定位潜在相关的记忆碎片，并返回轻量级的索引列表。

// 调用 search 工具查询指定项目的 Bug 修复记录
search({
  query: "authentication bug",
  obs_type: "bugfix",
  limit: 10,
  project: "my-project",
});

为实现精准定位，搜索工具提供了丰富的多维度过滤参数：

参数 类型 说明
query string 搜索的核心关键词。
limit number 最大返回的结果数（默认 20，最大 100）。
project string 限定搜索的项目范围。
type string 检索的目标表（observations / sessions / prompts）。
obs_type string 观察类型过滤（bugfix, feature, decision, discovery, change）。
dateStart string 检索时间范围的起始日期 (YYYY-MM-DD)。
dateEnd string 检索时间范围的结束日期 (YYYY-MM-DD)。

返回的结果附带直观的类型图标，便于大模型快速判断信息价值：

  • 🟣 Feature（功能）
  • 🔴 Bugfix（修复）
  • 🟡 Decision（决策）
  • 🟢 Discovery（发现）
  • 🔵 Refactor（重构）

4.6 第二层：时间线上下文

在锁定特定记忆节点后，时间线工具能够帮助还原事件发生前后的完整上下文链路，帮助大模型理解“来龙去脉”。

当已知目标观察的 ID 时，可以直接将其作为时间线中心锚点，提取前后关联事件：

// 方式一：通过具体的观察 ID 锚定时间线上下文
timeline({
  anchor: 11131,
  depth_before: 3,
  depth_after: 3,
  project: "my-project",
});

若无明确 ID，工具也支持通过关键字动态匹配锚点并展开上下文：

// 方式二：通过关键字自动查找锚点并获取上下文
timeline({
  query: "authentication",
  depth_before: 3,
  depth_after: 3,
});

4.7 第三层：完整详情

当需要深入了解某次操作的具体细节时，该工具提供了精确拉取完整记忆载体的能力。

// 批量获取指定观察 ID 的完整详细信息
get_observations({
  ids: [11131, 10942],
  orderBy: "date_desc",
});

[!TIP] 最佳实践：Agent 应当始终批量获取多个观察（一次传入数组），坚决避免在循环中逐个发起请求，以节约网络开销和 Token。

4.8 AST 智能代码导航

除了自然语言记忆，系统还提供了基于抽象语法树 (AST) 的代码结构探索工具，进一步提升了对未知代码库的理解效率。

// 使用 AST 解析引擎搜索特定的代码符号（如类名、函数名）
smart_search({
  query: "SessionStore",
  path: "./src",
  max_results: 20,
});

// 提取指定文件的结构大纲，避免加载整个文件内容
smart_outline({
  file_path: "./src/services/sqlite/SessionStore.ts",
});

// 仅展开并读取特定代码符号的完整实现体
smart_unfold({
  file_path: "./src/services/sqlite/SessionStore.ts",
  symbol_name: "getObservationsForSession",
});

5. 如何接入与应用 Claude-Mem？

无论是日常的故障排查，还是长周期的架构演进，Claude-Mem 都能以极低的接入成本，为开发者提供持久的上下文支持。通过标准化的插件安装流程，该系统能够迅速融入现有的工作流，并在复杂的缺陷定位与团队知识传承中释放巨大价值。

5.1 快速开始

只需两条简单的终端命令，即可将持久化记忆能力无缝集成到现有的 Claude Code 工作流中：

# 1. 将 Claude-Mem 插件添加到本地插件市场
/plugin marketplace add thedotmack/claude-mem
# 2. 正式安装插件并初始化底层数据库与 Worker 服务
/plugin install claude-mem

安装完成后重启 Claude Code，系统便会自动接管上下文注入。

5.2 首次会话体验

接入插件后，系统将在 Claude Code 的生命周期中自动接管记忆流的读写。开发者可以在不同交互阶段直观感受到上下文无缝注入所带来的连贯性与效率跃升：

阶段 系统动作
会话开始时 自动向上下文中注入最近 10 个会话的摘要索引。
工作中 伴随开发过程，实时捕获工具调用并生成结构化观察。
会话结束时 在后台静默生成本次会话的全局摘要，为下次启动做准备。

此外，开发者可以通过浏览器访问 http://localhost:37777 打开 Web 查看器，实时监控并管理记忆流。

5.3 隐私与数据控制

在自动化收集上下文的同时，系统赋予了开发者绝对的数据控制权，确保敏感信息的物理隔离。开发者只需使用 <private> 标签包裹敏感内容：

<!-- 使用 private 标签包裹的内容将在前端 Hook 层被直接拦截，绝不会写入后台数据库 -->
<private>
  这段内容包含极其敏感的生产环境配置，不会被存储到记忆中。
  API_KEY=sk-xxxxx
</private>

标签的剥离处理直接发生在前端的 Hook 拦截层（边缘处理）。这意味着被保护的数据在到达后台 Worker 和数据库之前就已经被彻底擦除。

5.4 长期开发项目

在生命周期较长的工程中，记忆系统能够有效打破时间造成的认知断层，保持开发节奏的一致性。Claude-Mem 可以在长达数月的开发周期内，随时通过 search 唤醒上个月针对性能瓶颈做出的架构妥协与解决方案。

5.5 复杂缺陷排查

面对错综复杂的系统缺陷，记忆记录能够清晰复现排查链路，避免陷入重复试错的泥潭。它忠实记录了 Agent 查看过的所有核心文件、失败的尝试逻辑以及关键线索。即使调查被中断数日，再次接手时也能一秒恢复现场思路。

5.6 团队知识传递

结构化的历史记忆天然具备沉淀团队经验的属性，为新成员快速融入项目提供了极具价值的参考资产。新人可以直接询问项目的架构决策史、高频踩坑点以及核心模块的演进脉络，大幅降低 Onboarding 成本。

6. 总结：迈向长期化 AI 结对编程

通过重新定义 AI 助手的上下文管理边界，Claude-Mem 不仅是一款简单的工具插件，更是迈向真正自主化、长期化 AI 结对编程的重要里程碑。持久化记忆带来的不仅是操作上的便利，更是从根本上提升了 AI 协同开发的信噪比与产出质量。在实际应用中，该系统通过独创的渐进式披露机制成功削减了 96% 的上下文浪费，并巧妙借助大模型的自然语言理解能力，实现了高达 100:1 的终端日志压缩率。同时，毫秒级的全局搜索延迟与后台异步 Worker 服务，确保了前端交互的绝对丝滑。

其克制而强大的底层架构，确保了在提供深度上下文支持的同时，最大程度降低了对开发者的认知负担。正如该项目的核心理念所言：“让 AI 随着时间变得更聪明，但始终保持隐形。”

随着大模型能力的不断进化，这类记忆系统也将朝着更加自适应与协作化的方向持续演进。根据官方透露的演进路线，Claude-Mem 未来计划引入基于 Embedding 相似度的相关性预排序、跨项目模式识别能力，乃至面向团队协作的共享记忆网络，进一步释放 AI 在软件工程中的潜能。

7. 参考资源

7.1 官方资源

资源名称 访问链接
官方文档 https://docs.claude-mem.ai
GitHub 仓库 https://github.com/thedotmack/claude-mem
Discord 社区 https://discord.com/invite/J4wttp9vDu
官方 X (Twitter) @Claude_Memory

7.2 社区评测与文章