Claude-Mem
为 Claude Code 构建的持久化记忆压缩系统
1. 项目简介
Claude-Mem 是一个为 Claude Code 构建的持久化记忆压缩系统，它能在多个会话之间自动捕获工具使用观察（observations）、生成语义摘要（summaries），并将其注入到未来的会话中，使 AI 编码助手具备跨会话的”记忆”能力。
核心功能
- 持久化记忆：自动捕获 Claude Code 会话中的工具使用记录，跨会话保留上下文
- 智能压缩：通过 Claude Agent SDK 驱动的 AI 代理，将原始工具调用压缩为结构化的观察记录
- 上下文注入：在新会话开始时，自动注入相关历史上下文
- 语义搜索：支持通过 MCP 工具进行自然语言搜索，采用 3 层渐进式披露策略
- 多 IDE 支持：适配 Claude Code、Cursor、Gemini CLI、Windsurf、OpenCode 等多种 IDE
- Web 查看器：提供 React 构建的实时记忆流查看界面（
http://localhost:37777） - 隐私控制：支持
<private>标签排除敏感内容
技术栈总览
| 类别 | 技术 | 版本 |
|---|---|---|
| 语言 | TypeScript | ^5.3.0 |
| 运行时 | Node.js / Bun | ≥18.0.0 / ≥1.0.0 |
| HTTP 框架 | Express | ^4.18.2 |
| 数据库 | SQLite（via bun:sqlite） | 内置 |
| 全文搜索 | SQLite FTS5 | 内置 |
| 向量搜索 | ChromaDB（via MCP） | 外部进程 |
| AI SDK | @anthropic-ai/claude-agent-sdk | ^0.1.76 |
| MCP 协议 | @modelcontextprotocol/sdk | ^1.25.1 |
| 前端框架 | React | ^18.3.1 |
| 构建工具 | esbuild | ^0.27.2 |
| 包管理 | npm | — |
2. 目录结构说明
claude-mem/
├── src/ # 📦 TypeScript 源码（核心）
│ ├── npx-cli/ # NPX 命令行入口（install/start/stop 等）
│ │ ├── index.ts # CLI 命令路由主入口
│ │ ├── commands/ # 各命令实现（install, runtime, uninstall）
│ │ └── utils/ # 路径解析、Bun 定位等工具
│ ├── cli/ # Hook 命令处理层
│ │ ├── hook-command.ts # Hook 命令统一入口（stdin→adapter→handler）
│ │ ├── adapters/ # 平台适配器（claude-code, cursor, gemini-cli 等）
│ │ ├── handlers/ # 事件处理器（context, observation, summarize 等）
│ │ ├── types.ts # 核心类型定义（NormalizedHookInput, HookResult 等）
│ │ └── stdin-reader.ts # 从标准输入读取 JSON 数据
│ ├── hooks/ # Hook 响应常量
│ ├── servers/ # MCP 服务器
│ │ └── mcp-server.ts # MCP 搜索工具服务（search, timeline, get_observations）
│ ├── sdk/ # SDK 集成层
│ │ ├── index.ts # 导出入口
│ │ ├── parser.ts # XML 解析器（解析 observation/summary XML）
│ │ └── prompts.ts # SDK Agent 提示词生成
│ ├── services/ # 核心业务服务
│ │ ├── worker-service.ts # Worker 服务编排入口（~300 行精简版）
│ │ ├── worker-spawner.ts # Worker 进程启动管理
│ │ ├── worker-types.ts # Worker 类型定义
│ │ ├── server/ # HTTP 服务器层
│ │ │ ├── Server.ts # Express 应用包装
│ │ │ ├── Middleware.ts # 中间件（日志、localhost 限制）
│ │ │ └── ErrorHandler.ts # 统一错误处理
│ │ ├── worker/ # Worker 业务逻辑
│ │ │ ├── SDKAgent.ts # Claude Agent SDK 代理
│ │ │ ├── GeminiAgent.ts # Gemini AI 代理
│ │ │ ├── OpenRouterAgent.ts # OpenRouter AI 代理
│ │ │ ├── SessionManager.ts # 会话生命周期管理
│ │ │ ├── DatabaseManager.ts # 数据库连接管理
│ │ │ ├── SearchManager.ts # 搜索编排入口
│ │ │ ├── SSEBroadcaster.ts # Server-Sent Events 广播
│ │ │ ├── search/ # 搜索引擎
│ │ │ │ ├── SearchOrchestrator.ts # 搜索策略选择与编排
│ │ │ │ ├── strategies/ # 搜索策略实现
│ │ │ │ │ ├── ChromaSearchStrategy.ts # 向量语义搜索
│ │ │ │ │ ├── SQLiteSearchStrategy.ts # SQLite 过滤搜索
│ │ │ │ │ └── HybridSearchStrategy.ts # 混合搜索
│ │ │ │ ├── ResultFormatter.ts # 结果格式化
│ │ │ │ └── TimelineBuilder.ts # 时间线构建
│ │ │ ├── http/routes/ # HTTP 路由处理器
│ │ │ │ ├── SessionRoutes.ts # 会话生命周期 API
│ │ │ │ ├── SearchRoutes.ts # 搜索与上下文 API
│ │ │ │ ├── ViewerRoutes.ts # Web 查看器页面
│ │ │ │ ├── DataRoutes.ts # 数据导出 API
│ │ │ │ ├── SettingsRoutes.ts # 设置管理 API
│ │ │ │ └── LogsRoutes.ts # 日志查看 API
│ │ │ ├── agents/ # AI 代理辅助模块
│ │ │ ├── knowledge/ # 知识库构建
│ │ │ ├── session/ # 会话完成处理
│ │ │ ├── events/ # 事件广播
│ │ │ └── validation/ # 隐私校验
│ │ ├── sqlite/ # SQLite 数据层
│ │ │ ├── Database.ts # 数据库初始化与连接管理
│ │ │ ├── migrations.ts # 数据库迁移定义（001-010）
│ │ │ ├── SessionStore.ts # 会话存储
│ │ │ ├── SessionSearch.ts # 会话搜索
│ │ │ ├── Observations.ts # 观察记录操作
│ │ │ ├── Sessions.ts # 会话操作
│ │ │ ├── Summaries.ts # 摘要操作
│ │ │ ├── Timeline.ts # 时间线查询
│ │ │ └── PendingMessageStore.ts # 待处理消息队列
│ │ ├── context/ # 上下文生成器
│ │ │ ├── ContextBuilder.ts # 上下文构建编排
│ │ │ ├── ContextConfigLoader.ts # 配置加载
│ │ │ ├── TokenCalculator.ts # Token 经济计算
│ │ │ ├── ObservationCompiler.ts # 数据检索与编译
│ │ │ ├── formatters/ # 输出格式化（Agent/Human）
│ │ │ └── sections/ # 分段渲染（Header/Timeline/Summary/Footer）
│ │ ├── sync/ # 向量同步
│ │ │ ├── ChromaSync.ts # ChromaDB 数据同步
│ │ │ └── ChromaMcpManager.ts # Chroma MCP 客户端管理
│ │ ├── infrastructure/ # 基础设施
│ │ │ ├── ProcessManager.ts # 进程管理（PID文件、守护进程）
│ │ │ ├── HealthMonitor.ts # 健康检查
│ │ │ ├── GracefulShutdown.ts # 优雅关闭
│ │ │ └── WorktreeAdoption.ts # Git worktree 合并
│ │ ├── integrations/ # IDE 集成安装器
│ │ ├── domain/ # 领域模型
│ │ │ └── ModeManager.ts # 工作模式管理
│ │ ├── queue/ # 队列处理
│ │ └── transcripts/ # 会话转录处理
│ ├── shared/ # 跨模块共享代码
│ │ ├── paths.ts # 路径常量（DATA_DIR, DB_PATH 等）
│ │ ├── hook-constants.ts # Hook 超时与退出码
│ │ ├── worker-utils.ts # Worker HTTP 请求工具
│ │ ├── EnvManager.ts # 环境变量管理
│ │ └── SettingsDefaultsManager.ts # 设置默认值管理
│ ├── supervisor/ # Worker 进程监管
│ ├── types/ # 全局类型定义
│ ├── ui/ # 前端 UI
│ │ └── viewer/ # React 查看器应用
│ │ ├── App.tsx # 应用入口组件
│ │ ├── components/ # UI 组件
│ │ ├── hooks/ # React Hooks
│ │ ├── constants/ # 常量定义
│ │ └── utils/ # 前端工具函数
│ └── utils/ # 工具函数
│ ├── logger.ts # 日志系统
│ ├── tag-stripping.ts # 隐私标签剥离
│ ├── context-injection.ts # 上下文注入到 Markdown
│ ├── project-name.ts # 项目名称解析
│ └── claude-md-utils.ts # CLAUDE.md 工具
├── plugin/ # 📦 构建产物（安装到用户机器上的插件）
│ ├── hooks/hooks.json # 生命周期钩子定义
│ ├── scripts/ # 运行时脚本（bun-runner, worker-service 等）
│ ├── skills/ # 技能定义（mem-search, make-plan, do 等）
│ ├── modes/ # 工作模式配置（code, code--zh, chill 等）
│ ├── ui/ # 构建后的前端资源
│ └── .claude-plugin/plugin.json # Claude 插件清单
├── openclaw/ # 📦 OpenClaw 网关集成
├── cursor-hooks/ # 📦 Cursor IDE 集成
├── docker/ # 🐳 Docker 部署配置
├── scripts/ # 🔧 开发/构建/运维脚本
├── tests/ # 🧪 测试套件（Bun test）
├── ragtime/ # 📦 Ragtime 模块（独立许可证）
├── install/ # 📦 安装脚本（Vercel 托管）
├── package.json # 项目配置与依赖
├── tsconfig.json # TypeScript 配置
├── CLAUDE.md # AI 开发指令文件
└── README.md # 项目说明3. 架构设计
整体架构模式
Claude-Mem 采用事件驱动 + 微服务风格的架构，核心思想是：
- Hook-Worker 分离：轻量级 Hook 脚本在 Claude Code 进程内执行，通过 HTTP 与常驻 Worker 服务通信
- 适配器模式：通过
PlatformAdapter抽象，统一支持多种 IDE 平台 - 策略模式：搜索引擎通过
SearchOrchestrator选择 Chroma/SQLite/Hybrid 三种策略 - 渐进式披露：搜索结果采用 3 层架构（索引 → 时间线 → 全文），大幅降低 Token 消耗
核心模块划分与职责
┌─────────────────────────────────────────────────────────────┐
│ Claude Code / Cursor / Gemini CLI │
│ (宿主 IDE 环境) │
└──────────┬──────────────────────────────────────────────────┘
│ Lifecycle Hooks (stdin/stdout JSON)
▼
┌─────────────────────────────────────────────────────────────┐
│ Hook 命令层 (src/cli/) │
│ ┌──────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ stdin │───▶│ Adapter │───▶│ Handler │ │
│ │ reader │ │ (平台适配) │ │ (事件处理) │ │
│ └──────────┘ └─────────────┘ └────────┬────────┘ │
└──────────────────────────────────────────────┼──────────────┘
│ HTTP API
▼
┌─────────────────────────────────────────────────────────────┐
│ Worker 服务 (端口 37777) │
│ ┌──────────┐ ┌──────────────┐ ┌────────────────────┐ │
│ │ Express │ │ Session │ │ SDK Agent │ │
│ │ Server │ │ Manager │ │ (Claude/Gemini/ │ │
│ │ │ │ (生命周期) │ │ OpenRouter) │ │
│ └──────────┘ └──────────────┘ └────────────────────┘ │
│ ┌──────────────────┐ ┌───────────────────────────────┐ │
│ │ Database Manager │ │ Search Manager │ │
│ │ (SQLite + Chroma)│ │ (Orchestrator + Strategies) │ │
│ └──────────────────┘ └───────────────────────────────┘ │
│ ┌──────────────────┐ ┌───────────────────────────────┐ │
│ │ Context Builder │ │ SSE Broadcaster │ │
│ │ (上下文生成) │ │ (实时事件推送) │ │
│ └──────────────────┘ └───────────────────────────────┘ │
└──────────────────────────────────────────────┬──────────────┘
│
┌──────────────────────────┼──────────────┐
▼ ▼ │
┌──────────────┐ ┌──────────────┐ │
│ SQLite DB │ │ ChromaDB │ │
│ (~/.claude- │ │ (向量搜索) │ │
│ mem/*.db) │ │ │ │
└──────────────┘ └──────────────┘ │
│
┌─────────────────────────────────────────┘
▼
┌──────────────┐
│ Web Viewer │
│ (React UI) │
│ :37777 │
└──────────────┘模块间调用关系与数据流向
数据写入流（工具使用 → 持久化存储）：
- Claude Code 执行工具后触发
PostToolUseHook - Hook 脚本调用
hook-command.ts，通过PlatformAdapter标准化输入 observationHandler将工具数据 POST 到 Worker 的/api/sessions/observations- Worker 的
SessionRoutes接收后，通过SessionManager入队 SDKAgent使用 Claude Agent SDK 将原始工具调用压缩为结构化<observation>XMLparser.ts解析 XML，DatabaseManager存入 SQLiteChromaSync异步将观察同步到 ChromaDB 向量数据库
数据读取流（上下文注入 → 新会话）：
- 新会话触发
SessionStartHook contextHandler请求 Worker 的/api/context/injectContextBuilder从 SQLite 查询最近观察和摘要- 按照 Token 预算、时间线格式渲染为 Markdown
- 返回给 Hook，注入到 Claude Code 会话上下文中
4. 核心流程解析
4.1 应用安装流程
入口文件：src/npx-cli/index.ts
npx claude-mem install
│
▼
src/npx-cli/index.ts → main() → switch('install')
│
▼
src/npx-cli/commands/install.ts → runInstallCommand()
│ 1. 检测已安装的 IDE（claude-code, cursor, gemini-cli 等）
│ 2. 交互式选择目标 IDE
│ 3. 复制 plugin/ 目录到 ~/.claude/plugins/marketplaces/thedotmack/
│ 4. 注册 hooks.json 到 IDE 配置
│ 5. 确保 Bun 运行时可用
▼
安装完成，重启 IDE 即生效4.2 会话启动与上下文注入流程
这是 Claude-Mem 最核心的流程，在每次新会话开始时自动执行：
Claude Code 启动新会话
│
▼
[Hook: SessionStart] → hooks.json 中的 3 条命令依次执行
│
├─ 1. smart-install.js # 检查依赖是否就绪
├─ 2. worker-service start # 启动/确认 Worker 服务
└─ 3. hook context # 注入历史上下文
│
▼
contextHandler.execute(input)
│
▼
GET /api/context/inject?projects=<project>
│
▼
ContextBuilder.build()
├─ loadContextConfig() # 加载用户上下文配置
├─ queryObservations() # 查询最近观察记录
├─ querySummaries() # 查询最近会话摘要
├─ calculateTokenEconomics() # 计算 Token 预算分配
├─ renderHeader() # 渲染头部信息
├─ renderTimeline() # 渲染时间线
└─ renderFooter() # 渲染页脚（搜索提示等）
│
▼
返回 Markdown 文本 → 注入 Claude Code 上下文关键代码片段（src/cli/handlers/context.ts）：
// Context Handler 核心逻辑
export const contextHandler: EventHandler = {
async execute(input: NormalizedHookInput): Promise<HookResult> {
const workerReady = await ensureWorkerRunning();
if (!workerReady) {
// Worker 不可用时优雅降级，返回空上下文
return { hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: '' } };
}
const cwd = input.cwd ?? process.cwd();
const context = getProjectContext(cwd);
// 将项目名作为参数请求 Worker API
const projectsParam = context.allProjects.join(',');
const response = await workerHttpRequest(
`/api/context/inject?projects=${encodeURIComponent(projectsParam)}`
);
const additionalContext = (await response.text()).trim();
return {
hookSpecificOutput: {
hookEventName: 'SessionStart',
additionalContext // 这段文本会被注入到 Claude 的会话上下文中
}
};
}
};4.3 工具使用观察捕获流程
每当 Claude Code 使用工具（读文件、写文件、执行命令等），都会触发此流程：
Claude Code 执行工具（如 Read file）
│
▼
[Hook: PostToolUse] → hooks.json 中的命令
│
▼
hookCommand('claude-code', 'observation')
│
▼
observationHandler.execute(input)
│ 1. 确认 Worker 运行中
│ 2. 检查项目是否被排除
│ 3. 剥离隐私标签 (<private>, <claude-mem-context>)
▼
POST /api/sessions/observations
│
▼
SessionRoutes → SessionManager.addObservation()
│ 1. 将观察入队到 PendingMessageStore
│ 2. 事件通知 SDKAgent 处理
▼
SDKAgent.processObservation()
│ 1. 构建 observation prompt
│ 2. 通过 Claude Agent SDK 发送给 Claude
│ 3. Claude 返回结构化 <observation> XML
▼
parser.parseObservations(text)
│ 解析 XML 为 ParsedObservation 对象
▼
DatabaseManager → SessionStore.storeObservation()
│ 存入 SQLite observations 表
▼
ChromaSync.syncObservation()
│ 同步到 ChromaDB 向量数据库4.4 会话摘要生成流程
当用户结束会话（Stop hook）时触发：
用户结束 Claude Code 会话
│
▼
[Hook: Stop] → summarizeHandler
│
├─ 1. 跳过子代理会话（subagent 不拥有摘要）
├─ 2. 从 transcript 提取最后一条助手消息
└─ 3. POST /api/sessions/summarize（fire-and-forget）
│
▼
SessionManager.queueSummarize()
│ 入队后立即返回，不阻塞用户终端
▼
SDKAgent 后台处理
│ 1. buildSummaryPrompt() 构建摘要提示词
│ 2. Claude 返回结构化摘要 XML
│ 3. 解析并存储到 session_summaries 表
▼
[Hook: SessionEnd] → sessionCompleteHandler
│ 从活跃会话 Map 中移除
│ 允许孤儿收割器清理残留子进程4.5 记忆搜索流程
通过 MCP 工具或 HTTP API 搜索历史记忆：
用户询问"之前修复认证 bug 的经历"
│
▼
MCP Server (mcp-server.ts) 接收 search 工具调用
│
▼
转发到 Worker: GET /api/search?query=authentication+bug
│
▼
SearchRoutes → SearchManager.search()
│
▼
SearchOrchestrator.executeWithFallback()
│
├─ 无查询文本 → SQLiteSearchStrategy（纯过滤）
├─ 有查询文本 + Chroma 可用 → ChromaSearchStrategy（语义搜索）
│ └─ Chroma 失败 → 回退到 SQLite
└─ 有查询 + 有过滤条件 → HybridSearchStrategy（混合搜索）
│
▼
ResultFormatter 格式化结果
返回紧凑索引（~50-100 tokens/条）3 层渐进式搜索策略：
search：返回紧凑索引（ID + 标题 + 类型），Token 开销极低timeline：获取某条观察前后的时间线上下文get_observations：按 ID 获取完整详情（~500-1000 tokens/条）
这种设计比一次获取全量数据节省约 10 倍 Token。
5. 关键设计与实现
设计模式
- 适配器模式（
src/cli/adapters/）：PlatformAdapter接口统一不同 IDE 平台的输入输出格式。每个平台（Claude Code、Cursor、Gemini CLI 等）实现自己的适配器，处理字段名差异（如camelCasevssnake_case） - 策略模式（
src/services/worker/search/strategies/）：搜索引擎通过SearchStrategy接口抽象，SearchOrchestrator根据查询条件自动选择最优策略 - 观察者/事件驱动（
SessionManager）：使用EventEmitter实现会话管理的零延迟事件通知，避免轮询 - 工厂模式（
src/cli/handlers/index.ts）：getEventHandler()根据事件类型返回对应的处理器实例 - 外观模式（
worker-service.ts）：从 2000 行单体重构为 ~300 行的精简编排器，委托给专门模块
数据模型 / 数据库设计
数据库位于 ~/.claude-mem/claude-mem.db，使用 SQLite 存储，共有 10 个版本迁移。核心表结构：
| 表名 | 用途 | 关键字段 |
|---|---|---|
| sdk_sessions | 会话追踪 | content_session_id（Claude 会话ID）, memory_session_id（SDK 会话ID）, project, status |
| observations | 工具使用观察记录 | type, title, subtitle, facts(JSON), narrative, concepts(JSON), files_read, files_modified |
| session_summaries | 会话摘要 | request, investigated, learned, completed, next_steps, notes |
| observations_fts | FTS5 全文搜索虚拟表 | 与 observations 同步，通过触发器维护 |
| session_summaries_fts | FTS5 全文搜索虚拟表 | 与 session_summaries 同步 |
| observation_feedback | 观察使用反馈 | signal_type, 为未来 Thompson Sampling 优化做准备 |
| pending_messages | 待处理消息队列 | 确保 Worker 重启时不丢失数据 |
迁移系统（src/services/sqlite/migrations.ts）采用版本号递增方式，每个迁移有 up/down 方法，且做到幂等安全（使用 IF NOT EXISTS、PRAGMA table_info 检查）。
隐私与安全机制
边缘处理模式：隐私标签在 Hook 层（数据入口）就被剥离，不会传播到 Worker 和数据库：
// src/utils/tag-stripping.ts - 支持的标签类型
content
.replace(/<claude-mem-context>[\s\S]*?<\/claude-mem-context>/g, '') // 系统标签
.replace(/<private>[\s\S]*?<\/private>/g, '') // 用户隐私标签
.replace(/<system_instruction>[\s\S]*?<\/system_instruction>/g, '') // 系统指令
.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '') // 系统提醒- ReDoS 防护：限制单个内容块的最大标签数（100 个），防止正则表达式拒绝服务攻击
- Localhost 限制：Worker HTTP 服务只监听本地回环地址，外部无法访问
- 项目排除：通过
CLAUDE_MEM_EXCLUDED_PROJECTS配置排除不需要记录的项目
错误处理与日志策略
退出码约定（src/shared/hook-constants.ts）：
| 退出码 | 含义 | 行为 |
|---|---|---|
| 0 | 成功 / 优雅降级 | stdout 加入上下文 |
| 1 | 非阻塞错误 | stderr 显示给用户 |
| 2 | 阻塞错误 | stderr 交给 Claude 处理 |
优雅降级哲学：Worker 不可用时，Hook 返回退出码 0（空上下文），不会阻断用户正常工作。isWorkerUnavailableError() 函数区分”Worker 不可达”（优雅降级）和”代码 bug”（上报错误）。
日志系统：所有日志写入文件（~/.claude-mem/logs/），Hook 执行时 stderr 被静默（防止 Claude Code 将 stderr 显示为错误 UI）。
多 AI 提供商支持
Worker 支持三种 AI 代理后端：
- SDKAgent（默认）：通过
@anthropic-ai/claude-agent-sdk调用 Claude - GeminiAgent：调用 Google Gemini
- OpenRouterAgent：通过 OpenRouter 路由到多种模型
在 SessionRoutes.getActiveAgent() 中根据用户设置自动切换，且支持会话中途切换提供商。
6. 环境搭建与运行
环境依赖
- Node.js ≥ 18.0.0
- Bun ≥ 1.0.0（安装过程中自动检测并安装）
- uv（Python 包管理器，用于 ChromaDB，自动安装）
- Claude Code（或 Cursor / Gemini CLI 等支持的 IDE）
安装步骤
# 1. 克隆仓库
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
# 2. 安装依赖
npm install
# 3. 构建项目（构建钩子脚本 + 同步插件清单）
npm run build
# 4. 同步到本地 Claude 插件市场目录
npm run sync-marketplace
# 5. 一键构建 + 同步 + 重启 Worker（开发常用）
npm run build-and-sync作为用户安装（非开发者）
# 一键安装到 Claude Code
npx claude-mem install
# 安装到 Gemini CLI
npx claude-mem install --ide gemini-cli
# 安装到 Cursor
npx claude-mem install --ide cursorWorker 服务管理
# 启动 Worker 服务
npm run worker:start
# 查看 Worker 状态
npm run worker:status
# 重启 Worker
npm run worker:restart
# 停止 Worker
npm run worker:stop
# 查看日志
npm run worker:logs运行测试
# 运行全部测试
bun test
# 运行特定模块的测试
bun test tests/sqlite/ # 数据库测试
bun test tests/server/ # 服务器测试
bun test tests/context/ # 上下文测试关键环境变量
| 变量名 | 默认值 | 说明 |
|---|---|---|
CLAUDE_MEM_DATA_DIR | ~/.claude-mem | 数据目录（数据库、日志等） |
CLAUDE_MEM_WORKER_PORT | 37700 + uid % 100 | Worker HTTP 端口 |
CLAUDE_MEM_WORKER_HOST | 127.0.0.1 | Worker 监听地址 |
CLAUDE_MEM_MODE | code | 工作模式（code, code--zh, chill 等） |
CLAUDE_MEM_CHROMA_ENABLED | true | 是否启用 ChromaDB 向量搜索 |
CLAUDE_MEM_EXCLUDED_PROJECTS | — | 排除不记录的项目列表 |
7. 推荐学习路线
阶段一：入门（1-2 天）
目标：理解项目做什么、怎么用、核心数据流向
-
先读：
README.md— 了解项目定位和功能概览CLAUDE.md— 了解架构全貌（这是给 AI 看的开发指令，包含精练的架构描述）package.json— 了解依赖和可用脚本
-
理解核心类型：
src/cli/types.ts— 阅读NormalizedHookInput、HookResult、PlatformAdapter、EventHandler四个核心接口
-
追踪一次完整的数据流：
plugin/hooks/hooks.json— 理解 7 个生命周期钩子的触发时机src/cli/hook-command.ts→src/cli/adapters/index.ts→src/cli/handlers/index.ts— 理解 Hook 的处理管线
阶段二：进阶（3-5 天）
目标：深入理解 Worker 服务、数据库设计、搜索引擎
-
Worker 服务架构：
src/services/worker-service.ts— 从编排器入手，了解模块组成src/services/server/Server.ts— Express 服务器初始化src/services/worker/http/routes/SessionRoutes.ts— 会话生命周期 APIsrc/services/worker/http/routes/SearchRoutes.ts— 搜索 API
-
数据库与持久化：
src/shared/paths.ts— 理解文件存储结构src/services/sqlite/Database.ts— 数据库初始化（含自修复机制）src/services/sqlite/migrations.ts— 10 个迁移版本的演进历程src/services/sqlite/SessionStore.ts— 核心存储操作
-
AI Agent 机制：
src/sdk/prompts.ts— 理解传递给 Claude 的提示词结构src/sdk/parser.ts— 理解<observation>XML 的解析逻辑src/services/worker/SDKAgent.ts— 理解 Agent 会话管理和消息生成器
-
搜索引擎：
src/services/worker/search/SearchOrchestrator.ts— 策略选择src/services/worker/search/strategies/— 三种搜索策略实现
阶段三：实践（持续）
目标：通过动手修改验证理解
-
添加一种新的观察类型：修改
plugin/modes/code.json中的observation_types数组，观察数据如何流经parser.ts和migrations.ts -
自定义上下文注入格式：修改
src/services/context/sections/TimelineRenderer.ts，改变时间线的 Markdown 输出格式 -
添加新的 IDE 适配器：参照
src/cli/adapters/gemini-cli.ts，为一个新的 IDE 创建适配器，理解normalizeInput和formatOutput的映射逻辑 -
探索 Web 查看器：访问
http://localhost:37777，阅读src/ui/viewer/App.tsx和src/ui/viewer/components/Feed.tsx，理解 SSE 实时推送机制 -
编写新的搜索策略：参照
SearchStrategy接口，实现一个自定义搜索策略，注册到SearchOrchestrator
8. 常见问题与注意事项
容易踩的坑
- Bun 与 Node 的运行时差异：Hook 脚本在 Node.js 下执行（不需要 Bun），但 Worker 服务运行在 Bun 下（使用
bun:sqlite）。plugin/scripts/bun-runner.js负责桥接两个运行时 - 端口计算逻辑：Worker 默认端口不是固定的 37777，而是
37700 + uid % 100（Linux/macOS），只有 Windows 固定为 37777。这在多用户环境下避免冲突 - stderr 静默：在 Hook 执行期间，
process.stderr.write被覆盖为空操作。这是因为 Claude Code 会将 stderr 显示为错误 UI，任何诊断日志都必须通过logger写入文件 - FTS5 可能不可用：在某些平台（如 Windows 上的 Bun），FTS5 模块可能缺失。
migration006会先探测后创建，搜索自动回退到 ChromaDB - Schema 自修复：当数据库在不同版本间同步时可能出现”malformed database schema”错误，
Database.ts会自动使用 Python 的sqlite3模块修复
代码规范与约定
- ESM + CJS 双模式：源码使用 ESM（
import/export），构建后的 Worker 和 MCP Server 使用 CJS（.cjs），通过 esbuild 转换 - Hook 返回值约定：所有 Hook 都必须返回
{ continue: true, suppressOutput: true }格式的 JSON - 隐私标签边缘处理：隐私相关的标签剥离必须在 Hook 层完成，不要在 Worker 层处理
- 观察 XML 格式：SDK Agent 的输出必须符合
<observation>XML 格式，由parser.ts解析 - 未知事件容错：
getEventHandler()对未知事件类型返回空操作处理器，不会抛出异常（修复 #984） - 子代理跳过摘要：当 Hook 在子代理（subagent）中触发时，
summarizeHandler会跳过摘要生成，因为子代理不拥有会话摘要
值得注意的技术债务
src/services/context-generator.ts标记为 DEPRECATED，新代码应从./context/index.js导入SearchManager中有标记为@deprecated的方法（如queryChroma），建议使用orchestrator.search()- 迁移版本号不连续：
migration008的 version 为 25（非 8），这是历史遗留问题，不影响功能 - Worker 从 2000 行单体文件重构：虽已完成模块化，但部分向后兼容的重导出仍然存在
- Windows 兼容性：部分 shell 命令、端口检测逻辑需要平台特殊处理，相关代码中有
process.platform === 'win32'分支
觉得有收获？给个赞吧