架构总览¶

系统组件¶

Claude-Mem 作为 Claude Code 插件运行，包含以下核心组件：

插件钩子（Plugin Hooks） - 生命周期事件（涵盖 SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PostToolUseFailure、Stop 和 SessionEnd 的生命周期钩子，外加一个 Setup 版本检查），每个钩子都以无 shell 的 claude-mem hook claude-code <event> 命令运行
工作进程服务（Worker Service） - 运行在每用户独立端口上的 Express HTTP API；通过 Claude Agent SDK（或 Gemini / OpenRouter）处理观察记录
数据库层（Database Layer） - SQLite + FTS5（以及可选的 Chroma 语义搜索）
搜索工具（Search Tools） - HTTP API + mem-search 技能 / MCP 服务器，用于渐进式披露搜索
查看器界面（Viewer UI） - 基于 React 的实时记忆流，由工作进程服务提供

技术栈¶

层级	技术
语言	TypeScript（ES2022、ESNext 模块）
运行时	Node.js 20+ 和 Bun ≥ 1.0
数据库	SQLite 3（使用 bun:sqlite 驱动）
向量存储	Chroma（可选，用于语义搜索）
HTTP 服务器	Express.js 5
实时通信	服务器发送事件（SSE）
UI 框架	React + TypeScript
AI SDK	@anthropic-ai/claude-agent-sdk（或 Gemini / OpenRouter）
构建工具	esbuild（打包 TypeScript）
进程管理器	Bun
测试	`bun test`

数据流¶

记忆流水线¶

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

输入：Claude Code 通过 stdin 将工具执行数据发送给钩子
存储：钩子将观察记录写入 SQLite 数据库
处理：工作进程服务读取观察记录，并通过 SDK 进行处理
输出：处理后的摘要写回数据库
检索：下一个会话的上下文钩子从数据库读取摘要

搜索流水线¶

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

用户查询：用户以自然语言提问：“我们修复了什么 bug？”
调用 MCP 工具：Claude 识别意图并调用 MCP 搜索工具
HTTP API：MCP 工具调用 HTTP 端点（例如 /api/search/observations）
会话搜索（SessionSearch）：工作进程服务查询 FTS5 虚拟表
格式化：结果经格式化后通过 MCP 返回
返回：Claude 将格式化结果呈现给用户

采用 3 层渐进式披露：search（搜索）→ timeline（时间线）→ get_observations（获取观察记录）

会话生命周期¶

┌─────────────────────────────────────────────────────────────────┐
│ 0. Install puts the claude-mem launcher on PATH                 │
│    npx claude-mem install/update, or the startup SessionStart   │
│    self-heal (ensure-launcher.cjs) for marketplace-only installs│
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 1. Session Starts → Worker-start, then Context Hook             │
│    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 启动器放入 PATH（通过 npx claude-mem install/update，或启动时的 SessionStart 自愈机制（ensure-launcher.cjs），适用于仅通过 marketplace 安装的情况）
会话开始 → 启动 Worker，然后执行上下文钩子：在需要时启动 Bun 工作进程，并注入来自先前会话的上下文（可配置观察记录数量）
用户输入提示词 → UserPromptSubmit 钩子触发：在数据库中创建会话，并将原始用户提示词保存到 FTS5
Claude 使用工具 → PostToolUse 钩子触发（100+ 次）：捕获工具执行记录，发送给工作进程进行 AI 压缩
工作进程处理 → Claude Agent SDK 分析：通过迭代式 AI 处理提取结构化学习成果
Claude 停止 → 摘要钩子触发：生成包含请求、完成情况、学习成果的最终摘要
会话结束 → 清理钩子触发：将会话标记为完成（优雅结束，而非 DELETE），为下一个会话的上下文做好准备。在 /clear 时跳过，以保留进行中的会话

目录结构¶

claude-mem/
├── src/
│   ├── hooks/                  # TypeScript hook implementations (built via esbuild)
│   ├── sdk/                    # Claude Agent SDK integration
│   ├── services/
│   │   ├── worker-service.ts   # Express HTTP + SSE service (worker entry point)
│   │   ├── sync/ChromaSync.ts  # Optional Chroma vector index
│   │   └── sqlite/             # SQLite + FTS5 storage layer
│   ├── ui/viewer/              # React + TypeScript web viewer
│   ├── shared/                 # Shared utilities (paths, settings defaults)
│   └── utils/                  # Logging, platform, tag-stripping helpers
│
├── scripts/                    # Build + utility scripts
│
├── plugin/                     # Plugin distribution (synced to marketplace)
│   ├── .claude-plugin/plugin.json
│   ├── hooks/hooks.json        # Hook registration (exec-form `claude-mem` hooks + Setup)
│   ├── scripts/                # Built executables
│   │   ├── claude-mem-launcher.cjs # Source of the on-PATH `claude-mem` hook launcher (compiled at install)
│   │   ├── ensure-launcher.cjs # Startup SessionStart self-heal: places/refreshes the launcher
│   │   ├── version-check.js    # Setup hook (--init / --maintenance): dependency check + install marker
│   │   ├── bun-runner.js       # Resolves Bun and runs worker-service.cjs (Codex hooks)
│   │   ├── worker-service.cjs  # Worker daemon + lifecycle hook dispatcher
│   │   ├── worker-cli.js       # CLI shim
│   │   ├── worker-wrapper.cjs  # Process wrapper
│   │   ├── mcp-server.cjs      # MCP search server
│   │   ├── statusline-counts.js
│   │   └── context-generator.cjs
│   ├── skills/                 # Agent skills (mem-search, make-plan, do, etc.)
│   └── ui/viewer.html          # Self-contained React bundle
│
├── tests/                      # Test suite (`bun test`)
├── docs/                       # Mintlify documentation
└── openclaw/                   # OpenClaw integration plugin

组件详情¶

1. 插件钩子¶

该插件注册了生命周期钩子，外加一个 Setup 阶段的 version-check.js。每个生命周期钩子都是一条 exec 形式的命令 claude-mem hook claude-code <event>，不使用 shell。claude-mem 是 PATH 上的一个小型编译启动器：它会找到插件根目录，并在 Bun 下运行 worker-service.cjs hook claude-code <event>；worker 进程是所有钩子逻辑的唯一调度器。事件如下：

Setup → version-check.js（安装缺失的插件依赖，然后记录安装标记）。仍然是一个 bash 入口，Claude Code 仅在 claude --init / --maintenance 时触发它。
SessionStart → claude-mem start（worker，异步），随后执行 hook claude-code context（上下文注入）；启动时还会执行 node ${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs（启动器自愈）
UserPromptSubmit → hook claude-code session-init
PreToolUse（匹配器 Read）→ hook claude-code file-context
PostToolUse（匹配器 *）→ hook claude-code observation
Stop → hook claude-code summarize（生成摘要）
SessionEnd → hook claude-code session-end

运行时安装（Bun、uv、bun install，以及将启动器编译到 ~/.local/bin 或 %LOCALAPPDATA%\claude-mem\bin）由 npx claude-mem install / npx claude-mem update 执行，并带有可见的安装旋转指示器。对于通过插件市场安装的情况，启动时的自愈逻辑会放置启动器；当插件依赖缺失时，Setup 钩子（在 claude --init / --maintenance 时）会运行 bun install。

详细的钩子文档请参阅插件钩子。

2. Worker Service¶

Express.js HTTP 服务器，运行在按用户分配的端口上（默认 37700 + (uid % 100)，可通过 CLAUDE_MEM_WORKER_PORT 覆盖），提供以下能力：

搜索 HTTP API 端点
Viewer UI HTTP/SSE 端点
通过 Claude Agent SDK（或 Gemini / OpenRouter）进行异步观察处理
通过 Server-Sent Events 实现实时更新
由 Bun 自动管理

HTTP API 和端点信息请参阅 Worker Service。

3. 数据库层¶

使用 bun:sqlite 驱动的 SQLite3，具有以下特性：

用于全文搜索的 FTS5 虚拟表
用于 CRUD 操作的 SessionStore
用于 FTS5 查询的 SessionSearch
存储位置：~/.claude-mem/claude-mem.db

有关 schema 和 FTS5 搜索，请参阅数据库架构。

4. 智能搜索：mem-search 技能（默认）¶

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

搜索观察、会话、提示词（全文 FTS5）
按类型、概念、文件进行过滤
获取近期上下文、时间线、按查询获取时间线
API 帮助文档

Token 节省：与 MCP 方案相比，每个会话约节省 2,250 tokens

技能 frontmatter：约 250 tokens（会话启动时加载）
完整指令：约 2,500 tokens（调用时按需加载）
使用 HTTP API 端点而非 MCP 工具

技能增强（v5.5.0）：为更好地区分适用范围，已从 “search” 更名为 “mem-search”。借助增强的触发器和全面的文档，有效性从 67% 提升到 100%。

技术细节和示例请参阅搜索架构。

5. Viewer UI¶

由 worker 在其配置的 CLAUDE_MEM_WORKER_PORT 端口上提供的 React + TypeScript Web 界面，具有以下特性：

通过 Server-Sent Events 实时传输记忆流
无限滚动分页，自动去重
项目过滤与设置持久化
GPU 加速的动画
自包含的 HTML 包（viewer.html）

使用 esbuild 构建为单文件部署。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/claude-mem