相关源码文件
以下源码文件用于生成本页说明： - [README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md) - [src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts) - [src/server/generation/providers/shared/prompt-builder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/providers/shared/prompt-builder.ts) - [src/ui/viewer/components/SummaryCard.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/SummaryCard.tsx) - [src/ui/viewer/components/ObservationCard.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ObservationCard.tsx) - [src/ui/viewer/components/ContextSettingsModal.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ContextSettingsModal.tsx) - [src/ui/viewer/App.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/App.tsx) - [src/services/smart-file-read/parser.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/smart-file-read/parser.ts){section.label}
{section.content}
-
{facts.map((fact: string, i: number) => (
- {fact} ))}
{observation.narrative}
)}
```
资料来源：[src/ui/viewer/components/ObservationCard.tsx:50-65](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ObservationCard.tsx)
### 7. Theme System
The viewer supports light and dark themes with CSS custom properties:
| Theme Variable | Light Mode | Dark Mode |
|----------------|------------|-----------|
| `--color-bg-primary` | #ffffff | #0d1117 |
| `--color-bg-secondary` | #efebe4 | #161b22 |
| `--color-bg-card` | #ffffff | #161b22 |
| `--color-bg-button` | #0969da | #238636 |
资料来源：[src/ui/viewer-template.html:20-40](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer-template.html)
## Architecture Diagram
```mermaid
graph TD
A[Claude Code Session] --> B[Observation Capture]
B --> C[Worker Service]
C --> D[SQLite Database]
D --> E[Context Builder]
E --> F[Prompt Injection]
F --> A
C --> G[Summary Generation]
G --> D
H[Web Viewer] --> E
H --> D
I[Smart File Parser] --> B
```
## Data Flow
```mermaid
sequenceDiagram
participant User
participant Claude as Claude Code
participant SDK as SDK/prompts.ts
participant Worker as Worker Service
participant DB as SQLite
participant Viewer as Web Viewer
User->>Claude: Start session
Claude->>SDK: Generate observation
SDK->>Worker: Send observation data
Worker->>DB: Store observation
User->>Viewer: Browse observations
Viewer->>DB: Query observations
DB-->>Viewer: Return data
User->>Claude: End session
Claude->>SDK: Request summary
SDK->>Worker: Generate summary
Worker->>DB: Store summary
User->>Claude: New session
Viewer->>Claude: Inject context
Claude->>User: Respond with context
```
## Key System Behaviors
### Observation Types
The system recognizes several observation types that categorize different tool operations:
1. **file_read** - When Claude reads a file
2. **file_modified** - When Claude edits or creates a file
3. **command** - When Claude runs shell commands
4. **code_change** - When significant code modifications occur
### XML Escaping
All user-generated content is properly escaped before insertion into XML output to prevent injection attacks:
```typescript
function escapeXml(text: string): string {
return text
.replace(/&/g, '&')
.replace(//g, '>')
.replace(/"/g, '"')
.replace(/'/g, ''');
}
```
资料来源：[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)
### Error Handling
The viewer implements error boundaries to gracefully handle component failures:
```typescript
class ErrorBoundary extends React.Component {
state = { error: null, errorInfo: null };
componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
this.setState({ error, errorInfo });
}
render() {
if (this.state.error) {
return (
Error details
{this.state.error.toString()}
相关源码文件
以下源码文件用于生成本页说明： - [README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md) - [src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts) - [src/server/generation/providers/shared/prompt-builder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/providers/shared/prompt-builder.ts) - [src/ui/viewer/App.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/App.tsx) - [src/ui/viewer/components/ContextSettingsModal.tsx](https://github.com/thedotmack/claude-mem/blob/main/src/ui/viewer/components/ContextSettingsModal.tsx) - [src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts)~/.claude-mem)] C --> E[Prompt Builder] E --> F[Claude API] F --> G[Parsed Observations] C --> G H[Viewer UI :8080] --> C H --> D ``` ## Core Components ### 1. Worker Service (`src/services/worker-service.ts`) The worker service is the central processing hub that: - Runs as a background process (default port 3000) - Receives tool usage observations from IDE plugins - Processes and stores observations in SQLite - Handles prompt generation and LLM interaction - Manages session context injection 资料来源：[src/npx-cli/commands/install.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/install.ts) ### 2. SDK Layer (`src/sdk/prompts.ts`) The SDK provides prompt building functions for different operation modes: | Function | Purpose | |----------|---------| | `buildObservationPrompt()` | Creates prompts for parsing tool observations into structured XML format | | `buildSummaryPrompt()` | Generates prompts for creating session summaries | | `buildContinuationPrompt()` | Builds prompts for continuing sessions with existing context | The SDK uses `ModeConfig` objects that define observation types, prompt templates, and output format guidelines specific to each IDE integration. 资料来源：[src/sdk/prompts.ts](https://github.com/thedotmack/claude-mem/blob/main/src/sdk/prompts.ts) ### 3. Prompt Builder (`src/server/generation/providers/shared/prompt-builder.ts`) Handles the generation of structured output schemas for LLM interactions: ```typescript function buildObservationOutputSchema(mode: ModeConfig): string { const types = mode.observation_types.map(t => t.id).join(' | '); return [ '
相关源码文件
以下源码文件用于生成本页说明： - [plugin/hooks/hooks.json](https://github.com/thedotmack/claude-mem/blob/main/plugin/hooks/hooks.json) - [src/cli/hook-command.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/hook-command.ts) - [src/shared/hook-constants.ts](https://github.com/thedotmack/claude-mem/blob/main/src/shared/hook-constants.ts) - [src/cli/handlers/observation.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/handlers/observation.ts) - [src/cli/handlers/session-init.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/handlers/session-init.ts) - [src/cli/handlers/user-message.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/handlers/user-message.ts) - [src/cli/handlers/summarize.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/handlers/summarize.ts)相关源码文件
以下源码文件用于生成本页说明： - [src/services/worker-service.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts) - [src/server/jobs/ServerJobQueue.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/jobs/ServerJobQueue.ts) - [src/services/worker/ClaudeProvider.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/ClaudeProvider.ts) - [src/services/worker/GeminiProvider.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/GeminiProvider.ts) - [src/services/worker/OpenRouterProvider.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/OpenRouterProvider.ts) - [src/services/worker/http/routes/MemoryRoutes.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/http/routes/MemoryRoutes.ts) - [src/npx-cli/commands/runtime.ts](https://github.com/thedotmack/claude-mem/blob/main/src/npx-cli/commands/runtime.ts) - [src/services/infrastructure/ProcessManager.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/infrastructure/ProcessManager.ts)相关源码文件
以下源码文件用于生成本页说明： - [src/services/sqlite/schema.sql](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/schema.sql) - [src/services/sqlite/SessionStore.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/SessionStore.ts) - [src/services/sqlite/Observations.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Observations.ts) - [src/services/sqlite/Summaries.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Summaries.ts) - [src/services/sqlite/Timeline.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/Timeline.ts) - [src/services/sqlite/migrations.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/migrations.ts) - [src/services/sqlite/migrations/runner.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/sqlite/migrations/runner.ts) - [src/storage/sqlite/schema.ts](https://github.com/thedotmack/claude-mem/blob/main/src/storage/sqlite/schema.ts)相关源码文件
以下源码文件用于生成本页说明： - [src/services/context/ContextBuilder.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/context/ContextBuilder.ts) - [src/services/context/ObservationCompiler.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/context/ObservationCompiler.ts) - [src/services/transcripts/processor.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/transcripts/processor.ts) - [src/services/transcripts/watcher.ts](https://github.com/thedotmack/claude-mem/blob/main/src/services/transcripts/watcher.ts) - [src/server/generation/ProviderObservationGenerator.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/generation/ProviderObservationGenerator.ts) - [src/cli/handlers/context.ts](https://github.com/thedotmack/claude-mem/blob/main/src/cli/handlers/context.ts)~/.claude-mem] FS --> OBS[Observations DB] FS --> SUMM[Summary DB] end subgraph Retrieval ["Retrieval Layer"] CLI[CLI Context Handler] --> SR[Search & Retrieval] SR --> CB CB --> CONTEXT[Context Injection] end subgraph Output ["Output Layer"] CONTEXT --> UI[Viewer UI] CONTEXT --> SDK[SDK Prompts] end ``` ## Core Data Flow Pipeline ### 1. Transcript Watching The transcript watcher monitors Claude Code sessions in real-time, capturing all activity as it occurs. **Key Components:** | Component | File | Purpose | |-----------|------|---------| | TranscriptWatcher | `src/services/transcripts/watcher.ts` | Monitors transcript files for changes | | TranscriptProcessor | `src/services/transcripts/processor.ts` | Parses and extracts events from transcripts | The watcher detects when new content is written to transcript files and triggers processing. Events captured include: - Tool invocations (`Read`, `Write`, `Edit`, `Bash`, etc.) - User prompts - Assistant responses - System events ### 2. Observation Generation Observations are generated from processed transcript events using LLM providers. ```mermaid graph LR subgraph Input EV[Event Data] --> PG[Prompt Builder] MC[Mode Config] --> PG end subgraph Generation PG --> LLM[LLM Provider] LLM --> XML[XML Output] end subgraph Output XML --> OBS[Observation Record] XML --> PRIV[Private Data Check] end ``` **ProviderObservationGenerator** handles the generation flow: 1. Builds prompts using `ModeConfig` and observation types 2. Sends requests to configured LLM provider (Claude by default) 3. Parses XML-structured responses 4. Validates and sanitizes output The generated observation schema follows this structure: ```xml
Max 3 attempts ``` **ServerJobQueue** manages job lifecycle: | Feature | Description | |---------|-------------| | Retry Policy | Automatic retry with exponential backoff | | Progress Tracking | Real-time job progress events | | Stalled Detection | Monitors for stuck jobs | | Cross-Process Events | Redis pub/sub for distributed workers | 资料来源：[src/server/jobs/ServerJobQueue.ts](https://github.com/thedotmack/claude-mem/blob/main/src/server/jobs/ServerJobQueue.ts) ## Storage Architecture All data persists to `~/.claude-mem/` on the local filesystem. ```mermaid graph TD subgraph "~/.claude-mem" OBS[observations/] SUMM[summary/] CONTEXT[context/] CONFIG[config.json] MODES[modes/] end OBS --> |JSON files| RECORDS[Individual records] SUMM --> |JSON files| SESSION_SUMM[Session summaries] CONTEXT --> |Compiled| READY[Ready for injection] ``` ### File Structure | Directory | Content | Format | |-----------|---------|--------| | `observations/` | Individual observations | JSON with metadata | | `summary/` | Session summaries | JSON with sections | | `context/` | Compiled context bundles | JSON arrays | | `modes/` | Mode configurations | JSON | | `transcripts/` | Raw session transcripts | Text/markdown | ## Summary Generation Flow Summaries are generated at session end to provide high-level overviews. ```mermaid graph TD subgraph SessionEnd END[Session Complete] --> EXTRACT[Extract Key Events] EXTRACT --> BUILD[Build Summary Prompt] end subgraph Generation BUILD --> LLM[LLM Generation] LLM --> PARSE[Parse Summary XML] end subgraph Output PARSE --> STRUCT[Structured Summary] STRUCT --> STORE[Store to summary/] STRUCT --> DISPLAY[Display in UI] end ``` Summary output format: ```xml