\n
\n\n# Key Features\n\nClaude-Mem provides persistent memory capabilities for AI coding assistants, enabling continuity of knowledge across sessions. This page documents the core architectural components and features that power the system.\n\n## System Overview\n\nClaude-Mem seamlessly preserves context across sessions by automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions. This enables Claude to maintain continuity of knowledge about projects even after sessions end or reconnect.\n\n资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n\n## Core Features\n\n### 1. Observation Capture System\n\nThe observation system automatically records tool usage events during Claude Code sessions. Each observation captures structured data about file operations, command executions, and code modifications.\n\n#### Observation Data Model\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `type` | string | Category of observation (file_read, file_modified, command, etc.) |\n| `title` | string | Brief title for the observation |\n| `subtitle` | string | Additional context or description |\n| `facts` | string[] | Key facts extracted from the operation |\n| `narrative` | string | Human-readable summary of the activity |\n| `concepts` | string[] | Extracted concepts and patterns |\n| `files_read` | string[] | Files that were read during this operation |\n| `files_modified` | string[] | Files that were modified |\n| `id` | number | Unique identifier for the observation |\n| `created_at_epoch` | number | Unix timestamp of creation |\n\n资料来源：[src/sdk/prompts.ts:24-42](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)\n\n#### XML Output Format\n\nObservations are rendered in a structured XML format that the AI can easily parse:\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/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/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/services/smart-file-read/parser.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/smart-file-read/parser.ts)\n\n 
\n
\n {section.label}
\n\n {section.content}\n
\n \n))\n```\n\n资料来源：[src/ui/viewer/components/SummaryCard.tsx:30-50](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/SummaryCard.tsx)\n\n#### Observation Card Display\n\nObservations support multiple view modes for flexible data presentation:\n\n```typescript\n{showFacts && facts.length > 0 && (\n - \n {facts.map((fact: string, i: number) => (\n
- {fact} \n ))}\n
\n {observation.narrative}\n
\n)}\n```\n\n资料来源：[src/ui/viewer/components/ObservationCard.tsx:50-65](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ObservationCard.tsx)\n\n### 7. Theme System\n\nThe viewer supports light and dark themes with CSS custom properties:\n\n| Theme Variable | Light Mode | Dark Mode |\n|----------------|------------|-----------|\n| `--color-bg-primary` | #ffffff | #0d1117 |\n| `--color-bg-secondary` | #efebe4 | #161b22 |\n| `--color-bg-card` | #ffffff | #161b22 |\n| `--color-bg-button` | #0969da | #238636 |\n\n资料来源：[src/ui/viewer-template.html:20-40](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer-template.html)\n\n## Architecture Diagram\n\n```mermaid\ngraph TD\n A[Claude Code Session] --> B[Observation Capture]\n B --> C[Worker Service]\n C --> D[SQLite Database]\n D --> E[Context Builder]\n E --> F[Prompt Injection]\n F --> A\n \n C --> G[Summary Generation]\n G --> D\n \n H[Web Viewer] --> E\n H --> D\n \n I[Smart File Parser] --> B\n```\n\n## Data Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Claude as Claude Code\n participant SDK as SDK/prompts.ts\n participant Worker as Worker Service\n participant DB as SQLite\n participant Viewer as Web Viewer\n \n User->>Claude: Start session\n Claude->>SDK: Generate observation\n SDK->>Worker: Send observation data\n Worker->>DB: Store observation\n \n User->>Viewer: Browse observations\n Viewer->>DB: Query observations\n DB-->>Viewer: Return data\n \n User->>Claude: End session\n Claude->>SDK: Request summary\n SDK->>Worker: Generate summary\n Worker->>DB: Store summary\n \n User->>Claude: New session\n Viewer->>Claude: Inject context\n Claude->>User: Respond with context\n```\n\n## Key System Behaviors\n\n### Observation Types\n\nThe system recognizes several observation types that categorize different tool operations:\n\n1. **file_read** - When Claude reads a file\n2. **file_modified** - When Claude edits or creates a file\n3. **command** - When Claude runs shell commands\n4. **code_change** - When significant code modifications occur\n\n### XML Escaping\n\nAll user-generated content is properly escaped before insertion into XML output to prevent injection attacks:\n\n```typescript\nfunction escapeXml(text: string): string {\n return text\n .replace(/&/g, '&')\n .replace(//g, '>')\n .replace(/\"/g, '"')\n .replace(/'/g, ''');\n}\n```\n\n资料来源：[src/server/generation/providers/shared/prompt-builder.ts:91-98](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/providers/shared/prompt-builder.ts)\n\n### Error Handling\n\nThe viewer implements error boundaries to gracefully handle component failures:\n\n```typescript\nclass ErrorBoundary extends React.Component {\n state = { error: null, errorInfo: null };\n \n componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {\n this.setState({ error, errorInfo });\n }\n \n render() {\n if (this.state.error) {\n return (\n \n
\n );\n }\n return this.props.children;\n }\n}\n```\n\n资料来源：[src/ui/viewer/components/ErrorBoundary.tsx:1-40](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ErrorBoundary.tsx)\n\n## Installation & Setup\n\n### Quick Install\n\n```bash\n# Standard Claude Code\nnpx claude-mem install\n\n# Gemini CLI\nnpx claude-mem install --ide gemini-cli\n\n# OpenCode\nnpx claude-mem install --ide opencode\n```\n\n### Post-Installation\n\n1. Keep the viewer URL open in a browser\n2. Open Claude Code in any project\n3. Observations stream automatically as Claude works\n4. Memory injection begins on the second session\n\n资料来源：[src/npx-cli/commands/install.ts:15-30](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n## Storage Location\n\nAll data is stored locally in `~/.claude-mem` on the user's machine. No data is sent to external servers except through Claude API calls for observation generation.\n\n## See Also\n\n- [Installation Guide](https://github.com/thedotmack/claude-mem#installation)\n- [Context Settings](src/ui/viewer/components/ContextSettingsModal.tsx)\n- [Prompt Builder](src/server/generation/providers/shared/prompt-builder.ts)\n\n---\n\n\n\n## System Architecture Overview\n\n### 相关页面\n\n相关主题：[Hooks System and Lifecycle](#page-hooks-system), [Worker Service Architecture](#page-worker-service), [Database Schema and Storage](#page-database-schema), [Data Flow and Processing](#page-data-flow)\n\nError details
\n{this.state.error.toString()}\n \n
\n\n# System Architecture Overview\n\nClaude-Mem is a persistent memory system for AI coding assistants (Claude Code, Gemini CLI, OpenCode). It automatically captures tool usage observations during coding sessions, generates semantic summaries, and makes them available to future sessions—enabling continuity of knowledge across sessions. 资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n\n## High-Level Architecture\n\nThe system follows a client-server architecture with a worker service that runs independently and a viewer UI for inspecting memory.\n\n```mermaid\ngraph TD\n A[Claude Code / Gemini CLI] -->|Tool Hooks| B[claude-mem Plugin Hooks]\n B --> C[Worker Service :3000]\n C --> D[(SQLite Database相关源码文件
\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/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/ui/viewer/App.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/App.tsx)\n- [src/ui/viewer/components/ContextSettingsModal.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ContextSettingsModal.tsx)\n- [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n~/.claude-mem)]\n C --> E[Prompt Builder]\n E --> F[Claude API]\n F --> G[Parsed Observations]\n C --> G\n H[Viewer UI :8080] --> C\n H --> D\n```\n\n## Core Components\n\n### 1. Worker Service (`src/services/worker-service.ts`)\n\nThe worker service is the central processing hub that:\n\n- Runs as a background process (default port 3000)\n- Receives tool usage observations from IDE plugins\n- Processes and stores observations in SQLite\n- Handles prompt generation and LLM interaction\n- Manages session context injection\n\n资料来源：[src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n### 2. SDK Layer (`src/sdk/prompts.ts`)\n\nThe SDK provides prompt building functions for different operation modes:\n\n| Function | Purpose |\n|----------|---------|\n| `buildObservationPrompt()` | Creates prompts for parsing tool observations into structured XML format |\n| `buildSummaryPrompt()` | Generates prompts for creating session summaries |\n| `buildContinuationPrompt()` | Builds prompts for continuing sessions with existing context |\n\nThe SDK uses `ModeConfig` objects that define observation types, prompt templates, and output format guidelines specific to each IDE integration.\n\n资料来源：[src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)\n\n### 3. Prompt Builder (`src/server/generation/providers/shared/prompt-builder.ts`)\n\nHandles the generation of structured output schemas for LLM interactions:\n\n```typescript\nfunction buildObservationOutputSchema(mode: ModeConfig): string {\n const types = mode.observation_types.map(t => t.id).join(' | ');\n return [\n '
\n
\n\n# Hooks System and Lifecycle\n\n## Overview\n\nThe Hooks System is the core mechanism by which Claude-Mem captures observations, user interactions, and session events from Claude Code to build persistent memory across sessions. The system integrates with Claude Code's plugin hook API to monitor and record agent activities at strategic points in the conversation lifecycle.\n\nClaude-Mem registers multiple hook handlers that fire at different stages: session initialization, user message processing, tool execution, and session termination. Each handler extracts relevant context and stores observations that inform future sessions about project state and progress.\n\n资料来源：[cursor-hooks/README.md](https://github.com/thedotmack/claude-mem/blob/main/cursor-hooks/README.md)\n\n---\n\n## Architecture Overview\n\n### Hook System Components\n\nThe hook system consists of three primary layers:\n\n| Layer | Purpose | Location |\n|-------|---------|----------|\n| **Hook Configuration** | Declares which hooks to register with Claude Code | `plugin/hooks/hooks.json` |\n| **Hook Handlers** | TypeScript implementations that process hook events | `src/cli/handlers/*.ts` |\n| **Hook Constants** | Shared definitions and configuration | `src/shared/hook-constants.ts` |\n\n资料来源：[src/cli/hook-command.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/hook-command.ts)\n\n### Hook Registration Flow\n\n```mermaid\ngraph TD\n A[Claude Code Startup] --> B[Load hooks.json]\n B --> C[Register All Hooks]\n C --> D{Hook Event Occurs}\n D -->|PreToolUse| E[observation.ts]\n D -->|PostToolUse| E\n D -->|User| F[user-message.ts]\n D -->|Stop| G[summarize.ts]\n D -->|Start| H[session-init.ts]\n E --> I[Extract Context]\n F --> I\n G --> I\n H --> I\n I --> J[Store Observation]\n J --> K[Memory Index Updated]\n```\n\n---\n\n## Hook Types and Handlers\n\n### Hook Configuration Schema\n\nThe `hooks.json` file defines the complete hook registration:\n\n```json\n{\n \"hooks\": {\n \"Start\": [\n {\n \"hook\": \"Start\",\n \"name\": \"session-init\",\n \"path\": \"相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [plugin/hooks/hooks.json](https://github.com/thedotmack/claude-mem/blob/main/plugin/hooks/hooks.json)\n- [src/cli/hook-command.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/hook-command.ts)\n- [src/shared/hook-constants.ts](https://github.com/thedotmack/claude-mem/blob/main/src/shared/hook-constants.ts)\n- [src/cli/handlers/observation.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/handlers/observation.ts)\n- [src/cli/handlers/session-init.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/handlers/session-init.ts)\n- [src/cli/handlers/user-message.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/handlers/user-message.ts)\n- [src/cli/handlers/summarize.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/handlers/summarize.ts)\n\n
\n\n# Worker Service Architecture\n\nThe Worker Service is the core backend component of claude-mem, responsible for processing, storing, and serving memory observations across Claude Code sessions. It runs as a persistent background service that handles LLM inference, observation generation, and semantic search operations.\n\n## Overview\n\nThe Worker Service operates independently from Claude Code sessions, maintaining a long-running process that:\n\n- Receives tool usage observations from Claude Code via plugin hooks\n- Generates semantic summaries using configured LLM providers (Claude, Gemini, OpenRouter)\n- Stores observations in a local SQLite database with Chroma vector embeddings\n- Serves a web-based viewer UI and REST API for browsing and querying memories\n\n```mermaid\ngraph TD\n subgraph \"Claude Code\"\n A[Tool Execution] --> B[Plugin Hooks]\n B --> C[Tool Result Persist Event]\n end\n \n subgraph \"Worker Service\"\n D[HTTP Server :37777] --> E[Route Handlers]\n E --> F[Session Manager]\n F --> G[Observation Generator]\n G --> H[LLM Providers]\n H --> I[Database Manager]\n I --> J[SQLite + Chroma]\n end\n \n C -->|SSE/WebSocket| D\n D -->|Viewer UI| K[Browser Client]\n D -->|REST API| L[External Clients]\n```\n\n## Core Components\n\n### WorkerService\n\nThe main service orchestrator located in `src/services/worker-service.ts`. It initializes all sub-components, registers HTTP routes, manages lifecycle events, and coordinates between the UI and backend processing.\n\n**Key Responsibilities:**\n\n| Responsibility | Description |\n|----------------|-------------|\n| Lifecycle Management | Coordinates startup/shutdown of all service components |\n| Route Registration | Registers ViewerRoutes, SessionRoutes, DataRoutes, SettingsRoutes, LogsRoutes, MemoryRoutes |\n| Middleware | Implements initialization check middleware (returns 503 during DB init) |\n| Database Initialization | Ensures SQLite and Chroma are ready before accepting requests |\n| SSE Broadcasting | Manages real-time event streaming to connected clients |\n\n资料来源：[src/services/worker-service.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts)\n\n### Session Manager\n\nManages individual Claude Code session lifecycles, tracking active sessions and coordinating observation generation per session.\n\n资料来源：[src/services/worker/SessionManager.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/SessionManager.ts)\n\n## LLM Provider Architecture\n\nThe Worker Service supports multiple LLM backends through a provider abstraction pattern.\n\n### Provider Comparison\n\n| Provider | Class | Purpose | API Endpoint |\n|----------|-------|---------|--------------|\n| Anthropic Claude | `ClaudeProvider` | Primary observation generation | api.anthropic.com |\n| Google Gemini | `GeminiProvider` | Alternative generation | Generative Language API |\n| OpenRouter | `OpenRouterProvider` | Unified multi-model access | openrouter.ai |\n\n资料来源：\n- [src/services/worker/ClaudeProvider.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/ClaudeProvider.ts)\n- [src/services/worker/GeminiProvider.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/GeminiProvider.ts)\n- [src/services/worker/OpenRouterProvider.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/OpenRouterProvider.ts)\n\n### Provider Selection\n\nThe system automatically selects providers based on:\n1. Configuration in `~/.claude-mem/settings.json`\n2. Available API keys in environment variables\n3. Fallback to Claude as primary provider\n\n## HTTP Route Architecture\n\nThe Worker Service exposes REST endpoints through registered route handlers:\n\n```mermaid\ngraph LR\n A[HTTP :37777] --> B[ViewerRoutes]\n A --> C[SessionRoutes]\n A --> D[DataRoutes]\n A --> E[SettingsRoutes]\n A --> F[LogsRoutes]\n A --> G[MemoryRoutes]\n A --> H[ServerV1Routes]\n```\n\n### Route Groups\n\n| Route | File | Purpose |\n|-------|------|---------|\n| Viewer | `ViewerRoutes` | Serves the web-based memory viewer UI |\n| Session | `SessionRoutes` | Manages session lifecycle, continuation prompts |\n| Data | `DataRoutes` | Pagination, filtering, observation retrieval |\n| Settings | `SettingsRoutes` | User preferences and configuration |\n| Logs | `LogsRoutes` | Service logging and diagnostics |\n| Memory | `MemoryRoutes` | Memory CRUD operations, search |\n| V1 API | `ServerV1Routes` | Legacy compatibility endpoints |\n\n资料来源：[src/services/worker/http/routes/MemoryRoutes.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/http/routes/MemoryRoutes.ts)\n\n## Job Queue System\n\nObservation generation is handled asynchronously through a BullMQ-based job queue system.\n\n### Queue Configuration\n\n```typescript\ninterface QueueConfig {\n connection: RedisConnectionConfig;\n prefix: string;\n defaultJobOptions: {\n attempts: number;\n backoff: { type: 'exponential'; delay: number };\n removeOnComplete: boolean;\n };\n}\n```\n\n资料来源：[src/server/jobs/ServerJobQueue.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/jobs/ServerJobQueue.ts)\n\n### Event Handling\n\nThe queue emits events for observability:\n\n| Event | Handler | Description |\n|-------|---------|-------------|\n| `completed` | `onCompleted` | Job finished successfully |\n| `failed` | `onFailed` | Job failed after all retries |\n| `progress` | `onProgress` | Job reported progress percentage |\n| `stalled` | `notifyStalled` | Job became unresponsive |\n\n## Process Management\n\nThe Worker Service can run in multiple modes:\n\n```mermaid\ngraph TD\n A[Start Command] --> B{IDE Type}\n B -->|claude-code| C[Claude Code Plugin Mode]\n B -->|gemini-cli| D[Gemini CLI Mode]\n B -->|opencode| E[OpenCode Mode]\n \n C --> F[Persistent Background Process]\n D --> F\n E --> F\n F --> G[Supervisor Process]\n G --> H[Worker Service :37777]\n```\n\n### Runtime Modes\n\n| Mode | Activation | Behavior |\n|------|------------|----------|\n| Auto-start | Default | Worker starts automatically on first session |\n| Manual | `npx claude-mem start` | Explicit user initiation |\n| Background | Supervisor-managed | Persistent daemon with health monitoring |\n\n资料来源：[src/npx-cli/commands/runtime.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/runtime.ts)\n\n### Process Manager\n\nThe `ProcessManager` handles:\n\n- Spawning and monitoring worker processes\n- Health check endpoints (`/health`, `/readiness`)\n- Automatic restart on crash\n- Graceful shutdown handling\n\n资料来源：[src/services/infrastructure/ProcessManager.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/infrastructure/ProcessManager.ts)\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CLAUDE_MEM_WORKER_PORT` | `37777` | Worker HTTP server port |\n| `CLAUDE_MEM_WORKER_HOST` | `localhost` | Worker binding host |\n| `CLAUDE_MEM_MODE` | - | Active mode configuration |\n| `CLAUDE_MEM_WELCOME_HINT_ENABLED` | `true` | Show first-use hints |\n\n### Service Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/health` | GET | Basic health check |\n| `/readiness` | GET | Readiness probe (DB initialized) |\n| `/version` | GET | Service version info |\n| `/chroma/status` | GET | Vector database status |\n\n## Startup Sequence\n\n```mermaid\nsequenceDiagram\n participant User\n participant Plugin as Claude Code Plugin\n participant Worker as Worker Service\n participant DB as SQLite/Chroma\n participant Queue as Job Queue\n\n User->>Plugin: First Claude Code session\n Plugin->>Worker: Tool result events\n Worker->>DB: Initialize connections\n DB-->>Worker: Ready\n Worker->>Queue: Start worker process\n Queue->>Worker: Ready\n Worker-->>Plugin: Service available\n Plugin->>Worker: Stream observations\n Worker->>Queue: Enqueue generation jobs\n Queue->>Worker: Process observations\n Worker->>DB: Store summaries\n```\n\n## Data Flow\n\n### Observation Lifecycle\n\n1. **Capture**: Plugin captures tool execution events (read, edit, shell commands)\n2. **Transmission**: Events sent via SSE to Worker Service\n3. **Queuing**: Jobs added to BullMQ generation queue\n4. **Processing**: LLM provider generates semantic summary\n5. **Storage**: SQLite stores structured data, Chroma stores vector embeddings\n6. **Retrieval**: Future sessions query relevant observations via semantic search\n\n资料来源：[src/services/worker-service.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts)\n\n## Error Handling\n\n### Initialization Guard\n\nDuring startup, the service returns HTTP 503 for all requests except health/readiness checks:\n\n```\nRequest → Middleware Check → DB Initialized?\n ├─ Yes → Pass through to routes\n └─ No → 503 \"Service initializing\"\n```\n\n### Queue Failure Handling\n\nFailed jobs trigger listener callbacks:\n\n```typescript\nw.on('failed', (jobId: string, error: Error) => {\n for (const l of this.listeners) {\n l.onFailed?.(jobId, attemptsMade, error.message);\n }\n});\n```\n\n资料来源：[src/server/jobs/ServerJobQueue.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/jobs/ServerJobQueue.ts)\n\n## Extension Points\n\n### Custom LLM Providers\n\nProviders implement a common interface allowing:\n\n- Custom API endpoints\n- Different authentication methods\n- Provider-specific prompt formatting\n- Rate limiting and retry policies\n\n### Mode System\n\nThe Worker Service supports configurable modes via `ModeConfig` that define:\n\n- Observation types to capture\n- Prompt templates for generation\n- Summary output formats\n- System identity instructions\n\n## Security Considerations\n\n- Service binds to localhost by default\n- No authentication on local-only deployments\n- All data stored in `~/.claude-mem` directory\n- API keys loaded from environment variables\n\n---\n\n\n\n## Database Schema and Storage\n\n### 相关页面\n\n相关主题：[System Architecture Overview](#page-architecture-overview), [Data Flow and Processing](#page-data-flow), [Search Architecture](#page-search-architecture)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/services/worker-service.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts)\n- [src/server/jobs/ServerJobQueue.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/jobs/ServerJobQueue.ts)\n- [src/services/worker/ClaudeProvider.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/ClaudeProvider.ts)\n- [src/services/worker/GeminiProvider.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/GeminiProvider.ts)\n- [src/services/worker/OpenRouterProvider.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/OpenRouterProvider.ts)\n- [src/services/worker/http/routes/MemoryRoutes.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/http/routes/MemoryRoutes.ts)\n- [src/npx-cli/commands/runtime.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/runtime.ts)\n- [src/services/infrastructure/ProcessManager.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/infrastructure/ProcessManager.ts)\n\n
\n\n# Database Schema and Storage\n\n## Overview\n\nClaude-Mem uses SQLite as its primary persistent storage layer to maintain session continuity, store observations, and preserve learned context across sessions. The database schema captures the complete lifecycle of AI sessions, including tool usage, observations, summaries, and temporal data for timeline reconstruction.\n\nThe storage system is designed to support:\n- Multi-session tracking with unique identifiers\n- Observation persistence with semantic metadata\n- Session summarization storage\n- Timeline event reconstruction\n- Project-based organization\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Worker Service] --> B[DBManager]\n B --> C[SQLite Database]\n C --> D[schema_versions]\n C --> E[sdk_sessions]\n C --> F[observations]\n C --> G[session_summaries]\n C --> H[pending_messages]\n C --> I[user_prompts]\n C --> J[projects]\n \n K[SessionStore] -.-> E\n L[Observations] -.-> F\n M[Summaries] -.-> G\n N[Timeline] -.-> J\n```\n\n## Core Tables\n\n### schema_versions\n\nTracks applied database migrations to ensure schema consistency across upgrades.\n\n| Column | Type | Description |\n|--------|------|-------------|\n| version | INTEGER PRIMARY KEY | Migration version number |\n| applied_at | TEXT | ISO timestamp of migration application |\n\n资料来源：[src/services/sqlite/migrations/runner.ts:1-50]()\n\n### sdk_sessions\n\nStores metadata about each Claude session managed by the SDK.\n\n| Column | Type | Description |\n|--------|------|-------------|\n| id | INTEGER PRIMARY KEY | Auto-incrementing row ID |\n| memory_session_id | TEXT NOT NULL | Unique session identifier |\n| content_session_id | TEXT NOT NULL | Content/session reference ID |\n| project | TEXT NOT NULL | Project name for grouping |\n| status | TEXT | Session status (active/completed/etc) |\n| created_at | TEXT NOT NULL | Creation timestamp |\n| created_at_epoch | INTEGER NOT NULL | Epoch timestamp for sorting |\n\n资料来源：[src/services/sqlite/migrations/runner.ts:60-90]()\n\n### observations\n\nRecords tool usage observations captured during sessions. Observations are the primary mechanism for preserving learned context.\n\n| Column | Type | Description |\n|--------|------|-------------|\n| id | INTEGER PRIMARY KEY | Auto-incrementing observation ID |\n| memory_session_id | TEXT NOT NULL | Foreign key to sdk_sessions |\n| tool_name | TEXT | Name of the tool used |\n| tool_input | TEXT | JSON-encoded tool input |\n| tool_output | TEXT | JSON-encoded tool output |\n| observation_type | TEXT | Type classification (fact, decision, etc.) |\n| title | TEXT | Observation title |\n| subtitle | TEXT | Brief description |\n| narrative | TEXT | Detailed narrative |\n| concepts | TEXT | JSON array of concept tags |\n| files_read | TEXT | JSON array of files read |\n| files_modified | TEXT | JSON array of files modified |\n| created_at | TEXT NOT NULL | Creation timestamp |\n| created_at_epoch | INTEGER NOT NULL | Epoch timestamp |\n\n资料来源：[src/services/sqlite/SessionStore.ts](), [src/services/sqlite/Observations.ts]()\n\n### session_summaries\n\nStores AI-generated summaries of completed sessions, capturing requests, findings, and next steps.\n\n| Column | Type | Description |\n|--------|------|-------------|\n| id | INTEGER PRIMARY KEY | Auto-incrementing summary ID |\n| memory_session_id | TEXT NOT NULL | Foreign key to sdk_sessions |\n| project | TEXT NOT NULL | Project name |\n| request | TEXT | Original user request |\n| investigated | TEXT | What was investigated |\n| learned | TEXT | Key learnings |\n| completed | TEXT | Completed work |\n| next_steps | TEXT | Planned next steps |\n| files_read | TEXT | Files read during session |\n| files_edited | TEXT | Files modified during session |\n| notes | TEXT | Additional notes |\n| prompt_number | INTEGER | Session prompt sequence number |\n| created_at | TEXT NOT NULL | Creation timestamp |\n| created_at_epoch | INTEGER NOT NULL | Epoch timestamp |\n\n资料来源：[src/services/sqlite/migrations/runner.ts:50-80](), [src/services/sqlite/Summaries.ts]()\n\n### pending_messages\n\nQueue table for messages awaiting processing by the worker service.\n\n| Column | Type | Description |\n|--------|------|-------------|\n| id | INTEGER PRIMARY KEY | Auto-incrementing message ID |\n| content_session_id | TEXT NOT NULL | Session reference |\n| message_id | INTEGER | Claude message ID |\n| message_type | TEXT | Message type (observation/summarize) |\n| payload | TEXT | JSON message payload |\n| status | TEXT | Processing status |\n| created_at | TEXT NOT NULL | Creation timestamp |\n| created_at_epoch | INTEGER NOT NULL | Epoch timestamp |\n| failed_at_epoch | INTEGER | Epoch timestamp of last failure |\n\n资料来源：[src/services/sqlite/migrations/runner.ts:200-230]()\n\n### user_prompts\n\nStores original user prompts for each session.\n\n| Column | Type | Description |\n|--------|------|-------------|\n| id | INTEGER PRIMARY KEY | Auto-incrementing prompt ID |\n| content_session_id | TEXT NOT NULL | Session reference |\n| prompt | TEXT NOT NULL | User prompt text |\n| created_at | TEXT NOT NULL | Creation timestamp |\n| created_at_epoch | INTEGER NOT NULL | Epoch timestamp |\n\n### projects\n\nMaintains project registry for organizing sessions and observations.\n\n| Column | Type | Description |\n|--------|------|-------------|\n| id | INTEGER PRIMARY KEY | Auto-incrementing project ID |\n| name | TEXT NOT NULL UNIQUE | Project name |\n| created_at | TEXT NOT NULL | Creation timestamp |\n\n资料来源：[src/storage/sqlite/schema.ts](), [src/services/sqlite/Timeline.ts]()\n\n## Schema Migrations\n\nThe system uses a versioned migration system to handle schema evolution. Migrations are applied sequentially and tracked in the `schema_versions` table.\n\n### Migration Version History\n\n| Version | Description |\n|---------|-------------|\n| 7 | Session summaries table creation with UNIQUE constraint removal |\n| 17 | Column renames: `sdk_session_id` → `memory_session_id`, `claude_session_id` → `content_session_id` |\n| 20 | Added `failed_at_epoch` column to `pending_messages` |\n\n资料来源：[src/services/sqlite/migrations/runner.ts:40-45](), [src/services/sqlite/migrations/runner.ts:150-180](), [src/services/sqlite/migrations/runner.ts:195-220]()\n\n### Migration Execution\n\nMigrations are executed via the `MigrationRunner` class which:\n\n1. Checks current schema version from `schema_versions`\n2. Applies pending migrations in order\n3. Records each applied version with timestamp\n4. Handles safe column renaming (only if column exists)\n\n```typescript\nprivate addFailedAtEpochColumn(): void {\n const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(20);\n if (applied) return;\n \n const tableInfo = this.db.query('PRAGMA table_info(pending_messages)').all();\n const hasColumn = tableInfo.some(col => col.name === 'failed_at_epoch');\n \n if (!hasColumn) {\n this.db.run('ALTER TABLE pending_messages ADD COLUMN failed_at_epoch INTEGER');\n }\n}\n```\n\n资料来源：[src/services/sqlite/migrations/runner.ts:195-215]()\n\n## Session ID Naming Convention\n\nThe system underwent a terminology migration in version 17:\n\n| Old Name | New Name | Purpose |\n|----------|----------|---------|\n| `sdk_session_id` | `memory_session_id` | Primary session identifier across memory system |\n| `claude_session_id` | `content_session_id` | Claude/Content API session reference |\n\nThis rename reflects the system's expansion beyond Claude Code to support other AI platforms (Gemini CLI, OpenClaw).\n\n资料来源：[src/services/sqlite/migrations/runner.ts:145-170]()\n\n## Data Access Layer\n\n### SessionStore\n\nProvides CRUD operations for session management:\n\n```typescript\ninterface SessionStore {\n createSession(session: Session): Promise相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/services/sqlite/schema.sql](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/schema.sql)\n- [src/services/sqlite/SessionStore.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/SessionStore.ts)\n- [src/services/sqlite/Observations.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Observations.ts)\n- [src/services/sqlite/Summaries.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Summaries.ts)\n- [src/services/sqlite/Timeline.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Timeline.ts)\n- [src/services/sqlite/migrations.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/migrations.ts)\n- [src/services/sqlite/migrations/runner.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/migrations/runner.ts)\n- [src/storage/sqlite/schema.ts](https://github.com/thedotmack/claude-mem/blob/main/src/storage/sqlite/schema.ts)\n\n
\n\n# Data Flow and Processing\n\n## Overview\n\nClaude-Mem implements a sophisticated data pipeline that captures, processes, stores, and retrieves contextual information from Claude Code sessions. The system transforms raw transcript data into structured observations and summaries that can be injected into future sessions, enabling persistent memory across sessions.\n\nThe data flow architecture spans multiple layers: **ingestion** (capturing session activity), **processing** (generating structured observations), **storage** (persisting to local filesystem), **retrieval** (searching and filtering), and **injection** (presenting relevant context to Claude).\n\n## System Architecture\n\n```mermaid\ngraph TD\n subgraph Ingestion [\"Ingestion Layer\"]\n TW[Transcript Watcher] --> TP[Transcript Processor]\n TP --> OG[Observation Generator]\n end\n \n subgraph Processing [\"Processing Layer\"]\n OG --> CB[Context Builder]\n CB --> OC[Observation Compiler]\n OC --> Q[Job Queue]\n Q --> QW[Queue Worker]\n end\n \n subgraph Storage [\"Storage Layer\"]\n QW --> FS[File System相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/services/context/ContextBuilder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/context/ContextBuilder.ts)\n- [src/services/context/ObservationCompiler.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/context/ObservationCompiler.ts)\n- [src/services/transcripts/processor.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/transcripts/processor.ts)\n- [src/services/transcripts/watcher.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/transcripts/watcher.ts)\n- [src/server/generation/ProviderObservationGenerator.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/ProviderObservationGenerator.ts)\n- [src/cli/handlers/context.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/handlers/context.ts)\n~/.claude-mem]\n FS --> OBS[Observations DB]\n FS --> SUMM[Summary DB]\n end\n \n subgraph Retrieval [\"Retrieval Layer\"]\n CLI[CLI Context Handler] --> SR[Search & Retrieval]\n SR --> CB\n CB --> CONTEXT[Context Injection]\n end\n \n subgraph Output [\"Output Layer\"]\n CONTEXT --> UI[Viewer UI]\n CONTEXT --> SDK[SDK Prompts]\n end\n```\n\n## Core Data Flow Pipeline\n\n### 1. Transcript Watching\n\nThe transcript watcher monitors Claude Code sessions in real-time, capturing all activity as it occurs.\n\n**Key Components:**\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| TranscriptWatcher | `src/services/transcripts/watcher.ts` | Monitors transcript files for changes |\n| TranscriptProcessor | `src/services/transcripts/processor.ts` | Parses and extracts events from transcripts |\n\nThe watcher detects when new content is written to transcript files and triggers processing. Events captured include:\n\n- Tool invocations (`Read`, `Write`, `Edit`, `Bash`, etc.)\n- User prompts\n- Assistant responses\n- System events\n\n### 2. Observation Generation\n\nObservations are generated from processed transcript events using LLM providers.\n\n```mermaid\ngraph LR\n subgraph Input\n EV[Event Data] --> PG[Prompt Builder]\n MC[Mode Config] --> PG\n end\n \n subgraph Generation\n PG --> LLM[LLM Provider]\n LLM --> XML[XML Output]\n end\n \n subgraph Output\n XML --> OBS[Observation Record]\n XML --> PRIV[Private Data Check]\n end\n```\n\n**ProviderObservationGenerator** handles the generation flow:\n\n1. Builds prompts using `ModeConfig` and observation types\n2. Sends requests to configured LLM provider (Claude by default)\n3. Parses XML-structured responses\n4. Validates and sanitizes output\n\nThe generated observation schema follows this structure:\n\n```xml\n
Max 3 attempts\n```\n\n**ServerJobQueue** manages job lifecycle:\n\n| Feature | Description |\n|---------|-------------|\n| Retry Policy | Automatic retry with exponential backoff |\n| Progress Tracking | Real-time job progress events |\n| Stalled Detection | Monitors for stuck jobs |\n| Cross-Process Events | Redis pub/sub for distributed workers |\n\n资料来源：[src/server/jobs/ServerJobQueue.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/jobs/ServerJobQueue.ts)\n\n## Storage Architecture\n\nAll data persists to `~/.claude-mem/` on the local filesystem.\n\n```mermaid\ngraph TD\n subgraph \"~/.claude-mem\"\n OBS[observations/]\n SUMM[summary/]\n CONTEXT[context/]\n CONFIG[config.json]\n MODES[modes/]\n end\n \n OBS --> |JSON files| RECORDS[Individual records]\n SUMM --> |JSON files| SESSION_SUMM[Session summaries]\n CONTEXT --> |Compiled| READY[Ready for injection]\n```\n\n### File Structure\n\n| Directory | Content | Format |\n|-----------|---------|--------|\n| `observations/` | Individual observations | JSON with metadata |\n| `summary/` | Session summaries | JSON with sections |\n| `context/` | Compiled context bundles | JSON arrays |\n| `modes/` | Mode configurations | JSON |\n| `transcripts/` | Raw session transcripts | Text/markdown |\n\n## Summary Generation Flow\n\nSummaries are generated at session end to provide high-level overviews.\n\n```mermaid\ngraph TD\n subgraph SessionEnd\n END[Session Complete] --> EXTRACT[Extract Key Events]\n EXTRACT --> BUILD[Build Summary Prompt]\n end\n \n subgraph Generation\n BUILD --> LLM[LLM Generation]\n LLM --> PARSE[Parse Summary XML]\n end\n \n subgraph Output\n PARSE --> STRUCT[Structured Summary]\n STRUCT --> STORE[Store to summary/]\n STRUCT --> DISPLAY[Display in UI]\n end\n```\n\nSummary output format:\n\n```xml\n
\n
\n\n# Search Architecture\n\n## Overview\n\nThe Search Architecture in claude-mem provides a multi-strategy search system that enables semantic and structured querying across observations, sessions, and prompts. The architecture employs a plugin-based strategy pattern that allows combining different search backends—primarily Chroma (vector database) and SQLite—through a unified orchestration layer.\n\nThe search system serves as the foundation for context injection, enabling Claude Code to retrieve relevant historical observations from previous sessions and maintain knowledge continuity across session boundaries.\n\n---\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Search Request] --> B[SearchOrchestrator]\n B --> C[HybridSearchStrategy]\n C --> D[ChromaSearchStrategy]\n C --> E[SQLiteSearchStrategy]\n D --> F[ChromaSync]\n F --> G[Chroma DB]\n E --> H[SQLite DB]\n I[ChromaMcpManager] --> G\n J[TimelineBuilder] --> K[Timeline Results]\n \n style B fill:#e1f5fe\n style C fill:#fff3e0\n style D fill:#e8f5e9\n style E fill:#fce4ec\n```\n\n---\n\n## Core Components\n\n### SearchOrchestrator\n\nThe `SearchOrchestrator` serves as the central entry point for all search operations. It receives search requests, determines which strategies to invoke, and aggregates results from multiple sources.\n\n**Key Responsibilities:**\n- Route search requests to appropriate strategies\n- Merge and rank results from different backends\n- Handle search type filtering (observations, sessions, prompts)\n- Support project-scoped searches\n\n**Search Types Supported:**\n\n| Search Type | Description |\n|-------------|-------------|\n| `all` | Search across observations, sessions, and prompts |\n| `observations` | Search observation records only |\n| `sessions` | Search session metadata |\n| `prompts` | Search user prompts |\n| `by-concept` | Find observations tagged with specific concepts |\n| `by-file` | Find observations related to specific file paths |\n| `by-type` | Filter by observation type (decisions, changes, etc.) |\n\n资料来源：[src/services/worker/search/SearchOrchestrator.ts]()\n\n### HybridSearchStrategy\n\nThe `HybridSearchStrategy` combines multiple search strategies to achieve optimal recall and precision. It orchestrates parallel execution of Chroma and SQLite searches, then merges the results.\n\n```mermaid\ngraph LR\n A[Query] --> B[Chroma Search]\n A --> C[SQLite Search]\n B --> D[Result Merge]\n C --> D\n D --> E[Ranked Results]\n```\n\n**Strategy Selection Logic:**\n- Vector similarity search → Chroma\n- Structured queries (filters, date ranges) → SQLite\n- Combined relevance + recency ranking → Hybrid merge\n\n资料来源：[src/services/worker/search/strategies/HybridSearchStrategy.ts]()\n\n### ChromaSearchStrategy\n\nThe `ChromaSearchStrategy` implements semantic search using the Chroma vector database. It provides high-dimensional embedding-based similarity search with filtering capabilities.\n\n**Core Features:**\n- Batch querying with configurable batch size (`SEARCH_CONSTANTS.CHROMA_BATCH_SIZE`)\n- Filter by document type, concepts, file paths\n- Ordering by relevance, date descending, or date ascending\n- Recency filtering of results\n\n**Key Methods:**\n- `executeChromaSearch()` - Performs the actual Chroma query\n- `filterByRecency()` - Filters results based on temporal relevance\n- `categorizeByDocType()` - Separates results into observations, sessions, prompts\n\n```typescript\nconst chromaResults = await this.chromaSync.queryChroma(\n query,\n SEARCH_CONSTANTS.CHROMA_BATCH_SIZE,\n whereFilter\n);\n```\n\n资料来源：[src/services/worker/search/strategies/ChromaSearchStrategy.ts:30-45]()\n\n### SQLiteSearchStrategy\n\nThe `SQLiteSearchStrategy` handles structured queries and provides fallback search when Chroma is unavailable. It performs full-text and attribute-based filtering using SQLite's query capabilities.\n\n**Use Cases:**\n- Exact match filtering\n- Date range queries\n- Project-specific searches\n- Filtered searches by metadata fields\n\n---\n\n## Vector Search Infrastructure\n\n### ChromaSync\n\n`ChromaSync` manages the synchronization between the local SQLite database and the Chroma vector database. It handles embedding generation and data persistence.\n\n**Responsibilities:**\n- Query Chroma collections\n- Sync observations to Chroma\n- Manage embedding pipelines\n- Handle batch operations\n\n资料来源：[src/services/sync/ChromaSync.ts]()\n\n### ChromaMcpManager\n\n`ChromaMcpManager` handles the Model Context Protocol (MCP) integration for Chroma. It provides an abstraction layer for interacting with Chroma's MCP server when available.\n\n**Features:**\n- MCP server status monitoring\n- Toggle MCP integration on/off\n- Graceful fallback when MCP unavailable\n\n资料来源：[src/services/sync/ChromaMcpManager.ts]()\n\n---\n\n## Search Routes API\n\nThe search functionality is exposed through HTTP routes managed by the Worker service:\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/search/observations` | GET | Search observations |\n| `/search/sessions` | GET | Search sessions |\n| `/search/prompts` | GET | Search prompts |\n| `/search/by-concept` | GET | Find by concept tag |\n| `/search/by-file` | GET | Find by file path |\n| `/search/by-type` | GET | Find by observation type |\n| `/search/recent-context` | GET | Get recent context |\n| `/search/context-timeline` | GET | Get context timeline |\n| `/search/timeline-by-query` | GET | Timeline by search query |\n| `/context/preview` | GET | Preview context |\n| `/context/inject` | POST | Inject context |\n\n资料来源：[src/services/worker/README.md]()\n\n---\n\n## Timeline Search\n\n### TimelineBuilder\n\n`TimelineBuilder` constructs temporal views of search results, enabling users to explore observations and context across time.\n\n**Capabilities:**\n- Build timelines based on search queries\n- Aggregate results by date periods\n- Support context preview generation\n- Inject timeline-based context into sessions\n\n```mermaid\ngraph TD\n A[Search Query] --> B[TimelineBuilder]\n B --> C[Group by Date]\n C --> D[Timeline Nodes]\n D --> E[Context Preview]\n E --> F[Inject to Session]\n```\n\n资料来源：[src/services/worker/search/TimelineBuilder.ts]()\n\n---\n\n## Search Configuration\n\n### Configuration Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | number | 50 | Observations to inject (1-200) |\n| `CLAUDE_MEM_CONTEXT_SESSIONS` | number | varies | Sessions to pull from (1-50) |\n\n### Search Constants\n\n```typescript\nconst SEARCH_CONSTANTS = {\n CHROMA_BATCH_SIZE: 100, // Batch size for Chroma queries\n // ... additional constants\n};\n```\n\n---\n\n## Search Workflow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Orchestrator\n participant HybridStrategy\n participant Chroma\n participant SQLite\n \n Client->>Orchestrator: Search Request\n Orchestrator->>HybridStrategy: Route to Hybrid\n HybridStrategy->>Chroma: Vector Query\n HybridStrategy->>SQLite: Structured Query\n Chroma-->>HybridStrategy: Embedding Results\n SQLite-->>HybridStrategy: Filtered Results\n HybridStrategy->>HybridStrategy: Merge & Rank\n HybridStrategy-->>Orchestrator: Combined Results\n Orchestrator-->>Client: Ranked Results\n```\n\n---\n\n## Data Flow\n\n### Observation Search Flow\n\n1. User initiates search via UI or API\n2. `SearchOrchestrator` receives and parses request\n3. Determines search scope (observations, sessions, prompts)\n4. Invokes `HybridSearchStrategy`\n5. Parallel execution:\n - `ChromaSearchStrategy` performs vector similarity search\n - `SQLiteSearchStrategy` performs structured filtering\n6. Results are categorized by document type\n7. Results filtered by recency if configured\n8. Final results merged and ranked\n9. Returned to client with metadata\n\n### Context Injection Flow\n\n1. User requests context preview or injection\n2. `TimelineBuilder` builds temporal view\n3. Observations retrieved based on recency and relevance\n4. Context formatted for Claude Code consumption\n5. Injected into active session via worker service\n\n---\n\n## Strategy Pattern Implementation\n\nThe search architecture follows the Strategy pattern, allowing runtime selection of search algorithms:\n\n```mermaid\nclassDiagram\n class SearchStrategy {\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/strategies/ChromaSearchStrategy.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/strategies/ChromaSearchStrategy.ts)\n- [src/services/worker/search/strategies/SQLiteSearchStrategy.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/strategies/SQLiteSearchStrategy.ts)\n- [src/services/sync/ChromaSync.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sync/ChromaSync.ts)\n- [src/services/sync/ChromaMcpManager.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sync/ChromaMcpManager.ts)\n- [src/services/worker/search/TimelineBuilder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/TimelineBuilder.ts)\n\n
\n\n# MCP Tools and Context Generation\n\n## Overview\n\nMCP (Model Context Protocol) Tools and Context Generation form the core infrastructure that enables claude-mem to provide persistent memory capabilities across Claude Code sessions. This system captures tool usage observations, generates semantic summaries, and makes them available to future sessions through a structured context injection mechanism.\n\nThe architecture consists of three primary layers:\n\n1. **Observation Capture Layer** - Captures tool interactions and state changes during Claude Code sessions\n2. **Context Generation Layer** - Transforms raw observations into structured, queryable context\n3. **Context Injection Layer** - Delivers relevant context to Claude Code when new sessions start\n\n资料来源：[src/server/generation/providers/shared/prompt-builder.ts:1-50]()\n\n---\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Observation Capture\"\n A[Claude Code Session] --> B[Tool Usage Events]\n B --> C[Observation Builder]\n C --> D[Observation XML Format]\n end\n\n subgraph \"Context Generation\"\n D --> E[Context Generator Service]\n E --> F[Smart File Parser]\n F --> G[Summary Generator]\n G --> H[Indexed Memory Store]\n end\n\n subgraph \"Context Injection\"\n H --> I[MCP Tools]\n H --> J[Search Routes]\n I --> K[Claude Code]\n J --> K\n end\n\n subgraph \"Storage Layer\"\n K --> L[~/.claude-mem]\n H --> L\n end\n```\n\n---\n\n## Observation System\n\n### XML Schema Structure\n\nObservations are generated in a standardized XML format that allows for structured parsing and searchability. The observation schema includes:\n\n```xml\nRelated Source Files
\n\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- [src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)\n- [src/sdk/parser.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/parser.ts)\n- [src/services/context-generator.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/context-generator.ts)\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/utils/claude-md-utils.ts](https://github.com/thedotmack/claude-mem/blob/main/src/utils/claude-md-utils.ts)\n\n
\n\n# Installation Guide\n\nClaude-Mem is a persistent memory plugin for Claude Code, enabling seamless context preservation across sessions. This guide covers all supported installation methods across different platforms and integrated development environments.\n\n## Overview\n\nClaude-Mem can be installed through multiple channels depending on your use case:\n\n| Installation Method | Platform | Use Case |\n|-------------------|----------|----------|\n| `npx claude-mem install` | macOS, Linux, Windows | Standard installation for Claude Code |\n| `npx claude-mem install --ide gemini-cli` | All platforms | Integration with Gemini CLI |\n| `npx claude-mem install --ide opencode` | All platforms | Integration with OpenCode |\n| `/plugin` commands | Claude Code | In-app plugin marketplace |\n| OpenClaw Gateway | OpenClaw | Persistent memory on OpenClaw gateways |\n| Docker | Containerized | Isolated deployment environments |\n\nAll installations store data locally in `~/.claude-mem` on the host machine. 资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n\n## System Requirements\n\nBefore installation, ensure your environment meets the following prerequisites:\n\n| Requirement | Specification |\n|-------------|---------------|\n| Node.js | 18+ |\n| Package Manager | npm, npx |\n| Claude Code | Pro/Max subscription for CLI-based auth |\n| API Key | `ANTHROPIC_API_KEY` (optional alternative) |\n\nFor API-based authentication in CI/CD environments, set the `ANTHROPIC_API_KEY` environment variable. Claude Code installations with authenticated Pro/Max subscriptions automatically use built-in authentication. 资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n\n## Standard Installation (Claude Code)\n\n### Quick Install\n\nThe recommended installation method uses npx to install and configure the plugin:\n\n```bash\nnpx claude-mem install\n```\n\nThis command performs the following operations:\n\n1. Detects the Claude Code installation location\n2. Installs plugin hooks in the appropriate configuration directory\n3. Sets up the worker service for observation capture\n4. Configures the local memory storage at `~/.claude-mem`\n\n### Post-Installation Steps\n\nAfter installation completes:\n\n1. Keep the provided localhost URL open in a browser\n2. Open Claude Code in any project\n3. Observations stream automatically as Claude reads, edits, and runs commands\n4. Memory injection starts on your second session in a project\n\nTwo paths are available for building memory:\n\n| Option | Approach | Time |\n|--------|----------|------|\n| A. Passive | Just start working; memory builds from your first prompt | Ongoing |\n| B. Front-load | Run `/learn-codebase` to ingest the entire repository | ~5 minutes |\n\n资料来源：[src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n## IDE-Specific Installations\n\n### Gemini CLI\n\n```bash\nnpx claude-mem install --ide gemini-cli\n```\n\nThis auto-detects the `~/.gemini` configuration directory and installs the appropriate hooks for Gemini CLI integration.\n\n### OpenCode\n\n```bash\nnpx claude-mem install --ide opencode\n```\n\nConfigures hooks specifically for OpenCode IDE environments.\n\n资料来源：[src/npx-cli/install/setup-runtime.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/install/setup-runtime.ts)\n\n## In-App Plugin Installation\n\nFor users who prefer the Claude Code interface:\n\n1. Open Claude Code and access the plugin marketplace\n2. Add the plugin: `/plugin marketplace add thedotmack/claude-mem`\n3. Install the plugin: `/plugin install claude-mem`\n4. Restart Claude Code or Gemini CLI\n\nContext from previous sessions automatically appears in new sessions after installation completes. 资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n\n## OpenClaw Gateway Installation\n\nFor persistent memory on OpenClaw gateways, a dedicated installation script is provided:\n\n```bash\ncurl -fsSL https://install.cmem.ai/openclaw.sh | bash\n```\n\nThis script configures claude-mem as a persistent memory plugin on OpenClaw gateways. 资料来源：[openclaw/install.sh](https://github.com/thedotmack/claude-mem/blob/main/openclaw/install.sh)\n\n### OpenClaw Plugin Configuration\n\nThe OpenClaw integration uses a plugin manifest file that defines:\n\n```json\n{\n \"name\": \"claude-mem\",\n \"version\": \"1.0.0\",\n \"description\": \"Persistent memory for Claude Code\"\n}\n```\n\n资料来源：[openclaw/openclaw.plugin.json](https://github.com/thedotmack/claude-mem/blob/main/openclaw/openclaw.plugin.json)\n\n## Docker Installation\n\nFor containerized or isolated deployment environments, Docker installation is available.\n\n### Building the Docker Image\n\n```bash\ncd docker/claude-mem\ndocker build -t claude-mem .\n```\n\n### Running the Container\n\n```bash\ndocker run -d \\\n --name claude-mem \\\n -p 8080:8080 \\\n -v ~/.claude-mem:/data \\\n claude-mem\n```\n\nThe Docker setup uses a multi-stage build with Node.js 20 as the base image and serves the worker service on port 8080. 资料来源：[docker/claude-mem/Dockerfile](https://github.com/thedotmack/claude-mem/blob/main/docker/claude-mem/Dockerfile)\n\n### Docker Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `PORT` | Worker service port | `8080` |\n| `CLAUDE_MEM_DATA_DIR` | Memory storage directory | `/data` |\n| `ANTHROPIC_API_KEY` | API authentication | Required if no Claude Code |\n\n资料来源：[docker/claude-mem/README.md](https://github.com/thedotmack/claude-mem/blob/main/docker/claude-mem/README.md)\n\n## Installation Workflow\n\n```mermaid\ngraph TD\n A[User runs npx claude-mem install] --> B{Detect Platform}\n B -->|macOS/Linux| C[Find Claude Code config]\n B -->|Windows| D[Find Claude Code config]\n B -->|Gemini CLI| E[Detect ~/.gemini]\n B -->|OpenCode| F[Detect OpenCode config]\n \n C --> G[Install hooks to config dir]\n D --> G\n E --> H[Install gemini-cli hooks]\n F --> I[Install opencode hooks]\n \n G --> J[Start worker service]\n H --> J\n I --> J\n \n J --> K[Display success URL]\n K --> L[User opens Claude Code]\n L --> M[Observations begin streaming]\n M --> N[Memory injection on 2nd session]\n```\n\n## Verification and Status\n\nAfter installation, verify the setup:\n\n```bash\nnpx claude-mem status\n```\n\nIf the worker is not yet ready:\n\n```bash\nnpx claude-mem start\n```\n\nManual startup may be required if the worker failed to start automatically on the configured port (default: 8080). 资料来源：[src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n## Uninstallation\n\nTo uninstall claude-mem:\n\n1. Close all Claude Code sessions (prevents hooks from recreating configuration)\n2. Run the uninstall command or manually remove:\n - `~/.claude-mem` directory\n - Plugin hooks from Claude Code config directory\n - Any installed Claude Code plugins\n\n资料来源：[src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| Worker not ready | Wait ~30 seconds, then run `npx claude-mem start` |\n| Hooks recreated | Close all Claude Code sessions before uninstalling |\n| No observations | Ensure memory injection starts on second session |\n| Auth issues | Verify `ANTHROPIC_API_KEY` or Claude Code Pro/Max subscription |\n\n### First Session Hint\n\nThe welcome hint on first sessions can be disabled:\n\n```bash\nCLAUDE_MEM_WELCOME_HINT_ENABLED=false\n```\n\n### Documentation\n\nFor additional help:\n\n- Documentation: https://docs.claude-mem.ai\n- How it works: `/how-it-works` in Claude Code\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：thedotmack/claude-mem\n\n摘要：发现 39 个潜在踩坑项，其中 13 个为 high/blocking；最高优先级：安装坑 - 来源证据：Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)。\n\n## 1. 安装坑 · 来源证据：Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_24ed2d144536406bb1235c9249013f81 | https://github.com/thedotmack/claude-mem/issues/2521 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\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. 安装坑 · 来源证据：Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2a88889db8f4416a9daf23d9979fee71 | https://github.com/thedotmack/claude-mem/issues/2432 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：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_e1a68c6d9a77481897440b34fca959e4 | https://github.com/thedotmack/claude-mem/issues/2438 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_13c1450c63bb4900bed699a4f9b2abb2 | https://github.com/thedotmack/claude-mem/issues/2407 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d56c3d9492594acab8d0bb29a46a6fee | https://github.com/thedotmack/claude-mem/issues/2520 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：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## 8. 配置坑 · 来源证据：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## 9. 配置坑 · 来源证据：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## 10. 运行坑 · 来源证据：自动运行时突然报下图所示内容，然后插件就不能用了\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## 11. 安全/权限坑 · 来源证据：Feature: Vertex AI support for Gemini provider\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: Vertex AI support for Gemini provider\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_77bf4085ec9e46c59fdaffa4ad889dcc | https://github.com/thedotmack/claude-mem/issues/2522 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f38d625f3d834e7d8179d4a3176f3a73 | https://github.com/thedotmack/claude-mem/issues/2509 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 安全/权限坑 · 来源证据：v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fbb9eadf507d4876b859b92bd87d2ab2 | https://github.com/thedotmack/claude-mem/issues/2485 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 安装坑 · 失败模式：installation: OpenClaw installer fails with TypeScript build error on Linux\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: OpenClaw installer fails with TypeScript build error on Linux\n- 对用户的影响：Developers may fail before the first successful local run: OpenClaw installer fails with TypeScript build error on Linux\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: OpenClaw installer fails with TypeScript build error on Linux. Context: Observed when using node, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_f6c0a0d684fa5f1135ac669cd98df70e | https://github.com/thedotmack/claude-mem/issues/2530 | OpenClaw installer fails with TypeScript build error on Linux\n\n## 15. 安装坑 · 失败模式：installation: Windows worker spawn silently fails when user home path contains a space (four stacked bugs,...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n- 对用户的影响：Developers may fail before the first successful local run: Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0). Context: Observed when using windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_0190fe2b64cffaffac244e9ef7033f4e | https://github.com/thedotmack/claude-mem/issues/2521 | Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n\n## 16. 安装坑 · 失败模式：installation: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new s...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n- 对用户的影响：Developers may fail before the first successful local run: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_967ff316b7cd3cebcc05db7b0d3c8d9d | https://github.com/thedotmack/claude-mem/issues/2432 | Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n\n## 17. 安装坑 · 失败模式：installation: [Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n- 对用户的影响：Developers may fail before the first successful local run: [Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry. Context: Observed when using node, python, macos, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_577adec48438b667deb5de48f5dca7f0 | https://github.com/thedotmack/claude-mem/issues/2437 | [Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n\n## 18. 安装坑 · 失败模式：installation: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain\n- 对用户的影响：Developers may fail before the first successful local run: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_4f334c0890e60adcd2706806e12f126c | https://github.com/thedotmack/claude-mem/issues/2528 | [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain\n\n## 19. 安装坑 · 失败模式：installation: [feat] Option to load only memory-related skills\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [feat] Option to load only memory-related skills\n- 对用户的影响：Developers may fail before the first successful local run: [feat] Option to load only memory-related skills\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [feat] Option to load only memory-related skills. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_838f002b6acafaa53828fd03d9450ed6 | https://github.com/thedotmack/claude-mem/issues/2448 | [feat] Option to load only memory-related skills\n\n## 20. 安装坑 · 失败模式：installation: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n- 对用户的影响：Developers may fail before the first successful local run: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection. Context: Observed when using python, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_9195685a79daaf4720e0243904f7946d | https://github.com/thedotmack/claude-mem/issues/2438 | chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n\n## 21. 安装坑 · 失败模式：installation: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n- 对用户的影响：Developers may fail before the first successful local run: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle. Context: Observed when using node, python, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_a54bc450a4d11e378deac2c0452f8c0f | https://github.com/thedotmack/claude-mem/issues/2450 | claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n\n## 22. 安装坑 · 失败模式：installation: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n- 对用户的影响：Developers may fail before the first successful local run: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote). Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_910a8a9b41ad8e6e15c1867e5ad4f96c | https://github.com/thedotmack/claude-mem/issues/2407 | v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n\n## 23. 安装坑 · 失败模式：installation: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n- 对用户的影响：Developers may fail before the first successful local run: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0. Context: Observed when using node, python, macos\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_32ef30e0e80f6e41f6f07078c0659311 | https://github.com/thedotmack/claude-mem/issues/2485 | v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n\n## 24. 安装坑 · 失败模式：installation: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars un...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)\n- 对用户的影响：Developers may fail before the first successful local run: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux). Context: Observed when using node, python, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_25d358b5f6dfe891ef20a29ba6e827dc | https://github.com/thedotmack/claude-mem/issues/2520 | v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)\n\n## 25. 安装坑 · 失败模式：installation: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_s...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated\n- 对用户的影响：Developers may fail before the first successful local run: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated. Context: Observed when using python, macos\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_62407cc74d1dc4a1fbebe438679ae0be | https://github.com/thedotmack/claude-mem/issues/2533 | v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated\n\n## 26. 安装坑 · 来源证据：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## 27. 安装坑 · 来源证据：[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## 28. 配置坑 · 可能修改宿主 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## 29. 配置坑 · 失败模式：configuration: Feature: Vertex AI support for Gemini provider\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: Feature: Vertex AI support for Gemini provider\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Feature: Vertex AI support for Gemini provider\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Feature: Vertex AI support for Gemini provider. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_d3519e41cb7b1df860b0a5e6ae7db82e | https://github.com/thedotmack/claude-mem/issues/2522 | Feature: Vertex AI support for Gemini provider\n\n## 30. 配置坑 · 失败模式：configuration: Use node to run mcp for windows environment\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: Use node to run mcp for windows environment\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Use node to run mcp for windows environment\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Use node to run mcp for windows environment. Context: Observed when using node, windows, macos, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_7e6bf076e8e465cee8256dd4cb41c3d4 | https://github.com/thedotmack/claude-mem/issues/2446 | Use node to run mcp for windows environment\n\n## 31. 配置坑 · 失败模式：configuration: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraint...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection. Context: Observed when using node, python, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_e40a2ed6db40844214cbb7d7c39088e4 | https://github.com/thedotmack/claude-mem/issues/2509 | Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection\n\n## 32. 配置坑 · 失败模式：configuration: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.e...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects. Context: Observed when using node, python, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_b7f38212a7bbb06091eda408d7b08fbb | https://github.com/thedotmack/claude-mem/issues/2529 | [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects\n\n## 33. 配置坑 · 来源证据：Native Azure AI Foundry support (ANTHROPIC_FOUNDRY_* env vars)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Native Azure AI Foundry support (ANTHROPIC_FOUNDRY_* env vars)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b7808109101d47ccb8519f238757da11 | https://github.com/thedotmack/claude-mem/issues/2524 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 34. 能力坑 · 能力判断依赖假设\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## 35. 维护坑 · 维护活跃度未知\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## 36. 安全/权限坑 · 下游验证发现风险项\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## 37. 安全/权限坑 · 存在评分风险\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## 38. 维护坑 · 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## 39. 维护坑 · 发布节奏不明确\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 项目说明书",
"目录",
"Introduction to Claude-Mem",
"Overview",
"Architecture",
"Installation",
"Configuration Options",
"Data Models",
"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- **Introduction to Claude-Mem**：importance `high`\n - source_paths: README.md, CLAUDE.md, docs/architecture-overview.md\n- **Key Features**：importance `high`\n - source_paths: README.md, src/services/context/ContextBuilder.ts, src/services/worker/knowledge/KnowledgeAgent.ts\n- **System Architecture Overview**：importance `high`\n - source_paths: docs/architecture-overview.md, src/services/server/Server.ts, src/services/worker-service.ts, docs/SESSION_ID_ARCHITECTURE.md\n- **Hooks System and Lifecycle**：importance `high`\n - source_paths: plugin/hooks/hooks.json, src/cli/hook-command.ts, src/shared/hook-constants.ts, src/cli/handlers/observation.ts, src/cli/handlers/session-init.ts\n- **Worker Service Architecture**：importance `high`\n - source_paths: src/services/worker-service.ts, src/services/worker/SessionManager.ts, src/services/worker/ClaudeProvider.ts, src/services/worker/GeminiProvider.ts, src/services/worker/OpenRouterProvider.ts\n- **Database Schema and Storage**：importance `high`\n - source_paths: src/services/sqlite/schema.sql, src/services/sqlite/SessionStore.ts, src/services/sqlite/Observations.ts, src/services/sqlite/Summaries.ts, src/services/sqlite/Timeline.ts\n- **Data Flow and Processing**：importance `medium`\n - source_paths: src/services/context/ContextBuilder.ts, src/services/context/ObservationCompiler.ts, src/services/transcripts/processor.ts, src/services/transcripts/watcher.ts, src/server/generation/ProviderObservationGenerator.ts\n- **Search Architecture**：importance `high`\n - source_paths: src/services/worker/search/SearchOrchestrator.ts, src/services/worker/search/strategies/HybridSearchStrategy.ts, src/services/worker/search/strategies/ChromaSearchStrategy.ts, src/services/worker/search/strategies/SQLiteSearchStrategy.ts, src/services/sync/ChromaSync.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: 来源证据：Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_24ed2d144536406bb1235c9249013f81 | https://github.com/thedotmack/claude-mem/issues/2521 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\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: 来源证据：Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2a88889db8f4416a9daf23d9979fee71 | https://github.com/thedotmack/claude-mem/issues/2432 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：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_e1a68c6d9a77481897440b34fca959e4 | https://github.com/thedotmack/claude-mem/issues/2438 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_13c1450c63bb4900bed699a4f9b2abb2 | https://github.com/thedotmack/claude-mem/issues/2407 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_d56c3d9492594acab8d0bb29a46a6fee | https://github.com/thedotmack/claude-mem/issues/2520 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：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 8: 来源证据：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 9: 来源证据：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 10: 来源证据：自动运行时突然报下图所示内容，然后插件就不能用了\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",
"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- 来源证据：Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)（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- 来源证据：Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)（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-15 12:40:04 UTC\n\n## 目录\n\n- [Introduction to Claude-Mem](#page-introduction)\n- [Key Features](#page-key-features)\n- [System Architecture Overview](#page-architecture-overview)\n- [Hooks System and Lifecycle](#page-hooks-system)\n- [Worker Service Architecture](#page-worker-service)\n- [Database Schema and Storage](#page-database-schema)\n- [Data Flow and Processing](#page-data-flow)\n- [Search Architecture](#page-search-architecture)\n- [MCP Tools and Context Generation](#page-mcp-tools)\n- [Installation Guide](#page-installation)\n\n\n\n## Introduction to Claude-Mem\n\n### 相关页面\n\n相关主题：[Key Features](#page-key-features), [System Architecture Overview](#page-architecture-overview)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n- [src/npx-cli/install/setup-runtime.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/install/setup-runtime.ts)\n- [openclaw/install.sh](https://github.com/thedotmack/claude-mem/blob/main/openclaw/install.sh)\n- [openclaw/openclaw.plugin.json](https://github.com/thedotmack/claude-mem/blob/main/openclaw/openclaw.plugin.json)\n- [docker/claude-mem/Dockerfile](https://github.com/thedotmack/claude-mem/blob/main/docker/claude-mem/Dockerfile)\n- [docker/claude-mem/README.md](https://github.com/thedotmack/claude-mem/blob/main/docker/claude-mem/README.md)\n\n
\n\n# Introduction to Claude-Mem\n\nClaude-Mem is a persistent memory plugin for Claude Code that automatically captures tool usage observations, generates semantic summaries, and makes them available across sessions. It enables Claude to maintain continuity of knowledge about projects even after sessions end or reconnect.\n\n资料来源：[README.md:1]()\n\n## Overview\n\nClaude-Mem solves the context continuity problem in AI-assisted development by:\n\n- **Automatically capturing** tool usage observations during development sessions\n- **Generating semantic summaries** using configurable AI models\n- **Persisting memory** in a local SQLite database (`~/.claude-mem`)\n- **Injecting relevant context** into new Claude Code sessions automatically\n\nThe system operates as a background worker service that monitors Claude Code activity, processes observations through AI models, and serves memory context on demand.\n\n资料来源：[README.md:1]()\n\n## Architecture\n\n### System Components\n\nClaude-Mem consists of several interconnected components:\n\n| Component | Location | Purpose |\n|-----------|----------|---------|\n| **NPX CLI** | `src/npx-cli/` | Installation, startup, and management commands |\n| **Worker Service** | `src/server/` | Background service for observation processing |\n| **SDK** | `src/sdk/` | Prompt building and shared utilities |\n| **UI Viewer** | `src/ui/viewer/` | Web-based memory viewer interface |\n| **Smart File Reader** | `src/services/smart-file-read/` | Intelligent code parsing and symbol extraction |\n\n资料来源：[src/npx-cli/commands/install.ts:1]()\n\n### Data Flow\n\n```mermaid\ngraph TD\n A[Claude Code Session] -->|Tool Usage Events| B[Claude-Mem Hooks]\n B -->|Observation Data| C[Worker Service]\n C -->|API Request| D[AI Provider相关源码文件
\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/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)\nClaude/Gemini]\n D -->|Structured Observation| E[SQLite Database
~/.claude-mem]\n E -->|Context Injection| F[Next Claude Session]\n \n G[UI Viewer] <-->|Query/Display| E\n G -->|Settings Changes| C\n```\n\n资料来源：[src/server/generation/providers/shared/prompt-builder.ts:1]()\n\n### Plugin Modes\n\nClaude-Mem supports different observation modes through the `ModeConfig` system. Each mode defines:\n\n- Prompt templates for observation generation\n- Observation types (e.g., `code_change`, `investigation`, `learning`)\n- XML output schema for structured responses\n- Mode-specific field guidance\n\n资料来源：[src/sdk/prompts.ts:1]()\n\n## Installation\n\n### Standard Installation (Claude Code)\n\n```bash\nnpx claude-mem install\n```\n\n资料来源：[README.md:11]()\n\n### Gemini CLI Installation\n\n```bash\nnpx claude-mem install --ide gemini-cli\n```\n\n资料来源：[README.md:14]()\n\n### OpenCode Installation\n\n```bash\nnpx claude-mem install --ide opencode\n```\n\n资料来源：[README.md:17]()\n\n### Claude Code Plugin Marketplace\n\n```bash\n/plugin marketplace add thedotmack/claude-mem\n/plugin install claude-mem\n```\n\n资料来源：[README.md:20]()\n\n> **Note:** The npm package (`npm install -g claude-mem`) installs only the SDK/library—it does not register plugin hooks or set up the worker service. Always use `npx claude-mem install` or the `/plugin` commands.\n\n资料来源：[README.md:27]()\n\n## Configuration Options\n\nThe memory context can be configured through environment variables or the UI settings modal:\n\n| Setting | Default | Description |\n|---------|---------|-------------|\n| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | 50 | Number of recent observations to include (1-200) |\n| `CLAUDE_MEM_CONTEXT_SESSIONS` | 10 | Number of recent sessions to pull from (1-50) |\n| `CLAUDE_MEM_PROVIDER` | claude | AI provider: `claude` or `gemini` |\n| `CLAUDE_MEM_MODEL` | haiku | Claude model: `haiku`, `sonnet`, or `opus` |\n| `CLAUDE_MEM_GEMINI_MODEL` | gemini-2.5-flash-lite | Gemini model variant |\n\n资料来源：[src/ui/viewer/components/ContextSettingsModal.tsx:1]()\n\n## Data Models\n\n### Observation Structure\n\nObservations are the core data unit in Claude-Mem:\n\n```typescript\ninterface Observation {\n id: string;\n tool_name: string;\n tool_input: string | object;\n tool_output: string | object;\n type: string; // Observation type (e.g., \"code_change\")\n title: string;\n subtitle?: string;\n facts: string[];\n narrative?: string;\n concepts: string[];\n files_read: string[];\n files_modified: string[];\n project: string;\n created_at_epoch: number;\n}\n```\n\n资料来源：[src/sdk/prompts.ts:1]()\n\n### Summary Structure\n\nSession summaries provide high-level context:\n\n```typescript\ninterface Summary {\n id: string;\n request: string; // What was requested\n investigated: string; // What was explored\n learned: string; // Key findings\n completed: string; // What was accomplished\n next_steps: string; // Suggested follow-ups\n notes?: string; // Additional notes\n project: string;\n created_at_epoch: number;\n}\n```\n\n资料来源：[src/ui/viewer/components/SummaryCard.tsx:1]()\n\n## Observation Generation\n\n### Prompt Building System\n\nThe SDK (`src/sdk/prompts.ts`) provides functions to construct structured prompts:\n\n| Function | Purpose |\n|----------|---------|\n| `buildFirstObservationPrompt()` | Initial observation for new sessions |\n| `buildContinuationPrompt()` | Continue observation from existing context |\n| `buildSummaryPrompt()` | Generate session summary |\n| `buildObservationPrompt()` | Process individual tool observations |\n\n资料来源：[src/sdk/prompts.ts:1]()\n\n### XML Output Schema\n\nObservations are formatted using XML with the following structure:\n\n```xml\n
\n
\n\n# Key Features\n\nClaude-Mem provides persistent memory capabilities for AI coding assistants, enabling continuity of knowledge across sessions. This page documents the core architectural components and features that power the system.\n\n## System Overview\n\nClaude-Mem seamlessly preserves context across sessions by automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions. This enables Claude to maintain continuity of knowledge about projects even after sessions end or reconnect.\n\n资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n\n## Core Features\n\n### 1. Observation Capture System\n\nThe observation system automatically records tool usage events during Claude Code sessions. Each observation captures structured data about file operations, command executions, and code modifications.\n\n#### Observation Data Model\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `type` | string | Category of observation (file_read, file_modified, command, etc.) |\n| `title` | string | Brief title for the observation |\n| `subtitle` | string | Additional context or description |\n| `facts` | string[] | Key facts extracted from the operation |\n| `narrative` | string | Human-readable summary of the activity |\n| `concepts` | string[] | Extracted concepts and patterns |\n| `files_read` | string[] | Files that were read during this operation |\n| `files_modified` | string[] | Files that were modified |\n| `id` | number | Unique identifier for the observation |\n| `created_at_epoch` | number | Unix timestamp of creation |\n\n资料来源：[src/sdk/prompts.ts:24-42](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)\n\n#### XML Output Format\n\nObservations are rendered in a structured XML format that the AI can easily parse:\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/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/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/services/smart-file-read/parser.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/smart-file-read/parser.ts)\n\n \n
\n {section.label}
\n\n {section.content}\n
\n \n))\n```\n\n资料来源：[src/ui/viewer/components/SummaryCard.tsx:30-50](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/SummaryCard.tsx)\n\n#### Observation Card Display\n\nObservations support multiple view modes for flexible data presentation:\n\n```typescript\n{showFacts && facts.length > 0 && (\n - \n {facts.map((fact: string, i: number) => (\n
- {fact} \n ))}\n
\n {observation.narrative}\n
\n)}\n```\n\n资料来源：[src/ui/viewer/components/ObservationCard.tsx:50-65](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ObservationCard.tsx)\n\n### 7. Theme System\n\nThe viewer supports light and dark themes with CSS custom properties:\n\n| Theme Variable | Light Mode | Dark Mode |\n|----------------|------------|-----------|\n| `--color-bg-primary` | #ffffff | #0d1117 |\n| `--color-bg-secondary` | #efebe4 | #161b22 |\n| `--color-bg-card` | #ffffff | #161b22 |\n| `--color-bg-button` | #0969da | #238636 |\n\n资料来源：[src/ui/viewer-template.html:20-40](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer-template.html)\n\n## Architecture Diagram\n\n```mermaid\ngraph TD\n A[Claude Code Session] --> B[Observation Capture]\n B --> C[Worker Service]\n C --> D[SQLite Database]\n D --> E[Context Builder]\n E --> F[Prompt Injection]\n F --> A\n \n C --> G[Summary Generation]\n G --> D\n \n H[Web Viewer] --> E\n H --> D\n \n I[Smart File Parser] --> B\n```\n\n## Data Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Claude as Claude Code\n participant SDK as SDK/prompts.ts\n participant Worker as Worker Service\n participant DB as SQLite\n participant Viewer as Web Viewer\n \n User->>Claude: Start session\n Claude->>SDK: Generate observation\n SDK->>Worker: Send observation data\n Worker->>DB: Store observation\n \n User->>Viewer: Browse observations\n Viewer->>DB: Query observations\n DB-->>Viewer: Return data\n \n User->>Claude: End session\n Claude->>SDK: Request summary\n SDK->>Worker: Generate summary\n Worker->>DB: Store summary\n \n User->>Claude: New session\n Viewer->>Claude: Inject context\n Claude->>User: Respond with context\n```\n\n## Key System Behaviors\n\n### Observation Types\n\nThe system recognizes several observation types that categorize different tool operations:\n\n1. **file_read** - When Claude reads a file\n2. **file_modified** - When Claude edits or creates a file\n3. **command** - When Claude runs shell commands\n4. **code_change** - When significant code modifications occur\n\n### XML Escaping\n\nAll user-generated content is properly escaped before insertion into XML output to prevent injection attacks:\n\n```typescript\nfunction escapeXml(text: string): string {\n return text\n .replace(/&/g, '&')\n .replace(//g, '>')\n .replace(/\"/g, '"')\n .replace(/'/g, ''');\n}\n```\n\n资料来源：[src/server/generation/providers/shared/prompt-builder.ts:91-98](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/providers/shared/prompt-builder.ts)\n\n### Error Handling\n\nThe viewer implements error boundaries to gracefully handle component failures:\n\n```typescript\nclass ErrorBoundary extends React.Component {\n state = { error: null, errorInfo: null };\n \n componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {\n this.setState({ error, errorInfo });\n }\n \n render() {\n if (this.state.error) {\n return (\n \n
\n );\n }\n return this.props.children;\n }\n}\n```\n\n资料来源：[src/ui/viewer/components/ErrorBoundary.tsx:1-40](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ErrorBoundary.tsx)\n\n## Installation & Setup\n\n### Quick Install\n\n```bash\n# Standard Claude Code\nnpx claude-mem install\n\n# Gemini CLI\nnpx claude-mem install --ide gemini-cli\n\n# OpenCode\nnpx claude-mem install --ide opencode\n```\n\n### Post-Installation\n\n1. Keep the viewer URL open in a browser\n2. Open Claude Code in any project\n3. Observations stream automatically as Claude works\n4. Memory injection begins on the second session\n\n资料来源：[src/npx-cli/commands/install.ts:15-30](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n## Storage Location\n\nAll data is stored locally in `~/.claude-mem` on the user's machine. No data is sent to external servers except through Claude API calls for observation generation.\n\n## See Also\n\n- [Installation Guide](https://github.com/thedotmack/claude-mem#installation)\n- [Context Settings](src/ui/viewer/components/ContextSettingsModal.tsx)\n- [Prompt Builder](src/server/generation/providers/shared/prompt-builder.ts)\n\n---\n\n\n\n## System Architecture Overview\n\n### 相关页面\n\n相关主题：[Hooks System and Lifecycle](#page-hooks-system), [Worker Service Architecture](#page-worker-service), [Database Schema and Storage](#page-database-schema), [Data Flow and Processing](#page-data-flow)\n\nError details
\n{this.state.error.toString()}\n \n
\n\n# System Architecture Overview\n\nClaude-Mem is a persistent memory system for AI coding assistants (Claude Code, Gemini CLI, OpenCode). It automatically captures tool usage observations during coding sessions, generates semantic summaries, and makes them available to future sessions—enabling continuity of knowledge across sessions. 资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n\n## High-Level Architecture\n\nThe system follows a client-server architecture with a worker service that runs independently and a viewer UI for inspecting memory.\n\n```mermaid\ngraph TD\n A[Claude Code / Gemini CLI] -->|Tool Hooks| B[claude-mem Plugin Hooks]\n B --> C[Worker Service :3000]\n C --> D[(SQLite Database相关源码文件
\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/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/ui/viewer/App.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/App.tsx)\n- [src/ui/viewer/components/ContextSettingsModal.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ContextSettingsModal.tsx)\n- [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n~/.claude-mem)]\n C --> E[Prompt Builder]\n E --> F[Claude API]\n F --> G[Parsed Observations]\n C --> G\n H[Viewer UI :8080] --> C\n H --> D\n```\n\n## Core Components\n\n### 1. Worker Service (`src/services/worker-service.ts`)\n\nThe worker service is the central processing hub that:\n\n- Runs as a background process (default port 3000)\n- Receives tool usage observations from IDE plugins\n- Processes and stores observations in SQLite\n- Handles prompt generation and LLM interaction\n- Manages session context injection\n\n资料来源：[src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n### 2. SDK Layer (`src/sdk/prompts.ts`)\n\nThe SDK provides prompt building functions for different operation modes:\n\n| Function | Purpose |\n|----------|---------|\n| `buildObservationPrompt()` | Creates prompts for parsing tool observations into structured XML format |\n| `buildSummaryPrompt()` | Generates prompts for creating session summaries |\n| `buildContinuationPrompt()` | Builds prompts for continuing sessions with existing context |\n\nThe SDK uses `ModeConfig` objects that define observation types, prompt templates, and output format guidelines specific to each IDE integration.\n\n资料来源：[src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)\n\n### 3. Prompt Builder (`src/server/generation/providers/shared/prompt-builder.ts`)\n\nHandles the generation of structured output schemas for LLM interactions:\n\n```typescript\nfunction buildObservationOutputSchema(mode: ModeConfig): string {\n const types = mode.observation_types.map(t => t.id).join(' | ');\n return [\n '
\n
\n\n# Hooks System and Lifecycle\n\n## Overview\n\nThe Hooks System is the core mechanism by which Claude-Mem captures observations, user interactions, and session events from Claude Code to build persistent memory across sessions. The system integrates with Claude Code's plugin hook API to monitor and record agent activities at strategic points in the conversation lifecycle.\n\nClaude-Mem registers multiple hook handlers that fire at different stages: session initialization, user message processing, tool execution, and session termination. Each handler extracts relevant context and stores observations that inform future sessions about project state and progress.\n\n资料来源：[cursor-hooks/README.md](https://github.com/thedotmack/claude-mem/blob/main/cursor-hooks/README.md)\n\n---\n\n## Architecture Overview\n\n### Hook System Components\n\nThe hook system consists of three primary layers:\n\n| Layer | Purpose | Location |\n|-------|---------|----------|\n| **Hook Configuration** | Declares which hooks to register with Claude Code | `plugin/hooks/hooks.json` |\n| **Hook Handlers** | TypeScript implementations that process hook events | `src/cli/handlers/*.ts` |\n| **Hook Constants** | Shared definitions and configuration | `src/shared/hook-constants.ts` |\n\n资料来源：[src/cli/hook-command.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/hook-command.ts)\n\n### Hook Registration Flow\n\n```mermaid\ngraph TD\n A[Claude Code Startup] --> B[Load hooks.json]\n B --> C[Register All Hooks]\n C --> D{Hook Event Occurs}\n D -->|PreToolUse| E[observation.ts]\n D -->|PostToolUse| E\n D -->|User| F[user-message.ts]\n D -->|Stop| G[summarize.ts]\n D -->|Start| H[session-init.ts]\n E --> I[Extract Context]\n F --> I\n G --> I\n H --> I\n I --> J[Store Observation]\n J --> K[Memory Index Updated]\n```\n\n---\n\n## Hook Types and Handlers\n\n### Hook Configuration Schema\n\nThe `hooks.json` file defines the complete hook registration:\n\n```json\n{\n \"hooks\": {\n \"Start\": [\n {\n \"hook\": \"Start\",\n \"name\": \"session-init\",\n \"path\": \"相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [plugin/hooks/hooks.json](https://github.com/thedotmack/claude-mem/blob/main/plugin/hooks/hooks.json)\n- [src/cli/hook-command.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/hook-command.ts)\n- [src/shared/hook-constants.ts](https://github.com/thedotmack/claude-mem/blob/main/src/shared/hook-constants.ts)\n- [src/cli/handlers/observation.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/handlers/observation.ts)\n- [src/cli/handlers/session-init.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/handlers/session-init.ts)\n- [src/cli/handlers/user-message.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/handlers/user-message.ts)\n- [src/cli/handlers/summarize.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/handlers/summarize.ts)\n\n
\n\n# Worker Service Architecture\n\nThe Worker Service is the core backend component of claude-mem, responsible for processing, storing, and serving memory observations across Claude Code sessions. It runs as a persistent background service that handles LLM inference, observation generation, and semantic search operations.\n\n## Overview\n\nThe Worker Service operates independently from Claude Code sessions, maintaining a long-running process that:\n\n- Receives tool usage observations from Claude Code via plugin hooks\n- Generates semantic summaries using configured LLM providers (Claude, Gemini, OpenRouter)\n- Stores observations in a local SQLite database with Chroma vector embeddings\n- Serves a web-based viewer UI and REST API for browsing and querying memories\n\n```mermaid\ngraph TD\n subgraph \"Claude Code\"\n A[Tool Execution] --> B[Plugin Hooks]\n B --> C[Tool Result Persist Event]\n end\n \n subgraph \"Worker Service\"\n D[HTTP Server :37777] --> E[Route Handlers]\n E --> F[Session Manager]\n F --> G[Observation Generator]\n G --> H[LLM Providers]\n H --> I[Database Manager]\n I --> J[SQLite + Chroma]\n end\n \n C -->|SSE/WebSocket| D\n D -->|Viewer UI| K[Browser Client]\n D -->|REST API| L[External Clients]\n```\n\n## Core Components\n\n### WorkerService\n\nThe main service orchestrator located in `src/services/worker-service.ts`. It initializes all sub-components, registers HTTP routes, manages lifecycle events, and coordinates between the UI and backend processing.\n\n**Key Responsibilities:**\n\n| Responsibility | Description |\n|----------------|-------------|\n| Lifecycle Management | Coordinates startup/shutdown of all service components |\n| Route Registration | Registers ViewerRoutes, SessionRoutes, DataRoutes, SettingsRoutes, LogsRoutes, MemoryRoutes |\n| Middleware | Implements initialization check middleware (returns 503 during DB init) |\n| Database Initialization | Ensures SQLite and Chroma are ready before accepting requests |\n| SSE Broadcasting | Manages real-time event streaming to connected clients |\n\n资料来源：[src/services/worker-service.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts)\n\n### Session Manager\n\nManages individual Claude Code session lifecycles, tracking active sessions and coordinating observation generation per session.\n\n资料来源：[src/services/worker/SessionManager.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/SessionManager.ts)\n\n## LLM Provider Architecture\n\nThe Worker Service supports multiple LLM backends through a provider abstraction pattern.\n\n### Provider Comparison\n\n| Provider | Class | Purpose | API Endpoint |\n|----------|-------|---------|--------------|\n| Anthropic Claude | `ClaudeProvider` | Primary observation generation | api.anthropic.com |\n| Google Gemini | `GeminiProvider` | Alternative generation | Generative Language API |\n| OpenRouter | `OpenRouterProvider` | Unified multi-model access | openrouter.ai |\n\n资料来源：\n- [src/services/worker/ClaudeProvider.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/ClaudeProvider.ts)\n- [src/services/worker/GeminiProvider.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/GeminiProvider.ts)\n- [src/services/worker/OpenRouterProvider.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/OpenRouterProvider.ts)\n\n### Provider Selection\n\nThe system automatically selects providers based on:\n1. Configuration in `~/.claude-mem/settings.json`\n2. Available API keys in environment variables\n3. Fallback to Claude as primary provider\n\n## HTTP Route Architecture\n\nThe Worker Service exposes REST endpoints through registered route handlers:\n\n```mermaid\ngraph LR\n A[HTTP :37777] --> B[ViewerRoutes]\n A --> C[SessionRoutes]\n A --> D[DataRoutes]\n A --> E[SettingsRoutes]\n A --> F[LogsRoutes]\n A --> G[MemoryRoutes]\n A --> H[ServerV1Routes]\n```\n\n### Route Groups\n\n| Route | File | Purpose |\n|-------|------|---------|\n| Viewer | `ViewerRoutes` | Serves the web-based memory viewer UI |\n| Session | `SessionRoutes` | Manages session lifecycle, continuation prompts |\n| Data | `DataRoutes` | Pagination, filtering, observation retrieval |\n| Settings | `SettingsRoutes` | User preferences and configuration |\n| Logs | `LogsRoutes` | Service logging and diagnostics |\n| Memory | `MemoryRoutes` | Memory CRUD operations, search |\n| V1 API | `ServerV1Routes` | Legacy compatibility endpoints |\n\n资料来源：[src/services/worker/http/routes/MemoryRoutes.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/http/routes/MemoryRoutes.ts)\n\n## Job Queue System\n\nObservation generation is handled asynchronously through a BullMQ-based job queue system.\n\n### Queue Configuration\n\n```typescript\ninterface QueueConfig {\n connection: RedisConnectionConfig;\n prefix: string;\n defaultJobOptions: {\n attempts: number;\n backoff: { type: 'exponential'; delay: number };\n removeOnComplete: boolean;\n };\n}\n```\n\n资料来源：[src/server/jobs/ServerJobQueue.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/jobs/ServerJobQueue.ts)\n\n### Event Handling\n\nThe queue emits events for observability:\n\n| Event | Handler | Description |\n|-------|---------|-------------|\n| `completed` | `onCompleted` | Job finished successfully |\n| `failed` | `onFailed` | Job failed after all retries |\n| `progress` | `onProgress` | Job reported progress percentage |\n| `stalled` | `notifyStalled` | Job became unresponsive |\n\n## Process Management\n\nThe Worker Service can run in multiple modes:\n\n```mermaid\ngraph TD\n A[Start Command] --> B{IDE Type}\n B -->|claude-code| C[Claude Code Plugin Mode]\n B -->|gemini-cli| D[Gemini CLI Mode]\n B -->|opencode| E[OpenCode Mode]\n \n C --> F[Persistent Background Process]\n D --> F\n E --> F\n F --> G[Supervisor Process]\n G --> H[Worker Service :37777]\n```\n\n### Runtime Modes\n\n| Mode | Activation | Behavior |\n|------|------------|----------|\n| Auto-start | Default | Worker starts automatically on first session |\n| Manual | `npx claude-mem start` | Explicit user initiation |\n| Background | Supervisor-managed | Persistent daemon with health monitoring |\n\n资料来源：[src/npx-cli/commands/runtime.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/runtime.ts)\n\n### Process Manager\n\nThe `ProcessManager` handles:\n\n- Spawning and monitoring worker processes\n- Health check endpoints (`/health`, `/readiness`)\n- Automatic restart on crash\n- Graceful shutdown handling\n\n资料来源：[src/services/infrastructure/ProcessManager.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/infrastructure/ProcessManager.ts)\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CLAUDE_MEM_WORKER_PORT` | `37777` | Worker HTTP server port |\n| `CLAUDE_MEM_WORKER_HOST` | `localhost` | Worker binding host |\n| `CLAUDE_MEM_MODE` | - | Active mode configuration |\n| `CLAUDE_MEM_WELCOME_HINT_ENABLED` | `true` | Show first-use hints |\n\n### Service Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/health` | GET | Basic health check |\n| `/readiness` | GET | Readiness probe (DB initialized) |\n| `/version` | GET | Service version info |\n| `/chroma/status` | GET | Vector database status |\n\n## Startup Sequence\n\n```mermaid\nsequenceDiagram\n participant User\n participant Plugin as Claude Code Plugin\n participant Worker as Worker Service\n participant DB as SQLite/Chroma\n participant Queue as Job Queue\n\n User->>Plugin: First Claude Code session\n Plugin->>Worker: Tool result events\n Worker->>DB: Initialize connections\n DB-->>Worker: Ready\n Worker->>Queue: Start worker process\n Queue->>Worker: Ready\n Worker-->>Plugin: Service available\n Plugin->>Worker: Stream observations\n Worker->>Queue: Enqueue generation jobs\n Queue->>Worker: Process observations\n Worker->>DB: Store summaries\n```\n\n## Data Flow\n\n### Observation Lifecycle\n\n1. **Capture**: Plugin captures tool execution events (read, edit, shell commands)\n2. **Transmission**: Events sent via SSE to Worker Service\n3. **Queuing**: Jobs added to BullMQ generation queue\n4. **Processing**: LLM provider generates semantic summary\n5. **Storage**: SQLite stores structured data, Chroma stores vector embeddings\n6. **Retrieval**: Future sessions query relevant observations via semantic search\n\n资料来源：[src/services/worker-service.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts)\n\n## Error Handling\n\n### Initialization Guard\n\nDuring startup, the service returns HTTP 503 for all requests except health/readiness checks:\n\n```\nRequest → Middleware Check → DB Initialized?\n ├─ Yes → Pass through to routes\n └─ No → 503 \"Service initializing\"\n```\n\n### Queue Failure Handling\n\nFailed jobs trigger listener callbacks:\n\n```typescript\nw.on('failed', (jobId: string, error: Error) => {\n for (const l of this.listeners) {\n l.onFailed?.(jobId, attemptsMade, error.message);\n }\n});\n```\n\n资料来源：[src/server/jobs/ServerJobQueue.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/jobs/ServerJobQueue.ts)\n\n## Extension Points\n\n### Custom LLM Providers\n\nProviders implement a common interface allowing:\n\n- Custom API endpoints\n- Different authentication methods\n- Provider-specific prompt formatting\n- Rate limiting and retry policies\n\n### Mode System\n\nThe Worker Service supports configurable modes via `ModeConfig` that define:\n\n- Observation types to capture\n- Prompt templates for generation\n- Summary output formats\n- System identity instructions\n\n## Security Considerations\n\n- Service binds to localhost by default\n- No authentication on local-only deployments\n- All data stored in `~/.claude-mem` directory\n- API keys loaded from environment variables\n\n---\n\n\n\n## Database Schema and Storage\n\n### 相关页面\n\n相关主题：[System Architecture Overview](#page-architecture-overview), [Data Flow and Processing](#page-data-flow), [Search Architecture](#page-search-architecture)\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/services/worker-service.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts)\n- [src/server/jobs/ServerJobQueue.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/jobs/ServerJobQueue.ts)\n- [src/services/worker/ClaudeProvider.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/ClaudeProvider.ts)\n- [src/services/worker/GeminiProvider.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/GeminiProvider.ts)\n- [src/services/worker/OpenRouterProvider.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/OpenRouterProvider.ts)\n- [src/services/worker/http/routes/MemoryRoutes.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/http/routes/MemoryRoutes.ts)\n- [src/npx-cli/commands/runtime.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/runtime.ts)\n- [src/services/infrastructure/ProcessManager.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/infrastructure/ProcessManager.ts)\n\n
\n\n# Database Schema and Storage\n\n## Overview\n\nClaude-Mem uses SQLite as its primary persistent storage layer to maintain session continuity, store observations, and preserve learned context across sessions. The database schema captures the complete lifecycle of AI sessions, including tool usage, observations, summaries, and temporal data for timeline reconstruction.\n\nThe storage system is designed to support:\n- Multi-session tracking with unique identifiers\n- Observation persistence with semantic metadata\n- Session summarization storage\n- Timeline event reconstruction\n- Project-based organization\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Worker Service] --> B[DBManager]\n B --> C[SQLite Database]\n C --> D[schema_versions]\n C --> E[sdk_sessions]\n C --> F[observations]\n C --> G[session_summaries]\n C --> H[pending_messages]\n C --> I[user_prompts]\n C --> J[projects]\n \n K[SessionStore] -.-> E\n L[Observations] -.-> F\n M[Summaries] -.-> G\n N[Timeline] -.-> J\n```\n\n## Core Tables\n\n### schema_versions\n\nTracks applied database migrations to ensure schema consistency across upgrades.\n\n| Column | Type | Description |\n|--------|------|-------------|\n| version | INTEGER PRIMARY KEY | Migration version number |\n| applied_at | TEXT | ISO timestamp of migration application |\n\n资料来源：[src/services/sqlite/migrations/runner.ts:1-50]()\n\n### sdk_sessions\n\nStores metadata about each Claude session managed by the SDK.\n\n| Column | Type | Description |\n|--------|------|-------------|\n| id | INTEGER PRIMARY KEY | Auto-incrementing row ID |\n| memory_session_id | TEXT NOT NULL | Unique session identifier |\n| content_session_id | TEXT NOT NULL | Content/session reference ID |\n| project | TEXT NOT NULL | Project name for grouping |\n| status | TEXT | Session status (active/completed/etc) |\n| created_at | TEXT NOT NULL | Creation timestamp |\n| created_at_epoch | INTEGER NOT NULL | Epoch timestamp for sorting |\n\n资料来源：[src/services/sqlite/migrations/runner.ts:60-90]()\n\n### observations\n\nRecords tool usage observations captured during sessions. Observations are the primary mechanism for preserving learned context.\n\n| Column | Type | Description |\n|--------|------|-------------|\n| id | INTEGER PRIMARY KEY | Auto-incrementing observation ID |\n| memory_session_id | TEXT NOT NULL | Foreign key to sdk_sessions |\n| tool_name | TEXT | Name of the tool used |\n| tool_input | TEXT | JSON-encoded tool input |\n| tool_output | TEXT | JSON-encoded tool output |\n| observation_type | TEXT | Type classification (fact, decision, etc.) |\n| title | TEXT | Observation title |\n| subtitle | TEXT | Brief description |\n| narrative | TEXT | Detailed narrative |\n| concepts | TEXT | JSON array of concept tags |\n| files_read | TEXT | JSON array of files read |\n| files_modified | TEXT | JSON array of files modified |\n| created_at | TEXT NOT NULL | Creation timestamp |\n| created_at_epoch | INTEGER NOT NULL | Epoch timestamp |\n\n资料来源：[src/services/sqlite/SessionStore.ts](), [src/services/sqlite/Observations.ts]()\n\n### session_summaries\n\nStores AI-generated summaries of completed sessions, capturing requests, findings, and next steps.\n\n| Column | Type | Description |\n|--------|------|-------------|\n| id | INTEGER PRIMARY KEY | Auto-incrementing summary ID |\n| memory_session_id | TEXT NOT NULL | Foreign key to sdk_sessions |\n| project | TEXT NOT NULL | Project name |\n| request | TEXT | Original user request |\n| investigated | TEXT | What was investigated |\n| learned | TEXT | Key learnings |\n| completed | TEXT | Completed work |\n| next_steps | TEXT | Planned next steps |\n| files_read | TEXT | Files read during session |\n| files_edited | TEXT | Files modified during session |\n| notes | TEXT | Additional notes |\n| prompt_number | INTEGER | Session prompt sequence number |\n| created_at | TEXT NOT NULL | Creation timestamp |\n| created_at_epoch | INTEGER NOT NULL | Epoch timestamp |\n\n资料来源：[src/services/sqlite/migrations/runner.ts:50-80](), [src/services/sqlite/Summaries.ts]()\n\n### pending_messages\n\nQueue table for messages awaiting processing by the worker service.\n\n| Column | Type | Description |\n|--------|------|-------------|\n| id | INTEGER PRIMARY KEY | Auto-incrementing message ID |\n| content_session_id | TEXT NOT NULL | Session reference |\n| message_id | INTEGER | Claude message ID |\n| message_type | TEXT | Message type (observation/summarize) |\n| payload | TEXT | JSON message payload |\n| status | TEXT | Processing status |\n| created_at | TEXT NOT NULL | Creation timestamp |\n| created_at_epoch | INTEGER NOT NULL | Epoch timestamp |\n| failed_at_epoch | INTEGER | Epoch timestamp of last failure |\n\n资料来源：[src/services/sqlite/migrations/runner.ts:200-230]()\n\n### user_prompts\n\nStores original user prompts for each session.\n\n| Column | Type | Description |\n|--------|------|-------------|\n| id | INTEGER PRIMARY KEY | Auto-incrementing prompt ID |\n| content_session_id | TEXT NOT NULL | Session reference |\n| prompt | TEXT NOT NULL | User prompt text |\n| created_at | TEXT NOT NULL | Creation timestamp |\n| created_at_epoch | INTEGER NOT NULL | Epoch timestamp |\n\n### projects\n\nMaintains project registry for organizing sessions and observations.\n\n| Column | Type | Description |\n|--------|------|-------------|\n| id | INTEGER PRIMARY KEY | Auto-incrementing project ID |\n| name | TEXT NOT NULL UNIQUE | Project name |\n| created_at | TEXT NOT NULL | Creation timestamp |\n\n资料来源：[src/storage/sqlite/schema.ts](), [src/services/sqlite/Timeline.ts]()\n\n## Schema Migrations\n\nThe system uses a versioned migration system to handle schema evolution. Migrations are applied sequentially and tracked in the `schema_versions` table.\n\n### Migration Version History\n\n| Version | Description |\n|---------|-------------|\n| 7 | Session summaries table creation with UNIQUE constraint removal |\n| 17 | Column renames: `sdk_session_id` → `memory_session_id`, `claude_session_id` → `content_session_id` |\n| 20 | Added `failed_at_epoch` column to `pending_messages` |\n\n资料来源：[src/services/sqlite/migrations/runner.ts:40-45](), [src/services/sqlite/migrations/runner.ts:150-180](), [src/services/sqlite/migrations/runner.ts:195-220]()\n\n### Migration Execution\n\nMigrations are executed via the `MigrationRunner` class which:\n\n1. Checks current schema version from `schema_versions`\n2. Applies pending migrations in order\n3. Records each applied version with timestamp\n4. Handles safe column renaming (only if column exists)\n\n```typescript\nprivate addFailedAtEpochColumn(): void {\n const applied = this.db.prepare('SELECT version FROM schema_versions WHERE version = ?').get(20);\n if (applied) return;\n \n const tableInfo = this.db.query('PRAGMA table_info(pending_messages)').all();\n const hasColumn = tableInfo.some(col => col.name === 'failed_at_epoch');\n \n if (!hasColumn) {\n this.db.run('ALTER TABLE pending_messages ADD COLUMN failed_at_epoch INTEGER');\n }\n}\n```\n\n资料来源：[src/services/sqlite/migrations/runner.ts:195-215]()\n\n## Session ID Naming Convention\n\nThe system underwent a terminology migration in version 17:\n\n| Old Name | New Name | Purpose |\n|----------|----------|---------|\n| `sdk_session_id` | `memory_session_id` | Primary session identifier across memory system |\n| `claude_session_id` | `content_session_id` | Claude/Content API session reference |\n\nThis rename reflects the system's expansion beyond Claude Code to support other AI platforms (Gemini CLI, OpenClaw).\n\n资料来源：[src/services/sqlite/migrations/runner.ts:145-170]()\n\n## Data Access Layer\n\n### SessionStore\n\nProvides CRUD operations for session management:\n\n```typescript\ninterface SessionStore {\n createSession(session: Session): Promise相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/services/sqlite/schema.sql](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/schema.sql)\n- [src/services/sqlite/SessionStore.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/SessionStore.ts)\n- [src/services/sqlite/Observations.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Observations.ts)\n- [src/services/sqlite/Summaries.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Summaries.ts)\n- [src/services/sqlite/Timeline.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Timeline.ts)\n- [src/services/sqlite/migrations.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/migrations.ts)\n- [src/services/sqlite/migrations/runner.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/migrations/runner.ts)\n- [src/storage/sqlite/schema.ts](https://github.com/thedotmack/claude-mem/blob/main/src/storage/sqlite/schema.ts)\n\n
\n\n# Data Flow and Processing\n\n## Overview\n\nClaude-Mem implements a sophisticated data pipeline that captures, processes, stores, and retrieves contextual information from Claude Code sessions. The system transforms raw transcript data into structured observations and summaries that can be injected into future sessions, enabling persistent memory across sessions.\n\nThe data flow architecture spans multiple layers: **ingestion** (capturing session activity), **processing** (generating structured observations), **storage** (persisting to local filesystem), **retrieval** (searching and filtering), and **injection** (presenting relevant context to Claude).\n\n## System Architecture\n\n```mermaid\ngraph TD\n subgraph Ingestion [\"Ingestion Layer\"]\n TW[Transcript Watcher] --> TP[Transcript Processor]\n TP --> OG[Observation Generator]\n end\n \n subgraph Processing [\"Processing Layer\"]\n OG --> CB[Context Builder]\n CB --> OC[Observation Compiler]\n OC --> Q[Job Queue]\n Q --> QW[Queue Worker]\n end\n \n subgraph Storage [\"Storage Layer\"]\n QW --> FS[File System相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/services/context/ContextBuilder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/context/ContextBuilder.ts)\n- [src/services/context/ObservationCompiler.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/context/ObservationCompiler.ts)\n- [src/services/transcripts/processor.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/transcripts/processor.ts)\n- [src/services/transcripts/watcher.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/transcripts/watcher.ts)\n- [src/server/generation/ProviderObservationGenerator.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/ProviderObservationGenerator.ts)\n- [src/cli/handlers/context.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/handlers/context.ts)\n~/.claude-mem]\n FS --> OBS[Observations DB]\n FS --> SUMM[Summary DB]\n end\n \n subgraph Retrieval [\"Retrieval Layer\"]\n CLI[CLI Context Handler] --> SR[Search & Retrieval]\n SR --> CB\n CB --> CONTEXT[Context Injection]\n end\n \n subgraph Output [\"Output Layer\"]\n CONTEXT --> UI[Viewer UI]\n CONTEXT --> SDK[SDK Prompts]\n end\n```\n\n## Core Data Flow Pipeline\n\n### 1. Transcript Watching\n\nThe transcript watcher monitors Claude Code sessions in real-time, capturing all activity as it occurs.\n\n**Key Components:**\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| TranscriptWatcher | `src/services/transcripts/watcher.ts` | Monitors transcript files for changes |\n| TranscriptProcessor | `src/services/transcripts/processor.ts` | Parses and extracts events from transcripts |\n\nThe watcher detects when new content is written to transcript files and triggers processing. Events captured include:\n\n- Tool invocations (`Read`, `Write`, `Edit`, `Bash`, etc.)\n- User prompts\n- Assistant responses\n- System events\n\n### 2. Observation Generation\n\nObservations are generated from processed transcript events using LLM providers.\n\n```mermaid\ngraph LR\n subgraph Input\n EV[Event Data] --> PG[Prompt Builder]\n MC[Mode Config] --> PG\n end\n \n subgraph Generation\n PG --> LLM[LLM Provider]\n LLM --> XML[XML Output]\n end\n \n subgraph Output\n XML --> OBS[Observation Record]\n XML --> PRIV[Private Data Check]\n end\n```\n\n**ProviderObservationGenerator** handles the generation flow:\n\n1. Builds prompts using `ModeConfig` and observation types\n2. Sends requests to configured LLM provider (Claude by default)\n3. Parses XML-structured responses\n4. Validates and sanitizes output\n\nThe generated observation schema follows this structure:\n\n```xml\n
Max 3 attempts\n```\n\n**ServerJobQueue** manages job lifecycle:\n\n| Feature | Description |\n|---------|-------------|\n| Retry Policy | Automatic retry with exponential backoff |\n| Progress Tracking | Real-time job progress events |\n| Stalled Detection | Monitors for stuck jobs |\n| Cross-Process Events | Redis pub/sub for distributed workers |\n\n资料来源：[src/server/jobs/ServerJobQueue.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/jobs/ServerJobQueue.ts)\n\n## Storage Architecture\n\nAll data persists to `~/.claude-mem/` on the local filesystem.\n\n```mermaid\ngraph TD\n subgraph \"~/.claude-mem\"\n OBS[observations/]\n SUMM[summary/]\n CONTEXT[context/]\n CONFIG[config.json]\n MODES[modes/]\n end\n \n OBS --> |JSON files| RECORDS[Individual records]\n SUMM --> |JSON files| SESSION_SUMM[Session summaries]\n CONTEXT --> |Compiled| READY[Ready for injection]\n```\n\n### File Structure\n\n| Directory | Content | Format |\n|-----------|---------|--------|\n| `observations/` | Individual observations | JSON with metadata |\n| `summary/` | Session summaries | JSON with sections |\n| `context/` | Compiled context bundles | JSON arrays |\n| `modes/` | Mode configurations | JSON |\n| `transcripts/` | Raw session transcripts | Text/markdown |\n\n## Summary Generation Flow\n\nSummaries are generated at session end to provide high-level overviews.\n\n```mermaid\ngraph TD\n subgraph SessionEnd\n END[Session Complete] --> EXTRACT[Extract Key Events]\n EXTRACT --> BUILD[Build Summary Prompt]\n end\n \n subgraph Generation\n BUILD --> LLM[LLM Generation]\n LLM --> PARSE[Parse Summary XML]\n end\n \n subgraph Output\n PARSE --> STRUCT[Structured Summary]\n STRUCT --> STORE[Store to summary/]\n STRUCT --> DISPLAY[Display in UI]\n end\n```\n\nSummary output format:\n\n```xml\n
\n
\n\n# Search Architecture\n\n## Overview\n\nThe Search Architecture in claude-mem provides a multi-strategy search system that enables semantic and structured querying across observations, sessions, and prompts. The architecture employs a plugin-based strategy pattern that allows combining different search backends—primarily Chroma (vector database) and SQLite—through a unified orchestration layer.\n\nThe search system serves as the foundation for context injection, enabling Claude Code to retrieve relevant historical observations from previous sessions and maintain knowledge continuity across session boundaries.\n\n---\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Search Request] --> B[SearchOrchestrator]\n B --> C[HybridSearchStrategy]\n C --> D[ChromaSearchStrategy]\n C --> E[SQLiteSearchStrategy]\n D --> F[ChromaSync]\n F --> G[Chroma DB]\n E --> H[SQLite DB]\n I[ChromaMcpManager] --> G\n J[TimelineBuilder] --> K[Timeline Results]\n \n style B fill:#e1f5fe\n style C fill:#fff3e0\n style D fill:#e8f5e9\n style E fill:#fce4ec\n```\n\n---\n\n## Core Components\n\n### SearchOrchestrator\n\nThe `SearchOrchestrator` serves as the central entry point for all search operations. It receives search requests, determines which strategies to invoke, and aggregates results from multiple sources.\n\n**Key Responsibilities:**\n- Route search requests to appropriate strategies\n- Merge and rank results from different backends\n- Handle search type filtering (observations, sessions, prompts)\n- Support project-scoped searches\n\n**Search Types Supported:**\n\n| Search Type | Description |\n|-------------|-------------|\n| `all` | Search across observations, sessions, and prompts |\n| `observations` | Search observation records only |\n| `sessions` | Search session metadata |\n| `prompts` | Search user prompts |\n| `by-concept` | Find observations tagged with specific concepts |\n| `by-file` | Find observations related to specific file paths |\n| `by-type` | Filter by observation type (decisions, changes, etc.) |\n\n资料来源：[src/services/worker/search/SearchOrchestrator.ts]()\n\n### HybridSearchStrategy\n\nThe `HybridSearchStrategy` combines multiple search strategies to achieve optimal recall and precision. It orchestrates parallel execution of Chroma and SQLite searches, then merges the results.\n\n```mermaid\ngraph LR\n A[Query] --> B[Chroma Search]\n A --> C[SQLite Search]\n B --> D[Result Merge]\n C --> D\n D --> E[Ranked Results]\n```\n\n**Strategy Selection Logic:**\n- Vector similarity search → Chroma\n- Structured queries (filters, date ranges) → SQLite\n- Combined relevance + recency ranking → Hybrid merge\n\n资料来源：[src/services/worker/search/strategies/HybridSearchStrategy.ts]()\n\n### ChromaSearchStrategy\n\nThe `ChromaSearchStrategy` implements semantic search using the Chroma vector database. It provides high-dimensional embedding-based similarity search with filtering capabilities.\n\n**Core Features:**\n- Batch querying with configurable batch size (`SEARCH_CONSTANTS.CHROMA_BATCH_SIZE`)\n- Filter by document type, concepts, file paths\n- Ordering by relevance, date descending, or date ascending\n- Recency filtering of results\n\n**Key Methods:**\n- `executeChromaSearch()` - Performs the actual Chroma query\n- `filterByRecency()` - Filters results based on temporal relevance\n- `categorizeByDocType()` - Separates results into observations, sessions, prompts\n\n```typescript\nconst chromaResults = await this.chromaSync.queryChroma(\n query,\n SEARCH_CONSTANTS.CHROMA_BATCH_SIZE,\n whereFilter\n);\n```\n\n资料来源：[src/services/worker/search/strategies/ChromaSearchStrategy.ts:30-45]()\n\n### SQLiteSearchStrategy\n\nThe `SQLiteSearchStrategy` handles structured queries and provides fallback search when Chroma is unavailable. It performs full-text and attribute-based filtering using SQLite's query capabilities.\n\n**Use Cases:**\n- Exact match filtering\n- Date range queries\n- Project-specific searches\n- Filtered searches by metadata fields\n\n---\n\n## Vector Search Infrastructure\n\n### ChromaSync\n\n`ChromaSync` manages the synchronization between the local SQLite database and the Chroma vector database. It handles embedding generation and data persistence.\n\n**Responsibilities:**\n- Query Chroma collections\n- Sync observations to Chroma\n- Manage embedding pipelines\n- Handle batch operations\n\n资料来源：[src/services/sync/ChromaSync.ts]()\n\n### ChromaMcpManager\n\n`ChromaMcpManager` handles the Model Context Protocol (MCP) integration for Chroma. It provides an abstraction layer for interacting with Chroma's MCP server when available.\n\n**Features:**\n- MCP server status monitoring\n- Toggle MCP integration on/off\n- Graceful fallback when MCP unavailable\n\n资料来源：[src/services/sync/ChromaMcpManager.ts]()\n\n---\n\n## Search Routes API\n\nThe search functionality is exposed through HTTP routes managed by the Worker service:\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/search/observations` | GET | Search observations |\n| `/search/sessions` | GET | Search sessions |\n| `/search/prompts` | GET | Search prompts |\n| `/search/by-concept` | GET | Find by concept tag |\n| `/search/by-file` | GET | Find by file path |\n| `/search/by-type` | GET | Find by observation type |\n| `/search/recent-context` | GET | Get recent context |\n| `/search/context-timeline` | GET | Get context timeline |\n| `/search/timeline-by-query` | GET | Timeline by search query |\n| `/context/preview` | GET | Preview context |\n| `/context/inject` | POST | Inject context |\n\n资料来源：[src/services/worker/README.md]()\n\n---\n\n## Timeline Search\n\n### TimelineBuilder\n\n`TimelineBuilder` constructs temporal views of search results, enabling users to explore observations and context across time.\n\n**Capabilities:**\n- Build timelines based on search queries\n- Aggregate results by date periods\n- Support context preview generation\n- Inject timeline-based context into sessions\n\n```mermaid\ngraph TD\n A[Search Query] --> B[TimelineBuilder]\n B --> C[Group by Date]\n C --> D[Timeline Nodes]\n D --> E[Context Preview]\n E --> F[Inject to Session]\n```\n\n资料来源：[src/services/worker/search/TimelineBuilder.ts]()\n\n---\n\n## Search Configuration\n\n### Configuration Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | number | 50 | Observations to inject (1-200) |\n| `CLAUDE_MEM_CONTEXT_SESSIONS` | number | varies | Sessions to pull from (1-50) |\n\n### Search Constants\n\n```typescript\nconst SEARCH_CONSTANTS = {\n CHROMA_BATCH_SIZE: 100, // Batch size for Chroma queries\n // ... additional constants\n};\n```\n\n---\n\n## Search Workflow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Orchestrator\n participant HybridStrategy\n participant Chroma\n participant SQLite\n \n Client->>Orchestrator: Search Request\n Orchestrator->>HybridStrategy: Route to Hybrid\n HybridStrategy->>Chroma: Vector Query\n HybridStrategy->>SQLite: Structured Query\n Chroma-->>HybridStrategy: Embedding Results\n SQLite-->>HybridStrategy: Filtered Results\n HybridStrategy->>HybridStrategy: Merge & Rank\n HybridStrategy-->>Orchestrator: Combined Results\n Orchestrator-->>Client: Ranked Results\n```\n\n---\n\n## Data Flow\n\n### Observation Search Flow\n\n1. User initiates search via UI or API\n2. `SearchOrchestrator` receives and parses request\n3. Determines search scope (observations, sessions, prompts)\n4. Invokes `HybridSearchStrategy`\n5. Parallel execution:\n - `ChromaSearchStrategy` performs vector similarity search\n - `SQLiteSearchStrategy` performs structured filtering\n6. Results are categorized by document type\n7. Results filtered by recency if configured\n8. Final results merged and ranked\n9. Returned to client with metadata\n\n### Context Injection Flow\n\n1. User requests context preview or injection\n2. `TimelineBuilder` builds temporal view\n3. Observations retrieved based on recency and relevance\n4. Context formatted for Claude Code consumption\n5. Injected into active session via worker service\n\n---\n\n## Strategy Pattern Implementation\n\nThe search architecture follows the Strategy pattern, allowing runtime selection of search algorithms:\n\n```mermaid\nclassDiagram\n class SearchStrategy {\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/strategies/ChromaSearchStrategy.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/strategies/ChromaSearchStrategy.ts)\n- [src/services/worker/search/strategies/SQLiteSearchStrategy.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/strategies/SQLiteSearchStrategy.ts)\n- [src/services/sync/ChromaSync.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sync/ChromaSync.ts)\n- [src/services/sync/ChromaMcpManager.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sync/ChromaMcpManager.ts)\n- [src/services/worker/search/TimelineBuilder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/TimelineBuilder.ts)\n\n
\n\n# MCP Tools and Context Generation\n\n## Overview\n\nMCP (Model Context Protocol) Tools and Context Generation form the core infrastructure that enables claude-mem to provide persistent memory capabilities across Claude Code sessions. This system captures tool usage observations, generates semantic summaries, and makes them available to future sessions through a structured context injection mechanism.\n\nThe architecture consists of three primary layers:\n\n1. **Observation Capture Layer** - Captures tool interactions and state changes during Claude Code sessions\n2. **Context Generation Layer** - Transforms raw observations into structured, queryable context\n3. **Context Injection Layer** - Delivers relevant context to Claude Code when new sessions start\n\n资料来源：[src/server/generation/providers/shared/prompt-builder.ts:1-50]()\n\n---\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Observation Capture\"\n A[Claude Code Session] --> B[Tool Usage Events]\n B --> C[Observation Builder]\n C --> D[Observation XML Format]\n end\n\n subgraph \"Context Generation\"\n D --> E[Context Generator Service]\n E --> F[Smart File Parser]\n F --> G[Summary Generator]\n G --> H[Indexed Memory Store]\n end\n\n subgraph \"Context Injection\"\n H --> I[MCP Tools]\n H --> J[Search Routes]\n I --> K[Claude Code]\n J --> K\n end\n\n subgraph \"Storage Layer\"\n K --> L[~/.claude-mem]\n H --> L\n end\n```\n\n---\n\n## Observation System\n\n### XML Schema Structure\n\nObservations are generated in a standardized XML format that allows for structured parsing and searchability. The observation schema includes:\n\n```xml\nRelated Source Files
\n\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- [src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts)\n- [src/sdk/parser.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/parser.ts)\n- [src/services/context-generator.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/context-generator.ts)\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/utils/claude-md-utils.ts](https://github.com/thedotmack/claude-mem/blob/main/src/utils/claude-md-utils.ts)\n\n
\n\n# Installation Guide\n\nClaude-Mem is a persistent memory plugin for Claude Code, enabling seamless context preservation across sessions. This guide covers all supported installation methods across different platforms and integrated development environments.\n\n## Overview\n\nClaude-Mem can be installed through multiple channels depending on your use case:\n\n| Installation Method | Platform | Use Case |\n|-------------------|----------|----------|\n| `npx claude-mem install` | macOS, Linux, Windows | Standard installation for Claude Code |\n| `npx claude-mem install --ide gemini-cli` | All platforms | Integration with Gemini CLI |\n| `npx claude-mem install --ide opencode` | All platforms | Integration with OpenCode |\n| `/plugin` commands | Claude Code | In-app plugin marketplace |\n| OpenClaw Gateway | OpenClaw | Persistent memory on OpenClaw gateways |\n| Docker | Containerized | Isolated deployment environments |\n\nAll installations store data locally in `~/.claude-mem` on the host machine. 资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n\n## System Requirements\n\nBefore installation, ensure your environment meets the following prerequisites:\n\n| Requirement | Specification |\n|-------------|---------------|\n| Node.js | 18+ |\n| Package Manager | npm, npx |\n| Claude Code | Pro/Max subscription for CLI-based auth |\n| API Key | `ANTHROPIC_API_KEY` (optional alternative) |\n\nFor API-based authentication in CI/CD environments, set the `ANTHROPIC_API_KEY` environment variable. Claude Code installations with authenticated Pro/Max subscriptions automatically use built-in authentication. 资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n\n## Standard Installation (Claude Code)\n\n### Quick Install\n\nThe recommended installation method uses npx to install and configure the plugin:\n\n```bash\nnpx claude-mem install\n```\n\nThis command performs the following operations:\n\n1. Detects the Claude Code installation location\n2. Installs plugin hooks in the appropriate configuration directory\n3. Sets up the worker service for observation capture\n4. Configures the local memory storage at `~/.claude-mem`\n\n### Post-Installation Steps\n\nAfter installation completes:\n\n1. Keep the provided localhost URL open in a browser\n2. Open Claude Code in any project\n3. Observations stream automatically as Claude reads, edits, and runs commands\n4. Memory injection starts on your second session in a project\n\nTwo paths are available for building memory:\n\n| Option | Approach | Time |\n|--------|----------|------|\n| A. Passive | Just start working; memory builds from your first prompt | Ongoing |\n| B. Front-load | Run `/learn-codebase` to ingest the entire repository | ~5 minutes |\n\n资料来源：[src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n## IDE-Specific Installations\n\n### Gemini CLI\n\n```bash\nnpx claude-mem install --ide gemini-cli\n```\n\nThis auto-detects the `~/.gemini` configuration directory and installs the appropriate hooks for Gemini CLI integration.\n\n### OpenCode\n\n```bash\nnpx claude-mem install --ide opencode\n```\n\nConfigures hooks specifically for OpenCode IDE environments.\n\n资料来源：[src/npx-cli/install/setup-runtime.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/install/setup-runtime.ts)\n\n## In-App Plugin Installation\n\nFor users who prefer the Claude Code interface:\n\n1. Open Claude Code and access the plugin marketplace\n2. Add the plugin: `/plugin marketplace add thedotmack/claude-mem`\n3. Install the plugin: `/plugin install claude-mem`\n4. Restart Claude Code or Gemini CLI\n\nContext from previous sessions automatically appears in new sessions after installation completes. 资料来源：[README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md)\n\n## OpenClaw Gateway Installation\n\nFor persistent memory on OpenClaw gateways, a dedicated installation script is provided:\n\n```bash\ncurl -fsSL https://install.cmem.ai/openclaw.sh | bash\n```\n\nThis script configures claude-mem as a persistent memory plugin on OpenClaw gateways. 资料来源：[openclaw/install.sh](https://github.com/thedotmack/claude-mem/blob/main/openclaw/install.sh)\n\n### OpenClaw Plugin Configuration\n\nThe OpenClaw integration uses a plugin manifest file that defines:\n\n```json\n{\n \"name\": \"claude-mem\",\n \"version\": \"1.0.0\",\n \"description\": \"Persistent memory for Claude Code\"\n}\n```\n\n资料来源：[openclaw/openclaw.plugin.json](https://github.com/thedotmack/claude-mem/blob/main/openclaw/openclaw.plugin.json)\n\n## Docker Installation\n\nFor containerized or isolated deployment environments, Docker installation is available.\n\n### Building the Docker Image\n\n```bash\ncd docker/claude-mem\ndocker build -t claude-mem .\n```\n\n### Running the Container\n\n```bash\ndocker run -d \\\n --name claude-mem \\\n -p 8080:8080 \\\n -v ~/.claude-mem:/data \\\n claude-mem\n```\n\nThe Docker setup uses a multi-stage build with Node.js 20 as the base image and serves the worker service on port 8080. 资料来源：[docker/claude-mem/Dockerfile](https://github.com/thedotmack/claude-mem/blob/main/docker/claude-mem/Dockerfile)\n\n### Docker Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `PORT` | Worker service port | `8080` |\n| `CLAUDE_MEM_DATA_DIR` | Memory storage directory | `/data` |\n| `ANTHROPIC_API_KEY` | API authentication | Required if no Claude Code |\n\n资料来源：[docker/claude-mem/README.md](https://github.com/thedotmack/claude-mem/blob/main/docker/claude-mem/README.md)\n\n## Installation Workflow\n\n```mermaid\ngraph TD\n A[User runs npx claude-mem install] --> B{Detect Platform}\n B -->|macOS/Linux| C[Find Claude Code config]\n B -->|Windows| D[Find Claude Code config]\n B -->|Gemini CLI| E[Detect ~/.gemini]\n B -->|OpenCode| F[Detect OpenCode config]\n \n C --> G[Install hooks to config dir]\n D --> G\n E --> H[Install gemini-cli hooks]\n F --> I[Install opencode hooks]\n \n G --> J[Start worker service]\n H --> J\n I --> J\n \n J --> K[Display success URL]\n K --> L[User opens Claude Code]\n L --> M[Observations begin streaming]\n M --> N[Memory injection on 2nd session]\n```\n\n## Verification and Status\n\nAfter installation, verify the setup:\n\n```bash\nnpx claude-mem status\n```\n\nIf the worker is not yet ready:\n\n```bash\nnpx claude-mem start\n```\n\nManual startup may be required if the worker failed to start automatically on the configured port (default: 8080). 资料来源：[src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n## Uninstallation\n\nTo uninstall claude-mem:\n\n1. Close all Claude Code sessions (prevents hooks from recreating configuration)\n2. Run the uninstall command or manually remove:\n - `~/.claude-mem` directory\n - Plugin hooks from Claude Code config directory\n - Any installed Claude Code plugins\n\n资料来源：[src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| Worker not ready | Wait ~30 seconds, then run `npx claude-mem start` |\n| Hooks recreated | Close all Claude Code sessions before uninstalling |\n| No observations | Ensure memory injection starts on second session |\n| Auth issues | Verify `ANTHROPIC_API_KEY` or Claude Code Pro/Max subscription |\n\n### First Session Hint\n\nThe welcome hint on first sessions can be disabled:\n\n```bash\nCLAUDE_MEM_WELCOME_HINT_ENABLED=false\n```\n\n### Documentation\n\nFor additional help:\n\n- Documentation: https://docs.claude-mem.ai\n- How it works: `/how-it-works` in Claude Code\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：thedotmack/claude-mem\n\n摘要：发现 39 个潜在踩坑项，其中 13 个为 high/blocking；最高优先级：安装坑 - 来源证据：Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)。\n\n## 1. 安装坑 · 来源证据：Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_24ed2d144536406bb1235c9249013f81 | https://github.com/thedotmack/claude-mem/issues/2521 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\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. 安装坑 · 来源证据：Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2a88889db8f4416a9daf23d9979fee71 | https://github.com/thedotmack/claude-mem/issues/2432 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：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_e1a68c6d9a77481897440b34fca959e4 | https://github.com/thedotmack/claude-mem/issues/2438 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_13c1450c63bb4900bed699a4f9b2abb2 | https://github.com/thedotmack/claude-mem/issues/2407 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d56c3d9492594acab8d0bb29a46a6fee | https://github.com/thedotmack/claude-mem/issues/2520 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：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## 8. 配置坑 · 来源证据：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## 9. 配置坑 · 来源证据：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## 10. 运行坑 · 来源证据：自动运行时突然报下图所示内容，然后插件就不能用了\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## 11. 安全/权限坑 · 来源证据：Feature: Vertex AI support for Gemini provider\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: Vertex AI support for Gemini provider\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_77bf4085ec9e46c59fdaffa4ad889dcc | https://github.com/thedotmack/claude-mem/issues/2522 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f38d625f3d834e7d8179d4a3176f3a73 | https://github.com/thedotmack/claude-mem/issues/2509 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 安全/权限坑 · 来源证据：v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fbb9eadf507d4876b859b92bd87d2ab2 | https://github.com/thedotmack/claude-mem/issues/2485 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 安装坑 · 失败模式：installation: OpenClaw installer fails with TypeScript build error on Linux\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: OpenClaw installer fails with TypeScript build error on Linux\n- 对用户的影响：Developers may fail before the first successful local run: OpenClaw installer fails with TypeScript build error on Linux\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: OpenClaw installer fails with TypeScript build error on Linux. Context: Observed when using node, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_f6c0a0d684fa5f1135ac669cd98df70e | https://github.com/thedotmack/claude-mem/issues/2530 | OpenClaw installer fails with TypeScript build error on Linux\n\n## 15. 安装坑 · 失败模式：installation: Windows worker spawn silently fails when user home path contains a space (four stacked bugs,...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n- 对用户的影响：Developers may fail before the first successful local run: Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0). Context: Observed when using windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_0190fe2b64cffaffac244e9ef7033f4e | https://github.com/thedotmack/claude-mem/issues/2521 | Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n\n## 16. 安装坑 · 失败模式：installation: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new s...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n- 对用户的影响：Developers may fail before the first successful local run: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_967ff316b7cd3cebcc05db7b0d3c8d9d | https://github.com/thedotmack/claude-mem/issues/2432 | Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n\n## 17. 安装坑 · 失败模式：installation: [Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n- 对用户的影响：Developers may fail before the first successful local run: [Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry. Context: Observed when using node, python, macos, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_577adec48438b667deb5de48f5dca7f0 | https://github.com/thedotmack/claude-mem/issues/2437 | [Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n\n## 18. 安装坑 · 失败模式：installation: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain\n- 对用户的影响：Developers may fail before the first successful local run: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_4f334c0890e60adcd2706806e12f126c | https://github.com/thedotmack/claude-mem/issues/2528 | [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain\n\n## 19. 安装坑 · 失败模式：installation: [feat] Option to load only memory-related skills\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [feat] Option to load only memory-related skills\n- 对用户的影响：Developers may fail before the first successful local run: [feat] Option to load only memory-related skills\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [feat] Option to load only memory-related skills. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_838f002b6acafaa53828fd03d9450ed6 | https://github.com/thedotmack/claude-mem/issues/2448 | [feat] Option to load only memory-related skills\n\n## 20. 安装坑 · 失败模式：installation: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n- 对用户的影响：Developers may fail before the first successful local run: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection. Context: Observed when using python, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_9195685a79daaf4720e0243904f7946d | https://github.com/thedotmack/claude-mem/issues/2438 | chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n\n## 21. 安装坑 · 失败模式：installation: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n- 对用户的影响：Developers may fail before the first successful local run: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle. Context: Observed when using node, python, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_a54bc450a4d11e378deac2c0452f8c0f | https://github.com/thedotmack/claude-mem/issues/2450 | claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n\n## 22. 安装坑 · 失败模式：installation: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n- 对用户的影响：Developers may fail before the first successful local run: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote). Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_910a8a9b41ad8e6e15c1867e5ad4f96c | https://github.com/thedotmack/claude-mem/issues/2407 | v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n\n## 23. 安装坑 · 失败模式：installation: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n- 对用户的影响：Developers may fail before the first successful local run: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0. Context: Observed when using node, python, macos\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_32ef30e0e80f6e41f6f07078c0659311 | https://github.com/thedotmack/claude-mem/issues/2485 | v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n\n## 24. 安装坑 · 失败模式：installation: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars un...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)\n- 对用户的影响：Developers may fail before the first successful local run: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux). Context: Observed when using node, python, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_25d358b5f6dfe891ef20a29ba6e827dc | https://github.com/thedotmack/claude-mem/issues/2520 | v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)\n\n## 25. 安装坑 · 失败模式：installation: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_s...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated\n- 对用户的影响：Developers may fail before the first successful local run: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated. Context: Observed when using python, macos\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_62407cc74d1dc4a1fbebe438679ae0be | https://github.com/thedotmack/claude-mem/issues/2533 | v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated\n\n## 26. 安装坑 · 来源证据：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## 27. 安装坑 · 来源证据：[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## 28. 配置坑 · 可能修改宿主 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## 29. 配置坑 · 失败模式：configuration: Feature: Vertex AI support for Gemini provider\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: Feature: Vertex AI support for Gemini provider\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Feature: Vertex AI support for Gemini provider\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Feature: Vertex AI support for Gemini provider. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_d3519e41cb7b1df860b0a5e6ae7db82e | https://github.com/thedotmack/claude-mem/issues/2522 | Feature: Vertex AI support for Gemini provider\n\n## 30. 配置坑 · 失败模式：configuration: Use node to run mcp for windows environment\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: Use node to run mcp for windows environment\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Use node to run mcp for windows environment\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Use node to run mcp for windows environment. Context: Observed when using node, windows, macos, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_7e6bf076e8e465cee8256dd4cb41c3d4 | https://github.com/thedotmack/claude-mem/issues/2446 | Use node to run mcp for windows environment\n\n## 31. 配置坑 · 失败模式：configuration: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraint...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection. Context: Observed when using node, python, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_e40a2ed6db40844214cbb7d7c39088e4 | https://github.com/thedotmack/claude-mem/issues/2509 | Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection\n\n## 32. 配置坑 · 失败模式：configuration: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.e...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects. Context: Observed when using node, python, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_b7f38212a7bbb06091eda408d7b08fbb | https://github.com/thedotmack/claude-mem/issues/2529 | [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects\n\n## 33. 配置坑 · 来源证据：Native Azure AI Foundry support (ANTHROPIC_FOUNDRY_* env vars)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Native Azure AI Foundry support (ANTHROPIC_FOUNDRY_* env vars)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b7808109101d47ccb8519f238757da11 | https://github.com/thedotmack/claude-mem/issues/2524 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 34. 能力坑 · 能力判断依赖假设\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## 35. 维护坑 · 维护活跃度未知\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## 36. 安全/权限坑 · 下游验证发现风险项\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## 37. 安全/权限坑 · 存在评分风险\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## 38. 维护坑 · 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## 39. 维护坑 · 发布节奏不明确\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摘要：发现 39 个潜在踩坑项，其中 13 个为 high/blocking；最高优先级：安装坑 - 来源证据：Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)。\n\n## 1. 安装坑 · 来源证据：Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_24ed2d144536406bb1235c9249013f81 | https://github.com/thedotmack/claude-mem/issues/2521 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\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. 安装坑 · 来源证据：Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2a88889db8f4416a9daf23d9979fee71 | https://github.com/thedotmack/claude-mem/issues/2432 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：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_e1a68c6d9a77481897440b34fca959e4 | https://github.com/thedotmack/claude-mem/issues/2438 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_13c1450c63bb4900bed699a4f9b2abb2 | https://github.com/thedotmack/claude-mem/issues/2407 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d56c3d9492594acab8d0bb29a46a6fee | https://github.com/thedotmack/claude-mem/issues/2520 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：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## 8. 配置坑 · 来源证据：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## 9. 配置坑 · 来源证据：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## 10. 运行坑 · 来源证据：自动运行时突然报下图所示内容，然后插件就不能用了\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## 11. 安全/权限坑 · 来源证据：Feature: Vertex AI support for Gemini provider\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: Vertex AI support for Gemini provider\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_77bf4085ec9e46c59fdaffa4ad889dcc | https://github.com/thedotmack/claude-mem/issues/2522 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f38d625f3d834e7d8179d4a3176f3a73 | https://github.com/thedotmack/claude-mem/issues/2509 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 安全/权限坑 · 来源证据：v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fbb9eadf507d4876b859b92bd87d2ab2 | https://github.com/thedotmack/claude-mem/issues/2485 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 安装坑 · 失败模式：installation: OpenClaw installer fails with TypeScript build error on Linux\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: OpenClaw installer fails with TypeScript build error on Linux\n- 对用户的影响：Developers may fail before the first successful local run: OpenClaw installer fails with TypeScript build error on Linux\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: OpenClaw installer fails with TypeScript build error on Linux. Context: Observed when using node, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_f6c0a0d684fa5f1135ac669cd98df70e | https://github.com/thedotmack/claude-mem/issues/2530 | OpenClaw installer fails with TypeScript build error on Linux\n\n## 15. 安装坑 · 失败模式：installation: Windows worker spawn silently fails when user home path contains a space (four stacked bugs,...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n- 对用户的影响：Developers may fail before the first successful local run: Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0). Context: Observed when using windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_0190fe2b64cffaffac244e9ef7033f4e | https://github.com/thedotmack/claude-mem/issues/2521 | Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)\n\n## 16. 安装坑 · 失败模式：installation: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new s...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n- 对用户的影响：Developers may fail before the first successful local run: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_967ff316b7cd3cebcc05db7b0d3c8d9d | https://github.com/thedotmack/claude-mem/issues/2432 | Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session\n\n## 17. 安装坑 · 失败模式：installation: [Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n- 对用户的影响：Developers may fail before the first successful local run: [Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry. Context: Observed when using node, python, macos, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_577adec48438b667deb5de48f5dca7f0 | https://github.com/thedotmack/claude-mem/issues/2437 | [Bug] 13.x worker fails with \"Cannot find module 'zod/v3'\" — package-lock.json missing zod entry\n\n## 18. 安装坑 · 失败模式：installation: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain\n- 对用户的影响：Developers may fail before the first successful local run: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_4f334c0890e60adcd2706806e12f126c | https://github.com/thedotmack/claude-mem/issues/2528 | [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain\n\n## 19. 安装坑 · 失败模式：installation: [feat] Option to load only memory-related skills\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [feat] Option to load only memory-related skills\n- 对用户的影响：Developers may fail before the first successful local run: [feat] Option to load only memory-related skills\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [feat] Option to load only memory-related skills. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_838f002b6acafaa53828fd03d9450ed6 | https://github.com/thedotmack/claude-mem/issues/2448 | [feat] Option to load only memory-related skills\n\n## 20. 安装坑 · 失败模式：installation: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n- 对用户的影响：Developers may fail before the first successful local run: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection. Context: Observed when using python, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_9195685a79daaf4720e0243904f7946d | https://github.com/thedotmack/claude-mem/issues/2438 | chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection\n\n## 21. 安装坑 · 失败模式：installation: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n- 对用户的影响：Developers may fail before the first successful local run: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle. Context: Observed when using node, python, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_a54bc450a4d11e378deac2c0452f8c0f | https://github.com/thedotmack/claude-mem/issues/2450 | claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle\n\n## 22. 安装坑 · 失败模式：installation: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n- 对用户的影响：Developers may fail before the first successful local run: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote). Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_910a8a9b41ad8e6e15c1867e5ad4f96c | https://github.com/thedotmack/claude-mem/issues/2407 | v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)\n\n## 23. 安装坑 · 失败模式：installation: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n- 对用户的影响：Developers may fail before the first successful local run: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0. Context: Observed when using node, python, macos\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_32ef30e0e80f6e41f6f07078c0659311 | https://github.com/thedotmack/claude-mem/issues/2485 | v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0\n\n## 24. 安装坑 · 失败模式：installation: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars un...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)\n- 对用户的影响：Developers may fail before the first successful local run: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux). Context: Observed when using node, python, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_25d358b5f6dfe891ef20a29ba6e827dc | https://github.com/thedotmack/claude-mem/issues/2520 | v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)\n\n## 25. 安装坑 · 失败模式：installation: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_s...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated\n- 对用户的影响：Developers may fail before the first successful local run: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated. Context: Observed when using python, macos\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_62407cc74d1dc4a1fbebe438679ae0be | https://github.com/thedotmack/claude-mem/issues/2533 | v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated\n\n## 26. 安装坑 · 来源证据：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## 27. 安装坑 · 来源证据：[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## 28. 配置坑 · 可能修改宿主 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## 29. 配置坑 · 失败模式：configuration: Feature: Vertex AI support for Gemini provider\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: Feature: Vertex AI support for Gemini provider\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Feature: Vertex AI support for Gemini provider\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Feature: Vertex AI support for Gemini provider. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_d3519e41cb7b1df860b0a5e6ae7db82e | https://github.com/thedotmack/claude-mem/issues/2522 | Feature: Vertex AI support for Gemini provider\n\n## 30. 配置坑 · 失败模式：configuration: Use node to run mcp for windows environment\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: Use node to run mcp for windows environment\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Use node to run mcp for windows environment\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Use node to run mcp for windows environment. Context: Observed when using node, windows, macos, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_7e6bf076e8e465cee8256dd4cb41c3d4 | https://github.com/thedotmack/claude-mem/issues/2446 | Use node to run mcp for windows environment\n\n## 31. 配置坑 · 失败模式：configuration: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraint...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection. Context: Observed when using node, python, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_e40a2ed6db40844214cbb7d7c39088e4 | https://github.com/thedotmack/claude-mem/issues/2509 | Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection\n\n## 32. 配置坑 · 失败模式：configuration: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.e...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects. Context: Observed when using node, python, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_b7f38212a7bbb06091eda408d7b08fbb | https://github.com/thedotmack/claude-mem/issues/2529 | [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects\n\n## 33. 配置坑 · 来源证据：Native Azure AI Foundry support (ANTHROPIC_FOUNDRY_* env vars)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Native Azure AI Foundry support (ANTHROPIC_FOUNDRY_* env vars)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b7808109101d47ccb8519f238757da11 | https://github.com/thedotmack/claude-mem/issues/2524 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 34. 能力坑 · 能力判断依赖假设\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## 35. 维护坑 · 维护活跃度未知\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## 36. 安全/权限坑 · 下游验证发现风险项\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## 37. 安全/权限坑 · 存在评分风险\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## 38. 维护坑 · 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## 39. 维护坑 · 发布节奏不明确\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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for thedotmack/claude-mem.\n\nProject:\n- Name: claude-mem\n- Repository: https://github.com/thedotmack/claude-mem\n- Summary: Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More\n- Host target: claude, claude_code\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-introduction: Introduction to Claude-Mem. Produce one small intermediate artifact and wait for confirmation.\n2. page-key-features: Key Features. Produce one small intermediate artifact and wait for confirmation.\n3. page-architecture-overview: System Architecture Overview. Produce one small intermediate artifact and wait for confirmation.\n4. page-hooks-system: Hooks System and Lifecycle. Produce one small intermediate artifact and wait for confirmation.\n5. page-worker-service: Worker Service Architecture. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\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"
}