;
```
## 观察记录（Observation）
Observation 是系统捕获的单个事件或活动记录。
### 观察记录结构
```xml
[ implementation | debugging | research | planning ]
观察标题
副标题
具体事实1
具体事实2
叙述性描述
相关概念1
相关概念2
读取的文件路径
修改的文件路径
```
### 观察类型
| 类型标识 | 用途 | 资料来源 |
|----------|------|----------|
| `implementation` | 代码实现活动 | src/services/context/types.ts |
| `debugging` | 调试和问题排查 | src/services/context/types.ts |
| `research` | 代码研究和分析 | src/services/context/types.ts |
| `planning` | 项目规划和设计 | src/services/context/types.ts |
### UI 展示组件
Observation 的 UI 展示由 `ObservationCard.tsx` 组件处理，支持以下功能：
- 按类型分组显示观察记录
- 展示关联的概念标签
- 显示涉及的文件（读取/修改）
- 显示观察记录的元数据（ID、日期）
```typescript
// 资料来源：src/ui/viewer/components/ObservationCard.tsx
{showFacts && (concepts.length > 0 || filesRead.length > 0 || filesModified.length > 0) && (
{concepts.map((concept: string, i: number) => (
{concept}
))}
{filesRead.length > 0 && (
read: {filesRead.join(', ')}
)}
)}
```
## 会话摘要（Summary）
Summary 是对整个会话的总结性描述。
### 摘要结构
```xml
用户请求
调查内容
学到的新知识
完成的工作
下一步计划
备注信息
```
### 摘要字段说明
| 字段 | 描述 | 必填 |
|------|------|------|
| `request` | 用户的原始请求 | 是 |
| `investigated` | 调查和研究的内容 | 是 |
| `learned` | 获得的新知识或发现 | 是 |
| `completed` | 完成的任务 | 是 |
| `next_steps` | 建议的后续步骤 | 否 |
| `notes` | 其他备注 | 否 |
### UI 展示组件
```typescript
// 资料来源：src/ui/viewer/components/SummaryCard.tsx
{sections.map((section, index) => (
{section.label}
{section.content}
))}
```
## 上下文编译（Context Compilation）
Context Compiler 负责将存储的记忆转换为可注入到 Claude 会话的格式。
### 编译流程
```mermaid
graph LR
A[Memory Storage] --> B[Query & Filter]
B --> C[ObservationCompiler]
C --> D[Format as XML]
D --> E[Inject to Session]
```
### 上下文配置
用户可以通过环境变量配置上下文注入行为：
| 配置项 | 默认值 | 说明 | 资料来源 |
|--------|--------|------|----------|
| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | 50 | 注入的观察记录数量（1-200） | src/ui/viewer/components/ContextSettingsModal.tsx |
| `CLAUDE_MEM_CONTEXT_SESSIONS` | 10 | 提取观察的会话数量（1-50） | src/ui/viewer/components/ContextSettingsModal.tsx |
### 提示词构建
SDK 使用结构化的提示词模板生成记忆：
```typescript
// 资料来源：src/sdk/prompts.ts
${mode.prompts.output_format_header}
[ ${mode.observation_types.map(t => t.id).join(' | ')} ]
${mode.prompts.xml_title_placeholder}
${mode.prompts.xml_subtitle_placeholder}
${mode.prompts.xml_fact_placeholder}
${mode.prompts.xml_narrative_placeholder}
${mode.prompts.xml_concept_placeholder}
```
## 数据持久化
### 存储位置
所有记忆数据存储在本地目录：
```
~/.claude-mem/
├── memories.db # SQLite 数据库
├── transcripts/ # 会话转录
├── vector-index/ # 向量索引（如启用）
└── config/ # 配置文件
```
### 会话延迟处理
为避免并发问题，系统支持会话延迟处理：
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `RAGTIME_SESSION_DELAY` | 2000ms | 会话间延迟 |
## 模式（Mode）系统
Claude-Mem 支持多种工作模式，每种模式有不同的观察类型和提示词配置。
### 默认模式
```typescript
// 资料来源：src/server/generation/providers/shared/prompt-builder.ts
const FALLBACK_OBSERVATION_TYPES = [
{ id: 'implementation' },
{ id: 'debugging' },
{ id: 'research' },
{ id: 'planning' },
];
```
### 模式配置结构
```typescript
interface ModeConfig {
prompts: {
header_memory_continued: string;
header_memory_start: string;
continuation_instruction: string;
output_format_header: string;
// ... 其他提示词配置
};
observation_types: ReadonlyArray<{
id: string;
}>;
}
```
## 工作流程
### 记忆捕获流程
```mermaid
sequenceDiagram
participant U as User
participant C as Claude Code
participant W as Worker Service
participant M as Memory Storage
U->>C: 执行任务
C->>W: 发送工具使用事件
W->>W: 生成观察记录
W->>M: 存储记忆
Note over C,M: 自动进行，无需用户干预
```
### 上下文注入流程
```mermaid
sequenceDiagram
participant C as Claude Code
participant W as Worker Service
participant M as Memory Storage
participant P as Prompt Builder
C->>W: 请求上下文
W->>M: 查询相关记忆
M-->>W: 返回记忆列表
W->>P: 构建提示词
P-->>W: 格式化的上下文
W-->>C: 注入上下文
Note over C: 新会话开始
```
## 关键配置变量
| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `CLAUDE_MEM_WORKER_PORT` | 37777 | Worker 服务端口 |
| `CLAUDE_MEM_WELCOME_HINT_ENABLED` | true | 是否显示欢迎提示 |
| `RAGTIME_TRANSCRIPT_MAX_AGE` | 24 | 转录文件最大保留时间（小时） |
| `RAGTIME_PROJECT_NAME` | ragtime-investigation | 项目名称 |
## 相关文件索引
| 功能模块 | 源码文件 |
|----------|----------|
| 数据模型 | `src/core/schemas/memory-item.ts` |
| UI 组件 | `src/ui/viewer/components/ObservationCard.tsx` |
| UI 组件 | `src/ui/viewer/components/SummaryCard.tsx` |
| 上下文类型 | `src/services/context/types.ts` |
| 提示词构建 | `src/sdk/prompts.ts` |
| 提示词生成 | `src/server/generation/providers/shared/prompt-builder.ts` |
| 安装命令 | `src/npx-cli/commands/install.ts` |
---
## 系统架构
### 相关页面
相关主题：[Worker 服务](#page-worker-service), [数据存储层](#page-data-storage), [生命周期钩子系统](#page-hooks-system)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)
- [src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)
- [src/ui/viewer/App.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/App.tsx)
- [src/ui/viewer/components/SummaryCard.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/SummaryCard.tsx)
- [src/ui/viewer/components/ObservationCard.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ObservationCard.tsx)
- [src/server/generation/providers/shared/prompt-builder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/providers/shared/prompt-builder.ts)
- [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)
- [src/ui/viewer/components/ContextSettingsModal.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ContextSettingsModal.tsx)
# 系统架构
## 概述
Claude-Mem 是一个为 Claude Code 提供持久化记忆功能的插件系统，其核心目标是实现跨会话的上下文连续性。该系统通过自动捕获工具使用观察、生成语义摘要，使 Claude 能够在会话结束后或重新连接时保持对项目的知识连续性。 资料来源：[README.md:1-10]()
系统架构采用插件化设计，支持多种 IDE 环境集成，包括 Claude Code、Gemini CLI 和 OpenCode。数据存储在本地文件系统（`~/.claude-mem`），确保用户对数据的完全控制。 资料来源：[README.md:28-35]()
## 核心组件架构
Claude-Mem 的系统架构由以下核心层次组成：
```mermaid
graph TD
subgraph "客户端层"
IDE[IDE 插件集成]
CLI[NPX CLI 工具]
end
subgraph "服务层"
Worker[Worker Service]
Server[Server 服务]
PromptBuilder[Prompt Builder]
end
subgraph "SDK 层"
PromptSDK[Prompts SDK]
ObservationSDK[Observation SDK]
end
subgraph "UI 层"
ViewerApp[Viewer 应用]
SummaryCard[摘要卡片]
ObservationCard[观察卡片]
SettingsModal[设置模态框]
end
subgraph "数据层"
Storage[本地存储 ~/.claude-mem]
SessionData[会话数据]
ObservationData[观察数据]
end
IDE --> Worker
CLI --> Worker
Worker --> Server
Server --> PromptBuilder
Server --> Storage
PromptBuilder --> PromptSDK
ViewerApp --> Server
ViewerApp --> SettingsModal
```
### 组件职责矩阵
| 组件 | 类型 | 主要职责 | 源码位置 |
|------|------|----------|----------|
| Worker Service | 服务进程 | 管理观察数据收集和处理的生命周期 | `src/services/worker-service.ts` |
| Server | HTTP 服务 | 提供 REST API，处理记忆注入请求 | `src/services/server/Server.ts` |
| Prompt Builder | 生成器 | 构建 LLM 提示词和输出模式 | `src/server/generation/providers/shared/prompt-builder.ts` |
| Prompts SDK | SDK 模块 | 封装提示词构建逻辑 | `src/sdk/prompts.ts` |
| Viewer App | React 应用 | 提供记忆查看器 UI | `src/ui/viewer/App.tsx` |
## 数据流架构
### 观察数据生命周期
```mermaid
graph LR
A[工具调用] --> B[观察捕获]
B --> C[输入解析]
C --> D[Prompt 构建]
D --> E[LLM 处理]
E --> F[结构化输出]
F --> G[存储]
G --> H[摘要生成]
H --> I[上下文注入]
```
1. **观察捕获阶段**：系统监听 Claude Code 的工具调用事件，自动捕获工具输入和输出 资料来源：[src/server/generation/providers/shared/prompt-builder.ts:1-30]()
2. **数据解析阶段**：对捕获的工具调用进行解析，提取关键信息并处理私有数据边界 资料来源：[src/server/generation/providers/shared/prompt-builder.ts:40-60]()
3. **Prompt 构建阶段**：根据活动模式（Mode）配置构建符合 XML 格式的观察输出 资料来源：[src/sdk/prompts.ts:1-50]()
4. **LLM 处理阶段**：使用配置的 LLM 模型生成语义化的观察摘要
5. **存储阶段**：将处理后的数据持久化到本地存储
6. **上下文注入阶段**：在新的会话中自动注入相关记忆
### 上下文注入流程
```mermaid
graph TD
A[新会话开始] --> B{检查记忆缓存}
B -->|首次会话| C[不注入历史]
B -->|非首次会话| D[查询历史观察]
D --> E[加载最近 N 条观察]
D --> F[加载最近 M 个会话]
E --> G[构建上下文 Prompt]
F --> G
G --> H[注入到系统提示]
H --> I[开始新会话]
C --> I
```
上下文注入可通过环境变量进行配置： 资料来源：[src/ui/viewer/components/ContextSettingsModal.tsx:30-60]()
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | 50 | 注入的观察数量（1-200） |
| `CLAUDE_MEM_CONTEXT_SESSIONS` | 10 | 抽取观察的会话数量（1-50） |
## 提示词生成架构
### Prompt SDK 结构
提示词生成采用模块化设计，支持多种模式配置： 资料来源：[src/sdk/prompts.ts:50-100]()
```typescript
interface ModeConfig {
prompts: {
continuation_instruction: string;
output_format_header: string;
xml_title_placeholder: string;
xml_subtitle_placeholder: string;
xml_fact_placeholder: string;
xml_narrative_placeholder: string;
xml_concept_placeholder: string;
xml_file_placeholder: string;
type_guidance: string;
field_guidance: string;
concept_guidance: string;
format_examples: string;
footer: string;
};
observation_types: ObservationType[];
}
```
### 输出模式构建
观察输出采用 XML 格式，包含以下结构化字段： 资料来源：[src/server/generation/providers/shared/prompt-builder.ts:70-90]()
```xml
[ observation | code_change | error_recovery | ... ]
...
...
...
...
...
...
...
```
### 摘要生成 Prompt
系统支持生成会话级别的语义摘要，用于高层次的项目状态追踪： 资料来源：[src/sdk/prompts.ts:80-120]()
```xml
用户原始请求
调查内容
学到的新知识
完成的任务
后续步骤
备注
```
## UI 组件架构
### 组件层次结构
```mermaid
graph TD
App --> Header
App --> WelcomeCard
App --> ObservationList
App --> SummaryList
App --> ContextSettingsModal
App --> LogsDrawer
ObservationList --> ObservationCard
SummaryList --> SummaryCard
ObservationCard --> ObservationType
ObservationCard --> FactsList
ObservationCard --> NarrativeView
SummaryCard --> SummarySection
SummarySection --> SectionHeader
SummarySection --> SectionContent
```
### 主要组件说明
#### Viewer 应用主容器 资料来源：[src/ui/viewer/App.tsx:1-50]()
| 状态管理 | 功能描述 |
|----------|----------|
| `settings` | 全局设置状态 |
| `welcomeDismissed` | 欢迎卡片显示控制 |
| `contextPreviewOpen` | 上下文预览模态框 |
| `logsModalOpen` | 日志抽屉开关 |
#### 观察卡片组件 资料来源：[src/ui/viewer/components/ObservationCard.tsx:1-80]()
显示单个观察记录的详细信息，支持两种视图模式切换：
| 视图模式 | 显示内容 |
|----------|----------|
| 摘要模式 | 标题、副标题 |
| 事实模式 | 类型徽章、事实列表、概念标签、文件引用 |
| 叙事模式 | 叙述性描述 |
#### 摘要卡片组件 资料来源：[src/ui/viewer/components/SummaryCard.tsx:1-50]()
展示会话级别的语义摘要，包含以下节：
- **Request**：用户请求
- **Investigated**：调查内容
- **Learned**：学到的知识
- **Completed**：完成的任务
- **Next Steps**：后续步骤
#### 设置模态框 资料来源：[src/ui/viewer/components/ContextSettingsModal.tsx:1-100]()
提供交互式的上下文注入配置界面，包含：
- 观察数量配置（1-200）
- 会话数量配置（1-50）
- 实时终端预览
## 安装与部署架构
### 插件安装流程
```mermaid
graph LR
A[npx claude-mem install] --> B{IDE 类型}
B -->|Claude Code| C[Marketplace 安装]
B -->|Gemini CLI| D[自动检测 ~/.gemini]
B -->|OpenCode| E[特定路径配置]
C --> F[Worker Service 启动]
D --> F
E --> F
F --> G[注册插件钩子]
G --> H[初始化本地存储]
H --> I[系统就绪]
```
### 安装命令支持 资料来源：[src/npx-cli/commands/install.ts:1-50]()
| 安装方式 | 命令 | 适用环境 |
|----------|------|----------|
| 标准安装 | `npx claude-mem install` | Claude Code |
| Gemini CLI | `npx claude-mem install --ide gemini-cli` | Gemini CLI |
| OpenCode | `npx claude-mem install --ide opencode` | OpenCode |
| 市场安装 | `/plugin marketplace add thedotmack/claude-mem` | Claude Code 内部 |
| OpenClaw | `curl -fsSL https://install.cmem.ai/openclaw.sh \| bash` | OpenClaw 网关 |
### 首次使用引导 资料来源：[src/npx-cli/commands/install.ts:50-80]()
首次安装后，系统提供两种启动路径：
| 路径 | 描述 | 推荐场景 |
|------|------|----------|
| A. 被动构建 | 直接开始工作，记忆从第一次提示中被动构建 | 日常使用（推荐） |
| B. 主动加载 | 运行 `/learn-codebase` 主动摄入整个代码仓库 | 需要快速建立上下文 |
## 记忆存储架构
### 本地存储结构
所有数据存储在用户本地目录 `~/.claude-mem`，包括：
- 会话记录
- 观察数据
- 生成的摘要
- 用户配置
### 数据隔离
系统通过以下机制保护数据隐私： 资料来源：[src/server/generation/providers/shared/prompt-builder.ts:20-40]()
1. **私有数据检测**：自动识别并标记包含敏感信息的内容
2. **数据边界控制**：通过 `docs/ip-boundary.md` 定义数据处理边界
3. **本地优先**：所有数据存储在用户本地，不上传至云端
## 多模式支持架构
系统支持可配置的操作模式（Mode），每种模式定义不同的：
| 配置维度 | 说明 |
|----------|------|
| `observation_types` | 支持的观察类型 |
| `prompts.*` | 各种提示词模板和占位符 |
| `type_guidance` | 类型选择指导 |
| `field_guidance` | 字段填写指导 |
模式管理器（ModeManager）提供活动模式的获取和切换功能。 资料来源：[src/server/generation/providers/shared/prompt-builder.ts:35-45]()
## 扩展点与集成
### IDE 插件钩子
系统通过插件钩子与 IDE 集成，支持：
- 工具调用拦截
- 会话状态监控
- 上下文注入
### MCP 服务器集成
Claude-Mem 可作为 MCP（Model Context Protocol）服务器运行，提供：
- 记忆查询接口
- 观察记录接口
- 配置管理接口
### 国际化支持
系统内置多语言支持，包括简体中文（`code--zh`）等语言模式。 资料来源：[README.md:80-90]()
## 安全与隐私
### 数据保护机制
| 机制 | 说明 |
|------|------|
| 本地存储 | 数据不离开用户设备 |
| 私有数据标记 | 敏感信息自动标记 |
| IP 边界文档 | 明确定义数据处理边界 |
### 许可证
项目采用 Apache License 2.0，该许可证允许在多种场景下使用，包括开发者工具、本地代理、MCP 服务器、企业系统、机器人栈和生产代理环境。 资料来源：[README.md:100-110]()
## 总结
Claude-Mem 采用分层架构设计，核心包括：
1. **观察捕获层**：通过 IDE 插件钩子自动捕获工具使用
2. **处理服务层**：Worker Service 和 Server 处理数据转换和存储
3. **生成引擎层**：Prompt Builder 构建 LLM 交互的提示词
4. **用户界面层**：React 组件提供记忆查看和配置功能
5. **存储持久层**：本地文件系统确保数据隐私和持久性
这种架构设计确保了系统具有良好的可扩展性、安全性和用户数据控制能力。
---
## Worker 服务
### 相关页面
相关主题：[系统架构](#page-architecture), [MCP 集成](#page-mcp-integration), [数据存储层](#page-data-storage)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server/jobs/ServerJobQueue.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/jobs/ServerJobQueue.ts)
- [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)
- [src/services/worker-service.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts)
- [src/services/worker/SessionManager.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/SessionManager.ts)
- [src/services/worker/FormattingService.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/FormattingService.ts)
- [src/services/worker/agents/ResponseProcessor.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/agents/ResponseProcessor.ts)
- [src/services/worker/http/routes](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/http/routes)
# Worker 服务
## 概述
Worker 服务是 claude-mem 系统中的核心后台处理组件，负责执行长期运行的任务队列、处理观察记录生成、以及管理会话上下文。该服务以独立进程方式运行，通过 BullMQ 与 Redis 进行进程间通信，实现高可靠性的任务处理能力。Worker 服务默认监听端口 37777，提供健康检查和状态监控接口。
Worker 服务的核心职责包括：
- 接收并处理来自主服务的任务队列请求
- 管理会话的上下文信息和历史记录
- 执行 LLM 响应处理和格式转换
- 维护任务执行状态和进度通知
- 处理失败任务的重试逻辑
资料来源：[src/npx-cli/commands/install.ts:1-100]()
## 核心组件
Worker 服务由多个协同工作的子模块组成，每个模块承担特定的职责。
### 组件架构表
| 组件名称 | 文件路径 | 职责描述 |
|---------|---------|---------|
| SessionManager | `src/services/worker/SessionManager.ts` | 管理会话生命周期、上下文存储与检索 |
| FormattingService | `src/services/worker/FormattingService.ts` | 处理观察记录的格式化和输出 |
| ResponseProcessor | `src/services/worker/agents/ResponseProcessor.ts` | 处理 LLM 响应、提取结构化数据 |
| HTTP Routes | `src/services/worker/http/routes` | 提供 RESTful API 接口 |
| ServerJobQueue | `src/server/jobs/ServerJobQueue.ts` | 任务队列管理与 BullMQ 集成 |
资料来源：[src/services/worker/SessionManager.ts](), [src/services/worker/FormattingService.ts](), [src/services/worker/agents/ResponseProcessor.ts]()
## 任务队列架构
Worker 服务基于 BullMQ 构建企业级任务队列系统，支持分布式处理和跨进程事件通知。
### 队列工作流程
```mermaid
graph TD
A[主服务提交任务] --> B[ServerJobQueue 入队]
B --> C[Redis 队列存储]
C --> D[Worker 进程轮询]
D --> E{任务类型判断}
E -->|生成任务| F[Generation Worker]
E -->|处理任务| G[Processing Worker]
F --> H[LLM 调用]
G --> I[数据处理]
H --> J[ResponseProcessor]
I --> J
J --> K[格式化输出]
K --> L[结果存储]
L --> M[QueueEvents 通知]
```
### 事件处理机制
Worker 服务通过 QueueEvents 订阅 Redis 发布/订阅通道，实现跨进程的可靠事件通知。
主要事件类型：
- **stalled**: 任务停滞检测，由 Worker 或 QueueEvents 触发
- **progress**: 任务进度更新
- **error**: 任务执行错误
- **failed**: 任务最终失败
```mermaid
graph LR
A[Worker 进程] -->|w.on| B[stalled 事件]
A -->|w.on| C[progress 事件]
A -->|w.on| D[error 事件]
A -->|w.on| E[failed 事件]
F[QueueEvents] -->|events.on| G[跨进程 stalled 通知]
G --> H[notifyStalled]
```
资料来源：[src/server/jobs/ServerJobQueue.ts:50-80]()
### 任务重试策略
Worker 实现智能重试机制，在任务失败时根据配置自动重试：
```typescript
// 伪代码示例，实际逻辑在 ServerJobQueue 中实现
{
attempts: 3, // 最大重试次数
backoff: {
type: 'exponential', // 指数退避
delay: 2000 // 基础延迟 2 秒
}
}
```
## 配置与端口
### 默认配置参数
| 参数名 | 默认值 | 说明 |
|-------|-------|------|
| `CLAUDE_MEM_WORKER_PORT` | 37777 | Worker 服务监听端口 |
| 队列前缀 | `cmem` | BullMQ 键名前缀 |
| 最大并发 | 可配置 | 同时处理的任务数上限 |
### 健康检查流程
Worker 服务启动后通过端口 37777 提供健康检查端点：
```mermaid
sequenceDiagram
participant CLI as Claude-Mem CLI
participant Worker as Worker Service
participant Redis as Redis
CLI->>Worker: 检查端口 37777 连接
alt 端口可达
Worker-->>CLI: Worker 就绪
CLI->>Worker: 启动完成提示
else 端口不可达
Worker-->>CLI: 仍在启动中
CLI->>User: 提示等待 30 秒后重试
end
```
资料来源：[src/npx-cli/commands/install.ts:20-60]()
## 状态监控
### 队列深度监控
Worker 服务的 Header 组件持续监控队列状态，当存在待处理任务时显示队列气泡指示器：
```tsx
// 队列气泡显示逻辑
{queueDepth > 0 && (
{queueDepth}
)}
```
### 错误边界处理
Worker 服务的 UI 组件实现了 ErrorBoundary 错误边界机制，确保单个组件错误不会导致整个界面崩溃：
```tsx
class ErrorBoundary extends Component {
state = { error: null, errorInfo: null };
componentDidCatch(error, errorInfo) {
this.setState({ error, errorInfo });
}
render() {
if (this.state.error) {
return ;
}
return this.props.children;
}
}
```
资料来源：[src/ui/viewer/components/ErrorBoundary.tsx:1-50](), [src/ui/viewer/components/Header.tsx:1-40]()
## 启动与管理
### 安装命令
Worker 服务通过 npx 命令安装并自动配置：
```bash
npx claude-mem install
```
安装过程会：
1. 检查 Worker 服务状态
2. 等待服务在端口 37777 上就绪
3. 显示连接信息和后续操作指引
### 手动启动
如需手动启动 Worker 服务：
```bash
npx claude-mem start
```
服务将以后台进程方式运行，日志输出到标准输出。
资料来源：[src/npx-cli/commands/install.ts:1-30]()
## 总结
Worker 服务是 claude-mem 架构中不可或缺的异步处理中枢，通过 BullMQ 和 Redis 实现高可靠性的分布式任务处理。服务支持事件驱动的进度监控、智能重试策略、以及完整的错误处理机制。SessionManager、FormattingService 和 ResponseProcessor 等子模块各司其职，共同完成从任务接收到结果输出的完整链路。
---
## 数据存储层
### 相关页面
相关主题：[搜索系统](#page-search-system), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [src/services/sqlite/Database.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Database.ts)
- [src/services/sqlite/schema.sql](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/schema.sql)
- [src/services/sqlite/Sessions.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Sessions.ts)
- [src/services/sqlite/Observations.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Observations.ts)
- [src/services/sync/ChromaSync.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sync/ChromaSync.ts)
- [src/services/worker/search/strategies](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/strategies)
# 数据存储层
## 概述
claude-mem 的数据存储层是整个记忆系统的核心基础设施，负责持久化会话数据、观察记录和语义向量。该层采用混合存储架构，结合 SQLite 的事务性数据存储和 Chroma 向量数据库的语义搜索能力，实现高效的数据读写和智能检索功能。
数据存储层的主要职责包括：
- **会话管理**：创建、更新和查询 Claude Code 会话记录
- **观察持久化**：存储 AI 生成的观察条目（observations）
- **语义同步**：将数据同步到向量数据库支持语义搜索
- **上下文注入**：为新会话提供历史记忆上下文
资料来源：[src/services/sqlite/Database.ts:1-50]()
## 架构设计
### 存储层组件
数据存储层由以下核心组件构成：
```mermaid
graph TD
A[claude-mem SDK] --> B[SQLite 数据库]
A --> C[Chroma 向量库]
B --> D[sessions 表]
B --> E[observations 表]
B --> F[prompts 表]
B --> G[summaries 表]
C --> H[向量嵌入]
E --> C
I[Worker Service] --> B
I --> C
```
| 组件 | 文件路径 | 职责 |
|------|----------|------|
| Database | `src/services/sqlite/Database.ts` | 数据库连接管理和初始化 |
| Sessions | `src/services/sqlite/Sessions.ts` | 会话记录的 CRUD 操作 |
| Observations | `src/services/sqlite/Observations.ts` | 观察数据的持久化 |
| ChromaSync | `src/services/sync/ChromaSync.ts` | 与向量数据库的同步 |
资料来源：[src/services/sqlite/schema.sql:1-20]()
### 数据模型
#### Sessions 表
会话表存储每次 Claude Code 交互会话的元数据：
```sql
CREATE TABLE sessions (
id TEXT PRIMARY KEY,
project TEXT NOT NULL,
server_session_id TEXT,
created_at_epoch INTEGER NOT NULL,
updated_at_epoch INTEGER NOT NULL,
summary_id TEXT,
mode TEXT,
event_count INTEGER DEFAULT 0
);
```
关键字段说明：
| 字段 | 类型 | 说明 |
|------|------|------|
| id | TEXT | 会话唯一标识符 |
| project | TEXT | 所属项目名称 |
| server_session_id | TEXT | 服务端会话 ID |
| created_at_epoch | INTEGER | 创建时间戳 |
| updated_at_epoch | INTEGER | 最后更新时间戳 |
| summary_id | TEXT | 关联的摘要记录 |
| mode | TEXT | 当前模式配置 |
| event_count | INTEGER | 事件计数 |
资料来源：[src/services/sqlite/schema.sql:1-10]()
#### Observations 表
观察表是核心数据存储，记录 AI 生成的结构化观察：
```sql
CREATE TABLE observations (
id TEXT PRIMARY KEY,
session_id TEXT NOT NULL,
project TEXT NOT NULL,
type TEXT NOT NULL,
title TEXT,
subtitle TEXT,
narrative TEXT,
facts TEXT, -- JSON array
concepts TEXT, -- JSON array
files_read TEXT, -- JSON array
files_modified TEXT, -- JSON array
tool_name TEXT,
tool_input TEXT,
tool_output TEXT,
occurred_at_epoch INTEGER NOT NULL,
created_at_epoch INTEGER NOT NULL,
is_summary_related INTEGER DEFAULT 0,
FOREIGN KEY (session_id) REFERENCES sessions(id)
);
```
| 字段 | 类型 | 说明 |
|------|------|------|
| id | TEXT | 观察记录唯一标识 |
| session_id | TEXT | 所属会话 ID |
| type | TEXT | 观察类型（如 code_analysis, bug_fix） |
| title | TEXT | 观察标题 |
| facts | TEXT | JSON 格式的事实列表 |
| concepts | TEXT | JSON 格式的概念标签 |
| files_read | TEXT | JSON 格式的读取文件列表 |
| files_modified | TEXT | JSON 格式的修改文件列表 |
| narrative | TEXT | 叙述性描述 |
| tool_name | TEXT | 关联的工具名称 |
| tool_input | TEXT | 工具输入（JSON 或文本） |
| tool_output | TEXT | 工具输出（JSON 或文本） |
资料来源：[src/services/sqlite/schema.sql:11-35]()
## 核心模块详解
### Database 模块
`Database.ts` 是存储层的入口点，负责：
- 建立 SQLite 数据库连接
- 执行 schema 初始化
- 提供事务支持
- 管理数据库路径配置
```typescript
// 典型初始化流程
const db = new Database(appDataPath);
await db.initialize();
```
资料来源：[src/services/sqlite/Database.ts:1-30]()
### Sessions 模块
`Sessions.ts` 实现会话管理的核心逻辑：
| 方法 | 功能 |
|------|------|
| createSession | 创建新会话记录 |
| updateSession | 更新会话状态 |
| getSession | 根据 ID 获取会话 |
| listSessions | 列出项目的所有会话 |
| deleteSession | 删除会话及关联数据 |
会话查询支持按项目名称、时间范围和模式类型过滤。
资料来源：[src/services/sqlite/Sessions.ts:1-50]()
### Observations 模块
`Observations.ts` 处理观察数据的读写操作：
```mermaid
graph LR
A[工具调用事件] --> B[ObservationParser]
B --> C[存储到SQLite]
C --> D[ChromaSync]
D --> E[生成向量嵌入]
E --> F[Chroma向量库]
```
关键功能包括：
- 将工具输入/输出解析为结构化观察
- 支持批量插入和分页查询
- 维护观察与会话、摘要的关联关系
资料来源：[src/services/sqlite/Observations.ts:1-60]()
## 向量同步机制
### ChromaSync 模块
`ChromaSync.ts` 负责将 SQLite 中的观察数据同步到 Chroma 向量数据库：
```mermaid
graph TD
A[SQLite observations] --> B[ChromaSync]
B --> C{同步状态检查}
C -->|已同步| D[跳过]
C -->|需同步| E[提取文本内容]
E --> F[调用Embedding API]
F --> G[生成向量]
G --> H[存储到Chroma]
H --> I[更新同步标记]
```
同步策略包括：
- **增量同步**：仅同步新增或更新的记录
- **批量处理**：分批处理大量数据避免内存溢出
- **错误重试**：失败时自动重试机制
资料来源：[src/services/sync/ChromaSync.ts:1-80]()
### 向量搜索策略
搜索策略模块实现了多种检索算法：
| 策略 | 说明 | 适用场景 |
|------|------|----------|
| 语义相似度 | 基于向量余弦相似度 | 语义相关查询 |
| 关键词匹配 | BM25 或全文索引 | 精确术语搜索 |
| 混合搜索 | 向量 + 关键词融合 | 平衡精确与语义 |
| 时间衰减 | 考虑时间因素的排序 | 最新相关 |
资料来源：[src/services/worker/search/strategies](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/strategies)
## 数据流
### 写入流程
```mermaid
sequenceDiagram
participant SDK as Claude SDK
participant Worker as Worker Service
participant SQLite as SQLite DB
participant Chroma as Chroma
SDK->>Worker: 发送工具调用事件
Worker->>Worker: 解析为 Observation
Worker->>SQLite: 存储观察记录
Worker->>Chroma: 同步向量数据
Chroma-->>Worker: 确认同步完成
Worker-->>SDK: 返回处理结果
```
### 读取流程
当新会话启动时，数据存储层提供上下文注入：
1. 解析用户请求
2. 根据配置选择观察数量和会话数量
3. 执行向量相似度搜索
4. 按时间排序和去重
5. 注入到提示上下文
资料来源：[src/services/sqlite/Observations.ts:60-100]()
## 配置与优化
### 存储路径
默认数据库存储路径为应用数据目录：
```bash
# macOS
~/Library/Application Support/claude-mem/
# Linux
~/.config/claude-mem/
# Windows
%APPDATA%/claude-mem/
```
### 性能考虑
- **索引优化**：对 `session_id`、`project`、`occurred_at_epoch` 等字段建立索引
- **批量写入**：使用事务批量提交减少 I/O
- **连接池**：复用数据库连接减少开销
资料来源：[src/services/sqlite/schema.sql:36-50]()
## 相关文档
- [安装指南](../getting-started/installation.md)
- [API 参考](../api-reference/server-routes.md)
- [搜索功能](../features/search.md)
---
## 搜索系统
### 相关页面
相关主题：[MCP 集成](#page-mcp-integration), [数据存储层](#page-data-storage)
相关源码文件
以下源码文件用于生成本页说明：
- [src/services/worker/search/SearchOrchestrator.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/SearchOrchestrator.ts)
- [src/services/worker/search/strategies/HybridSearchStrategy.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/strategies/HybridSearchStrategy.ts)
- [src/services/worker/search/TimelineBuilder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/TimelineBuilder.ts)
- [src/services/sqlite/observations/get.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/observations/get.ts)
- [src/server/mcp/tools.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/mcp/tools.ts)
# 搜索系统
## 概述
搜索系统是 claude-mem 的核心功能模块，负责在历史观察记录、会话和提示词中进行语义检索。该系统通过混合搜索策略结合关键词匹配与语义理解，使用户能够快速定位跨越多个会话积累的项目知识。搜索结果不仅返回匹配的观察记录，还支持时间线构建、上下文预览和自动注入功能，使 AI 能够在新的会话中无缝利用历史上下文。
## 架构设计
### 系统组件
搜索系统由多个协同工作的组件构成，形成从请求处理到结果返回的完整管道。
| 组件名称 | 文件路径 | 职责描述 |
|---------|---------|---------|
| SearchOrchestrator | `src/services/worker/search/SearchOrchestrator.ts` | 搜索请求的统一入口，负责协调各搜索策略的执行 |
| HybridSearchStrategy | `src/services/worker/search/strategies/HybridSearchStrategy.ts` | 实现混合搜索策略，结合关键词与语义检索 |
| TimelineBuilder | `src/services/worker/search/TimelineBuilder.ts` | 构建搜索结果的时间线视图 |
| 观察记录获取 | `src/services/sqlite/observations/get.ts` | 从 SQLite 数据库检索观察记录 |
| MCP 工具层 | `src/server/mcp/tools.ts` | 提供 MCP 协议接口供外部调用搜索功能 |
### 数据流向
```mermaid
graph TD
A[用户搜索请求] --> B[SearchOrchestrator]
B --> C{HybridSearchStrategy}
C --> D[关键词搜索]
C --> E[语义向量搜索]
D --> F[结果合并与排序]
E --> F
F --> G[TimelineBuilder]
G --> H[搜索结果响应]
H --> I[上下文预览/注入]
```
## 核心组件详解
### SearchOrchestrator
SearchOrchestrator 作为搜索系统的协调器，负责接收和处理所有搜索请求。它根据请求类型分发到相应的搜索策略，并协调结果的聚合与格式化。
**主要职责：**
- 路由不同类型的搜索请求（观察记录、会话、提示词等）
- 管理搜索策略的执行顺序
- 处理搜索结果的缓存与去重
- 提供搜索帮助信息
### HybridSearchStrategy
混合搜索策略是本系统的核心创新，它结合了传统关键词搜索的精确性与语义搜索的智能化理解能力。
```mermaid
graph LR
A[查询字符串] --> B[分词处理]
B --> C[关键词匹配]
B --> D[语义向量化]
C --> E[BM25 评分]
D --> F[向量相似度]
E --> G[分数融合]
F --> G
G --> H[Top-K 结果]
```
**搜索模式支持：**
- **全文搜索**：对观察记录的标题、副标题、事实描述进行全文检索
- **标签搜索**：按概念标签、文件路径、观察类型过滤
- **时间范围搜索**：限定在特定时间段内的记录
- **项目隔离搜索**：仅在指定项目中搜索
### TimelineBuilder
TimelineBuilder 负责将搜索结果按时间顺序组织，帮助用户理解知识在项目演进过程中的累积过程。
**时间线类型：**
- `timeline-by-query`：基于搜索查询的时间线
- `context-timeline`：上下文注入时的时间线
- `recent-context`：最近上下文的综合视图
## API 端点
### 搜索相关端点
| 端点路径 | HTTP 方法 | 功能描述 |
|---------|-----------|---------|
| `/search/observations` | GET | 搜索观察记录 |
| `/search/sessions` | GET | 搜索会话 |
| `/search/prompts` | GET | 搜索提示词 |
| `/search/by-concept` | GET | 按概念标签查找 |
| `/search/by-file` | GET | 按文件路径查找 |
| `/search/by-type` | GET | 按观察类型查找 |
| `/search/recent-context` | GET | 获取最近上下文 |
| `/search/context-timeline` | GET | 获取上下文时间线 |
| `/search/timeline-by-query` | GET | 基于查询的时间线 |
| `/search/help` | GET | 获取搜索帮助 |
### 上下文相关端点
| 端点路径 | HTTP 方法 | 功能描述 |
|---------|-----------|---------|
| `/context/preview` | GET | 预览上下文内容 |
| `/context/inject` | POST | 注入上下文到会话 |
## 观察记录检索
### SQLite 数据模型
观察记录存储在 SQLite 数据库中，支持多种查询模式。资料来源：`src/services/sqlite/observations/get.ts`
**支持的操作类型：**
```typescript
type ObservationKind = 'decision' | 'change' | 'how-it-works';
```
**检索函数签名：**
- `getObservations(filters)`：基础观察记录检索
- `getObservationsBySession(sessionId)`：按会话筛选
- `getObservationsByProject(projectId)`：按项目筛选
- `getObservationsByType(type)`：按类型筛选
### 查询参数
| 参数名 | 类型 | 描述 |
|-------|------|-----|
| `query` | string | 搜索查询字符串 |
| `sessionId` | string | 会话 ID |
| `projectId` | string | 项目 ID |
| `type` | string | 观察类型 |
| `concept` | string | 概念标签 |
| `filePath` | string | 文件路径 |
| `limit` | number | 返回结果数量限制 |
| `offset` | number | 结果偏移量 |
## MCP 工具接口
MCP（Model Context Protocol）工具层为外部 AI 客户端提供搜索访问接口。资料来源：`src/server/mcp/tools.ts`
### 工具定义
```typescript
// MCP 搜索工具结构
interface SearchTool {
name: string; // 工具名称
description: string; // 功能描述
inputSchema: object; // 输入参数模式
}
```
### 可用搜索工具
| 工具名称 | 功能 | 输入参数 |
|---------|------|---------|
| `search_observations` | 搜索观察记录 | query, filters |
| `search_sessions` | 搜索会话 | query, dateRange |
| `search_by_concept` | 按概念搜索 | concept, limit |
| `search_by_file` | 按文件路径搜索 | filePath, limit |
| `inject_context` | 注入上下文 | sessionId, observationIds |
## 搜索策略实现
### 混合评分机制
混合搜索策略通过加权融合关键词匹配分数和语义相似度分数来生成最终排名。资料来源：`src/services/worker/search/strategies/HybridSearchStrategy.ts`
**评分公式：**
```
final_score = α × bm25_score + β × semantic_similarity
```
其中 α 和 β 为可配置的权重参数，默认 α = 0.4，β = 0.6。
### 结果重排序
搜索结果返回前会根据以下因素进行重排序：
- 时间衰减因子：新近记录优先
- 项目相关性：与当前项目关联度高的记录
- 使用频率：被引用次数多的记录
## 使用场景
### 场景一：跨会话知识检索
当开发者需要回顾之前实现某个功能的技术决策时，可以通过概念标签或文件路径快速定位相关观察记录。
### 场景二：上下文恢复
在长时间中断后重新开始工作时，系统可以将相关的历史观察打包为上下文预览，帮助 AI 快速恢复项目认知。
### 场景三：知识图谱构建
通过分析搜索结果中的概念标签和文件关联，系统可以自动构建项目的知识图谱结构。
## 配置选项
### 搜索配置参数
| 配置项 | 默认值 | 描述 |
|-------|-------|------|
| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | 50 | 注入上下文时包含的观察记录数量 |
| `CLAUDE_MEM_CONTEXT_SESSIONS` | 10 | 从多少个会话中拉取观察记录 |
| `search.defaultLimit` | 20 | 默认搜索结果限制 |
| `search.maxLimit` | 200 | 最大搜索结果限制 |
| `hybrid.alpha` | 0.4 | BM25 权重 |
| `hybrid.beta` | 0.6 | 语义相似度权重 |
## 总结
搜索系统通过混合搜索策略、灵活的时间线构建和完整的 MCP 工具接口，为 claude-mem 提供了强大的知识检索能力。该系统使得跨会话的上下文保持和知识复用成为可能，显著提升了 AI 在长期项目中的工作效率。
---
## 生命周期钩子系统
### 相关页面
相关主题：[系统架构](#page-architecture), [IDE 集成](#page-ide-integrations)
相关源码文件
以下源码文件用于生成本页说明：
- [openclaw/src/index.ts](https://github.com/thedotmack/claude-mem/blob/main/openclaw/src/index.ts)
- [cursor-hooks/README.md](https://github.com/thedotmack/claude-mem/blob/main/cursor-hooks/README.md)
- [src/services/smart-file-read/parser.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/smart-file-read/parser.ts)
- [src/server/generation/providers/shared/prompt-builder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/providers/shared/prompt-builder.ts)
- [src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)
# 生命周期钩子系统
## 概述
生命周期钩子系统（Lifecycle Hook System）是 claude-mem 的核心模块，负责在 Claude Code、Gemini CLI、OpenClaw Gateway 和 Cursor 等 IDE 的运行过程中自动捕获用户操作、生成语义摘要，并使历史上下文可供未来会话使用。该系统通过事件驱动的架构，在 IDE 的关键生命周期节点注入自定义逻辑，实现跨会话的持久记忆功能。 资料来源：[README.md]()
## 架构设计
### 系统组件
```mermaid
graph TD
subgraph "IDE 运行环境"
CLI[Claude Code / Gemini CLI / Cursor / OpenClaw]
end
subgraph "钩子系统核心"
HC[Hook Manager]
EP[Event Processor]
OBS[Observation Store]
SUM[Summary Generator]
end
subgraph "存储层"
DB[(SQLite/JSON)]
FS[文件系统]
end
CLI -->|触发生命周期事件| HC
HC -->|处理事件| EP
EP -->|生成观测记录| OBS
EP -->|触发摘要生成| SUM
OBS -->|持久化| DB
SUM -->|持久化| FS
```
### 事件流处理
钩子系统采用事件驱动模式，在 IDE 的生命周期各阶段触发相应的处理函数。每个事件都携带上下文数据，经处理器转换后存入持久化存储。 资料来源：[openclaw/src/index.ts:1-50]()
## 钩子事件类型
### OpenClaw Gateway 事件
OpenClaw Gateway 提供了完整的事件订阅接口，支持以下生命周期事件： 资料来源：[openclaw/src/index.ts:15-27]()
| 事件名称 | 触发时机 | 回调参数 | 功能描述 |
|---------|---------|---------|---------|
| `before_prompt_build` | 构建提示词前 | `PromptBuildCallback` | 修改或增强提示词内容 |
| `before_agent_start` | Agent 启动前 | `BeforeAgentStartEvent` | 执行预启动准备工作 |
| `tool_result_persist` | 工具执行结果返回时 | `ToolResultPersistEvent` | 持久化工具输出 |
| `agent_end` | Agent 执行完成时 | `AgentEndEvent` | 执行后处理逻辑 |
| `session_start` | 会话启动时 | `SessionStartEvent` | 初始化会话上下文 |
| `session_end` | 会话结束时 | `SessionEndEvent` | 生成会话摘要 |
| `message_received` | 收到用户消息时 | `MessageReceivedEvent` | 处理用户输入 |
| `after_compaction` | 上下文压缩后 | `AfterCompactionEvent` | 处理压缩后的状态 |
| `gateway_start` | Gateway 启动时 | 无参数 | 执行初始化逻辑 |
### 事件回调接口定义
```typescript
interface PluginInterface {
on: ((
event: "before_prompt_build",
callback: PromptBuildCallback
) => void) &
((
event: "before_agent_start",
callback: EventCallback
) => void) &
// ... 其他事件类型
((
event: "after_compaction",
callback: EventCallback
) => void);
}
```
资料来源：[openclaw/src/index.ts:15-27]()
## 观测记录捕获机制
### 工具使用观测
系统通过 `PostToolUse` 钩子捕获所有工具调用，包括文件读取、编辑、执行命令等操作。 资料来源：[cursor-hooks/README.md:1-20]()
```mermaid
sequenceDiagram
participant User as 用户
participant IDE as Claude Code
participant Hook as 钩子系统
participant Store as 观测存储
User->>IDE: 执行操作
IDE->>Hook: PostToolUse 事件
Hook->>Hook: 提取工具参数和输出
Hook->>Store: 保存观测记录
Store-->>Hook: 确认保存
Hook-->>IDE: 处理完成
```
### 文件编辑观测
针对文件修改操作，系统在 `afterFileEdit` 钩子中捕获变更详情，包括文件路径、修改内容和行号范围。 资料来源：[cursor-hooks/README.md:1-20]()
### Shell 命令观测
通过 `afterShellExecution` 钩子捕获命令行执行结果，记录命令内容、退出码和标准输出/错误。 资料来源：[cursor-hooks/README.md:1-20]()
## 会话摘要系统
### 摘要生成流程
```mermaid
graph LR
A[会话结束] --> B[收集观测记录]
B --> C[生成摘要请求]
C --> D[LLM 摘要生成]
D --> E[解析 XML 格式]
E --> F[存储摘要]
G[新会话开始] --> H[加载历史摘要]
H --> I[注入上下文]
```
### 摘要内容结构
摘要采用 XML 格式组织，包含以下关键字段： 资料来源：[src/sdk/prompts.ts:1-30]()
| 字段名称 | 类型 | 描述 |
|---------|------|------|
| `` | string | 用户原始请求 |
| `` | string | 调查分析过程 |
| `` | string | 学习到的内容 |
| `` | string | 完成的工作 |
| `` | string | 下一步计划 |
| `` | string | 备注信息 |
### 摘要格式模板
```xml
用户请求内容
调查分析过程
学习到的内容
完成的工作
下一步计划
备注信息
```
资料来源：[src/sdk/prompts.ts:1-30]()
## 多平台钩子配置
### Claude Code 钩子
Claude Code 通过插件系统注册钩子，主要配置文件位于 `plugin/hooks/hooks.json`。系统支持 `Stop` 钩子用于会话结束时的摘要生成。 资料来源：[cursor-hooks/README.md:1-20]()
### Cursor IDE 钩子
Cursor 通过 shell 脚本实现钩子功能，配置文件包括： 资料来源：[cursor-hooks/README.md:20-35]()
| 文件名称 | 功能描述 |
|---------|---------|
| `hooks.json` | 钩子配置定义 |
| `common.sh` | 共享工具函数 |
| `session-init.sh` | 会话初始化 |
| `context-inject.sh` | 上下文注入 |
| `save-observation.sh` | 观测记录保存 |
| `save-file-edit.sh` | 文件编辑观测 |
| `session-summary.sh` | 摘要生成 |
### OpenClaw Gateway 钩子
OpenClaw Gateway 采用 TypeScript 接口定义钩子，支持通过 `pluginConfig` 进行自定义配置，并通过 `registerService` 注册后台服务。 资料来源：[openclaw/src/index.ts:1-50]()
## 观测记录数据结构
### 观测记录模型
```typescript
interface Observation {
id: number; // 唯一标识符
eventType: string; // 事件类型
tool_name?: string; // 工具名称
tool_input?: string; // 工具输入
tool_output?: string; // 工具输出
sourceAdapter: string; // 来源适配器
occurredAtEpoch: number; // 发生时间戳
payload?: string; // 载荷数据
facts?: string[]; // 提取的事实
narrative?: string; // 叙述文本
concepts?: string[]; // 概念标签
files_read?: string[]; // 读取的文件
files_modified?: string[]; // 修改的文件
}
```
资料来源：[src/server/generation/providers/shared/prompt-builder.ts:1-30]()
### 代码块去重机制
系统内置代码块去重逻辑，避免重复记录相同的代码段： 资料来源：[src/services/smart-file-read/parser.ts:30-50]()
```mermaid
graph TD
A[遍历符号] --> B{是代码块?}
B -->|否| E[跳过]
B -->|是| C{范围已存在?}
C -->|否| F[添加到映射]
C -->|是| D{是匿名块?}
D -->|是| G[标记为重复]
D -->|否| H[替换现有块]
F --> E
G --> E
H --> E
```
## 上下文注入机制
### 上下文加载配置
用户可通过环境变量配置上下文加载行为： 资料来源：[src/ui/viewer/components/ContextSettingsModal.tsx:1-30]()
| 环境变量 | 默认值 | 说明 |
|---------|-------|------|
| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | 50 | 注入的观测记录数量（1-200） |
| `CLAUDE_MEM_CONTEXT_SESSIONS` | 50 | 加载的会话数量（1-50） |
### 提示词构建
上下文信息通过专门的提示词构建器注入到新会话中： 资料来源：[src/sdk/prompts.ts:30-60]()
```mermaid
graph TD
A[新会话开始] --> B[加载历史摘要]
B --> C[构建摘要上下文]
C --> D[注入 system_identity]
D --> E[添加 observer_role]
E --> F[注入 spatial_awareness]
F --> G[应用 recording_focus]
G --> H[生成完整提示词]
```
## 服务注册与生命周期
### 后台服务注册
OpenClaw Gateway 支持通过 `registerService` 注册后台服务，每个服务可以定义启动和停止逻辑： 资料来源：[openclaw/src/index.ts:1-15]()
```typescript
registerService({
id: string;
start: (ctx: PluginServiceContext) => void | Promise;
stop?: (ctx: PluginServiceContext) => void | Promise;
});
```
### 命令注册
插件可以注册自定义命令供用户在 IDE 中调用：
```typescript
registerCommand({
name: string; // 命令名称
description: string; // 命令描述
acceptsArgs?: boolean; // 是否接受参数
requireAuth?: boolean; // 是否需要认证
handler: (ctx: PluginCommandContext) => PluginCommandResult;
});
```
资料来源：[openclaw/src/index.ts:1-15]()
## 配置管理
### 钩子设置存储
钩子配置通过 `hook-settings.ts` 集中管理，支持运行时修改和持久化。 资料来源：[cursor-hooks/README.md:20-35]()
### 检测机制
系统提供 `detectClaudeCode()` 函数检测 Claude CLI 是否可用：
```typescript
export async function detectClaudeCode(): Promise {
// 检查 PATH 中是否存在 claude 命令
// 或检查 ~/.claude/plugins 目录
}
```
资料来源：[src/services/integrations/CursorHooksInstaller.ts:40-65]()
## 最佳实践
### 观测记录优化
1. **避免重复捕获**：利用代码块去重机制减少冗余数据
2. **控制观测数量**：通过 `CLAUDE_MEM_CONTEXT_OBSERVATIONS` 限制注入量
3. **定期清理**：配置自动清理策略，避免存储膨胀
### 性能考虑
1. **异步处理**：钩子回调应尽可能异步执行，避免阻塞主流程
2. **批量写入**：多个观测记录可批量写入存储
3. **延迟初始化**：非关键服务采用延迟加载策略
### 安全性
1. **数据隔离**：确保用户数据存储在隔离目录（如 `~/.claude-mem`）
2. **敏感信息过滤**：在 `tool_result_persist` 钩子中过滤敏感输出
3. **访问控制**：合理配置 `requireAuth` 参数
## 相关文档
- [主项目文档](https://docs.claude-mem.ai)
- [Cursor 钩子参考](../docs/context/cursor-hooks-reference.md)
- [架构概览](https://docs.claude-mem.ai/architecture/overview)
---
## MCP 集成
### 相关页面
相关主题：[搜索系统](#page-search-system), [Worker 服务](#page-worker-service)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server/mcp/tools.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/mcp/tools.ts)
- [src/server/mcp/register.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/mcp/register.ts)
- [src/server/mcp/resources.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/mcp/resources.ts)
- [src/server/mcp/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/mcp/prompts.ts)
- [src/servers/mcp-server.ts](https://github.com/thedotmack/claude-mem/blob/main/src/servers/mcp-server.ts)
# MCP 集成
## 概述
Claude-Mem 通过 Model Context Protocol (MCP) 实现与多种 AI Agent 平台的深度集成。MCP 作为连接 AI 助手与外部工具、资源的标准协议，使 claude-mem 能够作为统一的知识记忆层，为不同 IDE 环境（如 Claude Code、OpenClaw、OpenCode 等）提供跨会话的持久化上下文能力。
MCP 集成模块位于 `src/server/mcp/` 目录，包含工具注册、资源管理、提示词模板和 MCP 服务器核心实现等组件。资料来源：[src/servers/mcp-server.ts:1]()
## 架构设计
### 模块结构
MCP 集成系统由以下核心模块组成：
```mermaid
graph TD
A[MCP 客户端
Claude Code / OpenClaw / OpenCode] --> B[MCP 服务器
mcp-server.ts]
B --> C[tools.ts
工具定义]
B --> D[resources.ts
资源提供]
B --> E[prompts.ts
提示词模板]
B --> F[register.ts
注册与生命周期]
C --> G[记忆存储
SQLite + claude.md]
D --> G
```
### 核心职责
| 模块 | 职责 | 主要功能 |
|------|------|----------|
| `mcp-server.ts` | MCP 服务器入口 | 初始化传输层、注册处理器、启动服务 |
| `tools.ts` | 工具定义 | 定义并暴露 AI Agent 可调用的记忆操作工具 |
| `resources.ts` | 资源管理 | 提供记忆数据作为可读取的资源 |
| `prompts.ts` | 提示词模板 | 生成 MCP 上下文相关的提示词 |
| `register.ts` | 注册管理 | 管理工具和资源的注册、生命周期事件 |
## 工具系统 (tools.ts)
### 工具定义
MCP 工具系统允许 AI Agent 通过标准化接口查询和操作记忆数据。工具定义遵循 MCP 协议规范，每个工具包含：
- **名称 (name)**: 工具的唯一标识符
- **描述 (description)**: 工具用途说明，供 AI Agent 理解何时调用
- **输入模式 (inputSchema)**: 工具参数的 JSON Schema 定义
### 可用工具类型
典型的 MCP 工具包括：
1. **记忆查询工具**: 根据时间范围、项目或关键词检索历史观察记录
2. **摘要生成工具**: 请求生成特定会话的语义摘要
3. **上下文注入工具**: 将检索到的记忆注入到当前会话上下文
4. **项目状态工具**: 查询当前项目的已知信息和状态
资料来源：[src/server/mcp/tools.ts:1]()
## 资源系统 (resources.ts)
### 资源模型
MCP 资源系统将 claude-mem 的记忆数据以 URI 形式暴露给 AI Agent，支持按需读取：
```mermaid
graph LR
A[AI Agent] -->|请求资源 URI| B[MCP 服务器]
B --> C[resources.ts]
C --> D[SQLite 数据库]
C --> E[claude.md 文件]
```
### 资源 URI 格式
资源使用统一资源标识符进行寻址：
| 资源类型 | URI 格式 | 说明 |
|----------|----------|------|
| 观察记录 | `mem://observations/{project_id}` | 获取项目的所有观察 |
| 摘要列表 | `mem://summaries/{session_id}` | 获取会话摘要 |
| 项目元数据 | `mem://projects/{project_path}` | 获取项目配置信息 |
| 时间线 | `mem://timeline/{project_id}` | 获取活动时间线 |
### 资源缓存策略
资源系统实现了智能缓存机制，避免重复读取相同数据。缓存失效策略与记忆更新事件联动，确保数据一致性。
资料来源：[src/server/mcp/resources.ts:1]()
## 提示词集成 (prompts.ts)
### 提示词模板系统
MCP 提示词模块负责生成与记忆相关的上下文模板，帮助 AI Agent 理解如何与记忆系统交互：
- **系统级提示词**: 定义 AI Agent 对记忆系统的认知角色
- **查询提示词**: 生成结构化的记忆查询指令
- **响应格式提示词**: 指定记忆数据的返回格式规范
### 模板变量
提示词系统支持动态变量注入：
| 变量 | 来源 | 用途 |
|------|------|------|
| `{project_id}` | 当前会话 | 限定记忆范围 |
| `{session_id}` | 会话上下文 | 关联特定会话 |
| `{time_range}` | 查询参数 | 时间范围过滤 |
| `{user_query}` | 用户输入 | 自然语言查询意图 |
资料来源：[src/server/mcp/prompts.ts:1]()
## 注册与生命周期 (register.ts)
### 初始化流程
```mermaid
sequenceDiagram
participant Host as MCP Host
participant Server as MCP Server
participant Registry as register.ts
participant Store as 记忆存储
Host->>Server: 连接请求
Server->>Registry: 初始化注册
Registry->>Registry: 注册工具定义
Registry->>Registry: 注册资源提供器
Registry->>Registry: 订阅生命周期事件
Registry->>Store: 验证连接
Server-->>Host: 连接就绪
```
### 生命周期管理
注册模块负责管理以下生命周期事件：
1. **连接建立**: 验证客户端权限，初始化会话上下文
2. **工具调用**: 路由工具请求到对应的处理器
3. **资源订阅**: 管理资源变更通知
4. **连接断开**: 清理会话状态，持久化临时数据
### 错误处理
注册系统实现了健壮的错误处理机制：
- 工具调用超时自动重试
- 资源不可用时的优雅降级
- 连接异常时的自动重连策略
资料来源：[src/server/mcp/register.ts:1]()
## MCP 服务器核心 (mcp-server.ts)
### 服务器架构
MCP 服务器是整个集成系统的核心入口点，负责：
1. **传输层管理**: 处理 STDIO 或 HTTP 传输
2. **协议实现**: 遵循 MCP 规范进行消息编解码
3. **请求路由**: 将入站请求分发到对应模块
4. **响应序列化**: 将处理结果格式化为 MCP 协议格式
### 启动配置
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| 端口 | 3100 | MCP 服务器监听端口 |
| 传输方式 | stdio | 支持 stdio 和 HTTP |
| 超时 | 30s | 工具调用超时时间 |
| 日志级别 | info | 日志输出级别 |
### 与其他集成方式的对比
Claude-Mem 支持多种集成方式，MCP 是其中最标准化的方案：
| 集成方式 | 适用场景 | 特点 |
|----------|----------|------|
| MCP | 标准 AI Agent 平台 | 协议标准化、跨平台支持 |
| 插件系统 | Claude Code | 深度集成、实时观察 |
| npx CLI | 手动操作 | 灵活但不持久 |
| OpenClaw Gateway | 企业部署 | 托管服务、高可用 |
资料来源：[src/servers/mcp-server.ts:1]()
## 使用场景
### 跨会话上下文保持
当 AI Agent 在新会话中处理项目时，可以通过 MCP 接口获取历史会话中积累的项目知识：
1. Agent 连接 MCP 服务器
2. 通过资源接口获取项目历史
3. 工具调用检索相关观察记录
4. 上下文注入当前会话
### 主动记忆增强
通过 MCP 工具， AI Agent 可以在处理复杂任务时主动查询记忆库：
```
用户请求: 重构 authentication 模块
↓
Agent 调用 MCP 工具: search_observations(project, "auth")
↓
获取历史修改记录、设计决策
↓
生成重构方案时参考历史上下文
```
### 多 Agent 知识共享
在 OpenClaw 等多 Agent 环境中，MCP 服务器可作为共享记忆中枢：
- 多个 Agent 实例共享同一记忆存储
- 通过 MCP 资源接口实现跨 Agent 知识传递
- 保持团队协作的上下文连续性
## 配置与调试
### 环境变量
| 变量 | 说明 |
|------|------|
| `CLAUDE_MEM_MCP_PORT` | MCP 服务器端口 |
| `CLAUDE_MEM_MCP_TRANSPORT` | 传输方式 (stdio/http) |
| `CLAUDE_MEM_LOG_LEVEL` | 日志级别 |
### 状态检查
```bash
npx claude-mem status
```
该命令可验证 MCP 服务器运行状态和连接状态。
## 安全考虑
### 数据隔离
- 每个项目的记忆数据相互隔离
- MCP 连接使用项目路径作为会话标识
- 资源访问遵循最小权限原则
### 敏感信息处理
记忆系统会自动过滤敏感信息（如 API Key、环境变量值），确保只记录语义内容而非凭证数据。
## 相关文档
- [快速开始指南](../getting-started.md) - MCP 集成的入门配置
- [SDK 文档](../sdk/overview.md) - 编程接口参考
- [开发指南](https://docs.claude-mem.ai/development) - MCP 模块开发说明
---
## IDE 集成
### 相关页面
相关主题：[生命周期钩子系统](#page-hooks-system), [安装与部署](#page-installation)
相关源码文件
以下源码文件用于生成本页说明：
- [src/services/integrations/CursorHooksInstaller.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/integrations/CursorHooksInstaller.ts)
- [src/cli/adapters](https://github.com/thedotmack/claude-mem/blob/main/src/cli/adapters)
- [cursor-hooks](https://github.com/thedotmack/claude-mem/blob/main/cursor-hooks)
- [plugin/modes](https://github.com/thedotmack/claude-mem/blob/main/plugin/modes)
- [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)
# IDE 集成
claude-mem 通过统一的集成框架支持多种主流 IDE 和 CLI 环境，实现跨平台的情境记忆功能。本页详细说明各 IDE 的集成架构、安装机制和运行时行为。
## 支持的 IDE 环境
claude-mem 支持以下集成目标：
| IDE/CLI | 安装命令 | 检测方式 | 钩子类型 |
|---------|---------|---------|---------|
| Claude Code | `npx claude-mem install` | `~/.claude` 目录 | 插件钩子 |
| Cursor | `npx claude-mem install --ide cursor` | 平台检测 | Cursor Hooks |
| Gemini CLI | `npx claude-mem install --ide gemini-cli` | `~/.gemini` 目录 | MCP 钩子 |
| OpenCode | `npx claude-mem install --ide opencode` | `OPENCODE_DIR` 环境变量 | MCP 钩子 |
资料来源：[src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)
## 集成架构概览
```
┌─────────────────────────────────────────────────────────────┐
│ claude-mem │
├─────────────────────────────────────────────────────────────┤
│ CLI 适配层 (src/cli/adapters) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ ClaudeCode │ │ Cursor │ │ GeminiCLI │ │
│ │ Adapter │ │ Adapter │ │ Adapter │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
├─────────┴────────────────┴────────────────┴─────────────────┤
│ 集成服务层 (src/services/integrations) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ HookInstaller 抽象工厂 │ │
│ │ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ ClaudeHooks │ │ CursorHooks │ │ │
│ │ │ Installer │ │ Installer │ │ │
│ │ └────────────────┘ └────────────────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## CLI 适配层
适配层负责检测目标 IDE 环境并提供统一的安装接口。
### Claude Code 适配器
Claude Code 通过插件机制集成：
```bash
# 通过插件市场安装
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
# 或通过命令行安装
npx claude-mem install
```
资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)
### 检测机制
集成系统通过多层次检测确定 IDE 环境：
```typescript
export async function detectClaudeCode(): Promise {
// 1. 检测 CLI 命令是否在 PATH 中
try {
const { stdout } = await execAsync('which claude || where claude', { timeout: 5000 });
if (stdout.trim()) {
return true;
}
} catch (error) {
logger.debug('WORKER', 'Claude CLI not in PATH', {}, error);
}
// 2. 检测插件目录是否存在
const pluginDir = path.join(CLAUDE_CONFIG_DIR, 'plugins');
if (existsSync(pluginDir)) {
return true;
}
return false;
}
```
资料来源：[src/services/integrations/CursorHooksInstaller.ts:60-79](https://github.com/thedotmack/claude-mem/blob/main/src/services/integrations/CursorHooksInstaller.ts)
### Cursor 集成
Cursor IDE 支持通过 Cursor Hooks 机制注入记忆功能：
```bash
npx claude-mem install --ide cursor
```
集成流程包括：
1. 检测 Cursor 安装路径
2. 创建项目级规则目录
3. 生成 `claude-mem-context.mdc` 上下文文件
4. 注册会话钩子
## 钩子系统
### Claude Code 插件钩子
Claude Code 通过插件系统实现钩子注册，支持以下事件：
| 事件类型 | 触发时机 | 记忆行为 |
|---------|---------|---------|
| `onStartup` | 会话启动 | 注入历史观测记录 |
| `onUserInput` | 用户输入 | 实时生成观测 |
| `onToolResult` | 工具执行结果 | 记录操作上下文 |
| `onShutdown` | 会话结束 | 生成会话摘要 |
### Cursor Hooks
Cursor 的钩子系统位于 `cursor-hooks` 目录，提供项目级别的上下文注入：
```typescript
interface CursorHook {
name: string;
trigger: 'project' | 'session' | 'command';
handler: (context: HookContext) => void;
}
```
资料来源：[cursor-hooks](https://github.com/thedotmack/claude-mem/blob/main/cursor-hooks)
## 模式系统
claude-mem 支持通过模式（Mode）自定义集成行为，不同模式可配置不同的观测类型和提示模板。
### 内置模式
| 模式 | 用途 | 观测类型 |
|-----|------|---------|
| `code` | 代码开发 | read, write, execute |
| `analysis` | 代码分析 | inspect, query, summarize |
| `debug` | 调试会话 | error, breakpoint, variable |
| `review` | 代码审查 | change, comment, approve |
### 模式配置
模式定义位于 `plugin/modes` 目录，每个模式包含：
```
plugin/modes/
├── code/
│ ├── config.json # 模式配置
│ ├── prompts.ts # 提示模板
│ └── observation-types.ts # 观测类型定义
└── ...
```
资料来源：[plugin/modes](https://github.com/thedotmack/claude-mem/blob/main/plugin/modes)
## 安装流程
### 统一安装命令
```bash
npx claude-mem install [options]
```
| 选项 | 说明 | 默认值 |
|-----|------|-------|
| `--ide ` | 目标 IDE | auto-detect |
| `--global` | 全局安装 | true |
| `--project ` | 项目路径 | 当前目录 |
| `--force` | 强制覆盖 | false |
### 安装状态检测
安装完成后，系统会执行状态检测：
```typescript
// 检测 worker 服务是否就绪
workerAlive
? 显示成功消息 + 访问 URL
: 显示等待提示 + 手动启动命令
```
资料来源：[src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)
## 运行时交互
### 首次使用流程
```
┌─────────────────────────────────────────────────────────────┐
│ 1. 用户首次启动 IDE │
├─────────────────────────────────────────────────────────────┤
│ 2. 插件检测到新会话 │
├─────────────────────────────────────────────────────────────┤
│ 3. 加载历史观测记录 (最近 50 条) │
├─────────────────────────────────────────────────────────────┤
│ 4. 显示欢迎提示卡片 │
├─────────────────────────────────────────────────────────────┤
│ 5. 用户开始交互，实时生成新观测 │
└─────────────────────────────────────────────────────────────┘
```
### 记忆注入机制
```mermaid
graph TD
A[用户会话开始] --> B{检测历史观测}
B -->|有记录| C[加载最近 N 条观测]
B -->|无记录| D[显示欢迎卡片]
C --> E[注入到上下文]
E --> F[用户交互]
F --> G[实时生成观测]
G --> H[存储到本地数据库]
H --> F
D --> F
I[会话结束] --> J[生成摘要]
J --> H
```
## 平台兼容性
### macOS / Linux
- 支持 Claude Code、Cursor、Gemini CLI、OpenCode
- 钩子安装到用户目录 `~/.claude-mem`
- 使用 Unix socket 通信
### Windows
| 组件 | 状态 | 说明 |
|-----|------|-----|
| Claude Code | ✅ 支持 | PowerShell 兼容 |
| Cursor | ⚠️ 部分支持 | Hook 安装受限 |
| Gemini CLI | ✅ 支持 | WSL 环境下测试 |
| OpenCode | ⚠️ 部分支持 | 路径格式转换 |
## 故障排除
### 常见问题
1. **IDE 未检测到**
检查 CLI 命令是否在 PATH 中：
```bash
which claude # Claude Code
which cursor # Cursor
```
2. **钩子未生效**
重启 IDE 会话，或手动触发：
```bash
npx claude-mem install --force
```
3. **记忆未注入**
检查 worker 服务状态：
```bash
npx claude-mem status
```
### 诊断命令
```bash
# 检测已安装的钩子
npx claude-mem cursor status
# 重新安装
npx claude-mem install --force
# 查看日志
tail -f ~/.claude-mem/logs/*.log
```
## 相关文档
- [快速开始指南](https://docs.claude-mem.ai/getting-started)
- [故障排除](https://docs.claude-mem.ai/troubleshooting)
- [开发指南](https://docs.claude-mem.ai/development)
---
## 安装与部署
### 相关页面
相关主题：[IDE 集成](#page-ide-integrations)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)
- [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)
- [src/ui/viewer/components/ContextSettingsModal.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ContextSettingsModal.tsx)
- [scripts/translate-readme/README.md](https://github.com/thedotmack/claude-mem/blob/main/scripts/translate-readme/README.md)
# 安装与部署
## 概述
Claude-Mem 提供多种安装方式，支持在不同集成环境中部署本插件。安装过程会自动配置后台运行服务（Worker）、数据存储目录以及与 Claude Code 的集成钩子。
## 安装方式
Claude-Mem 支持以下几种安装途径：
### 1. NPX 一键安装（推荐）
通过 npx 命令直接安装，这是最简单的方式：
```bash
npx claude-mem install
```
安装完成后，系统会显示欢迎提示，包含以下信息：
- Worker 服务状态（启动中或已就绪）
- 访问本地查看器的 URL
- 后续操作指引
资料来源：[README.md:1-30]()
### 2. Claude Code 插件市场安装
对于 Claude Code 用户，可以通过内置的 `/plugin` 命令安装：
```bash
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
```
安装完成后需要重启 Claude Code。
资料来源：[README.md:30-35]()
### 3. Gemini CLI 安装
针对 Gemini CLI 用户，可以指定 `--ide` 参数：
```bash
npx claude-mem install --ide gemini-cli
```
该命令会自动检测 `~/.gemini` 目录并完成配置。
资料来源：[README.md:18-22]()
### 4. OpenCode 安装
针对 OpenCode 编辑器用户：
```bash
npx claude-mem install --ide opencode
```
资料来源：[README.md:25-28]()
### 5. OpenClaw Gateway 安装
在 OpenClaw 网关上安装持久化内存插件：
```bash
curl -fsSL https://install.cmem.ai/openclaw.sh | bash
```
资料来源：[README.md:45-50]()
## 安装流程架构
```mermaid
graph TD
A[用户执行安装命令] --> B{安装方式}
B -->|npx claude-mem install| C[初始化配置文件]
B -->|/plugin install| D[检测 Claude Code 环境]
B -->|OpenClaw| E[下载安装脚本]
C --> F[启动 Worker 服务]
D --> F
E --> G[配置 Gateway]
F --> H[创建 ~/.claude-mem 目录]
H --> I[注册集成钩子]
I --> J[安装完成，显示提示]
J --> K[首次启动建议]
K --> L["方式A: 直接开始工作"]
K --> M["方式B: 运行 /learn-codebase"]
```
## Worker 服务配置
### 默认配置
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| 端口 | 18789 | Worker 服务监听端口 |
| 数据目录 | `~/.claude-mem` | 存储观察记录和配置 |
| 自动启动 | 启用 | 系统启动时自动运行 |
### 启动状态检测
安装完成后，系统会检查 Worker 服务状态：
```typescript
workerAlive
? [workerHeadline, firstSuccessMessage, twoPathsMessage]
: [waitMessage, manualStartHint]
```
资料来源：[src/npx-cli/commands/install.ts:10-30]()
### 手动启动
如果 Worker 未自动启动，可手动启动：
```bash
npx claude-mem start
```
## 环境变量配置
### 安装后提示控制
首次安装后，系统会显示欢迎提示。可通过环境变量禁用：
```bash
CLAUDE_MEM_WELCOME_HINT_ENABLED=false
```
资料来源：[src/npx-cli/commands/install.ts:20-25]()
### 查看器配置
通过 `ContextSettingsModal.tsx` 可以配置以下参数：
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | 50 | 注入上下文的观察数量 (1-200) |
| `CLAUDE_MEM_CONTEXT_SESSIONS` | - | 拉取观察的会话数量 (1-50) |
资料来源：[src/ui/viewer/components/ContextSettingsModal.tsx:40-60]()
## 卸载说明
卸载前需要关闭所有 Claude Code 会话，否则活动钩子会重新创建配置目录：
```bash
npx claude-mem uninstall
```
> **注意**：关闭所有 Claude Code 会话后再执行卸载，否则 `~/.claude-mem` 目录会被重新创建。
资料来源：[src/npx-cli/commands/install.ts:15-18]()
## 快速验证安装
安装完成后按以下步骤验证：
1. 启动 Claude Code
2. 确认控制台无错误信息
3. 在新项目中输入测试提示
4. 第二次会话时应能看到历史上下文注入
## 安装方式对比
| 安装方式 | 适用环境 | 是否需要重启 | 自动化程度 |
|----------|----------|--------------|------------|
| `npx claude-mem install` | 通用 | 是 | 高 |
| `/plugin` 命令 | Claude Code | 是 | 高 |
| OpenClaw 脚本 | OpenClaw Gateway | 是 | 高 |
| 源码编译 | 开发/自定义 | 是 | 低 |
## 常见问题
### Q: npm install -g claude-mem 是否可行？
**不行**。通过 `npm install -g` 安装的是 SDK/库版本，不会注册插件钩子或设置 Worker 服务。必须使用 `npx claude-mem install` 或 `/plugin` 命令安装。
资料来源：[README.md:36-40]()
### Q: 如何检查服务状态？
```bash
npx claude-mem status
```
### Q: Worker 启动后显示等待状态怎么办？
这是正常现象，Worker 启动需要约 30 秒。等待完成后刷新浏览器即可。
资料来源：[src/npx-cli/commands/install.ts:35-40]()
## 后续步骤
安装完成后，推荐以下两种初始化方式：
**方式 A（推荐）**：直接开始工作，记忆会从第一次提示中被动构建。
**方式 B**：运行 `/learn-codebase` 命令预加载整个代码仓库（约 5 分钟，可选）。
资料来源：[src/npx-cli/commands/install.ts:22-28]()
## 相关文档
- [使用指南](./使用指南.md)
- [配置选项](./配置选项.md)
- [故障排除](./故障排除.md)
---
---
## Doramagic 踩坑日志
项目：thedotmack/claude-mem
摘要：发现 24 个潜在踩坑项，其中 8 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories。
## 1. 安装坑 · 来源证据：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_28646536cf7d499aadab2346c2666f89 | https://github.com/thedotmack/claude-mem/issues/2389 | 来源类型 github_issue 暴露的待验证使用条件。
## 2. 安装坑 · 来源证据：Windows: cmd.exe /c uvx wrapper breaks Chroma MCP stdio on WinGet uv installs (regression after #1190 / #1199) --> FIX…
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows: cmd.exe /c uvx wrapper breaks Chroma MCP stdio on WinGet uv installs (regression after #1190 / #1199) --> FIX attacched
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a6c844000d9b4adead4a2fdb73660c8d | https://github.com/thedotmack/claude-mem/issues/2426 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：[Bug] 13.x worker fails with "Cannot find module 'zod/v3'" — package-lock.json missing zod entry
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] 13.x worker fails with "Cannot find module 'zod/v3'" — package-lock.json missing zod entry
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9e74ac48a1744106a07ff519ad2d2773 | https://github.com/thedotmack/claude-mem/issues/2437 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 4. 安装坑 · 来源证据：v13: merged_into_project migration silently skipped on pre-existing DBs (schema_versions ≤ 23)
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13: merged_into_project migration silently skipped on pre-existing DBs (schema_versions ≤ 23)
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_510ecb03a1de412f940987e370c68fac | https://github.com/thedotmack/claude-mem/issues/2433 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。
## 5. 配置坑 · 来源证据：Use node to run mcp for windows environment
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Use node to run mcp for windows environment
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_95d37c5d34a749f7a25fdd5fe1dc7969 | https://github.com/thedotmack/claude-mem/issues/2446 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 6. 配置坑 · 来源证据：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_77fdc7c371f042eeb70fbeb52a7a2788 | https://github.com/thedotmack/claude-mem/issues/2438 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 7. 运行坑 · 来源证据：自动运行时突然报下图所示内容，然后插件就不能用了
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：自动运行时突然报下图所示内容，然后插件就不能用了
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2d5aa43a4c5a4e46a0f2122dea46947a | https://github.com/thedotmack/claude-mem/issues/2441 | 来源类型 github_issue 暴露的待验证使用条件。
## 8. 安全/权限坑 · 来源证据：[Bug] Codex CLI plugin hooks consume Claude Code session quota via Claude Code SDK
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] Codex CLI plugin hooks consume Claude Code session quota via Claude Code SDK
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8b77cb6420d845a9bd38852571b6adbd | https://github.com/thedotmack/claude-mem/issues/2431 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。
## 9. 安装坑 · 来源证据：Codex CLI: PreToolUse hook returned unsupported suppressOutput
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex CLI: PreToolUse hook returned unsupported suppressOutput
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9022a732f6e54ba39309c5377cf2d8fa | https://github.com/thedotmack/claude-mem/issues/2360 | 来源类型 github_issue 暴露的待验证使用条件。
## 10. 安装坑 · 来源证据：[feat] Option to load only memory-related skills
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[feat] Option to load only memory-related skills
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_efa30fc4873343aea26f804c8d1113ec | https://github.com/thedotmack/claude-mem/issues/2448 | 来源类型 github_issue 暴露的待验证使用条件。
## 11. 安装坑 · 来源证据：server-beta: ModeManager not initialized — generation jobs fail with 'No mode loaded'
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：server-beta: ModeManager not initialized — generation jobs fail with 'No mode loaded'
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_757115889024465dbafb2f4ffcbe8356 | https://github.com/thedotmack/claude-mem/issues/2443 | 来源类型 github_issue 暴露的待验证使用条件。
## 12. 安装坑 · 来源证据：v12.1.1: hooks/hooks.json references removed scripts/worker-service.cjs — all hooks fail with "Module not found"
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v12.1.1: hooks/hooks.json references removed scripts/worker-service.cjs — all hooks fail with "Module not found"
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0e29da4de6004faea2de867f758794f8 | https://github.com/thedotmack/claude-mem/issues/1835 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 13. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | host_targets=claude, claude_code
## 14. 配置坑 · 来源证据：server-beta: runServerBetaCli() default command exits immediately — unusable with systemd
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：server-beta: runServerBetaCli() default command exits immediately — unusable with systemd
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2613a65b36064bfeb5bbaf9fed69672d | https://github.com/thedotmack/claude-mem/issues/2444 | 来源类型 github_issue 暴露的待验证使用条件。
## 15. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | README/documentation is current enough for a first validation pass.
## 16. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | last_activity_observed missing
## 17. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | no_demo; severity=medium
## 18. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | No sandbox install has been executed yet; downstream must verify before user use.
## 19. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | no_demo; severity=medium
## 20. 安全/权限坑 · 来源证据：Daemon survives plugin disable, burns 500M+ tokens/week with no observable user-facing benefit
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Daemon survives plugin disable, burns 500M+ tokens/week with no observable user-facing benefit
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a4e91994a3834fc4a64f07b31ce17242 | https://github.com/thedotmack/claude-mem/issues/2451 | 来源类型 github_issue 暴露的待验证使用条件。
## 21. 安全/权限坑 · 来源证据：Long-running Worker endpoints share health-check timeout (HEALTH_TIMEOUT_MS); should use per-endpoint timeouts
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Long-running Worker endpoints share health-check timeout (HEALTH_TIMEOUT_MS); should use per-endpoint timeouts
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8b61a79c5ae144fcbd7cb8737397dbee | https://github.com/thedotmack/claude-mem/issues/2447 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。
## 22. 安全/权限坑 · 来源证据：claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c23b4f1758454233a20f5c0653d69d51 | https://github.com/thedotmack/claude-mem/issues/2450 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 23. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | issue_or_pr_quality=unknown
## 24. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | release_recency=unknown