架构概述

系统组件

Claude-Mem 作为 Claude Code 插件运行，具有五个核心组件：

插件钩子 - 捕获生命周期事件（6 个钩子文件）
智能安装 - 缓存依赖检查器（预钩子脚本，在上下文钩子之前运行）
Worker 服务 - 通过 Claude Agent SDK HTTP API 处理观察（10 个搜索端点）
数据库层 - 存储会话和观察记录（SQLite FTS5 ChromaDB）
mem-search 技能 - 基于技能的搜索与渐进式披露 (v5.4.0)
查看器界面 - 基于网页的实时内存流可视化

技术栈

层	技术
语言	TypeScript (ES2022, ESNext 模块)
运行时	Node.js 18
数据库	使用 bun:sqlite 驱动的 SQLite 3
向量存储	ChromaDB（可选，用于语义搜索）
HTTP 服务器	Express.js 4.18
实时	服务器发送事件 (SSE)
用户界面框架	React TypeScript
人工智能 SDK	@anthropic-ai/claude-agent-sdk
Build Tool	esbuild (bundling TypeScript)
进程管理器	Bun
测试	Node.js 内置测试运行器

数据流

内存流水线

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

输入：Claude Code 通过标准输入将工具执行数据发送到 hooks
存储：钩子将观察结果写入 SQLite 数据库
处理：Worker 服务读取观测数据，通过 SDK 处理
输出：处理后的摘要已写回数据库
检索：下一次会话的上下文挂钩从数据库读取摘要

搜索管道

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

用户查询：用户自然地问：“我们修复了哪些漏洞？”
MCP 工具已调用：Claude 识别意图并调用 MCP 搜索工具
HTTP API：MCP 工具调用 HTTP 端点（例如，/api/search/observations）
SessionSearch：Worker 服务查询 FTS5 虚拟表
格式：结果通过 MCP 格式化并返回
返回：Claude向用户呈现格式化结果

使用三层渐进式显示：搜索 → 时间线 → 获取观察结果

会话生命周期

┌─────────────────────────────────────────────────────────────────┐
│ 0. Smart Install Pre-Hook Fires                                 │
│    Checks dependencies (cached), only runs on version changes   │
│    Not a lifecycle hook - runs before context-hook starts       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 1. Session Starts → Context Hook Fires                          │
│    Starts Bun worker if needed, injects context from previous   │
│    sessions (configurable observation count)                    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 2. User Types Prompt → UserPromptSubmit Hook Fires              │
│    Creates session in database, saves raw user prompt for FTS5  │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 3. Claude Uses Tools → PostToolUse Hook Fires (100+ times)      │
│    Captures tool executions, sends to worker for AI compression │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 4. Worker Processes → Claude Agent SDK Analyzes                 │
│    Extracts structured learnings via iterative AI processing    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 5. Claude Stops → Summary Hook Fires                            │
│    Generates final summary with request, completions, learnings │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 6. Session Ends → Cleanup Hook Fires                            │
│    Marks session complete (graceful, not DELETE), ready for     │
│    next session context. Skips on /clear to preserve ongoing    │
└─────────────────────────────────────────────────────────────────┘

目录结构

claude-mem/
├── src/
│   ├── hooks/                  # Hook implementations (6 hooks)
│   │   ├── context-hook.ts     # SessionStart
│   │   ├── user-message-hook.ts # UserMessage (for debugging)
│   │   ├── new-hook.ts         # UserPromptSubmit
│   │   ├── save-hook.ts        # PostToolUse
│   │   ├── summary-hook.ts     # Stop
│   │   ├── cleanup-hook.ts     # SessionEnd
│   │   └── hook-response.ts    # Hook response utilities
│   │
│   ├── sdk/                    # Claude Agent SDK integration
│   │   ├── prompts.ts          # XML prompt builders
│   │   ├── parser.ts           # XML response parser
│   │   └── worker.ts           # Main SDK agent loop
│   │
│   ├── services/
│   │   ├── worker-service.ts   # Express HTTP + SSE service
│   │   └── sqlite/             # Database layer
│   │       ├── SessionStore.ts # CRUD operations
│   │       ├── SessionSearch.ts # FTS5 search service
│   │       ├── migrations.ts
│   │       └── types.ts
│   │
│   ├── ui/                     # Viewer UI
│   │   └── viewer/             # React + TypeScript web interface
│   │       ├── components/     # UI components
│   │       ├── hooks/          # React hooks
│   │       ├── utils/          # Utilities
│   │       └── assets/         # Fonts, logos
│   │
│   ├── shared/                 # Shared utilities
│   │   ├── config.ts
│   │   ├── paths.ts
│   │   └── storage.ts
│   │
│   └── utils/
│       ├── logger.ts
│       ├── platform.ts
│       └── port-allocator.ts
│
├── scripts/                    # Build and utility scripts
│   └── smart-install.js        # Cached dependency checker (pre-hook)
│
├── plugin/                     # Plugin distribution
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── hooks/
│   │   └── hooks.json
│   ├── scripts/                # Built executables
│   │   ├── context-hook.js
│   │   ├── user-message-hook.js
│   │   ├── new-hook.js
│   │   ├── save-hook.js
│   │   ├── summary-hook.js
│   │   ├── cleanup-hook.js
│   │   └── worker-service.cjs  # Background worker + HTTP API
│   │
│   ├── skills/                 # Agent skills (v5.4.0+)
│   │   ├── mem-search/         # Search skill with progressive disclosure (v5.5.0)
│   │   │   ├── SKILL.md        # Skill frontmatter (~250 tokens)
│   │   │   ├── operations/     # 12 detailed operation docs
│   │   │   └── principles/     # 2 principle guides
│   │   ├── troubleshoot/       # Troubleshooting skill
│   │   │   ├── SKILL.md
│   │   │   └── operations/     # 6 operation docs
│   │   └── version-bump/       # Version management skill (deprecated)
│   │
│   └── ui/                     # Built viewer UI
│       └── viewer.html         # Self-contained bundle
│
├── tests/                      # Test suite
├── docs/                       # Documentation
└── ecosystem.config.cjs        # Process configuration (deprecated)

组件详情

1. 插件钩子（6 个钩子）

context-hook.js - SessionStart：启动 Bun Worker 进程，注入上下文
user-message-hook.js - 用户消息：调试钩子
new-hook.js - 用户提交提示：创建会话，保存提示
save-hook.js - PostToolUse：捕获工具执行
summary-hook.js - Stop: Generate session summary
cleanup-hook.js - 会话结束：标记会话完成

注意：smart-install.js 是一个预钩子依赖检查器（不是生命周期钩子）。它通过 hooks.json 中的命令链在 context-hook 之前被调用，并且只在需要更新依赖时运行。

请参阅 Plugin Hooks 了解详细的钩子文档。

2. Worker 服务

Express.js HTTP 服务器，端口 37777（可配置），具备以下功能：

10 个搜索 HTTP API 端点（v5.4.0）
8 个查看器 UI HTTP/SSE 端点
通过 Claude Agent SDK 进行异步观察处理
通过服务器发送事件的实时更新
由 Bun 自动管理

Please refer to Worker Service] for HTTP API and endpoint information.

3. 数据库层

Using bun:sqlite driver for SQLite3, features include:

用于全文搜索的 FTS5 虚拟表
用于 CRUD 操作的会话存储
FTS5 查询的会话搜索
地点：~/.claude-mem/claude-mem.db

请参见 Database Architecture 了解架构和 FTS5 搜索。

4. mem-search 技能 (v5.4.0)

基于技能的搜索，采用渐进式披露，提供10种搜索操作：

搜索观测、会话、提示（全文本 FTS5）
按类型、概念、文件筛选
获取最近的上下文、时间线、按查询的时间线
API 帮助文档

token 节省：每次会话约 2,250 个 token，相比 MCP 方法

技能前言：约250个标记（在会话开始时加载）
完整说明：约 2,500 个标记（在调用时按需加载）
HTTP API endpoint instead of MCP tool

Skill Enhancement (v5.5.0): Renamed 'search' to 'mem-search' for better scope distinction. Effectiveness increased from 67% to 100% through enhanced triggers and complete documentation.

有关技术细节和示例，请参见 Search Architecture。

5. 查看器界面

In the React TypeScript web interface of http://localhost:37777, features include:

通过服务器发送事件的实时内存流
无限滚动分页与自动去重
项目筛选和设置持久化
GPU加速动画
Independent HTML Package (viewer.html)

Use esbuild to build for single-file deployment.

架构概述 ​

系统组件 ​

技术栈 ​

数据流 ​

内存流水线 ​

搜索管道 ​

会话生命周期 ​

目录结构 ​

组件详情 ​

1. 插件钩子（6 个钩子） ​

2. Worker 服务 ​

3. 数据库层 ​

4. mem-search 技能 (v5.4.0) ​

5. 查看器界面 ​