架构总览

相关源文件

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

• docs/public/architecture/overview.mdx
• docs/public/architecture/hooks.mdx
• docs/public/architecture/worker-service.mdx
• docs/public/architecture/database.mdx
• src/services/worker-service.ts
• src/services/sqlite/Database.ts
• src/services/sqlite/types.ts
• src/services/sqlite/index.ts
• src/services/sqlite/Import.ts
• src/services/sqlite/Prompts.ts
• src/sdk/index.ts
• openclaw/src/index.ts
• installer/src/index.ts
• src/supervisor/index.ts
• scripts/bug-report/index.ts
• scripts/translate-readme/index.ts
• src/cli/adapters/index.ts
• src/cli/handlers/index.ts
• src/services/server/index.ts
• src/services/context/index.ts

Claude-Mem 是一个 Claude Code 插件，通过 5 阶段 Hook 系统捕获开发工作，并利用 SQLite + FTS5 实现持久化存储与全文检索。以下从系统组件、数据流、会话生命周期、目录结构及组件详情等方面展开架构分析。

系统组件

Claude-Mem 作为 Claude Code 插件运行，包含五个核心组件（docs/public/architecture/overview.mdx:8-33）：

技术栈采用 TypeScript（ES2022，ESNext modules）作为开发语言，运行时为 Node.js 18+，数据库使用 SQLite 3 配合 bun:sqlite 驱动，向量存储可选 ChromaDB，HTTP 服务基于 Express.js 4.18，实时通信采用 Server-Sent Events（SSE），UI 框架为 React + TypeScript，AI SDK 使用 @anthropic-ai/claude-agent-sdk，构建工具为 esbuild，进程管理由 Bun 原生支持（docs/public/architecture/overview.mdx:19-33）。

数据流

Memory Pipeline

Memory Pipeline 描述了从 Hook 输入到检索的完整流程（docs/public/architecture/overview.mdx:35-60）：

Hook (stdin) → Database → Worker Service → SDK Processor → Database → Next Session Hook

1. 输入：Claude Code 通过 stdin 将工具执行数据发送到 hooks
2. 存储：Hooks 将 observations 写入 SQLite 数据库
3. 处理：Worker service 读取 observations，通过 SDK 处理
4. 输出：处理后的 summaries 写回数据库
5. 检索：下一个会话的 context hook 从数据库读取 summaries

Search Pipeline

Search Pipeline 描述了从用户查询到返回结果的流程（docs/public/architecture/overview.mdx:48-60）：

User Query → MCP Tools Invoked → HTTP API → SessionSearch Service → FTS5 Database → Search Results → Claude

1. 用户查询：用户自然语言提问，如 "What bugs did we fix?"
2. MCP Tools 调用：Claude 识别意图并调用 MCP 搜索工具
3. HTTP API：MCP 工具调用 HTTP 端点（如 /api/search/observations）
4. SessionSearch：Worker service 查询 FTS5 虚拟表
5. 格式化：结果格式化后通过 MCP 返回
6. 返回：Claude 将格式化结果呈现给用户

异步处理管道

异步处理管道确保 observations 从扩展流向数据库时不阻塞 IDE（docs/public/architecture/hooks.mdx:149-175）：

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

关键模式：扩展的 HTTP 调用具有 2 秒超时，不等待 AI 处理。Worker 使用事件驱动队列异步处理压缩。

会话生命周期

Claude-Mem 实现了 5 阶段 Hook 系统，捕获 Claude Code 会话中的开发工作（docs/public/architecture/hooks.mdx:176-185）：

会话生命周期流程如下（docs/public/architecture/overview.mdx:62-108）：

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

注意：smart-install.js 是 pre-hook 依赖检查器（非生命周期 hook），通过 hooks.json 中的命令链在 context-hook 之前调用，仅在依赖需要更新时运行（docs/public/architecture/overview.mdx:183-195）。

目录结构

源代码组织

源代码按功能模块组织（docs/public/architecture/overview.mdx:109-147）：

src/
├── hooks/                  # Hook 实现（6 个 hooks）
│   ├── context-hook.ts     # SessionStart
│   ├── user-message-hook.ts # UserMessage（用于调试）
│   ├── new-hook.ts         # UserPromptSubmit
│   ├── save-hook.ts        # PostToolUse
│   ├── summary-hook.ts     # Stop
│   ├── cleanup-hook.ts     # SessionEnd
│   └── hook-response.ts    # Hook 响应工具
│
├── sdk/                    # Claude Agent SDK 集成
│   ├── prompts.ts          # XML prompt 构建器
│   ├── parser.ts           # XML 响应解析器
│   └── worker.ts           # 主 SDK agent 循环
│
├── services/
│   ├── worker-service.ts   # Express HTTP + SSE 服务
│   └── sqlite/             # 数据库层
│       ├── SessionStore.ts # CRUD 操作
│       ├── SessionSearch.ts # FTS5 搜索服务
│       ├── migrations.ts
│       └── types.ts
│
├── ui/                     # Viewer UI
│   └── viewer/             # React + TypeScript Web 界面
│
├── shared/                 # 共享工具
│   ├── config.ts
│   ├── paths.ts
│   └── storage.ts
│
└── utils/
    ├── logger.ts
    ├── platform.ts
    └── port-allocator.ts

插件分发目录

插件分发目录包含构建后的可执行文件和技能定义（docs/public/architecture/overview.mdx:148-181）：

plugin/
├── .claude-plugin/
│   └── plugin.json
├── hooks/
│   └── hooks.json
├── scripts/                # 构建后的可执行文件
│   ├── context-hook.js
│   ├── user-message-hook.js
│   ├── new-hook.js
│   ├── save-hook.js
│   ├── summary-hook.js
│   ├── cleanup-hook.js
│   └── worker-service.cjs  # 后台 worker + HTTP API
│
├── skills/                 # Agent 技能（v5.4.0+）
│   ├── mem-search/         # 搜索技能，支持渐进式披露（v5.5.0）
│   │   ├── SKILL.md        # 技能前言（约 250 tokens）
│   │   ├── operations/     # 12 个详细操作文档
│   │   └── principles/     # 2 个原则指南
│   └── troubleshoot/       # 故障排除技能
│
└── ui/                     # 构建后的 Viewer UI
    └── viewer.html         # 自包含 bundle

组件详情

Worker Service

Worker Service 是基于 Express.js 的长期运行 HTTP API，由 Bun 原生管理，通过 Claude Agent SDK 单独处理 observations 以防止超时问题（docs/public/architecture/overview.mdx:197-214）。

技术特性：

• 技术：Express.js HTTP 服务器
• 运行时：Bun（缺失时自动安装）
• 进程管理：通过 ProcessManager 进行 Bun 原生进程管理
• 端口：固定端口 37777（可通过 CLAUDE_MEM_WORKER_PORT 配置）
• 位置：src/services/worker-service.ts
• 构建输出：plugin/scripts/worker-service.cjs
• 模型：可通过 CLAUDE_MEM_MODEL 环境变量配置（默认：sonnet）

Worker Service 暴露 22 个 HTTP 端点，分为六类（docs/public/architecture/worker-service.mdx:20-70）：

Viewer & Health 端点：

• GET / - 提供 Web-based Viewer UI（v5.1.0+）
• GET /health - Worker 健康状态检查
• GET /stream - Viewer UI 的实时更新 SSE 流

Context Injection 端点：

• GET /api/context/inject - 获取先前会话上下文用于注入

Search API 端点（10 个）：

• GET /api/search/observations - 全文搜索 observations
• GET /api/search/sessions - 全文搜索会话摘要
• GET /api/search/prompts - 全文搜索用户 prompts
• GET /api/search/concepts - 按概念标签搜索
• GET /api/search/files - 按文件引用搜索
• GET /api/search/types - 按 observation 类型搜索
• GET /api/search/recent - 获取最近会话上下文
• GET /api/search/timeline - 获取时间线视图
• GET /api/search/timeline-query - 按查询获取时间线
• GET /api/search/help - API 帮助文档

Database Layer

Database Layer 使用 SQLite 3 配合 bun:sqlite 原生模块进行持久化存储，FTS5 用于全文搜索（docs/public/architecture/overview.mdx:207-214）。

数据库位置：~/.claude-mem/claude-mem.db

数据库使用 SQLite 的 WAL（Write-Ahead Logging）模式支持并发读写。

核心表 sdk_sessions（docs/public/architecture/database.mdx:24-48）：

sql
1CREATE TABLE sdk_sessions (
2  id INTEGER PRIMARY KEY AUTOINCREMENT,
3  sdk_session_id TEXT UNIQUE NOT NULL,
4  claude_session_id TEXT,
5  project TEXT NOT NULL,
6  prompt_counter INTEGER DEFAULT 0,
7  status TEXT NOT NULL DEFAULT 'active',
8  created_at TEXT NOT NULL,
9  created_at_epoch INTEGER NOT NULL,
10  completed_at TEXT,
11  completed_at_epoch INTEGER,
12  last_activity_at TEXT,
13  last_activity_epoch INTEGER
14);

索引：

• idx_sdk_sessions_claude_session on claude_session_id
• idx_sdk_sessions_project on project

数据库类：

• SessionStore（src/services/sqlite/SessionStore.ts）：sessions、observations、summaries 和 user prompts 的 CRUD 操作
• SessionSearch（src/services/sqlite/SessionSearch.ts）：FTS5 全文搜索，提供 8 个专门搜索方法

核心设计决策

1. 两进程架构

Claude-Mem 采用两进程架构，扩展进程和 Worker 进程分离（docs/public/architecture/hooks.mdx:14-58）：

关键原则：

• 扩展进程永不阻塞（fire-and-forget HTTP）
• Worker 异步处理 observations
• 会话状态在 IDE 重启后持久化

2. Fire-and-Forget HTTP 模式

扩展的 HTTP 调用具有 2 秒超时，不等待 AI 处理。这确保 IDE 响应性不受影响（docs/public/architecture/hooks.mdx:149-175）。

3. FTS5 全文搜索

使用 SQLite FTS5 虚拟表实现全文搜索，显著优于 LIKE 查询。所有 FTS5 查询都经过适当转义以防止 SQL 注入（docs/public/architecture/database.mdx:246-250）。

4. 渐进式披露搜索

mem-search Skill 采用三层渐进式披露：search → timeline → get_observations，节省约 2,250 tokens 每会话（docs/public/architecture/overview.mdx:216-230）。

5. 优雅降级

Worker 实现优雅降级策略（docs/public/architecture/worker-service.mdx:677-684）：

• 数据库错误：记录日志但不崩溃服务
• SDK 错误：指数退避重试
• 网络错误：记录日志并跳过
• 无效输入：验证并拒绝，返回错误响应

技术选型

模块依赖关系

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

关键配置与启动流程

环境变量

启动流程

1. Smart Install：检查依赖，仅在版本变更时运行
2. Worker Start：启动 Bun worker 服务（端口 37777）
3. Context Hook：健康检查（最多 10 秒重试），获取先前上下文
4. Session Init：用户提交 prompt 时创建/获取 session
5. Observation Processing：异步处理工具执行记录

Windows 特殊处理

Worker Service 在 Windows 平台上实现了 spawn 冷却机制，防止快速重复启动（src/services/worker-service.ts:28-83）：

• 使用 .worker-start-attempted 锁文件跟踪启动尝试
• 冷却期内跳过重复 spawn
• 最佳努力清理锁文件