\n {concepts.map((concept: string, i: number) => (\n {concept}\n ))}\n {filesRead.length > 0 && (\n \n read: {filesRead.join(', ')}\n \n )}\n
\n)}\n```\n\n## 会话摘要（Summary）\n\nSummary 是对整个会话的总结性描述。\n\n### 摘要结构\n\n```xml\n\n 
\n
\n {section.label}
\n\n {section.content}\n
\n \n))}\n```\n\n## 上下文编译（Context Compilation）\n\nContext Compiler 负责将存储的记忆转换为可注入到 Claude 会话的格式。\n\n### 编译流程\n\n```mermaid\ngraph LR\n A[Memory Storage] --> B[Query & Filter]\n B --> C[ObservationCompiler]\n C --> D[Format as XML]\n D --> E[Inject to Session]\n```\n\n### 上下文配置\n\n用户可以通过环境变量配置上下文注入行为：\n\n| 配置项 | 默认值 | 说明 | 资料来源 |\n|--------|--------|------|----------|\n| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | 50 | 注入的观察记录数量（1-200） | src/ui/viewer/components/ContextSettingsModal.tsx |\n| `CLAUDE_MEM_CONTEXT_SESSIONS` | 10 | 提取观察的会话数量（1-50） | src/ui/viewer/components/ContextSettingsModal.tsx |\n\n### 提示词构建\n\nSDK 使用结构化的提示词模板生成记忆：\n\n```typescript\n// 资料来源：src/sdk/prompts.ts\n${mode.prompts.output_format_header}\n\n\n
\n\n# 系统架构\n\n## 概述\n\nClaude-Mem 是一个为 Claude Code 提供持久化记忆功能的插件系统，其核心目标是实现跨会话的上下文连续性。该系统通过自动捕获工具使用观察、生成语义摘要，使 Claude 能够在会话结束后或重新连接时保持对项目的知识连续性。 资料来源：[README.md:1-10]()\n\n系统架构采用插件化设计，支持多种 IDE 环境集成，包括 Claude Code、Gemini CLI 和 OpenCode。数据存储在本地文件系统（`~/.claude-mem`），确保用户对数据的完全控制。 资料来源：[README.md:28-35]()\n\n## 核心组件架构\n\nClaude-Mem 的系统架构由以下核心层次组成：\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n IDE[IDE 插件集成]\n CLI[NPX CLI 工具]\n end\n \n subgraph \"服务层\"\n Worker[Worker Service]\n Server[Server 服务]\n PromptBuilder[Prompt Builder]\n end\n \n subgraph \"SDK 层\"\n PromptSDK[Prompts SDK]\n ObservationSDK[Observation SDK]\n end\n \n subgraph \"UI 层\"\n ViewerApp[Viewer 应用]\n SummaryCard[摘要卡片]\n ObservationCard[观察卡片]\n SettingsModal[设置模态框]\n end\n \n subgraph \"数据层\"\n Storage[本地存储 ~/.claude-mem]\n SessionData[会话数据]\n ObservationData[观察数据]\n end\n \n IDE --> Worker\n CLI --> Worker\n Worker --> Server\n Server --> PromptBuilder\n Server --> Storage\n PromptBuilder --> PromptSDK\n ViewerApp --> Server\n ViewerApp --> SettingsModal\n```\n\n### 组件职责矩阵\n\n| 组件 | 类型 | 主要职责 | 源码位置 |\n|------|------|----------|----------|\n| Worker Service | 服务进程 | 管理观察数据收集和处理的生命周期 | `src/services/worker-service.ts` |\n| Server | HTTP 服务 | 提供 REST API，处理记忆注入请求 | `src/services/server/Server.ts` |\n| Prompt Builder | 生成器 | 构建 LLM 提示词和输出模式 | `src/server/generation/providers/shared/prompt-builder.ts` |\n| Prompts SDK | SDK 模块 | 封装提示词构建逻辑 | `src/sdk/prompts.ts` |\n| Viewer App | React 应用 | 提供记忆查看器 UI | `src/ui/viewer/App.tsx` |\n\n## 数据流架构\n\n### 观察数据生命周期\n\n```mermaid\ngraph LR\n A[工具调用] --> B[观察捕获]\n B --> C[输入解析]\n C --> D[Prompt 构建]\n D --> E[LLM 处理]\n E --> F[结构化输出]\n F --> G[存储]\n G --> H[摘要生成]\n H --> I[上下文注入]\n```\n\n1. **观察捕获阶段**：系统监听 Claude Code 的工具调用事件，自动捕获工具输入和输出 资料来源：[src/server/generation/providers/shared/prompt-builder.ts:1-30]()\n2. **数据解析阶段**：对捕获的工具调用进行解析，提取关键信息并处理私有数据边界 资料来源：[src/server/generation/providers/shared/prompt-builder.ts:40-60]()\n3. **Prompt 构建阶段**：根据活动模式（Mode）配置构建符合 XML 格式的观察输出 资料来源：[src/sdk/prompts.ts:1-50]()\n4. **LLM 处理阶段**：使用配置的 LLM 模型生成语义化的观察摘要\n5. **存储阶段**：将处理后的数据持久化到本地存储\n6. **上下文注入阶段**：在新的会话中自动注入相关记忆\n\n### 上下文注入流程\n\n```mermaid\ngraph TD\n A[新会话开始] --> B{检查记忆缓存}\n B -->|首次会话| C[不注入历史]\n B -->|非首次会话| D[查询历史观察]\n D --> E[加载最近 N 条观察]\n D --> F[加载最近 M 个会话]\n E --> G[构建上下文 Prompt]\n F --> G\n G --> H[注入到系统提示]\n H --> I[开始新会话]\n \n C --> I\n```\n\n上下文注入可通过环境变量进行配置： 资料来源：[src/ui/viewer/components/ContextSettingsModal.tsx:30-60]()\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | 50 | 注入的观察数量（1-200） |\n| `CLAUDE_MEM_CONTEXT_SESSIONS` | 10 | 抽取观察的会话数量（1-50） |\n\n## 提示词生成架构\n\n### Prompt SDK 结构\n\n提示词生成采用模块化设计，支持多种模式配置： 资料来源：[src/sdk/prompts.ts:50-100]()\n\n```typescript\ninterface ModeConfig {\n prompts: {\n continuation_instruction: string;\n output_format_header: string;\n xml_title_placeholder: string;\n xml_subtitle_placeholder: string;\n xml_fact_placeholder: string;\n xml_narrative_placeholder: string;\n xml_concept_placeholder: string;\n xml_file_placeholder: string;\n type_guidance: string;\n field_guidance: string;\n concept_guidance: string;\n format_examples: string;\n footer: string;\n };\n observation_types: ObservationType[];\n}\n```\n\n### 输出模式构建\n\n观察输出采用 XML 格式，包含以下结构化字段： 资料来源：[src/server/generation/providers/shared/prompt-builder.ts:70-90]()\n\n```xml\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n- [src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)\n- [src/ui/viewer/App.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/App.tsx)\n- [src/ui/viewer/components/SummaryCard.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/SummaryCard.tsx)\n- [src/ui/viewer/components/ObservationCard.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ObservationCard.tsx)\n- [src/server/generation/providers/shared/prompt-builder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/providers/shared/prompt-builder.ts)\n- [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n- [src/ui/viewer/components/ContextSettingsModal.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ContextSettingsModal.tsx)\n\n
\n\n# Worker 服务\n\n## 概述\n\nWorker 服务是 claude-mem 系统中的核心后台处理组件，负责执行长期运行的任务队列、处理观察记录生成、以及管理会话上下文。该服务以独立进程方式运行，通过 BullMQ 与 Redis 进行进程间通信，实现高可靠性的任务处理能力。Worker 服务默认监听端口 37777，提供健康检查和状态监控接口。\n\nWorker 服务的核心职责包括：\n\n- 接收并处理来自主服务的任务队列请求\n- 管理会话的上下文信息和历史记录\n- 执行 LLM 响应处理和格式转换\n- 维护任务执行状态和进度通知\n- 处理失败任务的重试逻辑\n\n资料来源：[src/npx-cli/commands/install.ts:1-100]()\n\n## 核心组件\n\nWorker 服务由多个协同工作的子模块组成，每个模块承担特定的职责。\n\n### 组件架构表\n\n| 组件名称 | 文件路径 | 职责描述 |\n|---------|---------|---------|\n| SessionManager | `src/services/worker/SessionManager.ts` | 管理会话生命周期、上下文存储与检索 |\n| FormattingService | `src/services/worker/FormattingService.ts` | 处理观察记录的格式化和输出 |\n| ResponseProcessor | `src/services/worker/agents/ResponseProcessor.ts` | 处理 LLM 响应、提取结构化数据 |\n| HTTP Routes | `src/services/worker/http/routes` | 提供 RESTful API 接口 |\n| ServerJobQueue | `src/server/jobs/ServerJobQueue.ts` | 任务队列管理与 BullMQ 集成 |\n\n资料来源：[src/services/worker/SessionManager.ts](), [src/services/worker/FormattingService.ts](), [src/services/worker/agents/ResponseProcessor.ts]()\n\n## 任务队列架构\n\nWorker 服务基于 BullMQ 构建企业级任务队列系统，支持分布式处理和跨进程事件通知。\n\n### 队列工作流程\n\n```mermaid\ngraph TD\n A[主服务提交任务] --> B[ServerJobQueue 入队]\n B --> C[Redis 队列存储]\n C --> D[Worker 进程轮询]\n D --> E{任务类型判断}\n E -->|生成任务| F[Generation Worker]\n E -->|处理任务| G[Processing Worker]\n F --> H[LLM 调用]\n G --> I[数据处理]\n H --> J[ResponseProcessor]\n I --> J\n J --> K[格式化输出]\n K --> L[结果存储]\n L --> M[QueueEvents 通知]\n```\n\n### 事件处理机制\n\nWorker 服务通过 QueueEvents 订阅 Redis 发布/订阅通道，实现跨进程的可靠事件通知。\n\n主要事件类型：\n\n- **stalled**: 任务停滞检测，由 Worker 或 QueueEvents 触发\n- **progress**: 任务进度更新\n- **error**: 任务执行错误\n- **failed**: 任务最终失败\n\n```mermaid\ngraph LR\n A[Worker 进程] -->|w.on| B[stalled 事件]\n A -->|w.on| C[progress 事件]\n A -->|w.on| D[error 事件]\n A -->|w.on| E[failed 事件]\n F[QueueEvents] -->|events.on| G[跨进程 stalled 通知]\n G --> H[notifyStalled]\n```\n\n资料来源：[src/server/jobs/ServerJobQueue.ts:50-80]()\n\n### 任务重试策略\n\nWorker 实现智能重试机制，在任务失败时根据配置自动重试：\n\n```typescript\n// 伪代码示例，实际逻辑在 ServerJobQueue 中实现\n{\n attempts: 3, // 最大重试次数\n backoff: {\n type: 'exponential', // 指数退避\n delay: 2000 // 基础延迟 2 秒\n }\n}\n```\n\n## 配置与端口\n\n### 默认配置参数\n\n| 参数名 | 默认值 | 说明 |\n|-------|-------|------|\n| `CLAUDE_MEM_WORKER_PORT` | 37777 | Worker 服务监听端口 |\n| 队列前缀 | `cmem` | BullMQ 键名前缀 |\n| 最大并发 | 可配置 | 同时处理的任务数上限 |\n\n### 健康检查流程\n\nWorker 服务启动后通过端口 37777 提供健康检查端点：\n\n```mermaid\nsequenceDiagram\n participant CLI as Claude-Mem CLI\n participant Worker as Worker Service\n participant Redis as Redis\n \n CLI->>Worker: 检查端口 37777 连接\n alt 端口可达\n Worker-->>CLI: Worker 就绪\n CLI->>Worker: 启动完成提示\n else 端口不可达\n Worker-->>CLI: 仍在启动中\n CLI->>User: 提示等待 30 秒后重试\n end\n```\n\n资料来源：[src/npx-cli/commands/install.ts:20-60]()\n\n## 状态监控\n\n### 队列深度监控\n\nWorker 服务的 Header 组件持续监控队列状态，当存在待处理任务时显示队列气泡指示器：\n\n```tsx\n// 队列气泡显示逻辑\n{queueDepth > 0 && (\n 相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/jobs/ServerJobQueue.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/jobs/ServerJobQueue.ts)\n- [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n- [src/services/worker-service.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts)\n- [src/services/worker/SessionManager.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/SessionManager.ts)\n- [src/services/worker/FormattingService.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/FormattingService.ts)\n- [src/services/worker/agents/ResponseProcessor.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/agents/ResponseProcessor.ts)\n- [src/services/worker/http/routes](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/http/routes)\n\n {queueDepth}\n
\n)}\n```\n\n### 错误边界处理\n\nWorker 服务的 UI 组件实现了 ErrorBoundary 错误边界机制，确保单个组件错误不会导致整个界面崩溃：\n\n```tsx\nclass ErrorBoundary extends Component {\n state = { error: null, errorInfo: null };\n \n componentDidCatch(error, errorInfo) {\n this.setState({ error, errorInfo });\n }\n \n render() {\n if (this.state.error) {\n return \n
\n\n# 数据存储层\n\n## 概述\n\nclaude-mem 的数据存储层是整个记忆系统的核心基础设施，负责持久化会话数据、观察记录和语义向量。该层采用混合存储架构，结合 SQLite 的事务性数据存储和 Chroma 向量数据库的语义搜索能力，实现高效的数据读写和智能检索功能。\n\n数据存储层的主要职责包括：\n\n- **会话管理**：创建、更新和查询 Claude Code 会话记录\n- **观察持久化**：存储 AI 生成的观察条目（observations）\n- **语义同步**：将数据同步到向量数据库支持语义搜索\n- **上下文注入**：为新会话提供历史记忆上下文\n\n资料来源：[src/services/sqlite/Database.ts:1-50]()\n\n## 架构设计\n\n### 存储层组件\n\n数据存储层由以下核心组件构成：\n\n```mermaid\ngraph TD\n A[claude-mem SDK] --> B[SQLite 数据库]\n A --> C[Chroma 向量库]\n B --> D[sessions 表]\n B --> E[observations 表]\n B --> F[prompts 表]\n B --> G[summaries 表]\n C --> H[向量嵌入]\n E --> C\n I[Worker Service] --> B\n I --> C\n```\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| Database | `src/services/sqlite/Database.ts` | 数据库连接管理和初始化 |\n| Sessions | `src/services/sqlite/Sessions.ts` | 会话记录的 CRUD 操作 |\n| Observations | `src/services/sqlite/Observations.ts` | 观察数据的持久化 |\n| ChromaSync | `src/services/sync/ChromaSync.ts` | 与向量数据库的同步 |\n\n资料来源：[src/services/sqlite/schema.sql:1-20]()\n\n### 数据模型\n\n#### Sessions 表\n\n会话表存储每次 Claude Code 交互会话的元数据：\n\n```sql\nCREATE TABLE sessions (\n id TEXT PRIMARY KEY,\n project TEXT NOT NULL,\n server_session_id TEXT,\n created_at_epoch INTEGER NOT NULL,\n updated_at_epoch INTEGER NOT NULL,\n summary_id TEXT,\n mode TEXT,\n event_count INTEGER DEFAULT 0\n);\n```\n\n关键字段说明：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | TEXT | 会话唯一标识符 |\n| project | TEXT | 所属项目名称 |\n| server_session_id | TEXT | 服务端会话 ID |\n| created_at_epoch | INTEGER | 创建时间戳 |\n| updated_at_epoch | INTEGER | 最后更新时间戳 |\n| summary_id | TEXT | 关联的摘要记录 |\n| mode | TEXT | 当前模式配置 |\n| event_count | INTEGER | 事件计数 |\n\n资料来源：[src/services/sqlite/schema.sql:1-10]()\n\n#### Observations 表\n\n观察表是核心数据存储，记录 AI 生成的结构化观察：\n\n```sql\nCREATE TABLE observations (\n id TEXT PRIMARY KEY,\n session_id TEXT NOT NULL,\n project TEXT NOT NULL,\n type TEXT NOT NULL,\n title TEXT,\n subtitle TEXT,\n narrative TEXT,\n facts TEXT, -- JSON array\n concepts TEXT, -- JSON array\n files_read TEXT, -- JSON array\n files_modified TEXT, -- JSON array\n tool_name TEXT,\n tool_input TEXT,\n tool_output TEXT,\n occurred_at_epoch INTEGER NOT NULL,\n created_at_epoch INTEGER NOT NULL,\n is_summary_related INTEGER DEFAULT 0,\n FOREIGN KEY (session_id) REFERENCES sessions(id)\n);\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | TEXT | 观察记录唯一标识 |\n| session_id | TEXT | 所属会话 ID |\n| type | TEXT | 观察类型（如 code_analysis, bug_fix） |\n| title | TEXT | 观察标题 |\n| facts | TEXT | JSON 格式的事实列表 |\n| concepts | TEXT | JSON 格式的概念标签 |\n| files_read | TEXT | JSON 格式的读取文件列表 |\n| files_modified | TEXT | JSON 格式的修改文件列表 |\n| narrative | TEXT | 叙述性描述 |\n| tool_name | TEXT | 关联的工具名称 |\n| tool_input | TEXT | 工具输入（JSON 或文本） |\n| tool_output | TEXT | 工具输出（JSON 或文本） |\n\n资料来源：[src/services/sqlite/schema.sql:11-35]()\n\n## 核心模块详解\n\n### Database 模块\n\n`Database.ts` 是存储层的入口点，负责：\n\n- 建立 SQLite 数据库连接\n- 执行 schema 初始化\n- 提供事务支持\n- 管理数据库路径配置\n\n```typescript\n// 典型初始化流程\nconst db = new Database(appDataPath);\nawait db.initialize();\n```\n\n资料来源：[src/services/sqlite/Database.ts:1-30]()\n\n### Sessions 模块\n\n`Sessions.ts` 实现会话管理的核心逻辑：\n\n| 方法 | 功能 |\n|------|------|\n| createSession | 创建新会话记录 |\n| updateSession | 更新会话状态 |\n| getSession | 根据 ID 获取会话 |\n| listSessions | 列出项目的所有会话 |\n| deleteSession | 删除会话及关联数据 |\n\n会话查询支持按项目名称、时间范围和模式类型过滤。\n\n资料来源：[src/services/sqlite/Sessions.ts:1-50]()\n\n### Observations 模块\n\n`Observations.ts` 处理观察数据的读写操作：\n\n```mermaid\ngraph LR\n A[工具调用事件] --> B[ObservationParser]\n B --> C[存储到SQLite]\n C --> D[ChromaSync]\n D --> E[生成向量嵌入]\n E --> F[Chroma向量库]\n```\n\n关键功能包括：\n\n- 将工具输入/输出解析为结构化观察\n- 支持批量插入和分页查询\n- 维护观察与会话、摘要的关联关系\n\n资料来源：[src/services/sqlite/Observations.ts:1-60]()\n\n## 向量同步机制\n\n### ChromaSync 模块\n\n`ChromaSync.ts` 负责将 SQLite 中的观察数据同步到 Chroma 向量数据库：\n\n```mermaid\ngraph TD\n A[SQLite observations] --> B[ChromaSync]\n B --> C{同步状态检查}\n C -->|已同步| D[跳过]\n C -->|需同步| E[提取文本内容]\n E --> F[调用Embedding API]\n F --> G[生成向量]\n G --> H[存储到Chroma]\n H --> I[更新同步标记]\n```\n\n同步策略包括：\n\n- **增量同步**：仅同步新增或更新的记录\n- **批量处理**：分批处理大量数据避免内存溢出\n- **错误重试**：失败时自动重试机制\n\n资料来源：[src/services/sync/ChromaSync.ts:1-80]()\n\n### 向量搜索策略\n\n搜索策略模块实现了多种检索算法：\n\n| 策略 | 说明 | 适用场景 |\n|------|------|----------|\n| 语义相似度 | 基于向量余弦相似度 | 语义相关查询 |\n| 关键词匹配 | BM25 或全文索引 | 精确术语搜索 |\n| 混合搜索 | 向量 + 关键词融合 | 平衡精确与语义 |\n| 时间衰减 | 考虑时间因素的排序 | 最新相关 |\n\n资料来源：[src/services/worker/search/strategies](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/strategies)\n\n## 数据流\n\n### 写入流程\n\n```mermaid\nsequenceDiagram\n participant SDK as Claude SDK\n participant Worker as Worker Service\n participant SQLite as SQLite DB\n participant Chroma as Chroma\n \n SDK->>Worker: 发送工具调用事件\n Worker->>Worker: 解析为 Observation\n Worker->>SQLite: 存储观察记录\n Worker->>Chroma: 同步向量数据\n Chroma-->>Worker: 确认同步完成\n Worker-->>SDK: 返回处理结果\n```\n\n### 读取流程\n\n当新会话启动时，数据存储层提供上下文注入：\n\n1. 解析用户请求\n2. 根据配置选择观察数量和会话数量\n3. 执行向量相似度搜索\n4. 按时间排序和去重\n5. 注入到提示上下文\n\n资料来源：[src/services/sqlite/Observations.ts:60-100]()\n\n## 配置与优化\n\n### 存储路径\n\n默认数据库存储路径为应用数据目录：\n\n```bash\n# macOS\n~/Library/Application Support/claude-mem/\n\n# Linux\n~/.config/claude-mem/\n\n# Windows\n%APPDATA%/claude-mem/\n```\n\n### 性能考虑\n\n- **索引优化**：对 `session_id`、`project`、`occurred_at_epoch` 等字段建立索引\n- **批量写入**：使用事务批量提交减少 I/O\n- **连接池**：复用数据库连接减少开销\n\n资料来源：[src/services/sqlite/schema.sql:36-50]()\n\n## 相关文档\n\n- [安装指南](../getting-started/installation.md)\n- [API 参考](../api-reference/server-routes.md)\n- [搜索功能](../features/search.md)\n\n---\n\n\n\n## 搜索系统\n\n### 相关页面\n\n相关主题：[MCP 集成](#page-mcp-integration), [数据存储层](#page-data-storage)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/services/sqlite/Database.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Database.ts)\n- [src/services/sqlite/schema.sql](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/schema.sql)\n- [src/services/sqlite/Sessions.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Sessions.ts)\n- [src/services/sqlite/Observations.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Observations.ts)\n- [src/services/sync/ChromaSync.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sync/ChromaSync.ts)\n- [src/services/worker/search/strategies](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/strategies)\n\n
\n\n# 搜索系统\n\n## 概述\n\n搜索系统是 claude-mem 的核心功能模块，负责在历史观察记录、会话和提示词中进行语义检索。该系统通过混合搜索策略结合关键词匹配与语义理解，使用户能够快速定位跨越多个会话积累的项目知识。搜索结果不仅返回匹配的观察记录，还支持时间线构建、上下文预览和自动注入功能，使 AI 能够在新的会话中无缝利用历史上下文。\n\n## 架构设计\n\n### 系统组件\n\n搜索系统由多个协同工作的组件构成，形成从请求处理到结果返回的完整管道。\n\n| 组件名称 | 文件路径 | 职责描述 |\n|---------|---------|---------|\n| SearchOrchestrator | `src/services/worker/search/SearchOrchestrator.ts` | 搜索请求的统一入口，负责协调各搜索策略的执行 |\n| HybridSearchStrategy | `src/services/worker/search/strategies/HybridSearchStrategy.ts` | 实现混合搜索策略，结合关键词与语义检索 |\n| TimelineBuilder | `src/services/worker/search/TimelineBuilder.ts` | 构建搜索结果的时间线视图 |\n| 观察记录获取 | `src/services/sqlite/observations/get.ts` | 从 SQLite 数据库检索观察记录 |\n| MCP 工具层 | `src/server/mcp/tools.ts` | 提供 MCP 协议接口供外部调用搜索功能 |\n\n### 数据流向\n\n```mermaid\ngraph TD\n A[用户搜索请求] --> B[SearchOrchestrator]\n B --> C{HybridSearchStrategy}\n C --> D[关键词搜索]\n C --> E[语义向量搜索]\n D --> F[结果合并与排序]\n E --> F\n F --> G[TimelineBuilder]\n G --> H[搜索结果响应]\n H --> I[上下文预览/注入]\n```\n\n## 核心组件详解\n\n### SearchOrchestrator\n\nSearchOrchestrator 作为搜索系统的协调器，负责接收和处理所有搜索请求。它根据请求类型分发到相应的搜索策略，并协调结果的聚合与格式化。\n\n**主要职责：**\n- 路由不同类型的搜索请求（观察记录、会话、提示词等）\n- 管理搜索策略的执行顺序\n- 处理搜索结果的缓存与去重\n- 提供搜索帮助信息\n\n### HybridSearchStrategy\n\n混合搜索策略是本系统的核心创新，它结合了传统关键词搜索的精确性与语义搜索的智能化理解能力。\n\n```mermaid\ngraph LR\n A[查询字符串] --> B[分词处理]\n B --> C[关键词匹配]\n B --> D[语义向量化]\n C --> E[BM25 评分]\n D --> F[向量相似度]\n E --> G[分数融合]\n F --> G\n G --> H[Top-K 结果]\n```\n\n**搜索模式支持：**\n- **全文搜索**：对观察记录的标题、副标题、事实描述进行全文检索\n- **标签搜索**：按概念标签、文件路径、观察类型过滤\n- **时间范围搜索**：限定在特定时间段内的记录\n- **项目隔离搜索**：仅在指定项目中搜索\n\n### TimelineBuilder\n\nTimelineBuilder 负责将搜索结果按时间顺序组织，帮助用户理解知识在项目演进过程中的累积过程。\n\n**时间线类型：**\n- `timeline-by-query`：基于搜索查询的时间线\n- `context-timeline`：上下文注入时的时间线\n- `recent-context`：最近上下文的综合视图\n\n## API 端点\n\n### 搜索相关端点\n\n| 端点路径 | HTTP 方法 | 功能描述 |\n|---------|-----------|---------|\n| `/search/observations` | GET | 搜索观察记录 |\n| `/search/sessions` | GET | 搜索会话 |\n| `/search/prompts` | GET | 搜索提示词 |\n| `/search/by-concept` | GET | 按概念标签查找 |\n| `/search/by-file` | GET | 按文件路径查找 |\n| `/search/by-type` | GET | 按观察类型查找 |\n| `/search/recent-context` | GET | 获取最近上下文 |\n| `/search/context-timeline` | GET | 获取上下文时间线 |\n| `/search/timeline-by-query` | GET | 基于查询的时间线 |\n| `/search/help` | GET | 获取搜索帮助 |\n\n### 上下文相关端点\n\n| 端点路径 | HTTP 方法 | 功能描述 |\n|---------|-----------|---------|\n| `/context/preview` | GET | 预览上下文内容 |\n| `/context/inject` | POST | 注入上下文到会话 |\n\n## 观察记录检索\n\n### SQLite 数据模型\n\n观察记录存储在 SQLite 数据库中，支持多种查询模式。资料来源：`src/services/sqlite/observations/get.ts`\n\n**支持的操作类型：**\n\n```typescript\ntype ObservationKind = 'decision' | 'change' | 'how-it-works';\n```\n\n**检索函数签名：**\n- `getObservations(filters)`：基础观察记录检索\n- `getObservationsBySession(sessionId)`：按会话筛选\n- `getObservationsByProject(projectId)`：按项目筛选\n- `getObservationsByType(type)`：按类型筛选\n\n### 查询参数\n\n| 参数名 | 类型 | 描述 |\n|-------|------|-----|\n| `query` | string | 搜索查询字符串 |\n| `sessionId` | string | 会话 ID |\n| `projectId` | string | 项目 ID |\n| `type` | string | 观察类型 |\n| `concept` | string | 概念标签 |\n| `filePath` | string | 文件路径 |\n| `limit` | number | 返回结果数量限制 |\n| `offset` | number | 结果偏移量 |\n\n## MCP 工具接口\n\nMCP（Model Context Protocol）工具层为外部 AI 客户端提供搜索访问接口。资料来源：`src/server/mcp/tools.ts`\n\n### 工具定义\n\n```typescript\n// MCP 搜索工具结构\ninterface SearchTool {\n name: string; // 工具名称\n description: string; // 功能描述\n inputSchema: object; // 输入参数模式\n}\n```\n\n### 可用搜索工具\n\n| 工具名称 | 功能 | 输入参数 |\n|---------|------|---------|\n| `search_observations` | 搜索观察记录 | query, filters |\n| `search_sessions` | 搜索会话 | query, dateRange |\n| `search_by_concept` | 按概念搜索 | concept, limit |\n| `search_by_file` | 按文件路径搜索 | filePath, limit |\n| `inject_context` | 注入上下文 | sessionId, observationIds |\n\n## 搜索策略实现\n\n### 混合评分机制\n\n混合搜索策略通过加权融合关键词匹配分数和语义相似度分数来生成最终排名。资料来源：`src/services/worker/search/strategies/HybridSearchStrategy.ts`\n\n**评分公式：**\n```\nfinal_score = α × bm25_score + β × semantic_similarity\n```\n\n其中 α 和 β 为可配置的权重参数，默认 α = 0.4，β = 0.6。\n\n### 结果重排序\n\n搜索结果返回前会根据以下因素进行重排序：\n- 时间衰减因子：新近记录优先\n- 项目相关性：与当前项目关联度高的记录\n- 使用频率：被引用次数多的记录\n\n## 使用场景\n\n### 场景一：跨会话知识检索\n\n当开发者需要回顾之前实现某个功能的技术决策时，可以通过概念标签或文件路径快速定位相关观察记录。\n\n### 场景二：上下文恢复\n\n在长时间中断后重新开始工作时，系统可以将相关的历史观察打包为上下文预览，帮助 AI 快速恢复项目认知。\n\n### 场景三：知识图谱构建\n\n通过分析搜索结果中的概念标签和文件关联，系统可以自动构建项目的知识图谱结构。\n\n## 配置选项\n\n### 搜索配置参数\n\n| 配置项 | 默认值 | 描述 |\n|-------|-------|------|\n| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | 50 | 注入上下文时包含的观察记录数量 |\n| `CLAUDE_MEM_CONTEXT_SESSIONS` | 10 | 从多少个会话中拉取观察记录 |\n| `search.defaultLimit` | 20 | 默认搜索结果限制 |\n| `search.maxLimit` | 200 | 最大搜索结果限制 |\n| `hybrid.alpha` | 0.4 | BM25 权重 |\n| `hybrid.beta` | 0.6 | 语义相似度权重 |\n\n## 总结\n\n搜索系统通过混合搜索策略、灵活的时间线构建和完整的 MCP 工具接口，为 claude-mem 提供了强大的知识检索能力。该系统使得跨会话的上下文保持和知识复用成为可能，显著提升了 AI 在长期项目中的工作效率。\n\n---\n\n\n\n## 生命周期钩子系统\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [IDE 集成](#page-ide-integrations)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/services/worker/search/SearchOrchestrator.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/SearchOrchestrator.ts)\n- [src/services/worker/search/strategies/HybridSearchStrategy.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/strategies/HybridSearchStrategy.ts)\n- [src/services/worker/search/TimelineBuilder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/TimelineBuilder.ts)\n- [src/services/sqlite/observations/get.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/observations/get.ts)\n- [src/server/mcp/tools.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/mcp/tools.ts)\n\n
\n\n# 生命周期钩子系统\n\n## 概述\n\n生命周期钩子系统（Lifecycle Hook System）是 claude-mem 的核心模块，负责在 Claude Code、Gemini CLI、OpenClaw Gateway 和 Cursor 等 IDE 的运行过程中自动捕获用户操作、生成语义摘要，并使历史上下文可供未来会话使用。该系统通过事件驱动的架构，在 IDE 的关键生命周期节点注入自定义逻辑，实现跨会话的持久记忆功能。 资料来源：[README.md]()\n\n## 架构设计\n\n### 系统组件\n\n```mermaid\ngraph TD\n subgraph \"IDE 运行环境\"\n CLI[Claude Code / Gemini CLI / Cursor / OpenClaw]\n end\n \n subgraph \"钩子系统核心\"\n HC[Hook Manager]\n EP[Event Processor]\n OBS[Observation Store]\n SUM[Summary Generator]\n end\n \n subgraph \"存储层\"\n DB[(SQLite/JSON)]\n FS[文件系统]\n end\n \n CLI -->|触发生命周期事件| HC\n HC -->|处理事件| EP\n EP -->|生成观测记录| OBS\n EP -->|触发摘要生成| SUM\n OBS -->|持久化| DB\n SUM -->|持久化| FS\n```\n\n### 事件流处理\n\n钩子系统采用事件驱动模式，在 IDE 的生命周期各阶段触发相应的处理函数。每个事件都携带上下文数据，经处理器转换后存入持久化存储。 资料来源：[openclaw/src/index.ts:1-50]()\n\n## 钩子事件类型\n\n### OpenClaw Gateway 事件\n\nOpenClaw Gateway 提供了完整的事件订阅接口，支持以下生命周期事件： 资料来源：[openclaw/src/index.ts:15-27]()\n\n| 事件名称 | 触发时机 | 回调参数 | 功能描述 |\n|---------|---------|---------|---------|\n| `before_prompt_build` | 构建提示词前 | `PromptBuildCallback` | 修改或增强提示词内容 |\n| `before_agent_start` | Agent 启动前 | `BeforeAgentStartEvent` | 执行预启动准备工作 |\n| `tool_result_persist` | 工具执行结果返回时 | `ToolResultPersistEvent` | 持久化工具输出 |\n| `agent_end` | Agent 执行完成时 | `AgentEndEvent` | 执行后处理逻辑 |\n| `session_start` | 会话启动时 | `SessionStartEvent` | 初始化会话上下文 |\n| `session_end` | 会话结束时 | `SessionEndEvent` | 生成会话摘要 |\n| `message_received` | 收到用户消息时 | `MessageReceivedEvent` | 处理用户输入 |\n| `after_compaction` | 上下文压缩后 | `AfterCompactionEvent` | 处理压缩后的状态 |\n| `gateway_start` | Gateway 启动时 | 无参数 | 执行初始化逻辑 |\n\n### 事件回调接口定义\n\n```typescript\ninterface PluginInterface {\n on: ((\n event: \"before_prompt_build\",\n callback: PromptBuildCallback\n ) => void) &\n ((\n event: \"before_agent_start\",\n callback: EventCallback相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [openclaw/src/index.ts](https://github.com/thedotmack/claude-mem/blob/main/openclaw/src/index.ts)\n- [cursor-hooks/README.md](https://github.com/thedotmack/claude-mem/blob/main/cursor-hooks/README.md)\n- [src/services/smart-file-read/parser.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/smart-file-read/parser.ts)\n- [src/server/generation/providers/shared/prompt-builder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/providers/shared/prompt-builder.ts)\n- [src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)\n\n
\n\n# MCP 集成\n\n## 概述\n\nClaude-Mem 通过 Model Context Protocol (MCP) 实现与多种 AI Agent 平台的深度集成。MCP 作为连接 AI 助手与外部工具、资源的标准协议，使 claude-mem 能够作为统一的知识记忆层，为不同 IDE 环境（如 Claude Code、OpenClaw、OpenCode 等）提供跨会话的持久化上下文能力。\n\nMCP 集成模块位于 `src/server/mcp/` 目录，包含工具注册、资源管理、提示词模板和 MCP 服务器核心实现等组件。资料来源：[src/servers/mcp-server.ts:1]()\n\n## 架构设计\n\n### 模块结构\n\nMCP 集成系统由以下核心模块组成：\n\n```mermaid\ngraph TD\n A[MCP 客户端相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/mcp/tools.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/mcp/tools.ts)\n- [src/server/mcp/register.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/mcp/register.ts)\n- [src/server/mcp/resources.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/mcp/resources.ts)\n- [src/server/mcp/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/mcp/prompts.ts)\n- [src/servers/mcp-server.ts](https://github.com/thedotmack/claude-mem/blob/main/src/servers/mcp-server.ts)\nClaude Code / OpenClaw / OpenCode] --> B[MCP 服务器
mcp-server.ts]\n B --> C[tools.ts
工具定义]\n B --> D[resources.ts
资源提供]\n B --> E[prompts.ts
提示词模板]\n B --> F[register.ts
注册与生命周期]\n C --> G[记忆存储
SQLite + claude.md]\n D --> G\n```\n\n### 核心职责\n\n| 模块 | 职责 | 主要功能 |\n|------|------|----------|\n| `mcp-server.ts` | MCP 服务器入口 | 初始化传输层、注册处理器、启动服务 |\n| `tools.ts` | 工具定义 | 定义并暴露 AI Agent 可调用的记忆操作工具 |\n| `resources.ts` | 资源管理 | 提供记忆数据作为可读取的资源 |\n| `prompts.ts` | 提示词模板 | 生成 MCP 上下文相关的提示词 |\n| `register.ts` | 注册管理 | 管理工具和资源的注册、生命周期事件 |\n\n## 工具系统 (tools.ts)\n\n### 工具定义\n\nMCP 工具系统允许 AI Agent 通过标准化接口查询和操作记忆数据。工具定义遵循 MCP 协议规范，每个工具包含：\n\n- **名称 (name)**: 工具的唯一标识符\n- **描述 (description)**: 工具用途说明，供 AI Agent 理解何时调用\n- **输入模式 (inputSchema)**: 工具参数的 JSON Schema 定义\n\n### 可用工具类型\n\n典型的 MCP 工具包括：\n\n1. **记忆查询工具**: 根据时间范围、项目或关键词检索历史观察记录\n2. **摘要生成工具**: 请求生成特定会话的语义摘要\n3. **上下文注入工具**: 将检索到的记忆注入到当前会话上下文\n4. **项目状态工具**: 查询当前项目的已知信息和状态\n\n资料来源：[src/server/mcp/tools.ts:1]()\n\n## 资源系统 (resources.ts)\n\n### 资源模型\n\nMCP 资源系统将 claude-mem 的记忆数据以 URI 形式暴露给 AI Agent，支持按需读取：\n\n```mermaid\ngraph LR\n A[AI Agent] -->|请求资源 URI| B[MCP 服务器]\n B --> C[resources.ts]\n C --> D[SQLite 数据库]\n C --> E[claude.md 文件]\n```\n\n### 资源 URI 格式\n\n资源使用统一资源标识符进行寻址：\n\n| 资源类型 | URI 格式 | 说明 |\n|----------|----------|------|\n| 观察记录 | `mem://observations/{project_id}` | 获取项目的所有观察 |\n| 摘要列表 | `mem://summaries/{session_id}` | 获取会话摘要 |\n| 项目元数据 | `mem://projects/{project_path}` | 获取项目配置信息 |\n| 时间线 | `mem://timeline/{project_id}` | 获取活动时间线 |\n\n### 资源缓存策略\n\n资源系统实现了智能缓存机制，避免重复读取相同数据。缓存失效策略与记忆更新事件联动，确保数据一致性。\n\n资料来源：[src/server/mcp/resources.ts:1]()\n\n## 提示词集成 (prompts.ts)\n\n### 提示词模板系统\n\nMCP 提示词模块负责生成与记忆相关的上下文模板，帮助 AI Agent 理解如何与记忆系统交互：\n\n- **系统级提示词**: 定义 AI Agent 对记忆系统的认知角色\n- **查询提示词**: 生成结构化的记忆查询指令\n- **响应格式提示词**: 指定记忆数据的返回格式规范\n\n### 模板变量\n\n提示词系统支持动态变量注入：\n\n| 变量 | 来源 | 用途 |\n|------|------|------|\n| `{project_id}` | 当前会话 | 限定记忆范围 |\n| `{session_id}` | 会话上下文 | 关联特定会话 |\n| `{time_range}` | 查询参数 | 时间范围过滤 |\n| `{user_query}` | 用户输入 | 自然语言查询意图 |\n\n资料来源：[src/server/mcp/prompts.ts:1]()\n\n## 注册与生命周期 (register.ts)\n\n### 初始化流程\n\n```mermaid\nsequenceDiagram\n participant Host as MCP Host\n participant Server as MCP Server\n participant Registry as register.ts\n participant Store as 记忆存储\n \n Host->>Server: 连接请求\n Server->>Registry: 初始化注册\n Registry->>Registry: 注册工具定义\n Registry->>Registry: 注册资源提供器\n Registry->>Registry: 订阅生命周期事件\n Registry->>Store: 验证连接\n Server-->>Host: 连接就绪\n```\n\n### 生命周期管理\n\n注册模块负责管理以下生命周期事件：\n\n1. **连接建立**: 验证客户端权限，初始化会话上下文\n2. **工具调用**: 路由工具请求到对应的处理器\n3. **资源订阅**: 管理资源变更通知\n4. **连接断开**: 清理会话状态，持久化临时数据\n\n### 错误处理\n\n注册系统实现了健壮的错误处理机制：\n\n- 工具调用超时自动重试\n- 资源不可用时的优雅降级\n- 连接异常时的自动重连策略\n\n资料来源：[src/server/mcp/register.ts:1]()\n\n## MCP 服务器核心 (mcp-server.ts)\n\n### 服务器架构\n\nMCP 服务器是整个集成系统的核心入口点，负责：\n\n1. **传输层管理**: 处理 STDIO 或 HTTP 传输\n2. **协议实现**: 遵循 MCP 规范进行消息编解码\n3. **请求路由**: 将入站请求分发到对应模块\n4. **响应序列化**: 将处理结果格式化为 MCP 协议格式\n\n### 启动配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| 端口 | 3100 | MCP 服务器监听端口 |\n| 传输方式 | stdio | 支持 stdio 和 HTTP |\n| 超时 | 30s | 工具调用超时时间 |\n| 日志级别 | info | 日志输出级别 |\n\n### 与其他集成方式的对比\n\nClaude-Mem 支持多种集成方式，MCP 是其中最标准化的方案：\n\n| 集成方式 | 适用场景 | 特点 |\n|----------|----------|------|\n| MCP | 标准 AI Agent 平台 | 协议标准化、跨平台支持 |\n| 插件系统 | Claude Code | 深度集成、实时观察 |\n| npx CLI | 手动操作 | 灵活但不持久 |\n| OpenClaw Gateway | 企业部署 | 托管服务、高可用 |\n\n资料来源：[src/servers/mcp-server.ts:1]()\n\n## 使用场景\n\n### 跨会话上下文保持\n\n当 AI Agent 在新会话中处理项目时，可以通过 MCP 接口获取历史会话中积累的项目知识：\n\n1. Agent 连接 MCP 服务器\n2. 通过资源接口获取项目历史\n3. 工具调用检索相关观察记录\n4. 上下文注入当前会话\n\n### 主动记忆增强\n\n通过 MCP 工具， AI Agent 可以在处理复杂任务时主动查询记忆库：\n\n```\n用户请求: 重构 authentication 模块\n ↓\nAgent 调用 MCP 工具: search_observations(project, \"auth\")\n ↓\n获取历史修改记录、设计决策\n ↓\n生成重构方案时参考历史上下文\n```\n\n### 多 Agent 知识共享\n\n在 OpenClaw 等多 Agent 环境中，MCP 服务器可作为共享记忆中枢：\n\n- 多个 Agent 实例共享同一记忆存储\n- 通过 MCP 资源接口实现跨 Agent 知识传递\n- 保持团队协作的上下文连续性\n\n## 配置与调试\n\n### 环境变量\n\n| 变量 | 说明 |\n|------|------|\n| `CLAUDE_MEM_MCP_PORT` | MCP 服务器端口 |\n| `CLAUDE_MEM_MCP_TRANSPORT` | 传输方式 (stdio/http) |\n| `CLAUDE_MEM_LOG_LEVEL` | 日志级别 |\n\n### 状态检查\n\n```bash\nnpx claude-mem status\n```\n\n该命令可验证 MCP 服务器运行状态和连接状态。\n\n## 安全考虑\n\n### 数据隔离\n\n- 每个项目的记忆数据相互隔离\n- MCP 连接使用项目路径作为会话标识\n- 资源访问遵循最小权限原则\n\n### 敏感信息处理\n\n记忆系统会自动过滤敏感信息（如 API Key、环境变量值），确保只记录语义内容而非凭证数据。\n\n## 相关文档\n\n- [快速开始指南](../getting-started.md) - MCP 集成的入门配置\n- [SDK 文档](../sdk/overview.md) - 编程接口参考\n- [开发指南](https://docs.claude-mem.ai/development) - MCP 模块开发说明\n\n---\n\n\n\n## IDE 集成\n\n### 相关页面\n\n相关主题：[生命周期钩子系统](#page-hooks-system), [安装与部署](#page-installation)\n\n
\n
\n\n# IDE 集成\n\nclaude-mem 通过统一的集成框架支持多种主流 IDE 和 CLI 环境，实现跨平台的情境记忆功能。本页详细说明各 IDE 的集成架构、安装机制和运行时行为。\n\n## 支持的 IDE 环境\n\nclaude-mem 支持以下集成目标：\n\n| IDE/CLI | 安装命令 | 检测方式 | 钩子类型 |\n|---------|---------|---------|---------|\n| Claude Code | `npx claude-mem install` | `~/.claude` 目录 | 插件钩子 |\n| Cursor | `npx claude-mem install --ide cursor` | 平台检测 | Cursor Hooks |\n| Gemini CLI | `npx claude-mem install --ide gemini-cli` | `~/.gemini` 目录 | MCP 钩子 |\n| OpenCode | `npx claude-mem install --ide opencode` | `OPENCODE_DIR` 环境变量 | MCP 钩子 |\n\n资料来源：[src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n## 集成架构概览\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ claude-mem │\n├─────────────────────────────────────────────────────────────┤\n│ CLI 适配层 (src/cli/adapters) │\n│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │\n│ │ ClaudeCode │ │ Cursor │ │ GeminiCLI │ │\n│ │ Adapter │ │ Adapter │ │ Adapter │ │\n│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │\n├─────────┴────────────────┴────────────────┴─────────────────┤\n│ 集成服务层 (src/services/integrations) │\n│ ┌──────────────────────────────────────────────────────┐ │\n│ │ HookInstaller 抽象工厂 │ │\n│ │ ┌────────────────┐ ┌────────────────┐ │ │\n│ │ │ ClaudeHooks │ │ CursorHooks │ │ │\n│ │ │ Installer │ │ Installer │ │ │\n│ │ └────────────────┘ └────────────────┘ │ │\n│ └──────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## CLI 适配层\n\n适配层负责检测目标 IDE 环境并提供统一的安装接口。\n\n### Claude Code 适配器\n\nClaude Code 通过插件机制集成：\n\n```bash\n# 通过插件市场安装\n/plugin marketplace add thedotmack/claude-mem\n/plugin install claude-mem\n\n# 或通过命令行安装\nnpx claude-mem install\n```\n\n资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n\n### 检测机制\n\n集成系统通过多层次检测确定 IDE 环境：\n\n```typescript\nexport async function detectClaudeCode(): Promise相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/services/integrations/CursorHooksInstaller.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/integrations/CursorHooksInstaller.ts)\n- [src/cli/adapters](https://github.com/thedotmack/claude-mem/blob/main/src/cli/adapters)\n- [cursor-hooks](https://github.com/thedotmack/claude-mem/blob/main/cursor-hooks)\n- [plugin/modes](https://github.com/thedotmack/claude-mem/blob/main/plugin/modes)\n- [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n
\n\n# 安装与部署\n\n## 概述\n\nClaude-Mem 提供多种安装方式，支持在不同集成环境中部署本插件。安装过程会自动配置后台运行服务（Worker）、数据存储目录以及与 Claude Code 的集成钩子。\n\n## 安装方式\n\nClaude-Mem 支持以下几种安装途径：\n\n### 1. NPX 一键安装（推荐）\n\n通过 npx 命令直接安装，这是最简单的方式：\n\n```bash\nnpx claude-mem install\n```\n\n安装完成后，系统会显示欢迎提示，包含以下信息：\n- Worker 服务状态（启动中或已就绪）\n- 访问本地查看器的 URL\n- 后续操作指引\n\n资料来源：[README.md:1-30]()\n\n### 2. Claude Code 插件市场安装\n\n对于 Claude Code 用户，可以通过内置的 `/plugin` 命令安装：\n\n```bash\n/plugin marketplace add thedotmack/claude-mem\n/plugin install claude-mem\n```\n\n安装完成后需要重启 Claude Code。\n\n资料来源：[README.md:30-35]()\n\n### 3. Gemini CLI 安装\n\n针对 Gemini CLI 用户，可以指定 `--ide` 参数：\n\n```bash\nnpx claude-mem install --ide gemini-cli\n```\n\n该命令会自动检测 `~/.gemini` 目录并完成配置。\n\n资料来源：[README.md:18-22]()\n\n### 4. OpenCode 安装\n\n针对 OpenCode 编辑器用户：\n\n```bash\nnpx claude-mem install --ide opencode\n```\n\n资料来源：[README.md:25-28]()\n\n### 5. OpenClaw Gateway 安装\n\n在 OpenClaw 网关上安装持久化内存插件：\n\n```bash\ncurl -fsSL https://install.cmem.ai/openclaw.sh | bash\n```\n\n资料来源：[README.md:45-50]()\n\n## 安装流程架构\n\n```mermaid\ngraph TD\n A[用户执行安装命令] --> B{安装方式}\n B -->|npx claude-mem install| C[初始化配置文件]\n B -->|/plugin install| D[检测 Claude Code 环境]\n B -->|OpenClaw| E[下载安装脚本]\n \n C --> F[启动 Worker 服务]\n D --> F\n E --> G[配置 Gateway]\n \n F --> H[创建 ~/.claude-mem 目录]\n H --> I[注册集成钩子]\n I --> J[安装完成，显示提示]\n \n J --> K[首次启动建议]\n K --> L[\"方式A: 直接开始工作\"]\n K --> M[\"方式B: 运行 /learn-codebase\"]\n```\n\n## Worker 服务配置\n\n### 默认配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| 端口 | 18789 | Worker 服务监听端口 |\n| 数据目录 | `~/.claude-mem` | 存储观察记录和配置 |\n| 自动启动 | 启用 | 系统启动时自动运行 |\n\n### 启动状态检测\n\n安装完成后，系统会检查 Worker 服务状态：\n\n```typescript\nworkerAlive\n ? [workerHeadline, firstSuccessMessage, twoPathsMessage]\n : [waitMessage, manualStartHint]\n```\n\n资料来源：[src/npx-cli/commands/install.ts:10-30]()\n\n### 手动启动\n\n如果 Worker 未自动启动，可手动启动：\n\n```bash\nnpx claude-mem start\n```\n\n## 环境变量配置\n\n### 安装后提示控制\n\n首次安装后，系统会显示欢迎提示。可通过环境变量禁用：\n\n```bash\nCLAUDE_MEM_WELCOME_HINT_ENABLED=false\n```\n\n资料来源：[src/npx-cli/commands/install.ts:20-25]()\n\n### 查看器配置\n\n通过 `ContextSettingsModal.tsx` 可以配置以下参数：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | 50 | 注入上下文的观察数量 (1-200) |\n| `CLAUDE_MEM_CONTEXT_SESSIONS` | - | 拉取观察的会话数量 (1-50) |\n\n资料来源：[src/ui/viewer/components/ContextSettingsModal.tsx:40-60]()\n\n## 卸载说明\n\n卸载前需要关闭所有 Claude Code 会话，否则活动钩子会重新创建配置目录：\n\n```bash\nnpx claude-mem uninstall\n```\n\n> **注意**：关闭所有 Claude Code 会话后再执行卸载，否则 `~/.claude-mem` 目录会被重新创建。\n\n资料来源：[src/npx-cli/commands/install.ts:15-18]()\n\n## 快速验证安装\n\n安装完成后按以下步骤验证：\n\n1. 启动 Claude Code\n2. 确认控制台无错误信息\n3. 在新项目中输入测试提示\n4. 第二次会话时应能看到历史上下文注入\n\n## 安装方式对比\n\n| 安装方式 | 适用环境 | 是否需要重启 | 自动化程度 |\n|----------|----------|--------------|------------|\n| `npx claude-mem install` | 通用 | 是 | 高 |\n| `/plugin` 命令 | Claude Code | 是 | 高 |\n| OpenClaw 脚本 | OpenClaw Gateway | 是 | 高 |\n| 源码编译 | 开发/自定义 | 是 | 低 |\n\n## 常见问题\n\n### Q: npm install -g claude-mem 是否可行？\n\n**不行**。通过 `npm install -g` 安装的是 SDK/库版本，不会注册插件钩子或设置 Worker 服务。必须使用 `npx claude-mem install` 或 `/plugin` 命令安装。\n\n资料来源：[README.md:36-40]()\n\n### Q: 如何检查服务状态？\n\n```bash\nnpx claude-mem status\n```\n\n### Q: Worker 启动后显示等待状态怎么办？\n\n这是正常现象，Worker 启动需要约 30 秒。等待完成后刷新浏览器即可。\n\n资料来源：[src/npx-cli/commands/install.ts:35-40]()\n\n## 后续步骤\n\n安装完成后，推荐以下两种初始化方式：\n\n**方式 A（推荐）**：直接开始工作，记忆会从第一次提示中被动构建。\n\n**方式 B**：运行 `/learn-codebase` 命令预加载整个代码仓库（约 5 分钟，可选）。\n\n资料来源：[src/npx-cli/commands/install.ts:22-28]()\n\n## 相关文档\n\n- [使用指南](./使用指南.md)\n- [配置选项](./配置选项.md)\n- [故障排除](./故障排除.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：thedotmack/claude-mem\n\n摘要：发现 24 个潜在踩坑项，其中 8 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories。\n\n## 1. 安装坑 · 来源证据：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_28646536cf7d499aadab2346c2666f89 | https://github.com/thedotmack/claude-mem/issues/2389 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Windows: cmd.exe /c uvx wrapper breaks Chroma MCP stdio on WinGet uv installs (regression after #1190 / #1199) --> FIX…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows: cmd.exe /c uvx wrapper breaks Chroma MCP stdio on WinGet uv installs (regression after #1190 / #1199) --> FIX attacched\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6c844000d9b4adead4a2fdb73660c8d | https://github.com/thedotmack/claude-mem/issues/2426 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：[Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9e74ac48a1744106a07ff519ad2d2773 | https://github.com/thedotmack/claude-mem/issues/2437 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：v13: merged_into_project migration silently skipped on pre-existing DBs (schema_versions ≤ 23)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13: merged_into_project migration silently skipped on pre-existing DBs (schema_versions ≤ 23)\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_510ecb03a1de412f940987e370c68fac | https://github.com/thedotmack/claude-mem/issues/2433 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：Use node to run mcp for windows environment\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Use node to run mcp for windows environment\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_95d37c5d34a749f7a25fdd5fe1dc7969 | https://github.com/thedotmack/claude-mem/issues/2446 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 来源证据：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_77fdc7c371f042eeb70fbeb52a7a2788 | https://github.com/thedotmack/claude-mem/issues/2438 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 运行坑 · 来源证据：自动运行时突然报下图所示内容，然后插件就不能用了\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：自动运行时突然报下图所示内容，然后插件就不能用了\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2d5aa43a4c5a4e46a0f2122dea46947a | https://github.com/thedotmack/claude-mem/issues/2441 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安全/权限坑 · 来源证据：[Bug] Codex CLI plugin hooks consume Claude Code session quota via Claude Code SDK\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] Codex CLI plugin hooks consume Claude Code session quota via Claude Code SDK\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b77cb6420d845a9bd38852571b6adbd | https://github.com/thedotmack/claude-mem/issues/2431 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：Codex CLI: PreToolUse hook returned unsupported suppressOutput\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex CLI: PreToolUse hook returned unsupported suppressOutput\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9022a732f6e54ba39309c5377cf2d8fa | https://github.com/thedotmack/claude-mem/issues/2360 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 安装坑 · 来源证据：[feat] Option to load only memory-related skills\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[feat] Option to load only memory-related skills\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_efa30fc4873343aea26f804c8d1113ec | https://github.com/thedotmack/claude-mem/issues/2448 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 安装坑 · 来源证据：server-beta: ModeManager not initialized — generation jobs fail with 'No mode loaded'\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：server-beta: ModeManager not initialized — generation jobs fail with 'No mode loaded'\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_757115889024465dbafb2f4ffcbe8356 | https://github.com/thedotmack/claude-mem/issues/2443 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 安装坑 · 来源证据：v12.1.1: hooks/hooks.json references removed scripts/worker-service.cjs — all hooks fail with \"Module not found\"\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v12.1.1: hooks/hooks.json references removed scripts/worker-service.cjs — all hooks fail with \"Module not found\"\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0e29da4de6004faea2de867f758794f8 | https://github.com/thedotmack/claude-mem/issues/1835 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 13. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | host_targets=claude, claude_code\n\n## 14. 配置坑 · 来源证据：server-beta: runServerBetaCli() default command exits immediately — unusable with systemd\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：server-beta: runServerBetaCli() default command exits immediately — unusable with systemd\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2613a65b36064bfeb5bbaf9fed69672d | https://github.com/thedotmack/claude-mem/issues/2444 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | README/documentation is current enough for a first validation pass.\n\n## 16. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | last_activity_observed missing\n\n## 17. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 19. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | no_demo; severity=medium\n\n## 20. 安全/权限坑 · 来源证据：Daemon survives plugin disable, burns 500M+ tokens/week with no observable user-facing benefit\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Daemon survives plugin disable, burns 500M+ tokens/week with no observable user-facing benefit\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a4e91994a3834fc4a64f07b31ce17242 | https://github.com/thedotmack/claude-mem/issues/2451 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 21. 安全/权限坑 · 来源证据：Long-running Worker endpoints share health-check timeout (HEALTH_TIMEOUT_MS); should use per-endpoint timeouts\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Long-running Worker endpoints share health-check timeout (HEALTH_TIMEOUT_MS); should use per-endpoint timeouts\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b61a79c5ae144fcbd7cb8737397dbee | https://github.com/thedotmack/claude-mem/issues/2447 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 22. 安全/权限坑 · 来源证据：claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c23b4f1758454233a20f5c0653d69d51 | https://github.com/thedotmack/claude-mem/issues/2450 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 23. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | issue_or_pr_quality=unknown\n\n## 24. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | release_recency=unknown\n\n\n",
"markdown_key": "claude-mem",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1048065319",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/thedotmack/claude-mem"
},
{
"evidence_id": "art_f08a1ec4431f47208d5037af21a8bfad",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/thedotmack/claude-mem#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "claude-mem 说明书",
"toc": [
"https://github.com/thedotmack/claude-mem 项目说明书",
"目录",
"项目概述",
"项目简介",
"核心功能",
"系统架构",
"安装与配置",
"首次使用流程",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "37d24944af5f4afaa0de2b0bd0034bb432f2b714",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"docker-compose.yml",
"docs/ip-boundary.md",
"docs/SESSION_ID_ARCHITECTURE.md",
"docs/server-storage-boundary.md",
"docs/adapters.md",
"docs/security.md",
"docs/api.md",
"docs/server-beta-release-readiness.md",
"docs/production-guide.md",
"docs/server.md",
"docs/docker.md",
"docs/architecture-overview.md",
"docs/server-beta-architecture-and-team-vision.md",
"docs/anti-pattern-cleanup-plan.md",
"docs/migration-worker-to-server.md",
"docs/server-beta-parity-map.md",
"docs/license.md",
"docs/context/agent-sdk-v2-preview.md",
"docs/context/agent-sdk-v2-examples.ts",
"docs/context/cursor-hooks-reference.md",
"docs/public/development.mdx",
"docs/public/troubleshooting.mdx",
"docs/public/openclaw-integration.mdx",
"docs/public/configuration.mdx",
"docs/public/file-read-gate.mdx",
"docs/public/context-engineering.mdx",
"docs/public/beta-features.mdx",
"docs/public/platform-integration.mdx",
"docs/public/endless-mode.mdx",
"docs/public/modes.mdx",
"docs/public/architecture-evolution.mdx",
"docs/public/smart-explore-benchmark.mdx",
"docs/public/progressive-disclosure.mdx",
"docs/public/installation.mdx",
"docs/public/hooks-architecture.mdx",
"docs/public/docs.json",
"docs/public/introduction.mdx",
"docs/bug-fixes/windows-spaces-issue.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# claude-mem - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 claude-mem 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`openclaw/SKILL.md`, `plugin/skills/babysit/SKILL.md`, `plugin/skills/do/SKILL.md`, `plugin/skills/how-it-works/SKILL.md` 等 Claim：`clm_0005` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`openclaw/SKILL.md`, `plugin/skills/babysit/SKILL.md`, `plugin/skills/do/SKILL.md`, `plugin/skills/how-it-works/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json` 等 Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 怎么开始\n\n- `npx claude-mem install` 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86\n- `npx claude-mem install --ide gemini-cli` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npx claude-mem install --ide opencode` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `/plugin marketplace add thedotmack/claude-mem` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `/plugin install claude-mem` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `curl -fsSL https://install.cmem.ai/openclaw.sh | bash` 证据：`README.md` Claim：`clm_0011` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`openclaw/SKILL.md`, `plugin/skills/babysit/SKILL.md`, `plugin/skills/do/SKILL.md`, `plugin/skills/how-it-works/SKILL.md` 等 Claim：`clm_0005` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`openclaw/SKILL.md`, `plugin/skills/babysit/SKILL.md`, `plugin/skills/do/SKILL.md`, `plugin/skills/how-it-works/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json` 等 Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json` 等\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0012` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json` 等 Claim：`clm_0013` supported 0.86\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0014` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`openclaw/SKILL.md`, `plugin/skills/babysit/SKILL.md`, `plugin/skills/do/SKILL.md`, `plugin/skills/how-it-works/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json` 等 Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 上下文规模\n\n- 文件总数：791\n- 重要文件覆盖：40/791\n- 证据索引条目：80\n- 角色 / Skill 条目：13\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 claude-mem 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 claude-mem 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 claude-mem 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 13 个角色 / Skill / 项目文档条目。\n\n- **Claude-Mem OpenClaw Plugin — Setup Guide**（skill）：Claude-Mem OpenClaw Plugin — Setup Guide 激活提示：当用户任务与“Claude-Mem OpenClaw Plugin — Setup Guide”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`openclaw/SKILL.md`\n- **babysit**（skill）：Watch a pull request or review cycle until it is ready to merge. Use when asked to babysit, monitor, or keep checking PR comments, reviews, and CI until all actionable issues are resolved. 激活提示：当用户任务与“babysit”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/babysit/SKILL.md`\n- **do**（skill）：Execute a phased implementation plan using subagents. Use when asked to execute, run, or carry out a plan — especially one created by make-plan. 激活提示：当用户任务与“do”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/do/SKILL.md`\n- **how-it-works**（skill）：Explain how claude-mem captures observations, when memory injection kicks in, and where data lives. Use when the user asks \"how does claude-mem work?\" or \"what is this thing doing?\". 激活提示：当用户任务与“how-it-works”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/how-it-works/SKILL.md`\n- **knowledge-agent**（skill）：Build and query AI-powered knowledge bases from claude-mem observations. Use when users want to create focused \"brains\" from their observation history, ask questions about past work patterns, or compile expertise on specific topics. 激活提示：当用户任务与“knowledge-agent”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/knowledge-agent/SKILL.md`\n- **learn-codebase**（skill）：Prime a codebase by reading every source file in full. Use when starting work on a new or unfamiliar project, or when the user asks to \"learn the codebase\", \"read the codebase\", \"prime\", or \"get up to speed\". 激活提示：当用户任务与“learn-codebase”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/learn-codebase/SKILL.md`\n- **make-plan**（skill）：Create a detailed, phased implementation plan with documentation discovery. Use when asked to plan a feature, task, or multi-step implementation — especially before executing with do. 激活提示：当用户任务与“make-plan”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/make-plan/SKILL.md`\n- **mem-search**（skill）：Search claude-mem's persistent cross-session memory database. Use when user asks \"did we already solve this?\", \"how did we do X last time?\", or needs work from previous sessions. 激活提示：当用户任务与“mem-search”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/mem-search/SKILL.md`\n- **pathfinder**（skill）：Map a codebase into feature-grouped flowcharts, identify duplicated concerns across features, and propose a unified architecture. Use when asked to \"find the ideal path,\" unify duplicated systems, or audit architecture before a refactor. Emits a proposed unified flowchart plus per-system /make-plan prompts. 激活提示：当用户任务与“pathfinder”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/pathfinder/SKILL.md`\n- **smart-explore**（skill）：Token-optimized structural code search using tree-sitter AST parsing. Use instead of reading full files when you need to understand code structure, find functions, or explore a codebase efficiently. 激活提示：当用户任务与“smart-explore”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/smart-explore/SKILL.md`\n- **timeline-report**（skill）：Generate a \"Journey Into Project \" narrative report analyzing a project's entire development history from claude-mem's timeline. Use when asked for a timeline report, project history analysis, development journey, or full project report. 激活提示：当用户任务与“timeline-report”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/timeline-report/SKILL.md`\n- **claude-code-plugin-release**（skill）：Automated semantic versioning and release workflow for Claude Code plugins. Handles version increments across package.json, marketplace.json, plugin.json manifests, npm publishing so npx claude-mem@X.Y.Z resolves , build verification, git tagging, GitHub releases, and changelog generation. 激活提示：当用户任务与“claude-code-plugin-release”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/version-bump/SKILL.md`\n- **wowerpoint**（skill）：Turn one document into a kawaii NotebookLM slide-deck PDF. Use for \"wowerpoint this\", \"make a deck about \", \"turn this report into slides\", or any request to render a single document as shareable narrative slides. 激活提示：当用户任务与“wowerpoint”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugin/skills/wowerpoint/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Claude-Mem: AI Development Instructions**（documentation）：Claude-Mem: AI Development Instructions 证据：`CLAUDE.md`\n- **Quick Start**（documentation）：🇨🇳 中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇵🇹 Português • 🇧🇷 Português • 🇰🇷 한국어 • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇮🇱 עברית • 🇸🇦 العربية • 🇷🇺 Русский • 🇵🇱 Polski • 🇨🇿 Čeština • 🇳🇱 Nederlands • 🇹🇷 Türkçe • 🇺🇦 Українська • 🇻🇳 Tiếng Việt • 🇵🇭 Tagalog • 🇮🇩 Indonesia • 🇹🇭 ไทย • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇷🇴 Română • 🇸🇪 Svenska • 🇮🇹 Italiano • 🇬🇷 Ελληνικά • 🇭🇺 Magyar • 🇫🇮 Suomi • 🇩🇰 Dansk • 🇳🇴 Norsk 证据：`README.md`\n- **Claude-Mem Cursor Hooks Integration**（documentation）：Claude-Mem Cursor Hooks Integration 证据：`cursor-hooks/README.md`\n- **Ragtime**（documentation）：Email Investigation Batch Processor using Claude-mem's email-investigation mode. 证据：`ragtime/README.md`\n- **claude-mem Docker harness**（documentation）：A minimal container for exercising claude-mem end-to-end without polluting your host. Not a dev environment — just enough to boot claude with the locally-built plugin and capture observations into a throwaway SQLite DB you can inspect afterwards. 证据：`docker/claude-mem/README.md`\n- **README Translator**（documentation）：Translate README.md files to multiple languages using the Claude Agent SDK. Perfect for build scripts and CI/CD pipelines. 证据：`scripts/translate-readme/README.md`\n- **Worker Service Architecture**（documentation）：The Worker Service is an Express HTTP server that handles all claude-mem operations. It runs on port 37777 configurable via CLAUDE MEM WORKER PORT and is managed by PM2. 证据：`src/services/worker/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@openclaw/claude-mem\", \"version\": \"1.0.0\", \"private\": true, \"license\": \"Apache-2.0\", \"type\": \"module\", \"main\": \"dist/index.js\", \"scripts\": { \"build\": \"tsc\", \"test\": \"tsc && node --test dist/index.test.js\" }, \"devDependencies\": { \"@types/node\": \"^25.6.2\", \"typescript\": \"^6.0.3\" }, \"openclaw\": { \"extensions\": \"./dist/index.js\" } } 证据：`openclaw/package.json`\n- **Package**（package_manifest）：{ \"name\": \"claude-mem\", \"version\": \"13.2.0\", \"description\": \"Memory compression system for Claude Code - persist context across sessions\", \"keywords\": \"claude\", \"claude-code\", \"claude-agent-sdk\", \"mcp\", \"plugin\", \"memory\", \"compression\", \"knowledge-graph\", \"transcript\", \"typescript\", \"nodejs\" , \"author\": \"Alex Newman\", \"license\": \"Apache-2.0\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/thedotmack/claude-mem.git\" }, \"homepage\": \"https://github.com/thedotmack/claude-mem readme\", \"bugs\": { \"url\": \"https://github.com/thedotmack/claude-mem/issues\" }, \"type\": \"module\", \"bin\": { \"claude-mem\": \"./dist/npx-cli/index.js\" }, \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"import\": \".… 证据：`package.json`\n- **Package**（package_manifest）：{ \"name\": \"claude-mem-plugin\", \"version\": \"13.2.0\", \"private\": true, \"description\": \"Runtime dependencies for claude-mem bundled hooks\", \"type\": \"module\", \"dependencies\": { \"zod\": \"^4.3.6\", \"tree-sitter-cli\": \"^0.26.5\", \"tree-sitter-c\": \"^0.24.1\", \"tree-sitter-cpp\": \"^0.23.4\", \"tree-sitter-go\": \"^0.25.0\", \"tree-sitter-java\": \"^0.23.5\", \"tree-sitter-javascript\": \"^0.25.0\", \"tree-sitter-python\": \"^0.25.0\", \"tree-sitter-ruby\": \"^0.23.1\", \"tree-sitter-rust\": \"^0.24.0\", \"tree-sitter-typescript\": \"^0.23.2\", \"tree-sitter-kotlin\": \"^0.3.8\", \"tree-sitter-swift\": \"^0.7.1\", \"tree-sitter-php\": \"^0.24.2\", \"tree-sitter-elixir\": \"^0.3.5\", \"@tree-sitter-grammars/tree-sitter-lua\": \"^0.4.1\", \"tree-sitter-sca… 证据：`plugin/package.json`\n- **Claude-Mem OpenClaw Plugin — Setup Guide**（skill_instruction）：Claude-Mem OpenClaw Plugin — Setup Guide 证据：`openclaw/SKILL.md`\n- **Babysit PR**（skill_instruction）：Stay with the PR until it is actually clean. Do not stop after one check pass if comments or review threads are still unresolved. 证据：`plugin/skills/babysit/SKILL.md`\n- **Do Plan**（skill_instruction）：You are an ORCHESTRATOR. Deploy subagents to execute all work. Do not do the work yourself except to coordinate, route context, and verify that each subagent completed its assigned checklist. 证据：`plugin/skills/do/SKILL.md`\n- **How claude-mem works**（skill_instruction）：Every Read, Edit, and Bash that Claude makes turns into a compressed observation. Observations get summarized at session end. Relevant ones get auto-injected into future prompts so the next session starts with context from the last one — no re-explaining the codebase, no re-discovering decisions. 证据：`plugin/skills/how-it-works/SKILL.md`\n- **Knowledge Agent**（skill_instruction）：Build and query AI-powered knowledge bases from claude-mem observations. 证据：`plugin/skills/knowledge-agent/SKILL.md`\n- **Learn Codebase**（skill_instruction）：Please learn about the codebase by systematically and thoroughly reading EVERY SOURCE FILE IN FULL, no matter how many there are. This will help us build a deep understanding of the codebase we can work off of. This is critical and non negotiable. 证据：`plugin/skills/learn-codebase/SKILL.md`\n- **Make Plan**（skill_instruction）：You are an ORCHESTRATOR. Create an LLM-friendly plan in phases that can be executed consecutively in new chat contexts. 证据：`plugin/skills/make-plan/SKILL.md`\n- **Memory Search**（skill_instruction）：Search past work across all sessions. Simple workflow: search - filter - fetch. 证据：`plugin/skills/mem-search/SKILL.md`\n- **Pathfinder**（skill_instruction）：You are an ORCHESTRATOR. Map the codebase into feature-grouped flowcharts, identify duplicated concerns, propose the simplest unified architecture, and hand off per-system plans to /make-plan . 证据：`plugin/skills/pathfinder/SKILL.md`\n- **Smart Explore**（skill_instruction）：Structural code exploration using AST parsing. This skill overrides your default exploration behavior. While this skill is active, use smart search/smart outline/smart unfold as your primary tools instead of Read, Grep, and Glob. 证据：`plugin/skills/smart-explore/SKILL.md`\n- **Timeline Report**（skill_instruction）：Generate a comprehensive narrative analysis of a project's entire development history using claude-mem's persistent memory timeline. 证据：`plugin/skills/timeline-report/SKILL.md`\n- **Version Bump & Release Workflow**（skill_instruction）：IMPORTANT: Plan and write detailed release notes before starting. 证据：`plugin/skills/version-bump/SKILL.md`\n- **Wowerpoint**（skill_instruction）：One doc in, one PDF out. Slide-deck only — videos and podcasts from the same engine are noticeably worse and out of scope; refer the user to the notebooklm CLI directly if they want those. 证据：`plugin/skills/wowerpoint/SKILL.md`\n- **Marketplace**（structured_config）：{ \"name\": \"thedotmack\", \"owner\": { \"name\": \"Alex Newman\" }, \"metadata\": { \"description\": \"Plugins by Alex Newman thedotmack \", \"homepage\": \"https://github.com/thedotmack/claude-mem\" }, \"plugins\": { \"name\": \"claude-mem\", \"version\": \"13.2.0\", \"source\": \"./plugin\", \"description\": \"Persistent memory system for Claude Code - context compression across sessions\" } } 证据：`.claude-plugin/marketplace.json`\n- **Plugin**（structured_config）：{ \"name\": \"claude-mem\", \"version\": \"13.2.0\", \"description\": \"Memory compression system for Claude Code - persist context across sessions\", \"author\": { \"name\": \"Alex Newman\" }, \"repository\": \"https://github.com/thedotmack/claude-mem\", \"license\": \"Apache-2.0\", \"keywords\": \"claude\", \"claude-code\", \"claude-agent-sdk\", \"mcp\", \"plugin\", \"memory\", \"compression\", \"knowledge-graph\", \"transcript\", \"typescript\", \"nodejs\" , \"homepage\": \"https://github.com/thedotmack/claude-mem readme\" } 证据：`.claude-plugin/plugin.json`\n- **Plugin**（structured_config）：{ \"name\": \"claude-mem\", \"version\": \"13.2.0\", \"description\": \"Memory compression system for Claude Code - persist context across sessions\", \"author\": { \"name\": \"Alex Newman\", \"url\": \"https://github.com/thedotmack\" }, \"homepage\": \"https://github.com/thedotmack/claude-mem readme\", \"repository\": \"https://github.com/thedotmack/claude-mem\", \"license\": \"Apache-2.0\", \"keywords\": \"claude\", \"claude-code\", \"claude-agent-sdk\", \"mcp\", \"plugin\", \"memory\", \"compression\", \"knowledge-graph\", \"transcript\", \"typescript\", \"nodejs\" , \"skills\": \"./plugin/skills/\", \"mcpServers\": \"./.mcp.json\", \"hooks\": \"./plugin/hooks/codex-hooks.json\", \"interface\": { \"displayName\": \"claude-mem\", \"shortDescription\": \"Persistent m… 证据：`.codex-plugin/plugin.json`\n- **Marketplace**（structured_config）：{ \"name\": \"claude-mem-local\", \"interface\": { \"displayName\": \"claude-mem local \" }, \"plugins\": { \"name\": \"claude-mem\", \"source\": { \"source\": \"local\", \"path\": \"./plugin\" }, \"policy\": { \"installation\": \"AVAILABLE\", \"authentication\": \"ON INSTALL\" }, \"category\": \"Productivity\" } } 证据：`.agents/plugins/marketplace.json`\n- **Plugin**（structured_config）：{ \"name\": \"claude-mem\", \"version\": \"13.2.0\", \"description\": \"Memory compression system for Claude Code - persist context across sessions\", \"author\": { \"name\": \"Alex Newman\" }, \"repository\": \"https://github.com/thedotmack/claude-mem\", \"license\": \"Apache-2.0\", \"keywords\": \"claude\", \"claude-code\", \"claude-agent-sdk\", \"mcp\", \"plugin\", \"memory\", \"compression\", \"knowledge-graph\", \"transcript\", \"typescript\", \"nodejs\" , \"homepage\": \"https://github.com/thedotmack/claude-mem readme\" } 证据：`plugin/.claude-plugin/plugin.json`\n- **Plugin**（structured_config）：{ \"name\": \"claude-mem\", \"version\": \"13.2.0\", \"description\": \"Memory compression system for Claude Code - persist context across sessions\", \"author\": { \"name\": \"Alex Newman\", \"url\": \"https://github.com/thedotmack\" }, \"homepage\": \"https://github.com/thedotmack/claude-mem readme\", \"repository\": \"https://github.com/thedotmack/claude-mem\", \"license\": \"Apache-2.0\", \"keywords\": \"claude\", \"claude-code\", \"claude-agent-sdk\", \"mcp\", \"plugin\", \"memory\", \"compression\", \"knowledge-graph\", \"transcript\", \"typescript\", \"nodejs\" , \"skills\": \"./skills/\", \"mcpServers\": \"./.mcp.json\", \"hooks\": \"./hooks/codex-hooks.json\", \"interface\": { \"displayName\": \"claude-mem\", \"shortDescription\": \"Persistent memory and cont… 证据：`plugin/.codex-plugin/plugin.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`ragtime/LICENSE`\n- **Session ID Architecture**（documentation）：Claude-mem uses two distinct session IDs to track conversations and memory: 证据：`docs/SESSION_ID_ARCHITECTURE.md`\n- **Adapters**（documentation）：Claude Code hook payloads are mapped through src/adapters/claude-code/mapper.ts into AgentEvent records. The mapper preserves legacy fields such as contentSessionId , tool name , tool input , tool response , cwd , agentId , agentType , platformSource , and both tool use id and toolUseId . 证据：`docs/adapters.md`\n- **Error Handling Anti-Pattern Cleanup Plan**（documentation）：Error Handling Anti-Pattern Cleanup Plan 证据：`docs/anti-pattern-cleanup-plan.md`\n- **Server API**（documentation）：REST V1 is mounted under /v1 ; legacy worker routes remain under /api . 证据：`docs/api.md`\n- **claude-mem Architecture Overview**（documentation）：Event Handler What it does Timeout ------- --------- ------------- --------- Setup version-check.js Sub-100ms version-marker check; prompts npx claude-mem repair on mismatch 60s SessionStart worker start + context Start worker service and inject context 60s UserPromptSubmit session-init Register session + start SDK agent + semantic injection 60s PostToolUse observation Capture tool usage - enqueue in worker 120s Summary summarize Request session summary from SDK agent 120s SessionEnd session-complete End session + drain pending messages 30s 证据：`docs/architecture-overview.md`\n- **Docker**（documentation）：The root docker-compose.yml starts Claude-Mem Server beta with a persistent Valkey sidecar. 证据：`docs/docker.md`\n- **IP Boundary**（documentation）：Claude-Mem uses an open-core structure. 证据：`docs/ip-boundary.md`\n- **License**（documentation）：Claude-Mem is licensed under the Apache License 2.0. 证据：`docs/license.md`\n- **Worker To Server Migration**（documentation）：Claude-Mem 13 keeps the worker path in place. Server beta is an additional runtime option for teams, deployable containers, API keys, and BullMQ/Valkey queues. 证据：`docs/migration-worker-to-server.md`\n- **claude-mem Production Guide**（documentation）：Practical guide based on 23 days of production usage with 3,400+ observations across two physical servers and 8 projects. 证据：`docs/production-guide.md`\n- **Security**（documentation）：Server beta defaults to API-key auth. CLAUDE MEM AUTH MODE=local-dev only enables the loopback development bypass when CLAUDE MEM ALLOW LOCAL DEV BYPASS=1 is also set; do not use it behind a reverse proxy or on a publicly reachable bind address. 证据：`docs/security.md`\n- **Server-Beta: Architecture, Team Vision, and the \"It Just Works\" Future**（documentation）：Server-Beta: Architecture, Team Vision, and the \"It Just Works\" Future 证据：`docs/server-beta-architecture-and-team-vision.md`\n- **Server Beta Parity Map**（documentation）：This document enumerates every legacy worker HTTP route under /api/ and records its status in the Server beta runtime Phase 9 onwards . 证据：`docs/server-beta-parity-map.md`\n- **Server Beta — Release Readiness Report**（documentation）：Server Beta — Release Readiness Report 证据：`docs/server-beta-release-readiness.md`\n- **Server Storage Boundary**（documentation）：Phase 4 adds the contracts and SQLite tables for the future server-owned storage model. It is additive only: worker routes, providers, existing search, and legacy observation writes still use the current sdk sessions , observations , session summaries , user prompts , and pending messages tables. 证据：`docs/server-storage-boundary.md`\n- **Claude-Mem Server Beta**（documentation）：Claude-Mem Server is the beta server runtime for Claude-Mem 13. It is a Postgres-backed, BullMQ-driven, API-key-authenticated runtime that replaces the legacy claude-mem worker for deployable use cases. 证据：`docs/server.md`\n- **Bug Report**（documentation）：Summary: Claude SDK Agent fails to start on Windows when the user's path contains spaces e.g., C:\\Users\\Anderson Wang\\ , causing PostToolUse hooks to hang indefinitely. 证据：`docs/bug-fixes/windows-spaces-issue.md`\n- **TypeScript SDK V2 interface preview**（documentation）：TypeScript SDK V2 interface preview 证据：`docs/context/agent-sdk-v2-preview.md`\n- **Hooks**（documentation）：Hooks let you observe, control, and extend the agent loop using custom scripts. Hooks are spawned processes that communicate over stdio using JSON in both directions. They run before or after defined stages of the agent loop and can observe, block, or modify behavior. 证据：`docs/context/cursor-hooks-reference.md`\n- **بداية سريعة**（documentation）：🇨🇳 中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇧🇷 Português • 🇰🇷 한국어 • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français 🇮🇱 עברית • 🇸🇦 العربية • 🇷🇺 Русский • 🇵🇱 Polski • 🇨🇿 Čeština • 🇳🇱 Nederlands • 🇹🇷 Türkçe • 🇺🇦 Українська • 🇻🇳 Tiếng Việt • 🇮🇩 Indonesia • 🇹🇭 ไทย • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇷🇴 Română • 🇸🇪 Svenska • 🇮🇹 Italiano • 🇬🇷 Ελληνικά • 🇭🇺 Magyar • 🇫🇮 Suomi • 🇩🇰 Dansk • 🇳🇴 Norsk 证据：`docs/i18n/README.ar.md`\n- **দ্রুত শুরু**（documentation）：🌐 এটি একটি স্বয়ংক্রিয় অনুবাদ। সম্প্রদায়ের সংশোধন স্বাগত জানাই! 证据：`docs/i18n/README.bn.md`\n- **Rychlý start**（documentation）：🌐 Toto je automatický překlad. Komunitní opravy jsou vítány! 证据：`docs/i18n/README.cs.md`\n- **Hurtig Start**（documentation）：🌐 Dette er en automatisk oversættelse. Fællesskabsrettelser er velkomne! 证据：`docs/i18n/README.da.md`\n- **Schnellstart**（documentation）：🌐 Dies ist eine automatisierte Übersetzung. Korrekturen aus der Community sind willkommen! 证据：`docs/i18n/README.de.md`\n- **Γρήγορη Εκκίνηση**（documentation）：🌐 Αυτή είναι μια αυτοματοποιημένη μετάφραση. Καλώς ορίζονται οι διορθώσεις από την κοινότητα! 证据：`docs/i18n/README.el.md`\n- **Inicio Rápido**（documentation）：🌐 Esta es una traducción automática. ¡Las correcciones de la comunidad son bienvenidas! 证据：`docs/i18n/README.es.md`\n- **Pikaopas**（documentation）：🌐 Tämä on automaattinen käännös. Yhteisön korjaukset ovat tervetulleita! 证据：`docs/i18n/README.fi.md`\n- **Démarrage rapide**（documentation）：🌐 Ceci est une traduction automatisée. Les corrections de la communauté sont les bienvenues ! 证据：`docs/i18n/README.fr.md`\n- **התחלה מהירה**（documentation）：🌐 זהו תרגום אוטומטי. תיקונים מהקהילה יתקבלו בברכה! 证据：`docs/i18n/README.he.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`CLAUDE.md`, `README.md`, `cursor-hooks/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`CLAUDE.md`, `README.md`, `cursor-hooks/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, CLAUDE.md, docs/architecture-overview.md\n- **核心概念**：importance `high`\n - source_paths: src/core/schemas/memory-item.ts, src/core/schemas/session.ts, src/services/context/ObservationCompiler.ts, src/services/context/types.ts\n- **系统架构**：importance `high`\n - source_paths: docs/architecture-overview.md, docs/SESSION_ID_ARCHITECTURE.md, src/services/server/Server.ts, src/services/worker-service.ts\n- **Worker 服务**：importance `high`\n - source_paths: src/services/worker-service.ts, src/services/worker/SessionManager.ts, src/services/worker/FormattingService.ts, src/services/worker/agents/ResponseProcessor.ts, src/services/worker/http/routes\n- **数据存储层**：importance `high`\n - source_paths: src/services/sqlite/Database.ts, src/services/sqlite/schema.sql, src/services/sqlite/Sessions.ts, src/services/sqlite/Observations.ts, src/services/sync/ChromaSync.ts\n- **搜索系统**：importance `high`\n - source_paths: src/services/worker/search/SearchOrchestrator.ts, src/services/worker/search/strategies/HybridSearchStrategy.ts, src/services/worker/search/TimelineBuilder.ts, src/services/sqlite/observations/get.ts, src/server/mcp/tools.ts\n- **生命周期钩子系统**：importance `high`\n - source_paths: src/cli/handlers, src/cli/hook-command.ts, src/shared/hook-constants.ts, src/shared/hook-settings.ts, plugin/hooks/hooks.json\n- **MCP 集成**：importance `high`\n - source_paths: src/server/mcp/tools.ts, src/server/mcp/register.ts, src/server/mcp/resources.ts, src/server/mcp/prompts.ts, src/servers/mcp-server.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `37d24944af5f4afaa0de2b0bd0034bb432f2b714`\n- inspected_files: `package.json`, `README.md`, `docker-compose.yml`, `docs/ip-boundary.md`, `docs/SESSION_ID_ARCHITECTURE.md`, `docs/server-storage-boundary.md`, `docs/adapters.md`, `docs/security.md`, `docs/api.md`, `docs/server-beta-release-readiness.md`, `docs/production-guide.md`, `docs/server.md`, `docs/docker.md`, `docs/architecture-overview.md`, `docs/server-beta-architecture-and-team-vision.md`, `docs/anti-pattern-cleanup-plan.md`, `docs/migration-worker-to-server.md`, `docs/server-beta-parity-map.md`, `docs/license.md`, `docs/context/agent-sdk-v2-preview.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_28646536cf7d499aadab2346c2666f89 | https://github.com/thedotmack/claude-mem/issues/2389 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Windows: cmd.exe /c uvx wrapper breaks Chroma MCP stdio on WinGet uv installs (regression after #1190 / #1199) --> FIX…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows: cmd.exe /c uvx wrapper breaks Chroma MCP stdio on WinGet uv installs (regression after #1190 / #1199) --> FIX attacched\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_a6c844000d9b4adead4a2fdb73660c8d | https://github.com/thedotmack/claude-mem/issues/2426 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：[Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_9e74ac48a1744106a07ff519ad2d2773 | https://github.com/thedotmack/claude-mem/issues/2437 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v13: merged_into_project migration silently skipped on pre-existing DBs (schema_versions ≤ 23)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13: merged_into_project migration silently skipped on pre-existing DBs (schema_versions ≤ 23)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_510ecb03a1de412f940987e370c68fac | https://github.com/thedotmack/claude-mem/issues/2433 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Use node to run mcp for windows environment\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Use node to run mcp for windows environment\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_95d37c5d34a749f7a25fdd5fe1dc7969 | https://github.com/thedotmack/claude-mem/issues/2446 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_77fdc7c371f042eeb70fbeb52a7a2788 | https://github.com/thedotmack/claude-mem/issues/2438 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：自动运行时突然报下图所示内容，然后插件就不能用了\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：自动运行时突然报下图所示内容，然后插件就不能用了\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2d5aa43a4c5a4e46a0f2122dea46947a | https://github.com/thedotmack/claude-mem/issues/2441 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：[Bug] Codex CLI plugin hooks consume Claude Code session quota via Claude Code SDK\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] Codex CLI plugin hooks consume Claude Code session quota via Claude Code SDK\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_8b77cb6420d845a9bd38852571b6adbd | https://github.com/thedotmack/claude-mem/issues/2431 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：Codex CLI: PreToolUse hook returned unsupported suppressOutput\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex CLI: PreToolUse hook returned unsupported suppressOutput\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_9022a732f6e54ba39309c5377cf2d8fa | https://github.com/thedotmack/claude-mem/issues/2360 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：[feat] Option to load only memory-related skills\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[feat] Option to load only memory-related skills\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_efa30fc4873343aea26f804c8d1113ec | https://github.com/thedotmack/claude-mem/issues/2448 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：thedotmack/claude-mem\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：claude, claude_code\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Windows: cmd.exe /c uvx wrapper breaks Chroma MCP stdio on WinGet uv installs (regression after #1190 / #1199) --> FIX…（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：v13: merged_into_project migration silently skipped on pre-existing DBs (schema_versions ≤ 23)（high）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Use node to run mcp for windows environment（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/thedotmack/claude-mem 项目说明书\n\n生成时间：2026-05-13 15:15:44 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [核心概念](#page-concepts)\n- [系统架构](#page-architecture)\n- [Worker 服务](#page-worker-service)\n- [数据存储层](#page-data-storage)\n- [搜索系统](#page-search-system)\n- [生命周期钩子系统](#page-hooks-system)\n- [MCP 集成](#page-mcp-integration)\n- [IDE 集成](#page-ide-integrations)\n- [安装与部署](#page-installation)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [核心概念](#page-concepts)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n- [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n- [src/ui/viewer/components/ContextSettingsModal.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ContextSettingsModal.tsx)\n- [scripts/translate-readme/README.md](https://github.com/thedotmack/claude-mem/blob/main/scripts/translate-readme/README.md)\n\n
\n\n# 项目概述\n\n## 项目简介\n\nClaude-Mem 是一个为 Claude Code 设计的持久化记忆系统，能够在不同会话之间自动保存和恢复上下文信息。该项目使 Claude Code 能够在会话结束后保留对项目的理解和学习成果，从而在新的会话中继续利用这些知识。资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n\n## 核心功能\n\n### 自动上下文保存\n\nClaude-Mem 在用户使用 Claude Code 的过程中自动捕获工具使用和观察结果，生成语义摘要，并在后续会话中提供这些信息。这使得 AI 能够维持对项目的连续性理解，即使在会话结束或重新连接后也能保留关键知识。资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n\n### 观察记录系统\n\n系统通过 `Observation` 数据模型记录每次重要的交互和发现。观察记录包含以下结构化字段：\n\n| 字段名 | 描述 |\n|--------|------|\n| `id` | 观察记录的唯一标识符 |\n| `tool_name` | 触发的工具名称 |\n| `tool_input` | 工具输入参数 |\n| `tool_output` | 工具执行结果 |\n| `title` | 观察标题 |\n| `subtitle` | 观察副标题 |\n| `facts` | 从观察中提取的关键事实列表 |\n| `narrative` | 叙述性描述 |\n| `concepts` | 相关的概念标签列表 |\n| `files_read` | 读取的文件路径列表 |\n| `files_modified` | 修改的文件路径列表 |\n\n资料来源：[src/server/generation/providers/shared/prompt-builder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/providers/shared/prompt-builder.ts)\n\n### 摘要生成\n\n系统支持生成会话级别的摘要（Summary），包含以下关键信息：\n\n| 字段名 | 描述 |\n|--------|------|\n| `request` | 用户原始请求 |\n| `investigated` | 已调查的内容 |\n| `learned` | 学习到的新知识 |\n| `completed` | 已完成的任务 |\n| `next_steps` | 后续步骤建议 |\n| `notes` | 附加备注 |\n\n资料来源：[src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)\n\n## 系统架构\n\nClaude-Mem 采用模块化架构，主要包含以下核心模块：\n\n```mermaid\ngraph TD\n A[Claude Code] <--> B[NPM CLI 模块]\n A <--> C[SDK 模块]\n B <--> D[Worker Service]\n C <--> D\n D <--> E[UI Viewer]\n D <--> F[存储层 ~/.claude-mem]\n```\n\n### SDK 模块\n\nSDK 模块负责生成 AI 可读的提示模板，支持观察记录和摘要的 XML 格式输出。该模块的核心功能包括：\n\n- **观察提示构建**：`buildObservationPrompt()` 函数生成用于引导 AI 生成观察记录的提示模板\n- **摘要提示构建**：`buildSummaryPrompt()` 函数生成用于生成会话摘要的提示模板\n- **继续提示构建**：`buildContinuationPrompt()` 函数处理跨会话的上下文延续\n\n资料来源：[src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)\n\n### 服务器端生成模块\n\n服务器端负责实际调用 AI 模型生成观察记录和摘要，主要通过 `prompt-builder.ts` 实现：\n\n- XML 格式的输出模式定义\n- 私有内容检测与脱敏处理\n- 活动模式（Mode）管理\n- 观察类型的灵活配置\n\n资料来源：[src/server/generation/providers/shared/prompt-builder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/providers/shared/prompt-builder.ts)\n\n### UI Viewer 模块\n\nUI 模块提供了一个可视化界面，用于浏览和管理记忆内容：\n\n| 组件 | 功能描述 |\n|------|----------|\n| `App.tsx` | 主应用容器，管理整体状态和路由 |\n| `SummaryCard.tsx` | 展示会话摘要卡片 |\n| `ObservationCard.tsx` | 展示观察记录卡片 |\n| `ContextSettingsModal.tsx` | 上下文加载设置模态框 |\n| `LogsModal.tsx` | 控制台日志查看器 |\n| `Header.tsx` | 应用头部导航 |\n\n资料来源：[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)\n\n### NPM CLI 模块\n\n命令行接口模块提供安装和管理功能：\n\n- `install` 命令：安装插件到 Claude Code、设置 worker 服务\n- `start` 命令：启动 worker 服务\n- `status` 命令：检查服务状态\n\n资料来源：[src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n## 安装与配置\n\n### 安装方式\n\nClaude-Mem 支持多种安装方式：\n\n| 安装方式 | 命令/步骤 |\n|----------|-----------|\n| 标准安装 | `npx claude-mem install` |\n| Gemini CLI | `npx claude-mem install --ide gemini-cli` |\n| OpenCode | `npx claude-mem install --ide opencode` |\n| Claude Code 插件市场 | `/plugin marketplace add thedotmack/claude-mem` 然后 `/plugin install claude-mem` |\n\n资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n\n### 上下文设置\n\n用户可以通过 UI 的 ContextSettingsModal 配置以下参数：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | 50 | 注入的观察记录数量（1-200） |\n| `CLAUDE_MEM_CONTEXT_SESSIONS` | 待确认 | 提取观察的会话数量范围 |\n\n资料来源：[src/ui/viewer/components/ContextSettingsModal.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ContextSettingsModal.tsx)\n\n## 首次使用流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as Claude Code CLI\n participant Worker as Worker Service\n participant Viewer as UI Viewer\n participant Storage as ~/.claude-mem\n\n User->>CLI: 运行 npx claude-mem install\n CLI->>Worker: 启动 Worker Service\n Worker->>Viewer: 打开浏览器管理界面\n User->>CLI: 开始第一个会话\n CLI->>Storage: 捕获观察记录\n Storage->>Worker: 存储观察数据\n User->>CLI: 开始第二个会话\n Worker->>CLI: 注入历史上下文\n CLI->>User: 显示上下文增强的响应\n```\n\n资料来源：[src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n## 数据存储\n\n所有数据默认存储在本地 `~/.claude-mem` 目录中，确保用户对数据拥有完全控制权。存储内容包括：\n\n- 观察记录（Observations）\n- 会话摘要（Summaries）\n- 用户设置\n- 日志文件\n\n## 技术栈\n\n| 层级 | 技术选型 |\n|------|----------|\n| 语言 | TypeScript |\n| 包管理 | npm |\n| UI 框架 | React |\n| 构建工具 | Vite |\n| 样式 | CSS Variables |\n| 数据格式 | XML（用于 AI 输出） |\n\n## 观察类型系统\n\n系统支持可配置的观察类型，通过 `observation_types` 定义。不同模式下可以定义不同的观察类型以适应特定场景需求。资料来源：[src/server/generation/providers/shared/prompt-builder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/providers/shared/prompt-builder.ts)\n\n## 相关资源\n\n- 官方文档：https://docs.claude-mem.ai\n- 项目主页：https://github.com/thedotmack/claude-mem\n- X (Twitter)：@Claude_Memory\n\n---\n\n\n\n## 核心概念\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [数据存储层](#page-data-storage)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n- [src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)\n- [src/ui/viewer/components/SummaryCard.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/SummaryCard.tsx)\n- [src/ui/viewer/components/ObservationCard.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ObservationCard.tsx)\n- [src/ui/viewer/components/ContextSettingsModal.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ContextSettingsModal.tsx)\n- [src/ui/viewer/App.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/App.tsx)\n- [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n- [src/server/generation/providers/shared/prompt-builder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/providers/shared/prompt-builder.ts)\n\n
\n\n# 核心概念\n\nClaude-Mem 是一个为 Claude Code 和 Gemini CLI 提供持久化记忆功能的插件系统。本页介绍其核心概念、数据模型和工作机制。\n\n## 系统架构概览\n\nClaude-Mem 采用客户端-服务端架构，包含以下核心组件：\n\n```mermaid\ngraph TD\n A[Claude Code / Gemini CLI] --> B[Worker Service]\n B --> C[Memory Storage相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/schemas/memory-item.ts](https://github.com/thedotmack/claude-mem/blob/main/src/core/schemas/memory-item.ts)\n- [src/ui/viewer/components/ObservationCard.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ObservationCard.tsx)\n- [src/ui/viewer/components/SummaryCard.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/SummaryCard.tsx)\n- [src/services/context/types.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/context/types.ts)\n- [src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)\n~/.claude-mem]\n B --> D[Context Compiler]\n D --> A\n C --> E[ObservationCompiler]\n E --> D\n```\n\n| 组件 | 功能 |\n|------|------|\n| Worker Service | 运行在端口 37777 的后台服务，处理记忆存储和检索 |\n| Memory Storage | 存储在 `~/.claude-mem` 目录下的 SQLite 数据库 |\n| Context Compiler | 将历史记忆编译为可注入的上下文格式 |\n| SDK Prompts | 构建用于生成记忆的提示词 |\n\n## 记忆项目（Memory Item）\n\nMemory Item 是 Claude-Mem 中存储记忆的基本单位。\n\n### 数据模型\n\n```typescript\n// 资料来源：src/core/schemas/memory-item.ts\nexport type MemoryItemKind = z.infer
\n {concepts.map((concept: string, i: number) => (\n {concept}\n ))}\n {filesRead.length > 0 && (\n \n read: {filesRead.join(', ')}\n \n )}\n
\n)}\n```\n\n## 会话摘要（Summary）\n\nSummary 是对整个会话的总结性描述。\n\n### 摘要结构\n\n```xml\n\n \n
\n {section.label}
\n\n {section.content}\n
\n \n))}\n```\n\n## 上下文编译（Context Compilation）\n\nContext Compiler 负责将存储的记忆转换为可注入到 Claude 会话的格式。\n\n### 编译流程\n\n```mermaid\ngraph LR\n A[Memory Storage] --> B[Query & Filter]\n B --> C[ObservationCompiler]\n C --> D[Format as XML]\n D --> E[Inject to Session]\n```\n\n### 上下文配置\n\n用户可以通过环境变量配置上下文注入行为：\n\n| 配置项 | 默认值 | 说明 | 资料来源 |\n|--------|--------|------|----------|\n| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | 50 | 注入的观察记录数量（1-200） | src/ui/viewer/components/ContextSettingsModal.tsx |\n| `CLAUDE_MEM_CONTEXT_SESSIONS` | 10 | 提取观察的会话数量（1-50） | src/ui/viewer/components/ContextSettingsModal.tsx |\n\n### 提示词构建\n\nSDK 使用结构化的提示词模板生成记忆：\n\n```typescript\n// 资料来源：src/sdk/prompts.ts\n${mode.prompts.output_format_header}\n\n\n
\n\n# 系统架构\n\n## 概述\n\nClaude-Mem 是一个为 Claude Code 提供持久化记忆功能的插件系统，其核心目标是实现跨会话的上下文连续性。该系统通过自动捕获工具使用观察、生成语义摘要，使 Claude 能够在会话结束后或重新连接时保持对项目的知识连续性。 资料来源：[README.md:1-10]()\n\n系统架构采用插件化设计，支持多种 IDE 环境集成，包括 Claude Code、Gemini CLI 和 OpenCode。数据存储在本地文件系统（`~/.claude-mem`），确保用户对数据的完全控制。 资料来源：[README.md:28-35]()\n\n## 核心组件架构\n\nClaude-Mem 的系统架构由以下核心层次组成：\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n IDE[IDE 插件集成]\n CLI[NPX CLI 工具]\n end\n \n subgraph \"服务层\"\n Worker[Worker Service]\n Server[Server 服务]\n PromptBuilder[Prompt Builder]\n end\n \n subgraph \"SDK 层\"\n PromptSDK[Prompts SDK]\n ObservationSDK[Observation SDK]\n end\n \n subgraph \"UI 层\"\n ViewerApp[Viewer 应用]\n SummaryCard[摘要卡片]\n ObservationCard[观察卡片]\n SettingsModal[设置模态框]\n end\n \n subgraph \"数据层\"\n Storage[本地存储 ~/.claude-mem]\n SessionData[会话数据]\n ObservationData[观察数据]\n end\n \n IDE --> Worker\n CLI --> Worker\n Worker --> Server\n Server --> PromptBuilder\n Server --> Storage\n PromptBuilder --> PromptSDK\n ViewerApp --> Server\n ViewerApp --> SettingsModal\n```\n\n### 组件职责矩阵\n\n| 组件 | 类型 | 主要职责 | 源码位置 |\n|------|------|----------|----------|\n| Worker Service | 服务进程 | 管理观察数据收集和处理的生命周期 | `src/services/worker-service.ts` |\n| Server | HTTP 服务 | 提供 REST API，处理记忆注入请求 | `src/services/server/Server.ts` |\n| Prompt Builder | 生成器 | 构建 LLM 提示词和输出模式 | `src/server/generation/providers/shared/prompt-builder.ts` |\n| Prompts SDK | SDK 模块 | 封装提示词构建逻辑 | `src/sdk/prompts.ts` |\n| Viewer App | React 应用 | 提供记忆查看器 UI | `src/ui/viewer/App.tsx` |\n\n## 数据流架构\n\n### 观察数据生命周期\n\n```mermaid\ngraph LR\n A[工具调用] --> B[观察捕获]\n B --> C[输入解析]\n C --> D[Prompt 构建]\n D --> E[LLM 处理]\n E --> F[结构化输出]\n F --> G[存储]\n G --> H[摘要生成]\n H --> I[上下文注入]\n```\n\n1. **观察捕获阶段**：系统监听 Claude Code 的工具调用事件，自动捕获工具输入和输出 资料来源：[src/server/generation/providers/shared/prompt-builder.ts:1-30]()\n2. **数据解析阶段**：对捕获的工具调用进行解析，提取关键信息并处理私有数据边界 资料来源：[src/server/generation/providers/shared/prompt-builder.ts:40-60]()\n3. **Prompt 构建阶段**：根据活动模式（Mode）配置构建符合 XML 格式的观察输出 资料来源：[src/sdk/prompts.ts:1-50]()\n4. **LLM 处理阶段**：使用配置的 LLM 模型生成语义化的观察摘要\n5. **存储阶段**：将处理后的数据持久化到本地存储\n6. **上下文注入阶段**：在新的会话中自动注入相关记忆\n\n### 上下文注入流程\n\n```mermaid\ngraph TD\n A[新会话开始] --> B{检查记忆缓存}\n B -->|首次会话| C[不注入历史]\n B -->|非首次会话| D[查询历史观察]\n D --> E[加载最近 N 条观察]\n D --> F[加载最近 M 个会话]\n E --> G[构建上下文 Prompt]\n F --> G\n G --> H[注入到系统提示]\n H --> I[开始新会话]\n \n C --> I\n```\n\n上下文注入可通过环境变量进行配置： 资料来源：[src/ui/viewer/components/ContextSettingsModal.tsx:30-60]()\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | 50 | 注入的观察数量（1-200） |\n| `CLAUDE_MEM_CONTEXT_SESSIONS` | 10 | 抽取观察的会话数量（1-50） |\n\n## 提示词生成架构\n\n### Prompt SDK 结构\n\n提示词生成采用模块化设计，支持多种模式配置： 资料来源：[src/sdk/prompts.ts:50-100]()\n\n```typescript\ninterface ModeConfig {\n prompts: {\n continuation_instruction: string;\n output_format_header: string;\n xml_title_placeholder: string;\n xml_subtitle_placeholder: string;\n xml_fact_placeholder: string;\n xml_narrative_placeholder: string;\n xml_concept_placeholder: string;\n xml_file_placeholder: string;\n type_guidance: string;\n field_guidance: string;\n concept_guidance: string;\n format_examples: string;\n footer: string;\n };\n observation_types: ObservationType[];\n}\n```\n\n### 输出模式构建\n\n观察输出采用 XML 格式，包含以下结构化字段： 资料来源：[src/server/generation/providers/shared/prompt-builder.ts:70-90]()\n\n```xml\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n- [src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)\n- [src/ui/viewer/App.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/App.tsx)\n- [src/ui/viewer/components/SummaryCard.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/SummaryCard.tsx)\n- [src/ui/viewer/components/ObservationCard.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ObservationCard.tsx)\n- [src/server/generation/providers/shared/prompt-builder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/providers/shared/prompt-builder.ts)\n- [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n- [src/ui/viewer/components/ContextSettingsModal.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ContextSettingsModal.tsx)\n\n
\n\n# Worker 服务\n\n## 概述\n\nWorker 服务是 claude-mem 系统中的核心后台处理组件，负责执行长期运行的任务队列、处理观察记录生成、以及管理会话上下文。该服务以独立进程方式运行，通过 BullMQ 与 Redis 进行进程间通信，实现高可靠性的任务处理能力。Worker 服务默认监听端口 37777，提供健康检查和状态监控接口。\n\nWorker 服务的核心职责包括：\n\n- 接收并处理来自主服务的任务队列请求\n- 管理会话的上下文信息和历史记录\n- 执行 LLM 响应处理和格式转换\n- 维护任务执行状态和进度通知\n- 处理失败任务的重试逻辑\n\n资料来源：[src/npx-cli/commands/install.ts:1-100]()\n\n## 核心组件\n\nWorker 服务由多个协同工作的子模块组成，每个模块承担特定的职责。\n\n### 组件架构表\n\n| 组件名称 | 文件路径 | 职责描述 |\n|---------|---------|---------|\n| SessionManager | `src/services/worker/SessionManager.ts` | 管理会话生命周期、上下文存储与检索 |\n| FormattingService | `src/services/worker/FormattingService.ts` | 处理观察记录的格式化和输出 |\n| ResponseProcessor | `src/services/worker/agents/ResponseProcessor.ts` | 处理 LLM 响应、提取结构化数据 |\n| HTTP Routes | `src/services/worker/http/routes` | 提供 RESTful API 接口 |\n| ServerJobQueue | `src/server/jobs/ServerJobQueue.ts` | 任务队列管理与 BullMQ 集成 |\n\n资料来源：[src/services/worker/SessionManager.ts](), [src/services/worker/FormattingService.ts](), [src/services/worker/agents/ResponseProcessor.ts]()\n\n## 任务队列架构\n\nWorker 服务基于 BullMQ 构建企业级任务队列系统，支持分布式处理和跨进程事件通知。\n\n### 队列工作流程\n\n```mermaid\ngraph TD\n A[主服务提交任务] --> B[ServerJobQueue 入队]\n B --> C[Redis 队列存储]\n C --> D[Worker 进程轮询]\n D --> E{任务类型判断}\n E -->|生成任务| F[Generation Worker]\n E -->|处理任务| G[Processing Worker]\n F --> H[LLM 调用]\n G --> I[数据处理]\n H --> J[ResponseProcessor]\n I --> J\n J --> K[格式化输出]\n K --> L[结果存储]\n L --> M[QueueEvents 通知]\n```\n\n### 事件处理机制\n\nWorker 服务通过 QueueEvents 订阅 Redis 发布/订阅通道，实现跨进程的可靠事件通知。\n\n主要事件类型：\n\n- **stalled**: 任务停滞检测，由 Worker 或 QueueEvents 触发\n- **progress**: 任务进度更新\n- **error**: 任务执行错误\n- **failed**: 任务最终失败\n\n```mermaid\ngraph LR\n A[Worker 进程] -->|w.on| B[stalled 事件]\n A -->|w.on| C[progress 事件]\n A -->|w.on| D[error 事件]\n A -->|w.on| E[failed 事件]\n F[QueueEvents] -->|events.on| G[跨进程 stalled 通知]\n G --> H[notifyStalled]\n```\n\n资料来源：[src/server/jobs/ServerJobQueue.ts:50-80]()\n\n### 任务重试策略\n\nWorker 实现智能重试机制，在任务失败时根据配置自动重试：\n\n```typescript\n// 伪代码示例，实际逻辑在 ServerJobQueue 中实现\n{\n attempts: 3, // 最大重试次数\n backoff: {\n type: 'exponential', // 指数退避\n delay: 2000 // 基础延迟 2 秒\n }\n}\n```\n\n## 配置与端口\n\n### 默认配置参数\n\n| 参数名 | 默认值 | 说明 |\n|-------|-------|------|\n| `CLAUDE_MEM_WORKER_PORT` | 37777 | Worker 服务监听端口 |\n| 队列前缀 | `cmem` | BullMQ 键名前缀 |\n| 最大并发 | 可配置 | 同时处理的任务数上限 |\n\n### 健康检查流程\n\nWorker 服务启动后通过端口 37777 提供健康检查端点：\n\n```mermaid\nsequenceDiagram\n participant CLI as Claude-Mem CLI\n participant Worker as Worker Service\n participant Redis as Redis\n \n CLI->>Worker: 检查端口 37777 连接\n alt 端口可达\n Worker-->>CLI: Worker 就绪\n CLI->>Worker: 启动完成提示\n else 端口不可达\n Worker-->>CLI: 仍在启动中\n CLI->>User: 提示等待 30 秒后重试\n end\n```\n\n资料来源：[src/npx-cli/commands/install.ts:20-60]()\n\n## 状态监控\n\n### 队列深度监控\n\nWorker 服务的 Header 组件持续监控队列状态，当存在待处理任务时显示队列气泡指示器：\n\n```tsx\n// 队列气泡显示逻辑\n{queueDepth > 0 && (\n 相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/jobs/ServerJobQueue.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/jobs/ServerJobQueue.ts)\n- [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n- [src/services/worker-service.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts)\n- [src/services/worker/SessionManager.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/SessionManager.ts)\n- [src/services/worker/FormattingService.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/FormattingService.ts)\n- [src/services/worker/agents/ResponseProcessor.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/agents/ResponseProcessor.ts)\n- [src/services/worker/http/routes](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/http/routes)\n\n {queueDepth}\n
\n)}\n```\n\n### 错误边界处理\n\nWorker 服务的 UI 组件实现了 ErrorBoundary 错误边界机制，确保单个组件错误不会导致整个界面崩溃：\n\n```tsx\nclass ErrorBoundary extends Component {\n state = { error: null, errorInfo: null };\n \n componentDidCatch(error, errorInfo) {\n this.setState({ error, errorInfo });\n }\n \n render() {\n if (this.state.error) {\n return \n
\n\n# 数据存储层\n\n## 概述\n\nclaude-mem 的数据存储层是整个记忆系统的核心基础设施，负责持久化会话数据、观察记录和语义向量。该层采用混合存储架构，结合 SQLite 的事务性数据存储和 Chroma 向量数据库的语义搜索能力，实现高效的数据读写和智能检索功能。\n\n数据存储层的主要职责包括：\n\n- **会话管理**：创建、更新和查询 Claude Code 会话记录\n- **观察持久化**：存储 AI 生成的观察条目（observations）\n- **语义同步**：将数据同步到向量数据库支持语义搜索\n- **上下文注入**：为新会话提供历史记忆上下文\n\n资料来源：[src/services/sqlite/Database.ts:1-50]()\n\n## 架构设计\n\n### 存储层组件\n\n数据存储层由以下核心组件构成：\n\n```mermaid\ngraph TD\n A[claude-mem SDK] --> B[SQLite 数据库]\n A --> C[Chroma 向量库]\n B --> D[sessions 表]\n B --> E[observations 表]\n B --> F[prompts 表]\n B --> G[summaries 表]\n C --> H[向量嵌入]\n E --> C\n I[Worker Service] --> B\n I --> C\n```\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| Database | `src/services/sqlite/Database.ts` | 数据库连接管理和初始化 |\n| Sessions | `src/services/sqlite/Sessions.ts` | 会话记录的 CRUD 操作 |\n| Observations | `src/services/sqlite/Observations.ts` | 观察数据的持久化 |\n| ChromaSync | `src/services/sync/ChromaSync.ts` | 与向量数据库的同步 |\n\n资料来源：[src/services/sqlite/schema.sql:1-20]()\n\n### 数据模型\n\n#### Sessions 表\n\n会话表存储每次 Claude Code 交互会话的元数据：\n\n```sql\nCREATE TABLE sessions (\n id TEXT PRIMARY KEY,\n project TEXT NOT NULL,\n server_session_id TEXT,\n created_at_epoch INTEGER NOT NULL,\n updated_at_epoch INTEGER NOT NULL,\n summary_id TEXT,\n mode TEXT,\n event_count INTEGER DEFAULT 0\n);\n```\n\n关键字段说明：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | TEXT | 会话唯一标识符 |\n| project | TEXT | 所属项目名称 |\n| server_session_id | TEXT | 服务端会话 ID |\n| created_at_epoch | INTEGER | 创建时间戳 |\n| updated_at_epoch | INTEGER | 最后更新时间戳 |\n| summary_id | TEXT | 关联的摘要记录 |\n| mode | TEXT | 当前模式配置 |\n| event_count | INTEGER | 事件计数 |\n\n资料来源：[src/services/sqlite/schema.sql:1-10]()\n\n#### Observations 表\n\n观察表是核心数据存储，记录 AI 生成的结构化观察：\n\n```sql\nCREATE TABLE observations (\n id TEXT PRIMARY KEY,\n session_id TEXT NOT NULL,\n project TEXT NOT NULL,\n type TEXT NOT NULL,\n title TEXT,\n subtitle TEXT,\n narrative TEXT,\n facts TEXT, -- JSON array\n concepts TEXT, -- JSON array\n files_read TEXT, -- JSON array\n files_modified TEXT, -- JSON array\n tool_name TEXT,\n tool_input TEXT,\n tool_output TEXT,\n occurred_at_epoch INTEGER NOT NULL,\n created_at_epoch INTEGER NOT NULL,\n is_summary_related INTEGER DEFAULT 0,\n FOREIGN KEY (session_id) REFERENCES sessions(id)\n);\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | TEXT | 观察记录唯一标识 |\n| session_id | TEXT | 所属会话 ID |\n| type | TEXT | 观察类型（如 code_analysis, bug_fix） |\n| title | TEXT | 观察标题 |\n| facts | TEXT | JSON 格式的事实列表 |\n| concepts | TEXT | JSON 格式的概念标签 |\n| files_read | TEXT | JSON 格式的读取文件列表 |\n| files_modified | TEXT | JSON 格式的修改文件列表 |\n| narrative | TEXT | 叙述性描述 |\n| tool_name | TEXT | 关联的工具名称 |\n| tool_input | TEXT | 工具输入（JSON 或文本） |\n| tool_output | TEXT | 工具输出（JSON 或文本） |\n\n资料来源：[src/services/sqlite/schema.sql:11-35]()\n\n## 核心模块详解\n\n### Database 模块\n\n`Database.ts` 是存储层的入口点，负责：\n\n- 建立 SQLite 数据库连接\n- 执行 schema 初始化\n- 提供事务支持\n- 管理数据库路径配置\n\n```typescript\n// 典型初始化流程\nconst db = new Database(appDataPath);\nawait db.initialize();\n```\n\n资料来源：[src/services/sqlite/Database.ts:1-30]()\n\n### Sessions 模块\n\n`Sessions.ts` 实现会话管理的核心逻辑：\n\n| 方法 | 功能 |\n|------|------|\n| createSession | 创建新会话记录 |\n| updateSession | 更新会话状态 |\n| getSession | 根据 ID 获取会话 |\n| listSessions | 列出项目的所有会话 |\n| deleteSession | 删除会话及关联数据 |\n\n会话查询支持按项目名称、时间范围和模式类型过滤。\n\n资料来源：[src/services/sqlite/Sessions.ts:1-50]()\n\n### Observations 模块\n\n`Observations.ts` 处理观察数据的读写操作：\n\n```mermaid\ngraph LR\n A[工具调用事件] --> B[ObservationParser]\n B --> C[存储到SQLite]\n C --> D[ChromaSync]\n D --> E[生成向量嵌入]\n E --> F[Chroma向量库]\n```\n\n关键功能包括：\n\n- 将工具输入/输出解析为结构化观察\n- 支持批量插入和分页查询\n- 维护观察与会话、摘要的关联关系\n\n资料来源：[src/services/sqlite/Observations.ts:1-60]()\n\n## 向量同步机制\n\n### ChromaSync 模块\n\n`ChromaSync.ts` 负责将 SQLite 中的观察数据同步到 Chroma 向量数据库：\n\n```mermaid\ngraph TD\n A[SQLite observations] --> B[ChromaSync]\n B --> C{同步状态检查}\n C -->|已同步| D[跳过]\n C -->|需同步| E[提取文本内容]\n E --> F[调用Embedding API]\n F --> G[生成向量]\n G --> H[存储到Chroma]\n H --> I[更新同步标记]\n```\n\n同步策略包括：\n\n- **增量同步**：仅同步新增或更新的记录\n- **批量处理**：分批处理大量数据避免内存溢出\n- **错误重试**：失败时自动重试机制\n\n资料来源：[src/services/sync/ChromaSync.ts:1-80]()\n\n### 向量搜索策略\n\n搜索策略模块实现了多种检索算法：\n\n| 策略 | 说明 | 适用场景 |\n|------|------|----------|\n| 语义相似度 | 基于向量余弦相似度 | 语义相关查询 |\n| 关键词匹配 | BM25 或全文索引 | 精确术语搜索 |\n| 混合搜索 | 向量 + 关键词融合 | 平衡精确与语义 |\n| 时间衰减 | 考虑时间因素的排序 | 最新相关 |\n\n资料来源：[src/services/worker/search/strategies](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/strategies)\n\n## 数据流\n\n### 写入流程\n\n```mermaid\nsequenceDiagram\n participant SDK as Claude SDK\n participant Worker as Worker Service\n participant SQLite as SQLite DB\n participant Chroma as Chroma\n \n SDK->>Worker: 发送工具调用事件\n Worker->>Worker: 解析为 Observation\n Worker->>SQLite: 存储观察记录\n Worker->>Chroma: 同步向量数据\n Chroma-->>Worker: 确认同步完成\n Worker-->>SDK: 返回处理结果\n```\n\n### 读取流程\n\n当新会话启动时，数据存储层提供上下文注入：\n\n1. 解析用户请求\n2. 根据配置选择观察数量和会话数量\n3. 执行向量相似度搜索\n4. 按时间排序和去重\n5. 注入到提示上下文\n\n资料来源：[src/services/sqlite/Observations.ts:60-100]()\n\n## 配置与优化\n\n### 存储路径\n\n默认数据库存储路径为应用数据目录：\n\n```bash\n# macOS\n~/Library/Application Support/claude-mem/\n\n# Linux\n~/.config/claude-mem/\n\n# Windows\n%APPDATA%/claude-mem/\n```\n\n### 性能考虑\n\n- **索引优化**：对 `session_id`、`project`、`occurred_at_epoch` 等字段建立索引\n- **批量写入**：使用事务批量提交减少 I/O\n- **连接池**：复用数据库连接减少开销\n\n资料来源：[src/services/sqlite/schema.sql:36-50]()\n\n## 相关文档\n\n- [安装指南](../getting-started/installation.md)\n- [API 参考](../api-reference/server-routes.md)\n- [搜索功能](../features/search.md)\n\n---\n\n\n\n## 搜索系统\n\n### 相关页面\n\n相关主题：[MCP 集成](#page-mcp-integration), [数据存储层](#page-data-storage)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/services/sqlite/Database.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Database.ts)\n- [src/services/sqlite/schema.sql](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/schema.sql)\n- [src/services/sqlite/Sessions.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Sessions.ts)\n- [src/services/sqlite/Observations.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Observations.ts)\n- [src/services/sync/ChromaSync.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sync/ChromaSync.ts)\n- [src/services/worker/search/strategies](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/strategies)\n\n
\n\n# 搜索系统\n\n## 概述\n\n搜索系统是 claude-mem 的核心功能模块，负责在历史观察记录、会话和提示词中进行语义检索。该系统通过混合搜索策略结合关键词匹配与语义理解，使用户能够快速定位跨越多个会话积累的项目知识。搜索结果不仅返回匹配的观察记录，还支持时间线构建、上下文预览和自动注入功能，使 AI 能够在新的会话中无缝利用历史上下文。\n\n## 架构设计\n\n### 系统组件\n\n搜索系统由多个协同工作的组件构成，形成从请求处理到结果返回的完整管道。\n\n| 组件名称 | 文件路径 | 职责描述 |\n|---------|---------|---------|\n| SearchOrchestrator | `src/services/worker/search/SearchOrchestrator.ts` | 搜索请求的统一入口，负责协调各搜索策略的执行 |\n| HybridSearchStrategy | `src/services/worker/search/strategies/HybridSearchStrategy.ts` | 实现混合搜索策略，结合关键词与语义检索 |\n| TimelineBuilder | `src/services/worker/search/TimelineBuilder.ts` | 构建搜索结果的时间线视图 |\n| 观察记录获取 | `src/services/sqlite/observations/get.ts` | 从 SQLite 数据库检索观察记录 |\n| MCP 工具层 | `src/server/mcp/tools.ts` | 提供 MCP 协议接口供外部调用搜索功能 |\n\n### 数据流向\n\n```mermaid\ngraph TD\n A[用户搜索请求] --> B[SearchOrchestrator]\n B --> C{HybridSearchStrategy}\n C --> D[关键词搜索]\n C --> E[语义向量搜索]\n D --> F[结果合并与排序]\n E --> F\n F --> G[TimelineBuilder]\n G --> H[搜索结果响应]\n H --> I[上下文预览/注入]\n```\n\n## 核心组件详解\n\n### SearchOrchestrator\n\nSearchOrchestrator 作为搜索系统的协调器，负责接收和处理所有搜索请求。它根据请求类型分发到相应的搜索策略，并协调结果的聚合与格式化。\n\n**主要职责：**\n- 路由不同类型的搜索请求（观察记录、会话、提示词等）\n- 管理搜索策略的执行顺序\n- 处理搜索结果的缓存与去重\n- 提供搜索帮助信息\n\n### HybridSearchStrategy\n\n混合搜索策略是本系统的核心创新，它结合了传统关键词搜索的精确性与语义搜索的智能化理解能力。\n\n```mermaid\ngraph LR\n A[查询字符串] --> B[分词处理]\n B --> C[关键词匹配]\n B --> D[语义向量化]\n C --> E[BM25 评分]\n D --> F[向量相似度]\n E --> G[分数融合]\n F --> G\n G --> H[Top-K 结果]\n```\n\n**搜索模式支持：**\n- **全文搜索**：对观察记录的标题、副标题、事实描述进行全文检索\n- **标签搜索**：按概念标签、文件路径、观察类型过滤\n- **时间范围搜索**：限定在特定时间段内的记录\n- **项目隔离搜索**：仅在指定项目中搜索\n\n### TimelineBuilder\n\nTimelineBuilder 负责将搜索结果按时间顺序组织，帮助用户理解知识在项目演进过程中的累积过程。\n\n**时间线类型：**\n- `timeline-by-query`：基于搜索查询的时间线\n- `context-timeline`：上下文注入时的时间线\n- `recent-context`：最近上下文的综合视图\n\n## API 端点\n\n### 搜索相关端点\n\n| 端点路径 | HTTP 方法 | 功能描述 |\n|---------|-----------|---------|\n| `/search/observations` | GET | 搜索观察记录 |\n| `/search/sessions` | GET | 搜索会话 |\n| `/search/prompts` | GET | 搜索提示词 |\n| `/search/by-concept` | GET | 按概念标签查找 |\n| `/search/by-file` | GET | 按文件路径查找 |\n| `/search/by-type` | GET | 按观察类型查找 |\n| `/search/recent-context` | GET | 获取最近上下文 |\n| `/search/context-timeline` | GET | 获取上下文时间线 |\n| `/search/timeline-by-query` | GET | 基于查询的时间线 |\n| `/search/help` | GET | 获取搜索帮助 |\n\n### 上下文相关端点\n\n| 端点路径 | HTTP 方法 | 功能描述 |\n|---------|-----------|---------|\n| `/context/preview` | GET | 预览上下文内容 |\n| `/context/inject` | POST | 注入上下文到会话 |\n\n## 观察记录检索\n\n### SQLite 数据模型\n\n观察记录存储在 SQLite 数据库中，支持多种查询模式。资料来源：`src/services/sqlite/observations/get.ts`\n\n**支持的操作类型：**\n\n```typescript\ntype ObservationKind = 'decision' | 'change' | 'how-it-works';\n```\n\n**检索函数签名：**\n- `getObservations(filters)`：基础观察记录检索\n- `getObservationsBySession(sessionId)`：按会话筛选\n- `getObservationsByProject(projectId)`：按项目筛选\n- `getObservationsByType(type)`：按类型筛选\n\n### 查询参数\n\n| 参数名 | 类型 | 描述 |\n|-------|------|-----|\n| `query` | string | 搜索查询字符串 |\n| `sessionId` | string | 会话 ID |\n| `projectId` | string | 项目 ID |\n| `type` | string | 观察类型 |\n| `concept` | string | 概念标签 |\n| `filePath` | string | 文件路径 |\n| `limit` | number | 返回结果数量限制 |\n| `offset` | number | 结果偏移量 |\n\n## MCP 工具接口\n\nMCP（Model Context Protocol）工具层为外部 AI 客户端提供搜索访问接口。资料来源：`src/server/mcp/tools.ts`\n\n### 工具定义\n\n```typescript\n// MCP 搜索工具结构\ninterface SearchTool {\n name: string; // 工具名称\n description: string; // 功能描述\n inputSchema: object; // 输入参数模式\n}\n```\n\n### 可用搜索工具\n\n| 工具名称 | 功能 | 输入参数 |\n|---------|------|---------|\n| `search_observations` | 搜索观察记录 | query, filters |\n| `search_sessions` | 搜索会话 | query, dateRange |\n| `search_by_concept` | 按概念搜索 | concept, limit |\n| `search_by_file` | 按文件路径搜索 | filePath, limit |\n| `inject_context` | 注入上下文 | sessionId, observationIds |\n\n## 搜索策略实现\n\n### 混合评分机制\n\n混合搜索策略通过加权融合关键词匹配分数和语义相似度分数来生成最终排名。资料来源：`src/services/worker/search/strategies/HybridSearchStrategy.ts`\n\n**评分公式：**\n```\nfinal_score = α × bm25_score + β × semantic_similarity\n```\n\n其中 α 和 β 为可配置的权重参数，默认 α = 0.4，β = 0.6。\n\n### 结果重排序\n\n搜索结果返回前会根据以下因素进行重排序：\n- 时间衰减因子：新近记录优先\n- 项目相关性：与当前项目关联度高的记录\n- 使用频率：被引用次数多的记录\n\n## 使用场景\n\n### 场景一：跨会话知识检索\n\n当开发者需要回顾之前实现某个功能的技术决策时，可以通过概念标签或文件路径快速定位相关观察记录。\n\n### 场景二：上下文恢复\n\n在长时间中断后重新开始工作时，系统可以将相关的历史观察打包为上下文预览，帮助 AI 快速恢复项目认知。\n\n### 场景三：知识图谱构建\n\n通过分析搜索结果中的概念标签和文件关联，系统可以自动构建项目的知识图谱结构。\n\n## 配置选项\n\n### 搜索配置参数\n\n| 配置项 | 默认值 | 描述 |\n|-------|-------|------|\n| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | 50 | 注入上下文时包含的观察记录数量 |\n| `CLAUDE_MEM_CONTEXT_SESSIONS` | 10 | 从多少个会话中拉取观察记录 |\n| `search.defaultLimit` | 20 | 默认搜索结果限制 |\n| `search.maxLimit` | 200 | 最大搜索结果限制 |\n| `hybrid.alpha` | 0.4 | BM25 权重 |\n| `hybrid.beta` | 0.6 | 语义相似度权重 |\n\n## 总结\n\n搜索系统通过混合搜索策略、灵活的时间线构建和完整的 MCP 工具接口，为 claude-mem 提供了强大的知识检索能力。该系统使得跨会话的上下文保持和知识复用成为可能，显著提升了 AI 在长期项目中的工作效率。\n\n---\n\n\n\n## 生命周期钩子系统\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [IDE 集成](#page-ide-integrations)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/services/worker/search/SearchOrchestrator.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/SearchOrchestrator.ts)\n- [src/services/worker/search/strategies/HybridSearchStrategy.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/strategies/HybridSearchStrategy.ts)\n- [src/services/worker/search/TimelineBuilder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/TimelineBuilder.ts)\n- [src/services/sqlite/observations/get.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/observations/get.ts)\n- [src/server/mcp/tools.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/mcp/tools.ts)\n\n
\n\n# 生命周期钩子系统\n\n## 概述\n\n生命周期钩子系统（Lifecycle Hook System）是 claude-mem 的核心模块，负责在 Claude Code、Gemini CLI、OpenClaw Gateway 和 Cursor 等 IDE 的运行过程中自动捕获用户操作、生成语义摘要，并使历史上下文可供未来会话使用。该系统通过事件驱动的架构，在 IDE 的关键生命周期节点注入自定义逻辑，实现跨会话的持久记忆功能。 资料来源：[README.md]()\n\n## 架构设计\n\n### 系统组件\n\n```mermaid\ngraph TD\n subgraph \"IDE 运行环境\"\n CLI[Claude Code / Gemini CLI / Cursor / OpenClaw]\n end\n \n subgraph \"钩子系统核心\"\n HC[Hook Manager]\n EP[Event Processor]\n OBS[Observation Store]\n SUM[Summary Generator]\n end\n \n subgraph \"存储层\"\n DB[(SQLite/JSON)]\n FS[文件系统]\n end\n \n CLI -->|触发生命周期事件| HC\n HC -->|处理事件| EP\n EP -->|生成观测记录| OBS\n EP -->|触发摘要生成| SUM\n OBS -->|持久化| DB\n SUM -->|持久化| FS\n```\n\n### 事件流处理\n\n钩子系统采用事件驱动模式，在 IDE 的生命周期各阶段触发相应的处理函数。每个事件都携带上下文数据，经处理器转换后存入持久化存储。 资料来源：[openclaw/src/index.ts:1-50]()\n\n## 钩子事件类型\n\n### OpenClaw Gateway 事件\n\nOpenClaw Gateway 提供了完整的事件订阅接口，支持以下生命周期事件： 资料来源：[openclaw/src/index.ts:15-27]()\n\n| 事件名称 | 触发时机 | 回调参数 | 功能描述 |\n|---------|---------|---------|---------|\n| `before_prompt_build` | 构建提示词前 | `PromptBuildCallback` | 修改或增强提示词内容 |\n| `before_agent_start` | Agent 启动前 | `BeforeAgentStartEvent` | 执行预启动准备工作 |\n| `tool_result_persist` | 工具执行结果返回时 | `ToolResultPersistEvent` | 持久化工具输出 |\n| `agent_end` | Agent 执行完成时 | `AgentEndEvent` | 执行后处理逻辑 |\n| `session_start` | 会话启动时 | `SessionStartEvent` | 初始化会话上下文 |\n| `session_end` | 会话结束时 | `SessionEndEvent` | 生成会话摘要 |\n| `message_received` | 收到用户消息时 | `MessageReceivedEvent` | 处理用户输入 |\n| `after_compaction` | 上下文压缩后 | `AfterCompactionEvent` | 处理压缩后的状态 |\n| `gateway_start` | Gateway 启动时 | 无参数 | 执行初始化逻辑 |\n\n### 事件回调接口定义\n\n```typescript\ninterface PluginInterface {\n on: ((\n event: \"before_prompt_build\",\n callback: PromptBuildCallback\n ) => void) &\n ((\n event: \"before_agent_start\",\n callback: EventCallback相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [openclaw/src/index.ts](https://github.com/thedotmack/claude-mem/blob/main/openclaw/src/index.ts)\n- [cursor-hooks/README.md](https://github.com/thedotmack/claude-mem/blob/main/cursor-hooks/README.md)\n- [src/services/smart-file-read/parser.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/smart-file-read/parser.ts)\n- [src/server/generation/providers/shared/prompt-builder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/providers/shared/prompt-builder.ts)\n- [src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)\n\n
\n\n# MCP 集成\n\n## 概述\n\nClaude-Mem 通过 Model Context Protocol (MCP) 实现与多种 AI Agent 平台的深度集成。MCP 作为连接 AI 助手与外部工具、资源的标准协议，使 claude-mem 能够作为统一的知识记忆层，为不同 IDE 环境（如 Claude Code、OpenClaw、OpenCode 等）提供跨会话的持久化上下文能力。\n\nMCP 集成模块位于 `src/server/mcp/` 目录，包含工具注册、资源管理、提示词模板和 MCP 服务器核心实现等组件。资料来源：[src/servers/mcp-server.ts:1]()\n\n## 架构设计\n\n### 模块结构\n\nMCP 集成系统由以下核心模块组成：\n\n```mermaid\ngraph TD\n A[MCP 客户端相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/mcp/tools.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/mcp/tools.ts)\n- [src/server/mcp/register.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/mcp/register.ts)\n- [src/server/mcp/resources.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/mcp/resources.ts)\n- [src/server/mcp/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/mcp/prompts.ts)\n- [src/servers/mcp-server.ts](https://github.com/thedotmack/claude-mem/blob/main/src/servers/mcp-server.ts)\nClaude Code / OpenClaw / OpenCode] --> B[MCP 服务器
mcp-server.ts]\n B --> C[tools.ts
工具定义]\n B --> D[resources.ts
资源提供]\n B --> E[prompts.ts
提示词模板]\n B --> F[register.ts
注册与生命周期]\n C --> G[记忆存储
SQLite + claude.md]\n D --> G\n```\n\n### 核心职责\n\n| 模块 | 职责 | 主要功能 |\n|------|------|----------|\n| `mcp-server.ts` | MCP 服务器入口 | 初始化传输层、注册处理器、启动服务 |\n| `tools.ts` | 工具定义 | 定义并暴露 AI Agent 可调用的记忆操作工具 |\n| `resources.ts` | 资源管理 | 提供记忆数据作为可读取的资源 |\n| `prompts.ts` | 提示词模板 | 生成 MCP 上下文相关的提示词 |\n| `register.ts` | 注册管理 | 管理工具和资源的注册、生命周期事件 |\n\n## 工具系统 (tools.ts)\n\n### 工具定义\n\nMCP 工具系统允许 AI Agent 通过标准化接口查询和操作记忆数据。工具定义遵循 MCP 协议规范，每个工具包含：\n\n- **名称 (name)**: 工具的唯一标识符\n- **描述 (description)**: 工具用途说明，供 AI Agent 理解何时调用\n- **输入模式 (inputSchema)**: 工具参数的 JSON Schema 定义\n\n### 可用工具类型\n\n典型的 MCP 工具包括：\n\n1. **记忆查询工具**: 根据时间范围、项目或关键词检索历史观察记录\n2. **摘要生成工具**: 请求生成特定会话的语义摘要\n3. **上下文注入工具**: 将检索到的记忆注入到当前会话上下文\n4. **项目状态工具**: 查询当前项目的已知信息和状态\n\n资料来源：[src/server/mcp/tools.ts:1]()\n\n## 资源系统 (resources.ts)\n\n### 资源模型\n\nMCP 资源系统将 claude-mem 的记忆数据以 URI 形式暴露给 AI Agent，支持按需读取：\n\n```mermaid\ngraph LR\n A[AI Agent] -->|请求资源 URI| B[MCP 服务器]\n B --> C[resources.ts]\n C --> D[SQLite 数据库]\n C --> E[claude.md 文件]\n```\n\n### 资源 URI 格式\n\n资源使用统一资源标识符进行寻址：\n\n| 资源类型 | URI 格式 | 说明 |\n|----------|----------|------|\n| 观察记录 | `mem://observations/{project_id}` | 获取项目的所有观察 |\n| 摘要列表 | `mem://summaries/{session_id}` | 获取会话摘要 |\n| 项目元数据 | `mem://projects/{project_path}` | 获取项目配置信息 |\n| 时间线 | `mem://timeline/{project_id}` | 获取活动时间线 |\n\n### 资源缓存策略\n\n资源系统实现了智能缓存机制，避免重复读取相同数据。缓存失效策略与记忆更新事件联动，确保数据一致性。\n\n资料来源：[src/server/mcp/resources.ts:1]()\n\n## 提示词集成 (prompts.ts)\n\n### 提示词模板系统\n\nMCP 提示词模块负责生成与记忆相关的上下文模板，帮助 AI Agent 理解如何与记忆系统交互：\n\n- **系统级提示词**: 定义 AI Agent 对记忆系统的认知角色\n- **查询提示词**: 生成结构化的记忆查询指令\n- **响应格式提示词**: 指定记忆数据的返回格式规范\n\n### 模板变量\n\n提示词系统支持动态变量注入：\n\n| 变量 | 来源 | 用途 |\n|------|------|------|\n| `{project_id}` | 当前会话 | 限定记忆范围 |\n| `{session_id}` | 会话上下文 | 关联特定会话 |\n| `{time_range}` | 查询参数 | 时间范围过滤 |\n| `{user_query}` | 用户输入 | 自然语言查询意图 |\n\n资料来源：[src/server/mcp/prompts.ts:1]()\n\n## 注册与生命周期 (register.ts)\n\n### 初始化流程\n\n```mermaid\nsequenceDiagram\n participant Host as MCP Host\n participant Server as MCP Server\n participant Registry as register.ts\n participant Store as 记忆存储\n \n Host->>Server: 连接请求\n Server->>Registry: 初始化注册\n Registry->>Registry: 注册工具定义\n Registry->>Registry: 注册资源提供器\n Registry->>Registry: 订阅生命周期事件\n Registry->>Store: 验证连接\n Server-->>Host: 连接就绪\n```\n\n### 生命周期管理\n\n注册模块负责管理以下生命周期事件：\n\n1. **连接建立**: 验证客户端权限，初始化会话上下文\n2. **工具调用**: 路由工具请求到对应的处理器\n3. **资源订阅**: 管理资源变更通知\n4. **连接断开**: 清理会话状态，持久化临时数据\n\n### 错误处理\n\n注册系统实现了健壮的错误处理机制：\n\n- 工具调用超时自动重试\n- 资源不可用时的优雅降级\n- 连接异常时的自动重连策略\n\n资料来源：[src/server/mcp/register.ts:1]()\n\n## MCP 服务器核心 (mcp-server.ts)\n\n### 服务器架构\n\nMCP 服务器是整个集成系统的核心入口点，负责：\n\n1. **传输层管理**: 处理 STDIO 或 HTTP 传输\n2. **协议实现**: 遵循 MCP 规范进行消息编解码\n3. **请求路由**: 将入站请求分发到对应模块\n4. **响应序列化**: 将处理结果格式化为 MCP 协议格式\n\n### 启动配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| 端口 | 3100 | MCP 服务器监听端口 |\n| 传输方式 | stdio | 支持 stdio 和 HTTP |\n| 超时 | 30s | 工具调用超时时间 |\n| 日志级别 | info | 日志输出级别 |\n\n### 与其他集成方式的对比\n\nClaude-Mem 支持多种集成方式，MCP 是其中最标准化的方案：\n\n| 集成方式 | 适用场景 | 特点 |\n|----------|----------|------|\n| MCP | 标准 AI Agent 平台 | 协议标准化、跨平台支持 |\n| 插件系统 | Claude Code | 深度集成、实时观察 |\n| npx CLI | 手动操作 | 灵活但不持久 |\n| OpenClaw Gateway | 企业部署 | 托管服务、高可用 |\n\n资料来源：[src/servers/mcp-server.ts:1]()\n\n## 使用场景\n\n### 跨会话上下文保持\n\n当 AI Agent 在新会话中处理项目时，可以通过 MCP 接口获取历史会话中积累的项目知识：\n\n1. Agent 连接 MCP 服务器\n2. 通过资源接口获取项目历史\n3. 工具调用检索相关观察记录\n4. 上下文注入当前会话\n\n### 主动记忆增强\n\n通过 MCP 工具， AI Agent 可以在处理复杂任务时主动查询记忆库：\n\n```\n用户请求: 重构 authentication 模块\n ↓\nAgent 调用 MCP 工具: search_observations(project, \"auth\")\n ↓\n获取历史修改记录、设计决策\n ↓\n生成重构方案时参考历史上下文\n```\n\n### 多 Agent 知识共享\n\n在 OpenClaw 等多 Agent 环境中，MCP 服务器可作为共享记忆中枢：\n\n- 多个 Agent 实例共享同一记忆存储\n- 通过 MCP 资源接口实现跨 Agent 知识传递\n- 保持团队协作的上下文连续性\n\n## 配置与调试\n\n### 环境变量\n\n| 变量 | 说明 |\n|------|------|\n| `CLAUDE_MEM_MCP_PORT` | MCP 服务器端口 |\n| `CLAUDE_MEM_MCP_TRANSPORT` | 传输方式 (stdio/http) |\n| `CLAUDE_MEM_LOG_LEVEL` | 日志级别 |\n\n### 状态检查\n\n```bash\nnpx claude-mem status\n```\n\n该命令可验证 MCP 服务器运行状态和连接状态。\n\n## 安全考虑\n\n### 数据隔离\n\n- 每个项目的记忆数据相互隔离\n- MCP 连接使用项目路径作为会话标识\n- 资源访问遵循最小权限原则\n\n### 敏感信息处理\n\n记忆系统会自动过滤敏感信息（如 API Key、环境变量值），确保只记录语义内容而非凭证数据。\n\n## 相关文档\n\n- [快速开始指南](../getting-started.md) - MCP 集成的入门配置\n- [SDK 文档](../sdk/overview.md) - 编程接口参考\n- [开发指南](https://docs.claude-mem.ai/development) - MCP 模块开发说明\n\n---\n\n\n\n## IDE 集成\n\n### 相关页面\n\n相关主题：[生命周期钩子系统](#page-hooks-system), [安装与部署](#page-installation)\n\n
\n
\n\n# IDE 集成\n\nclaude-mem 通过统一的集成框架支持多种主流 IDE 和 CLI 环境，实现跨平台的情境记忆功能。本页详细说明各 IDE 的集成架构、安装机制和运行时行为。\n\n## 支持的 IDE 环境\n\nclaude-mem 支持以下集成目标：\n\n| IDE/CLI | 安装命令 | 检测方式 | 钩子类型 |\n|---------|---------|---------|---------|\n| Claude Code | `npx claude-mem install` | `~/.claude` 目录 | 插件钩子 |\n| Cursor | `npx claude-mem install --ide cursor` | 平台检测 | Cursor Hooks |\n| Gemini CLI | `npx claude-mem install --ide gemini-cli` | `~/.gemini` 目录 | MCP 钩子 |\n| OpenCode | `npx claude-mem install --ide opencode` | `OPENCODE_DIR` 环境变量 | MCP 钩子 |\n\n资料来源：[src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n## 集成架构概览\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ claude-mem │\n├─────────────────────────────────────────────────────────────┤\n│ CLI 适配层 (src/cli/adapters) │\n│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │\n│ │ ClaudeCode │ │ Cursor │ │ GeminiCLI │ │\n│ │ Adapter │ │ Adapter │ │ Adapter │ │\n│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │\n├─────────┴────────────────┴────────────────┴─────────────────┤\n│ 集成服务层 (src/services/integrations) │\n│ ┌──────────────────────────────────────────────────────┐ │\n│ │ HookInstaller 抽象工厂 │ │\n│ │ ┌────────────────┐ ┌────────────────┐ │ │\n│ │ │ ClaudeHooks │ │ CursorHooks │ │ │\n│ │ │ Installer │ │ Installer │ │ │\n│ │ └────────────────┘ └────────────────┘ │ │\n│ └──────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## CLI 适配层\n\n适配层负责检测目标 IDE 环境并提供统一的安装接口。\n\n### Claude Code 适配器\n\nClaude Code 通过插件机制集成：\n\n```bash\n# 通过插件市场安装\n/plugin marketplace add thedotmack/claude-mem\n/plugin install claude-mem\n\n# 或通过命令行安装\nnpx claude-mem install\n```\n\n资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n\n### 检测机制\n\n集成系统通过多层次检测确定 IDE 环境：\n\n```typescript\nexport async function detectClaudeCode(): Promise相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/services/integrations/CursorHooksInstaller.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/integrations/CursorHooksInstaller.ts)\n- [src/cli/adapters](https://github.com/thedotmack/claude-mem/blob/main/src/cli/adapters)\n- [cursor-hooks](https://github.com/thedotmack/claude-mem/blob/main/cursor-hooks)\n- [plugin/modes](https://github.com/thedotmack/claude-mem/blob/main/plugin/modes)\n- [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n
\n\n# 安装与部署\n\n## 概述\n\nClaude-Mem 提供多种安装方式，支持在不同集成环境中部署本插件。安装过程会自动配置后台运行服务（Worker）、数据存储目录以及与 Claude Code 的集成钩子。\n\n## 安装方式\n\nClaude-Mem 支持以下几种安装途径：\n\n### 1. NPX 一键安装（推荐）\n\n通过 npx 命令直接安装，这是最简单的方式：\n\n```bash\nnpx claude-mem install\n```\n\n安装完成后，系统会显示欢迎提示，包含以下信息：\n- Worker 服务状态（启动中或已就绪）\n- 访问本地查看器的 URL\n- 后续操作指引\n\n资料来源：[README.md:1-30]()\n\n### 2. Claude Code 插件市场安装\n\n对于 Claude Code 用户，可以通过内置的 `/plugin` 命令安装：\n\n```bash\n/plugin marketplace add thedotmack/claude-mem\n/plugin install claude-mem\n```\n\n安装完成后需要重启 Claude Code。\n\n资料来源：[README.md:30-35]()\n\n### 3. Gemini CLI 安装\n\n针对 Gemini CLI 用户，可以指定 `--ide` 参数：\n\n```bash\nnpx claude-mem install --ide gemini-cli\n```\n\n该命令会自动检测 `~/.gemini` 目录并完成配置。\n\n资料来源：[README.md:18-22]()\n\n### 4. OpenCode 安装\n\n针对 OpenCode 编辑器用户：\n\n```bash\nnpx claude-mem install --ide opencode\n```\n\n资料来源：[README.md:25-28]()\n\n### 5. OpenClaw Gateway 安装\n\n在 OpenClaw 网关上安装持久化内存插件：\n\n```bash\ncurl -fsSL https://install.cmem.ai/openclaw.sh | bash\n```\n\n资料来源：[README.md:45-50]()\n\n## 安装流程架构\n\n```mermaid\ngraph TD\n A[用户执行安装命令] --> B{安装方式}\n B -->|npx claude-mem install| C[初始化配置文件]\n B -->|/plugin install| D[检测 Claude Code 环境]\n B -->|OpenClaw| E[下载安装脚本]\n \n C --> F[启动 Worker 服务]\n D --> F\n E --> G[配置 Gateway]\n \n F --> H[创建 ~/.claude-mem 目录]\n H --> I[注册集成钩子]\n I --> J[安装完成，显示提示]\n \n J --> K[首次启动建议]\n K --> L[\"方式A: 直接开始工作\"]\n K --> M[\"方式B: 运行 /learn-codebase\"]\n```\n\n## Worker 服务配置\n\n### 默认配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| 端口 | 18789 | Worker 服务监听端口 |\n| 数据目录 | `~/.claude-mem` | 存储观察记录和配置 |\n| 自动启动 | 启用 | 系统启动时自动运行 |\n\n### 启动状态检测\n\n安装完成后，系统会检查 Worker 服务状态：\n\n```typescript\nworkerAlive\n ? [workerHeadline, firstSuccessMessage, twoPathsMessage]\n : [waitMessage, manualStartHint]\n```\n\n资料来源：[src/npx-cli/commands/install.ts:10-30]()\n\n### 手动启动\n\n如果 Worker 未自动启动，可手动启动：\n\n```bash\nnpx claude-mem start\n```\n\n## 环境变量配置\n\n### 安装后提示控制\n\n首次安装后，系统会显示欢迎提示。可通过环境变量禁用：\n\n```bash\nCLAUDE_MEM_WELCOME_HINT_ENABLED=false\n```\n\n资料来源：[src/npx-cli/commands/install.ts:20-25]()\n\n### 查看器配置\n\n通过 `ContextSettingsModal.tsx` 可以配置以下参数：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | 50 | 注入上下文的观察数量 (1-200) |\n| `CLAUDE_MEM_CONTEXT_SESSIONS` | - | 拉取观察的会话数量 (1-50) |\n\n资料来源：[src/ui/viewer/components/ContextSettingsModal.tsx:40-60]()\n\n## 卸载说明\n\n卸载前需要关闭所有 Claude Code 会话，否则活动钩子会重新创建配置目录：\n\n```bash\nnpx claude-mem uninstall\n```\n\n> **注意**：关闭所有 Claude Code 会话后再执行卸载，否则 `~/.claude-mem` 目录会被重新创建。\n\n资料来源：[src/npx-cli/commands/install.ts:15-18]()\n\n## 快速验证安装\n\n安装完成后按以下步骤验证：\n\n1. 启动 Claude Code\n2. 确认控制台无错误信息\n3. 在新项目中输入测试提示\n4. 第二次会话时应能看到历史上下文注入\n\n## 安装方式对比\n\n| 安装方式 | 适用环境 | 是否需要重启 | 自动化程度 |\n|----------|----------|--------------|------------|\n| `npx claude-mem install` | 通用 | 是 | 高 |\n| `/plugin` 命令 | Claude Code | 是 | 高 |\n| OpenClaw 脚本 | OpenClaw Gateway | 是 | 高 |\n| 源码编译 | 开发/自定义 | 是 | 低 |\n\n## 常见问题\n\n### Q: npm install -g claude-mem 是否可行？\n\n**不行**。通过 `npm install -g` 安装的是 SDK/库版本，不会注册插件钩子或设置 Worker 服务。必须使用 `npx claude-mem install` 或 `/plugin` 命令安装。\n\n资料来源：[README.md:36-40]()\n\n### Q: 如何检查服务状态？\n\n```bash\nnpx claude-mem status\n```\n\n### Q: Worker 启动后显示等待状态怎么办？\n\n这是正常现象，Worker 启动需要约 30 秒。等待完成后刷新浏览器即可。\n\n资料来源：[src/npx-cli/commands/install.ts:35-40]()\n\n## 后续步骤\n\n安装完成后，推荐以下两种初始化方式：\n\n**方式 A（推荐）**：直接开始工作，记忆会从第一次提示中被动构建。\n\n**方式 B**：运行 `/learn-codebase` 命令预加载整个代码仓库（约 5 分钟，可选）。\n\n资料来源：[src/npx-cli/commands/install.ts:22-28]()\n\n## 相关文档\n\n- [使用指南](./使用指南.md)\n- [配置选项](./配置选项.md)\n- [故障排除](./故障排除.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：thedotmack/claude-mem\n\n摘要：发现 24 个潜在踩坑项，其中 8 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories。\n\n## 1. 安装坑 · 来源证据：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_28646536cf7d499aadab2346c2666f89 | https://github.com/thedotmack/claude-mem/issues/2389 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Windows: cmd.exe /c uvx wrapper breaks Chroma MCP stdio on WinGet uv installs (regression after #1190 / #1199) --> FIX…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows: cmd.exe /c uvx wrapper breaks Chroma MCP stdio on WinGet uv installs (regression after #1190 / #1199) --> FIX attacched\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6c844000d9b4adead4a2fdb73660c8d | https://github.com/thedotmack/claude-mem/issues/2426 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：[Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9e74ac48a1744106a07ff519ad2d2773 | https://github.com/thedotmack/claude-mem/issues/2437 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：v13: merged_into_project migration silently skipped on pre-existing DBs (schema_versions ≤ 23)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13: merged_into_project migration silently skipped on pre-existing DBs (schema_versions ≤ 23)\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_510ecb03a1de412f940987e370c68fac | https://github.com/thedotmack/claude-mem/issues/2433 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：Use node to run mcp for windows environment\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Use node to run mcp for windows environment\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_95d37c5d34a749f7a25fdd5fe1dc7969 | https://github.com/thedotmack/claude-mem/issues/2446 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 来源证据：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_77fdc7c371f042eeb70fbeb52a7a2788 | https://github.com/thedotmack/claude-mem/issues/2438 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 运行坑 · 来源证据：自动运行时突然报下图所示内容，然后插件就不能用了\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：自动运行时突然报下图所示内容，然后插件就不能用了\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2d5aa43a4c5a4e46a0f2122dea46947a | https://github.com/thedotmack/claude-mem/issues/2441 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安全/权限坑 · 来源证据：[Bug] Codex CLI plugin hooks consume Claude Code session quota via Claude Code SDK\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] Codex CLI plugin hooks consume Claude Code session quota via Claude Code SDK\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b77cb6420d845a9bd38852571b6adbd | https://github.com/thedotmack/claude-mem/issues/2431 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：Codex CLI: PreToolUse hook returned unsupported suppressOutput\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex CLI: PreToolUse hook returned unsupported suppressOutput\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9022a732f6e54ba39309c5377cf2d8fa | https://github.com/thedotmack/claude-mem/issues/2360 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 安装坑 · 来源证据：[feat] Option to load only memory-related skills\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[feat] Option to load only memory-related skills\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_efa30fc4873343aea26f804c8d1113ec | https://github.com/thedotmack/claude-mem/issues/2448 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 安装坑 · 来源证据：server-beta: ModeManager not initialized — generation jobs fail with 'No mode loaded'\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：server-beta: ModeManager not initialized — generation jobs fail with 'No mode loaded'\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_757115889024465dbafb2f4ffcbe8356 | https://github.com/thedotmack/claude-mem/issues/2443 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 安装坑 · 来源证据：v12.1.1: hooks/hooks.json references removed scripts/worker-service.cjs — all hooks fail with \"Module not found\"\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v12.1.1: hooks/hooks.json references removed scripts/worker-service.cjs — all hooks fail with \"Module not found\"\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0e29da4de6004faea2de867f758794f8 | https://github.com/thedotmack/claude-mem/issues/1835 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 13. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | host_targets=claude, claude_code\n\n## 14. 配置坑 · 来源证据：server-beta: runServerBetaCli() default command exits immediately — unusable with systemd\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：server-beta: runServerBetaCli() default command exits immediately — unusable with systemd\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2613a65b36064bfeb5bbaf9fed69672d | https://github.com/thedotmack/claude-mem/issues/2444 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | README/documentation is current enough for a first validation pass.\n\n## 16. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | last_activity_observed missing\n\n## 17. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 19. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | no_demo; severity=medium\n\n## 20. 安全/权限坑 · 来源证据：Daemon survives plugin disable, burns 500M+ tokens/week with no observable user-facing benefit\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Daemon survives plugin disable, burns 500M+ tokens/week with no observable user-facing benefit\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a4e91994a3834fc4a64f07b31ce17242 | https://github.com/thedotmack/claude-mem/issues/2451 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 21. 安全/权限坑 · 来源证据：Long-running Worker endpoints share health-check timeout (HEALTH_TIMEOUT_MS); should use per-endpoint timeouts\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Long-running Worker endpoints share health-check timeout (HEALTH_TIMEOUT_MS); should use per-endpoint timeouts\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b61a79c5ae144fcbd7cb8737397dbee | https://github.com/thedotmack/claude-mem/issues/2447 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 22. 安全/权限坑 · 来源证据：claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c23b4f1758454233a20f5c0653d69d51 | https://github.com/thedotmack/claude-mem/issues/2450 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 23. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | issue_or_pr_quality=unknown\n\n## 24. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：thedotmack/claude-mem\n\n摘要：发现 24 个潜在踩坑项，其中 8 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories。\n\n## 1. 安装坑 · 来源证据：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_28646536cf7d499aadab2346c2666f89 | https://github.com/thedotmack/claude-mem/issues/2389 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Windows: cmd.exe /c uvx wrapper breaks Chroma MCP stdio on WinGet uv installs (regression after #1190 / #1199) --> FIX…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows: cmd.exe /c uvx wrapper breaks Chroma MCP stdio on WinGet uv installs (regression after #1190 / #1199) --> FIX attacched\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6c844000d9b4adead4a2fdb73660c8d | https://github.com/thedotmack/claude-mem/issues/2426 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：[Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9e74ac48a1744106a07ff519ad2d2773 | https://github.com/thedotmack/claude-mem/issues/2437 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：v13: merged_into_project migration silently skipped on pre-existing DBs (schema_versions ≤ 23)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13: merged_into_project migration silently skipped on pre-existing DBs (schema_versions ≤ 23)\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_510ecb03a1de412f940987e370c68fac | https://github.com/thedotmack/claude-mem/issues/2433 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：Use node to run mcp for windows environment\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Use node to run mcp for windows environment\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_95d37c5d34a749f7a25fdd5fe1dc7969 | https://github.com/thedotmack/claude-mem/issues/2446 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 来源证据：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_77fdc7c371f042eeb70fbeb52a7a2788 | https://github.com/thedotmack/claude-mem/issues/2438 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 运行坑 · 来源证据：自动运行时突然报下图所示内容，然后插件就不能用了\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：自动运行时突然报下图所示内容，然后插件就不能用了\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2d5aa43a4c5a4e46a0f2122dea46947a | https://github.com/thedotmack/claude-mem/issues/2441 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安全/权限坑 · 来源证据：[Bug] Codex CLI plugin hooks consume Claude Code session quota via Claude Code SDK\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] Codex CLI plugin hooks consume Claude Code session quota via Claude Code SDK\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b77cb6420d845a9bd38852571b6adbd | https://github.com/thedotmack/claude-mem/issues/2431 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：Codex CLI: PreToolUse hook returned unsupported suppressOutput\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex CLI: PreToolUse hook returned unsupported suppressOutput\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9022a732f6e54ba39309c5377cf2d8fa | https://github.com/thedotmack/claude-mem/issues/2360 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 安装坑 · 来源证据：[feat] Option to load only memory-related skills\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[feat] Option to load only memory-related skills\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_efa30fc4873343aea26f804c8d1113ec | https://github.com/thedotmack/claude-mem/issues/2448 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 安装坑 · 来源证据：server-beta: ModeManager not initialized — generation jobs fail with 'No mode loaded'\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：server-beta: ModeManager not initialized — generation jobs fail with 'No mode loaded'\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_757115889024465dbafb2f4ffcbe8356 | https://github.com/thedotmack/claude-mem/issues/2443 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 安装坑 · 来源证据：v12.1.1: hooks/hooks.json references removed scripts/worker-service.cjs — all hooks fail with \"Module not found\"\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v12.1.1: hooks/hooks.json references removed scripts/worker-service.cjs — all hooks fail with \"Module not found\"\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0e29da4de6004faea2de867f758794f8 | https://github.com/thedotmack/claude-mem/issues/1835 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 13. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | host_targets=claude, claude_code\n\n## 14. 配置坑 · 来源证据：server-beta: runServerBetaCli() default command exits immediately — unusable with systemd\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：server-beta: runServerBetaCli() default command exits immediately — unusable with systemd\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2613a65b36064bfeb5bbaf9fed69672d | https://github.com/thedotmack/claude-mem/issues/2444 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | README/documentation is current enough for a first validation pass.\n\n## 16. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | last_activity_observed missing\n\n## 17. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 19. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | no_demo; severity=medium\n\n## 20. 安全/权限坑 · 来源证据：Daemon survives plugin disable, burns 500M+ tokens/week with no observable user-facing benefit\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Daemon survives plugin disable, burns 500M+ tokens/week with no observable user-facing benefit\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a4e91994a3834fc4a64f07b31ce17242 | https://github.com/thedotmack/claude-mem/issues/2451 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 21. 安全/权限坑 · 来源证据：Long-running Worker endpoints share health-check timeout (HEALTH_TIMEOUT_MS); should use per-endpoint timeouts\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Long-running Worker endpoints share health-check timeout (HEALTH_TIMEOUT_MS); should use per-endpoint timeouts\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b61a79c5ae144fcbd7cb8737397dbee | https://github.com/thedotmack/claude-mem/issues/2447 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 22. 安全/权限坑 · 来源证据：claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c23b4f1758454233a20f5c0653d69d51 | https://github.com/thedotmack/claude-mem/issues/2450 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 23. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | issue_or_pr_quality=unknown\n\n## 24. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# claude-mem - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 claude-mem 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude / Claude Code\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-concepts：核心概念。围绕“核心概念”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-worker-service：Worker 服务。围绕“Worker 服务”模拟一次用户任务，不展示安装或运行结果。\n5. page-data-storage：数据存储层。围绕“数据存储层”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-concepts\n输入：用户提供的“核心概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-worker-service\n输入：用户提供的“Worker 服务”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-data-storage\n输入：用户提供的“数据存储层”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-concepts：Step 2 必须围绕“核心概念”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-worker-service：Step 4 必须围绕“Worker 服务”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-data-storage：Step 5 必须围绕“数据存储层”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/thedotmack/claude-mem\n- https://github.com/thedotmack/claude-mem#readme\n- openclaw/SKILL.md\n- plugin/skills/babysit/SKILL.md\n- plugin/skills/do/SKILL.md\n- plugin/skills/how-it-works/SKILL.md\n- plugin/skills/knowledge-agent/SKILL.md\n- plugin/skills/learn-codebase/SKILL.md\n- plugin/skills/make-plan/SKILL.md\n- plugin/skills/mem-search/SKILL.md\n- plugin/skills/pathfinder/SKILL.md\n- plugin/skills/smart-explore/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 claude-mem 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：thedotmack/claude-mem\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx claude-mem\n```\n\n来源：https://github.com/thedotmack/claude-mem#readme\n\n## 来源\n\n- repo: https://github.com/thedotmack/claude-mem\n- docs: https://github.com/thedotmack/claude-mem#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_91ef68b98b124130b50f4582468b8a9d"
}