Claude-Mem 深度解析：让 Claude Code 拥有持久记忆的工程实践

引言：AI 编程助手的记忆困境

用过 Claude Code 的开发者都有一个共同的痛点：每次新开会话，都要重新解释一遍项目背景。

"这是一个 React + TypeScript 项目，使用 Vite 构建，状态管理用 Zustand，API 层封装在 /src/api 目录下..."

这样的开场白，资深用户可能已经说了几十遍。Claude Code 虽然强大，但本质上仍是一个"短期记忆"系统——会话结束，上下文清空，下次重来。

这种"失忆"带来的成本是实实在在的：

• 时间成本：每次 5-10 分钟的项目背景说明
• 认知成本：重复解释已做过的技术决策
• 错误成本：模型因缺乏历史上下文而做出矛盾建议
• 成本成本：冗余的上下文占用宝贵的 token 额度

2026 年 4 月，GitHub 上一个名为 claude-mem 的开源项目以惊人的速度蹿红——54,592 Stars，单日增长超过 3,185 Stars。它为 Claude Code 构建了一套完整的持久记忆系统，让 AI 编程助手真正拥有了"长期记忆"能力。

本文将从架构设计、实现原理、源码解析到实战部署，全方位剖析 claude-mem 的技术内幕。

一、核心架构：三层记忆工作流

claude-mem 的设计理念可以用一句话概括：不是简单存储，而是智能压缩与精准注入。

1.1 系统架构全景

┌─────────────────────────────────────────────────────────────────┐
│                     Claude Code 会话层                           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │ 用户输入    │  │ 工具调用    │  │ 上下文组装              │  │
│  └──────┬──────┘  └──────┬──────┘  └───────────┬─────────────┘  │
└─────────┼────────────────┼────────────────────┼────────────────┘
          │                │                    │
          ▼                ▼                    ▼
┌─────────────────────────────────────────────────────────────────┐
│                     claude-mem 核心层                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │ Hook 拦截器  │  │ 观察记录器   │  │ 记忆压缩引擎         │  │
│  │ (5个生命周期)│  │ (结构化捕获) │  │ (AI 摘要生成)        │  │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬───────────┘  │
└─────────┼─────────────────┼────────────────────┼───────────────┘
          │                 │                    │
          ▼                 ▼                    ▼
┌─────────────────────────────────────────────────────────────────┐
│                     存储与检索层                                 │
│  ┌──────────────────┐  ┌──────────────────────────────────────┐ │
│  │ SQLite + FTS5    │  │ Chroma 向量数据库                    │ │
│  │ (结构化数据存储) │  │ (语义相似度检索)                     │ │
│  └──────────────────┘  └──────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

1.2 五层生命周期钩子

claude-mem 通过 Claude Code 的 Plugin Hook 机制，在五个关键生命周期节点植入记忆逻辑：

这种设计的关键在于渐进式记忆构建——不是等到会话结束才一股脑存储，而是在整个会话过程中持续捕获、增量压缩。

1.3 三层搜索工作流

claude-mem 的记忆检索采用**渐进式披露（Progressive Disclosure）**策略，按优先级分层加载：

// 伪代码示意三层搜索流程
async function retrieveRelevantMemories(query: string, projectPath: string) {
  const memories = [];
  
  // Layer 1: 精确匹配（项目级 CLAUDE.md + 最近会话摘要）
  memories.push(await searchExactMatches(projectPath, 5));
  
  // Layer 2: 关键词检索（SQLite FTS5 全文搜索）
  memories.push(await searchKeywordMatches(query, 10));
  
  // Layer 3: 语义检索（Chroma 向量数据库相似度搜索）
  memories.push(await searchSemanticMatches(query, 5));
  
  // 去重、排序、截断，确保总 token 不超过阈值
  return deduplicateAndRank(memories).slice(0, MAX_TOKENS);
}

这种分层设计确保最相关的记忆优先加载，同时控制总体 token 消耗。据项目文档称，相比加载完整历史，这种策略可节省约 10 倍 token。

二、实现原理：从观察到压缩的完整链路

2.1 观察记录（Observation）的数据模型

claude-mem 捕获的每一条"观察"都是一个结构化对象：

interface Observation {
  // 基础元数据
  id: string;                    // UUID v4
  timestamp: number;             // Unix 毫秒时间戳
  sessionId: string;             // 所属会话 ID
  projectPath: string;           // 项目绝对路径（用于关联）
  
  // 观察类型
  type: 'tool_use' | 'user_message' | 'assistant_message' | 'file_change';
  
  // 工具调用详情（type='tool_use' 时）
  tool?: {
    name: string;                // 工具名称：Read/Write/Edit/Bash/Glob/Grep...
    parameters: Record<string, any>;  // 调用参数
    result: string;              // 工具返回结果（截断存储）
    duration: number;            // 执行耗时（ms）
  };
  
  // 内容（消息类型时）
  content?: string;              // 原始内容（压缩存储）
  
  // 文件变更（type='file_change' 时）
  fileChange?: {
    path: string;                // 文件路径
    changeType: 'create' | 'modify' | 'delete';
    diff?: string;               // 变更 diff（大文件截断）
    language?: string;           // 编程语言（用于语法高亮）
  };
  
  // 用于检索的索引字段
  keywords: string[];            // 提取的关键词
  embedding?: number[];          // 向量嵌入（由 Chroma 生成）
}

这种结构化设计的精妙之处在于：

1. 类型安全：TypeScript 接口确保数据一致性
2. 可扩展性：新增观察类型只需扩展枚举
3. 检索友好：关键词和 embedding 字段支持多模态检索
4. 存储效率：大字段（如 diff）支持智能截断

2.2 AI 压缩引擎：从原始上下文到高密度记忆

这是 claude-mem 最核心的技术创新。不是简单存储原始文本，而是使用 Claude API 本身进行智能压缩：

// 记忆压缩的核心算法
async function compressObservations(
  observations: Observation[],
  sessionContext: SessionContext
): Promise<CompressedMemory> {
  
  // 1. 按时间窗口分组（避免单条记忆过大）
  const chunks = groupByTimeWindow(observations, MAX_WINDOW_MS);
  
  // 2. 对每个时间窗口生成摘要
  const summaries = await Promise.all(
    chunks.map(async chunk => {
      const prompt = buildCompressionPrompt(chunk, sessionContext);
      
      // 调用 Claude API 生成高密度摘要
      const summary = await claudeApi.complete({
        model: 'claude-3-5-sonnet-20241022',
        max_tokens: 500,
        temperature: 0.1,  // 低温度确保事实准确性
        messages: [{
          role: 'user',
          content: prompt
        }]
      });
      
      return {
        timeRange: [chunk[0].timestamp, chunk[chunk.length - 1].timestamp],
        summary: summary.content,
        keyDecisions: extractDecisions(summary.content),
        codeReferences: extractCodeRefs(chunk)
      };
    })
  );
  
  // 3. 生成会话级元摘要
  const metaSummary = await generateMetaSummary(summaries);
  
  return {
    sessionId: sessionContext.id,
    createdAt: Date.now(),
    projectPath: sessionContext.projectPath,
    summaries,
    metaSummary,
    tokenSaved: calculateTokenSavings(observations, summaries)
  };
}

// 压缩提示词模板
function buildCompressionPrompt(
  chunk: Observation[],
  context: SessionContext
): string {
  return `你是一位技术文档专家。请将以下 Claude Code 会话记录压缩成高密度技术摘要。

原始记录（${chunk.length} 条观察）：
${formatObservations(chunk)}

项目背景：
- 项目路径：${context.projectPath}
- 技术栈：${context.techStack || '未知'}
- 会话目标：${context.goal || '通用编码任务'}

请生成摘要，包含以下要素：
1. 【执行的操作】：用户要求做了什么
2. 【探索过程】：如何调研和定位问题
3. 【关键决策】：做了哪些技术选择，为什么
4. 【代码变更】：修改了哪些文件，核心逻辑是什么
5. 【经验教训】：遇到的问题和解决方案
6. 【后续建议】：下一步可以做什么

要求：
- 使用技术术语，保持专业
- 保留关键代码片段（用 \\\`\\\`\\\` 包裹）
- 总长度控制在 300-500 tokens
- 去除冗余对话，保留实质内容`;
}

这种压缩策略的效果是显著的。以一个典型编码会话为例：

2.3 向量检索的语义增强

claude-mem 不仅支持关键词检索，还集成了 Chroma 向量数据库实现语义搜索：

# Chroma 集成示意（简化版）
from chromadb import Client, Settings
import hashlib

class MemoryVectorStore:
    def __init__(self, db_path: str):
        self.client = Client(Settings(
            chroma_db_impl="duckdb+parquet",
            persist_directory=db_path
        ))
        self.collection = self.client.get_or_create_collection(
            name="claude_memories",
            metadata={"hnsw:space": "cosine"}
        )
    
    def add_memory(self, memory: CompressedMemory):
        """添加记忆到向量库"""
        # 生成文档 ID（基于内容哈希，确保幂等性）
        doc_id = hashlib.sha256(
            memory.metaSummary.encode()
        ).hexdigest()[:16]
        
        # 提取用于 embedding 的文本
        documents = [s.summary for s in memory.summaries]
        
        # 元数据用于过滤
        metadatas = [{
            "session_id": memory.sessionId,
            "project_path": memory.projectPath,
            "created_at": memory.createdAt,
            "type": "session_summary"
        }]
        
        self.collection.add(
            ids=[doc_id],
            documents=documents,
            metadatas=metadatas
        )
    
    def search_similar(
        self, 
        query: str, 
        project_path: str = None,
        top_k: int = 5
    ) -> List[MemoryResult]:
        """语义相似度搜索"""
        
        # 构建过滤条件
        where_filter = None
        if project_path:
            where_filter = {"project_path": project_path}
        
        results = self.collection.query(
            query_texts=[query],
            n_results=top_k,
            where=where_filter
        )
        
        return self._format_results(results)

向量检索的优势在于语义理解能力。例如，用户查询"怎么优化 React 性能"，即使历史记忆中没有出现"性能优化"字样，只要包含"useMemo"、"虚拟列表"、"代码分割"等相关内容，语义检索也能召回。

三、源码解析：关键模块实现

3.1 Hook 系统的实现

claude-mem 通过 Claude Code 的 Plugin API 注册生命周期钩子：

// src/hooks/index.ts
import { ClaudePlugin, HookContext } from '@anthropic-ai/claude-plugin-sdk';

export class MemoryHooks implements ClaudePlugin {
  private storage: MemoryStorage;
  private compressor: MemoryCompressor;
  private vectorStore: VectorStore;
  
  async onSessionStart(ctx: HookContext): Promise<void> {
    const { projectPath } = ctx;
    
    // 1. 检索相关记忆
    const relevantMemories = await this.retrieveMemories(projectPath);
    
    // 2. 构建记忆注入提示
    const memoryPrompt = this.buildMemoryPrompt(relevantMemories);
    
    // 3. 注入到 Claude 上下文
    ctx.injectSystemMessage(memoryPrompt);
    
    console.log(`[claude-mem] 已注入 ${relevantMemories.length} 条相关记忆`);
  }
  
  async onPostToolUse(ctx: HookContext, toolResult: ToolResult): Promise<void> {
    // 创建观察记录
    const observation: Observation = {
      id: generateUUID(),
      timestamp: Date.now(),
      sessionId: ctx.sessionId,
      projectPath: ctx.projectPath,
      type: 'tool_use',
      tool: {
        name: toolResult.toolName,
        parameters: toolResult.parameters,
        result: this.truncateResult(toolResult.result),
        duration: toolResult.duration
      },
      keywords: this.extractKeywords(toolResult)
    };
    
    // 存储到 SQLite
    await this.storage.saveObservation(observation);
  }
  
  async onSessionEnd(ctx: HookContext): Promise<void> {
    // 1. 获取本会话的所有观察
    const observations = await this.storage.getSessionObservations(ctx.sessionId);
    
    // 2. 压缩生成记忆
    const compressedMemory = await this.compressor.compress(
      observations,
      ctx
    );
    
    // 3. 存储到 SQLite
    await this.storage.saveMemory(compressedMemory);
    
    // 4. 添加到向量库
    await this.vectorStore.addMemory(compressedMemory);
    
    console.log(`[claude-mem] 会话记忆已持久化，节省 ${compressedMemory.tokenSaved} tokens`);
  }
  
  private buildMemoryPrompt(memories: CompressedMemory[]): string {
    if (memories.length === 0) return '';
    
    const sections = memories.map((m, i) => `
## 历史会话 ${i + 1} (${formatDate(m.createdAt)})
${m.metaSummary}

关键决策：
${m.summaries.flatMap(s => s.keyDecisions).map(d => `- ${d}`).join('\n')}
`).join('\n---\n');
    
    return `以下是你在本项目的历史工作记录，供参考：

${sections}

注意：以上信息来自历史会话，当前任务可能需要在此基础上继续推进。`;
  }
}

3.2 SQLite 存储层设计

claude-mem 使用 SQLite 作为本地存储引擎，schema 设计兼顾查询性能和存储效率：

-- 观察记录表（高频写入）
CREATE TABLE observations (
    id TEXT PRIMARY KEY,
    session_id TEXT NOT NULL,
    project_path TEXT NOT NULL,
    timestamp INTEGER NOT NULL,
    type TEXT NOT NULL,
    tool_name TEXT,
    tool_params TEXT,  -- JSON
    tool_result TEXT,
    content TEXT,
    file_path TEXT,
    file_change_type TEXT,
    keywords TEXT,     -- 逗号分隔，用于 FTS5
    created_at INTEGER DEFAULT (unixepoch() * 1000)
);

-- 全文搜索虚拟表
CREATE VIRTUAL TABLE observations_fts USING fts5(
    content='observations',
    content_rowid='rowid',
    keywords,
    tool_result,
    content
);

-- 压缩记忆表（低频写入，高频读取）
CREATE TABLE memories (
    id TEXT PRIMARY KEY,
    session_id TEXT UNIQUE NOT NULL,
    project_path TEXT NOT NULL,
    created_at INTEGER NOT NULL,
    meta_summary TEXT NOT NULL,
    summaries TEXT NOT NULL,  -- JSON 数组
    token_saved INTEGER,
    -- 用于快速检索的索引字段
    key_decisions TEXT,       -- JSON 数组
    code_refs TEXT            -- JSON 数组
);

-- 索引优化
CREATE INDEX idx_obs_project ON observations(project_path, timestamp DESC);
CREATE INDEX idx_obs_session ON observations(session_id, timestamp);
CREATE INDEX idx_memories_project ON memories(project_path, created_at DESC);
CREATE INDEX idx_memories_time ON memories(created_at DESC);

-- 触发器：自动同步 FTS5
CREATE TRIGGER observations_ai AFTER INSERT ON observations BEGIN
    INSERT INTO observations_fts(rowid, keywords, tool_result, content)
    VALUES (new.rowid, new.keywords, new.tool_result, new.content);
END;

3.3 Worker 服务架构

claude-mem 使用 Bun 运行一个本地 HTTP 服务，处理耗时操作（如向量检索、AI 压缩）：

// src/worker/server.ts
import { serve } from 'bun';

const server = serve({
  port: 37777,  // 默认端口，可配置
  
  async fetch(req: Request): Promise<Response> {
    const url = new URL(req.url);
    
    switch (url.pathname) {
      case '/api/search':
        return handleSearch(req);
      case '/api/compress':
        return handleCompression(req);
      case '/api/stats':
        return handleStats(req);
      case '/api/webui':
        return serveWebUI();  // 内置记忆浏览界面
      default:
        return new Response('Not Found', { status: 404 });
    }
  }
});

async function handleSearch(req: Request): Promise<Response> {
  const { query, projectPath, limit = 10 } = await req.json();
  
  // 并行执行三层搜索
  const [exactMatches, keywordMatches, semanticMatches] = await Promise.all([
    searchExact(projectPath, limit),
    searchKeywords(query, limit),
    searchSemantic(query, projectPath, limit)
  ]);
  
  // 融合排序（Reciprocal Rank Fusion）
  const fused = reciprocalRankFusion([
    exactMatches,
    keywordMatches,
    semanticMatches
  ]);
  
  return Response.json({
    results: fused.slice(0, limit),
    sources: {
      exact: exactMatches.length,
      keyword: keywordMatches.length,
      semantic: semanticMatches.length
    }
  });
}

// RRF 融合算法
function reciprocalRankFusion(lists: SearchResult[][]): SearchResult[] {
  const scores = new Map<string, number>();
  const items = new Map<string, SearchResult>();
  
  const k = 60;  // RRF 常数
  
  lists.forEach(list => {
    list.forEach((item, rank) => {
      const id = item.memoryId;
      const score = 1 / (k + rank + 1);
      scores.set(id, (scores.get(id) || 0) + score);
      items.set(id, item);
    });
  });
  
  return Array.from(items.values())
    .sort((a, b) => scores.get(b.memoryId)! - scores.get(a.memoryId)!);
}

四、实战部署与配置

4.1 安装步骤

# 方式一：通过 Claude Code 插件市场安装（推荐）
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

# 方式二：手动安装
npm install -g claude-mem
claude-mem install

# 安装后会自动：
# 1. 检测并安装 Bun（如果未安装）
# 2. 在 ~/.claude/ 目录注册 Hooks
# 3. 启动 worker 服务（端口 37777）
# 4. 初始化 SQLite 数据库

4.2 配置文件详解

// ~/.claude-mem/config.json
{
  "storage": {
    "sqlitePath": "~/.claude-mem/memories.db",
    "vectorDbPath": "~/.claude-mem/vectors",
    "maxDbSize": "1GB"
  },
  "compression": {
    "model": "claude-3-5-sonnet-20241022",
    "maxTokensPerSummary": 500,
    "temperature": 0.1,
    "timeWindowMs": 300000  // 5 分钟聚合窗口
  },
  "retrieval": {
    "maxMemoriesPerSession": 5,
    "maxTokensPerMemory": 800,
    "exactMatchWeight": 1.0,
    "keywordMatchWeight": 0.8,
    "semanticMatchWeight": 0.6
  },
  "server": {
    "port": 37777,
    "host": "127.0.0.1",
    "enableWebUI": true,
    "webUIPort": 37778
  },
  "privacy": {
    "excludePatterns": [
      "*.key",
      "*.pem",
      ".env*",
      "**/secrets/**"
    ],
    "maskCredentials": true,
    "localOnly": true  // 数据永不离开本地
  }
}

4.3 使用 MCP 工具主动管理记忆

claude-mem 提供 4 个 MCP 工具，可在 Claude Code 中直接调用：

// 1. 搜索记忆
/search_memories query="用户认证实现"

// 2. 查看最近记忆
/recent_memories limit=5

// 3. 手动添加记忆
/add_memory content="项目使用 JWT + Redis 实现分布式会话"

// 4. 删除记忆（支持按项目、时间范围删除）
/delete_memories project="~/my-project" before="2026-01-01"

4.4 Web UI 界面

claude-mem 内置一个轻量级 Web 界面，方便浏览和管理记忆：

# 启动 Web UI
claude-mem webui

# 或访问
open http://localhost:37778

Web UI 功能包括：

• 按项目浏览历史会话
• 全文搜索记忆内容
• 查看记忆详情和元数据
• 手动编辑或删除记忆
• 导出/导入记忆数据

五、性能优化与最佳实践

5.1 Token 节省实测

我们在一个真实项目中测试了 claude-mem 的效果：

测试场景：中型 React 项目（约 200 个组件），连续 10 个编码会话

5.2 记忆质量优化建议

1. 定期清理过期记忆

   # 删除 3 个月前的记忆
   claude-mem cleanup --before "3 months ago"
   

2. 为重要项目创建 CLAUDE.md

   # CLAUDE.md
   ## 项目概述
   - 名称：电商平台前端
   - 技术栈：Next.js 14 + TypeScript + Tailwind + Prisma
   
   ## 架构决策
   - 状态管理：Zustand（轻量，避免 Redux  boilerplate）
   - 数据获取：React Query + Server Actions
   - 认证：NextAuth.js + JWT
   
   ## 代码规范
   - 组件使用函数式 + Hooks
   - API 层统一放在 `/src/lib/api`
   - 错误处理使用自定义 Error Boundary
   

3. 调整压缩参数

   • 对于复杂项目，增加 timeWindowMs 以捕获更多上下文
   • 对于简单任务，降低 maxTokensPerSummary 节省存储

5.3 故障排查

六、与其他记忆方案的对比

claude-mem 的核心优势在于零配置自动化——安装后无需额外操作，即可在后台持续工作。相比手动维护的 CLAUDE.md，它能捕获更多隐式知识；相比云端方案，它提供了更好的隐私保护。

七、未来展望与局限性

7.1 当前局限性

1. 仅支持 Claude Code：目前无法用于其他 AI 编程工具（如 Cursor、GitHub Copilot）
2. 压缩质量依赖模型：AI 生成的摘要可能遗漏某些细节
3. 本地存储限制：SQLite 在极端大规模场景下（百万级记忆）性能可能下降
4. 无协作功能：不支持团队共享记忆

7.2 路线图

根据项目 GitHub 的 Roadmap，未来计划包括：

• v0.5：支持 Cursor 和 Windsurf 编辑器
• v0.6：团队协作功能（共享记忆空间）
• v0.7：智能记忆合并（自动识别重复记忆）
• v1.0：跨设备同步（端到端加密）

八、总结

claude-mem 代表了 AI 编程助手向"持续学习系统"演进的重要一步。它通过智能压缩和精准注入两大核心技术，解决了 Claude Code 的"失忆"问题，让 AI 助手真正拥有了长期记忆能力。

对于重度 Claude Code 用户，claude-mem 带来的价值是显而易见的：

• 时间节省：告别重复的项目背景说明
• 体验提升：会话间无缝衔接，像与一位了解项目的资深工程师对话
• 成本优化：智能记忆检索减少冗余 token 消耗
• 知识沉淀：编码过程中的决策和经验被持久化保存

如果你每天使用 Claude Code 超过 2 小时，claude-mem 几乎是必装插件。它的安装成本接近于零，但带来的效率提升是持续累积的——就像为 Claude Code 装上了一个外接大脑。

参考资源

• GitHub 仓库：https://github.com/thedotmack/claude-mem
• 官方文档：https://docs.claude-mem.dev
• MCP 协议规范：https://modelcontextprotocol.io
• Claude Code 官方文档：https://docs.anthropic.com/en/docs/claude-code

本文撰写于 2026 年 4 月，基于 claude-mem v0.4.2 版本。项目迭代迅速，部分细节可能已有更新，请以官方文档为准。