项目总览

相关源文件

本页面内容基于以下源文件生成：

• README.md
• CLAUDE.md
• package.json
• docs/public/introduction.mdx
• src/services/sqlite/types.ts
• src/services/sqlite/index.ts
• src/services/sqlite/Import.ts
• src/services/sqlite/Prompts.ts
• src/services/sqlite/Database.ts
• src/services/sqlite/Timeline.ts

Claude-Mem 是一个为 Claude Code 构建的持久化记忆压缩系统，通过自动捕获工具使用观察、生成语义摘要，并在后续会话中注入相关上下文，实现跨会话的知识连续性。该项目采用 TypeScript 开发，基于 AGPL-3.0 许可证开源，当前版本为 10.6.1（package.json:1-20）。

系统的核心价值在于解决 AI 辅助编程工具的"记忆遗忘"问题——每次新会话开始时，Claude 无法访问之前会话中的项目知识、决策历史和代码上下文。Claude-Mem 通过生命周期钩子机制自动捕获会话数据，使用 Claude Agent SDK 进行智能压缩，并借助混合搜索（全文检索 + 向量语义）在适当时机注入历史上下文，从而实现"持久记忆"能力（docs/public/introduction.mdx:1-30）。

系统架构与核心组件

Claude-Mem 采用分层架构设计，由生命周期钩子层、Worker 服务层、数据持久层和搜索能力层四个核心层次构成。各层职责明确，通过 HTTP API 和文件系统进行解耦通信。

架构总览

正在加载图表渲染器...

架构要点说明：

1. 钩子层边界：5 个生命周期钩子运行在 Claude Code 进程内，通过 HTTP 调用与 Worker 服务通信，实现进程隔离（CLAUDE.md:5-24）
2. Worker 服务职责：Express API 监听 37777 端口，处理异步 AI 处理任务，由 Bun 管理进程生命周期（README.md:201-213）
3. 数据层分离：SQLite 存储结构化数据（会话、观察、摘要），Chroma 存储向量嵌入支持语义搜索
4. 技能层入口：mem-search 技能和 MCP 工具作为用户查询入口，通过 HTTP API 访问数据层

核心模块详解

生命周期钩子系统

钩子系统是 Claude-Mem 与 Claude Code 的集成点，遵循 Claude Code 的钩子契约规范。每个钩子在不同生命周期阶段被触发，负责捕获特定类型的数据。

钩子使用特定退出码策略：Exit 0 表示成功或优雅关闭；Exit 1 表示非阻塞错误（stderr 显示给用户但继续执行）；Exit 2 表示阻塞错误（stderr 传递给 Claude 处理）。Worker/钩子错误统一使用 Exit 0 以防止 Windows Terminal 标签页累积（CLAUDE.md:48-58）。

Worker 服务模块

Worker 服务是系统的核心处理引擎，基于 Express 框架构建，提供 10+ 个搜索端点和异步 AI 处理能力。服务由 Bun 运行时管理，支持自动重启和日志记录。

typescript
1// Worker 服务核心配置（示意）
2const WORKER_PORT = 37777;
3const WORKER_SCRIPT = 'plugin/scripts/worker-service.cjs';
4
5// 进程管理命令
6bun ${WORKER_SCRIPT} start    // 启动服务
7bun ${WORKER_SCRIPT} stop     // 停止服务
8bun ${WORKER_SCRIPT} restart  // 重启服务
9bun ${WORKER_SCRIPT} status   // 查询状态

Worker 服务的关键 API 端点包括：搜索索引、时间线查询、观察详情获取、会话管理等。所有端点在 localhost:37777 上开放，Pro 功能通过许可证验证而非修改核心端点实现访问控制（CLAUDE.md:72-91）。

SQLite 数据库模块

数据库模块位于 src/services/sqlite/ 目录，使用 SQLite3 存储会话、观察和摘要数据。数据库文件位于 ~/.claude-mem/claude-mem.db，支持 FTS5 全文搜索。

核心数据表结构（基于架构推断）：

数据库模块提供类型安全的 TypeScript 接口，定义在 src/services/sqlite/types.ts 中，支持批量导入、提示管理、时间线查询等操作（CLAUDE.md:13）。

Chroma 向量数据库模块

Chroma 向量数据库提供语义搜索能力，存储在 ~/.claude-mem/chroma/ 目录。系统实现混合搜索策略：结合全文检索（FTS5）和向量语义匹配，提高上下文检索的准确性。

向量嵌入通过 Claude Agent SDK 生成，支持自然语言查询。当用户询问项目历史时，系统首先进行语义匹配，再通过时间线获取上下文，最后按需获取完整观察详情（CLAUDE.md:21）。

MCP 搜索工具与工作流

Claude-Mem 提供 4 个 MCP（Model Context Protocol）搜索工具，采用 token 高效的 3 层工作流模式，实现约 10 倍的 token 节省。

3 层工作流模式

正在加载图表渲染器...

工作流要点说明：

1. 第一层 - search：返回紧凑索引，包含 ID 和元数据，每个结果约 50-100 tokens。支持按类型、日期、项目过滤（README.md:216-238）
2. 第二层 - timeline：获取特定观察周围的时序上下文，帮助理解事件发生背景
3. 第三层 - get_observations：仅对过滤后的 ID 获取完整详情，每个结果约 500-1000 tokens
4. token 优化原理：先获取轻量索引进行筛选，再按需获取完整数据，避免传输大量无关内容

可用 MCP 工具列表

MCP 工具支持自然语言查询，Claude 可直接调用这些工具搜索项目历史，无需用户手动触发（docs/public/introduction.mdx:23-30）。

技术栈与版本信息

Claude-Mem 采用现代 TypeScript 技术栈，依赖 Bun 作为主要运行时，结合 Node.js 生态工具链。

核心技术栈

项目使用 esbuild 进行快速构建，支持 tree-sitter 多语言解析（C、C++、Go、Java、JavaScript、Python、Ruby、Rust、TypeScript），为代码分析提供基础能力（package.json:98-132）。

构建与部署脚本

bash
1# 核心构建命令
2npm run build              # 构建钩子脚本
3npm run build-and-sync     # 构建 + 同步到市场 + 重启 Worker
4
5# Worker 管理
6npm run worker:start       # 启动 Worker 服务
7npm run worker:stop        # 停止 Worker 服务
8npm run worker:restart     # 重启 Worker 服务
9npm run worker:status      # 查询 Worker 状态
10npm run worker:logs        # 查看最近日志
11npm run worker:tail        # 实时跟踪日志
12
13# 队列管理
14npm run queue              # 检查待处理队列
15npm run queue:process      # 处理待处理队列
16npm run queue:clear        # 清除失败队列
17
18# 测试
19npm run test               # 运行所有测试
20npm run test:sqlite        # SQLite 模块测试
21npm run test:agents        # Agent 测试
22npm run test:search        # 搜索功能测试

项目使用 np 工具进行版本发布，支持 patch/minor/major 三种发布模式（package.json:48-97）。

文件结构与配置

目录结构

claude-mem/
├── src/                          # 源代码目录
│   ├── hooks/                    # 生命周期钩子
│   ├── services/
│   │   ├── sqlite/               # SQLite 数据库模块
│   │   │   ├── types.ts          # 类型定义
│   │   │   ├── index.ts          # 模块入口
│   │   │   ├── Import.ts         # 数据导入
│   │   │   ├── Prompts.ts        # 提示管理
│   │   │   ├── Database.ts       # 数据库核心
│   │   │   └── Timeline.ts       # 时间线查询
│   │   ├── worker-service.ts     # Worker 服务
│   │   └── sync/
│   │       └── ChromaSync.ts     # Chroma 同步
│   ├── ui/viewer/                # React Viewer UI
│   └── utils/
│       └── tag-stripping.ts      # 隐私标签处理
├── plugin/                       # 构建产物目录
│   ├── scripts/                  # 编译后的钩子脚本
│   ├── skills/                   # 技能定义
│   │   ├── mem-search/           # 记忆搜索技能
│   │   ├── make-plan/            # 规划技能
│   │   └── do/                   # 执行技能
│   ├── modes/                    # 多语言模式
│   └── ui/viewer.html            # Viewer UI 入口
├── docs/                         # 文档源码
│   └── public/                   # MDX 文档文件
├── scripts/                      # 构建脚本
└── package.json

关键文件位置

配置文件在首次运行时自动创建，包含默认设置。隐私标签 <private> 在钩子层进行处理，数据到达 Worker/数据库前即被剥离（CLAUDE.md:36-47）。

npm 包导出配置

json
1{
2  "exports": {
3    ".": {
4      "types": "./dist/index.d.ts",
5      "import": "./dist/index.js"
6    },
7    "./sdk": {
8      "types": "./dist/sdk/index.d.ts",
9      "import": "./dist/sdk/index.js"
10    },
11    "./modes/*": "./plugin/modes/*"
12  },
13  "files": ["dist", "plugin"]
14}

包导出支持主入口、SDK 入口和多语言模式路径，发布时包含 dist 和 plugin 目录（package.json:29-47）。

核心特性与适用场景

核心特性

1. 🧠 持久记忆：上下文跨会话保持，解决 AI 助手"遗忘"问题
2. 📁 文件夹上下文：自动在项目文件夹生成 CLAUDE.md，包含活动时间线
3. 🌐 多语言模式：支持 28 种语言（中文、西班牙语、法语、日语等）
4. 🎭 模式系统：可切换工作流模式（代码、邮件调查、休闲等）
5. 🔍 MCP 搜索工具：自然语言查询项目历史，3 层工作流优化 token 消耗
6. 📊 混合搜索：结合 FTS5 全文检索和 Chroma 向量语义搜索
7. 🔒 隐私控制：支持 <private> 标签手动阻止特定内容存储
8. ⚡ 异步处理：Worker 服务异步处理 AI 压缩，不阻塞主会话

适用场景

量化指标

• 支持语言数：28 种语言模式
• 生命周期钩子：5 个核心钩子 + 1 个预钩子（智能安装检查）
• 搜索端点：10+ 个 HTTP API 端点
• MCP 工具：3 个核心搜索工具
• Token 节省：约 10 倍（通过 3 层工作流）
• 运行时要求：Bun >=1.0.0, Node.js >=18.0.0

报告阅读路线图

以下 Mermaid 图表展示本技术分析报告各章节的关系与推荐阅读顺序：

正在加载图表渲染器...

推荐阅读路径：

1. 快速入门路径：项目总览 → 架构设计 → 钩子系统 → 配置管理
2. 深度理解路径：项目总览 → 架构设计 → 数据模型 → API 设计 → 搜索机制
3. 开发集成路径：项目总览 → 钩子系统 → API 设计 → 配置管理

各章节详细内容将在后续页面展开，涵盖源码级实现细节、关键数据结构、调用链分析和错误处理策略。