docs: comprehensive v5.1.2 documentation update
This commit brings all documentation up to date with the current v5.1.2 codebase, addressing 12+ critical discrepancies and adding 2 major new documentation files. ## Files Modified (18 documentation files): ### Root Documentation: - README.md: Updated version badge (4.3.1 → 5.1.2), tool count (7 → 9), added viewer UI and theme toggle features, updated "What's New" section - CHANGELOG.md: Added 8 missing releases (v4.3.2 through v5.1.2) with comprehensive release notes - CLAUDE.md: Removed hardcoded personal paths, documented all 14 worker endpoints (was 8), added Chroma integration overview, updated v5.x releases ### Mintlify Documentation (docs/): - introduction.mdx: Updated search tool count to 9, added viewer UI and theme toggle to features - configuration.mdx: Added smart-install.js documentation, clarified data directory locations, added CLAUDE_CODE_PATH env var, explained observations vs sessions, updated hook configuration examples - development.mdx: Added comprehensive viewer UI development section (103 lines), updated build output filenames (search-server.mjs) - usage/search-tools.mdx: Added get_context_timeline and get_timeline_by_query documentation with examples, updated tool count to 9 - architecture/overview.mdx: Updated to 7 hook files, 9 search tools, added Chroma to tech stack, enhanced component details with viewer UI - architecture/hooks.mdx: Added smart-install.js and user-message-hook.js documentation, updated hook count to 7 - architecture/worker-service.mdx: Documented all 14 endpoints organized by category (Viewer & Health, Data Retrieval, Settings, Session Management) - architecture/mcp-search.mdx: Added timeline tools documentation, updated tool count to 9, fixed filename references (search-server.mjs) - architecture-evolution.mdx: Added complete v5.x release history (v5.0.0 through v5.1.2), updated title to "v3 to v5" - hooks-architecture.mdx: Updated to "Seven Hook Scripts", added smart-install and user-message-hook documentation - troubleshooting.mdx: Added v5.x specific issues section (viewer, theme toggle, SSE, Chroma, PM2 Windows fix) ### New Documentation Files: - docs/VIEWER.md: Complete 400+ line guide to web viewer UI including architecture, features, usage, development, API integration, performance considerations - docs/CHROMA.md: Complete 450+ line guide to vector database integration including hybrid search architecture, semantic search explanation, performance benchmarks, installation, configuration, troubleshooting ## Key Corrections Made: 1. ✅ Updated version badges and references: 4.3.1 → 5.1.2 2. ✅ Corrected search tool count: 7 → 9 (added get_context_timeline, get_timeline_by_query) 3. ✅ Fixed MCP server filename: search-server.js → search-server.mjs 4. ✅ Updated hook count: 5 → 7 (added smart-install.js, user-message-hook.js) 5. ✅ Documented all 14 worker endpoints (was 8, incorrectly claimed 6 were missing) 6. ✅ Removed hardcoded personal file paths 7. ✅ Added Chroma vector database documentation 8. ✅ Added viewer UI comprehensive documentation 9. ✅ Updated CHANGELOG with all missing v4.3.2-v5.1.2 releases 10. ✅ Clarified data directory locations (production vs development) 11. ✅ Added smart-install.js caching system documentation 12. ✅ Updated SessionStart hook configuration examples ## Documentation Statistics: - Total files modified: 18 - New files created: 2 - Lines added: ~2,000+ - Version mismatches fixed: 2 critical - Missing features documented: 5+ major - Missing tools documented: 2 MCP tools - Missing endpoints documented: 6 API endpoints ## Impact: Documentation now accurately reflects the current v5.1.2 codebase with: - Complete viewer UI documentation (v5.1.0) - Theme toggle feature (v5.1.2) - Hybrid search architecture with Chroma (v5.0.0) - Smart install caching (v5.0.3) - All 7 hook scripts documented - All 9 MCP search tools documented - All 14 worker service endpoints documented - Comprehensive troubleshooting for v5.x issues 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Alex Newman
+405
@@ -0,0 +1,405 @@
|
||||
# Viewer UI - Web-Based Memory Stream Visualization
|
||||
|
||||
## Overview
|
||||
|
||||
The Claude-Mem Viewer UI is a production-ready web interface that provides real-time visualization of your memory stream. Access it at **http://localhost:37777** while the claude-mem worker is running.
|
||||
|
||||
**Key Features:**
|
||||
- 🔴 **Real-time Updates** - Server-Sent Events (SSE) stream new observations, sessions, and prompts instantly
|
||||
- 📜 **Infinite Scroll** - Load historical data progressively with automatic pagination
|
||||
- 🎯 **Project Filtering** - Focus on specific codebases with smart project selection
|
||||
- 🎨 **Theme Toggle** - Light, dark, or system preference with persistent settings
|
||||
- 💾 **Settings Persistence** - Sidebar state and project filters saved automatically
|
||||
- 🔄 **Auto-Reconnection** - Exponential backoff ensures connection stability
|
||||
- ⚡ **GPU Acceleration** - Smooth animations and transitions
|
||||
|
||||
## Architecture
|
||||
|
||||
### Technology Stack
|
||||
|
||||
| Component | Technology | Purpose |
|
||||
|-----------|-----------|---------|
|
||||
| **Framework** | React + TypeScript | Component-based UI with type safety |
|
||||
| **Build System** | esbuild | Self-contained HTML bundle (no separate assets) |
|
||||
| **Real-time** | Server-Sent Events (SSE) | Push-based updates from worker service |
|
||||
| **State Management** | React hooks | Local state with custom hooks for SSE, pagination, settings |
|
||||
| **Styling** | Inline CSS | No external stylesheets, fully self-contained |
|
||||
| **Typography** | Monaspace Radon | Embedded monospace font for code aesthetics |
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
src/ui/viewer/
|
||||
├── App.tsx # Main application component
|
||||
├── types.ts # TypeScript interfaces
|
||||
├── components/
|
||||
│ ├── Header.tsx # Top navigation with logo and theme toggle
|
||||
│ ├── Sidebar.tsx # Project filter and stats sidebar
|
||||
│ ├── Feed.tsx # Main feed with infinite scroll
|
||||
│ ├── ThemeToggle.tsx # Light/dark/system theme selector
|
||||
│ └── cards/
|
||||
│ ├── ObservationCard.tsx # Displays individual observations
|
||||
│ ├── SummaryCard.tsx # Displays session summaries
|
||||
│ ├── PromptCard.tsx # Displays user prompts
|
||||
│ └── SkeletonCard.tsx # Loading placeholder
|
||||
├── hooks/
|
||||
│ ├── useSSE.ts # Server-Sent Events connection
|
||||
│ ├── usePagination.ts # Infinite scroll logic
|
||||
│ ├── useSettings.ts # Settings persistence
|
||||
│ ├── useStats.ts # Database statistics
|
||||
│ └── useTheme.ts # Theme management
|
||||
└── utils/
|
||||
├── constants.ts # Configuration constants
|
||||
├── data.ts # Data merging and deduplication
|
||||
└── formatters.ts # Date/time formatting helpers
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Worker Service (port 37777) │
|
||||
│ - Express HTTP API │
|
||||
│ - SSE endpoint: /stream │
|
||||
│ - REST endpoints: /api/* │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Viewer UI (React App) │
|
||||
│ - useSSE hook: Real-time stream │
|
||||
│ - usePagination hook: Historical data │
|
||||
│ - useSettings hook: Persistent preferences │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Feed Component │
|
||||
│ - Merges real-time + paginated data │
|
||||
│ - Deduplicates by ID │
|
||||
│ - Filters by selected project │
|
||||
│ - Infinite scroll triggers pagination │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Features In Detail
|
||||
|
||||
### Real-Time Updates (SSE)
|
||||
|
||||
The viewer uses Server-Sent Events to receive updates instantly:
|
||||
|
||||
```typescript
|
||||
// SSE message format
|
||||
{
|
||||
"type": "observation" | "summary" | "prompt" | "projects" | "processing",
|
||||
"data": { /* record data */ }
|
||||
}
|
||||
```
|
||||
|
||||
**Event Types:**
|
||||
- `observation` - New observation created
|
||||
- `summary` - Session summary generated
|
||||
- `prompt` - User prompt captured
|
||||
- `projects` - Project list updated
|
||||
- `processing` - Session processing status changed
|
||||
|
||||
**Connection Management:**
|
||||
- Auto-reconnect on disconnect with exponential backoff
|
||||
- Visual connection status indicator in header
|
||||
- Graceful degradation if SSE unavailable
|
||||
|
||||
### Infinite Scroll Pagination
|
||||
|
||||
The feed loads historical data progressively:
|
||||
|
||||
1. **Initial Load**: First 20 records loaded on mount
|
||||
2. **Scroll Trigger**: When user scrolls to 80% of feed height
|
||||
3. **Batch Load**: Next 20 records fetched via `/api/{type}?offset=X&limit=20`
|
||||
4. **Deduplication**: Merges with real-time data, removes duplicates by ID
|
||||
5. **Loading State**: Skeleton cards show while fetching
|
||||
|
||||
**Performance:**
|
||||
- Requests debounced to prevent spam
|
||||
- Only visible when scrolled near bottom
|
||||
- Continues until no more records available
|
||||
|
||||
### Project Filtering
|
||||
|
||||
Filter memory stream by specific projects:
|
||||
|
||||
1. Projects extracted from observations, summaries, and prompts
|
||||
2. Sidebar shows all unique project names with counts
|
||||
3. Click project name to filter feed
|
||||
4. Click "All Projects" to clear filter
|
||||
5. Filter persisted to localStorage
|
||||
|
||||
**Project Detection:**
|
||||
- Extracted from `projectPath` or `project` field in records
|
||||
- Basename of path used as project name
|
||||
- Empty/null projects shown as "(No Project)"
|
||||
|
||||
### Theme Toggle (v5.1.2)
|
||||
|
||||
Three theme modes available:
|
||||
|
||||
- **Light Mode**: Clean white background, dark text
|
||||
- **Dark Mode**: Dark background, light text (default)
|
||||
- **System**: Matches OS preference automatically
|
||||
|
||||
**Implementation:**
|
||||
```typescript
|
||||
// Theme preference stored in localStorage
|
||||
localStorage.setItem('theme-preference', 'light' | 'dark' | 'system');
|
||||
|
||||
// CSS variables updated dynamically
|
||||
document.documentElement.setAttribute('data-theme', resolvedTheme);
|
||||
```
|
||||
|
||||
**CSS Variables:**
|
||||
```css
|
||||
:root[data-theme="light"] {
|
||||
--bg-primary: #ffffff;
|
||||
--text-primary: #1f2937;
|
||||
/* ... */
|
||||
}
|
||||
|
||||
:root[data-theme="dark"] {
|
||||
--bg-primary: #111827;
|
||||
--text-primary: #f9fafb;
|
||||
/* ... */
|
||||
}
|
||||
```
|
||||
|
||||
### Settings Persistence
|
||||
|
||||
Settings automatically saved to worker service:
|
||||
|
||||
**Saved Settings:**
|
||||
- `sidebarOpen` - Sidebar expanded/collapsed state
|
||||
- `selectedProject` - Current project filter
|
||||
- `theme` - Theme preference (light/dark/system)
|
||||
|
||||
**API Endpoints:**
|
||||
- `GET /api/settings` - Retrieve saved settings
|
||||
- `POST /api/settings` - Save settings (debounced 500ms)
|
||||
|
||||
**Local Fallback:**
|
||||
- If API unavailable, settings stored in localStorage
|
||||
- Synced back to API when connection restored
|
||||
|
||||
## Usage Guide
|
||||
|
||||
### Opening the Viewer
|
||||
|
||||
1. Ensure claude-mem worker is running (auto-starts with Claude Code)
|
||||
2. Open browser to http://localhost:37777
|
||||
3. Viewer loads automatically with recent records
|
||||
|
||||
### Navigating the Feed
|
||||
|
||||
**Cards Displayed:**
|
||||
- **Observation Cards** (blue accent) - Tool usage observations with title, narrative, concepts, files
|
||||
- **Summary Cards** (green accent) - Session summaries with request, completion, learnings
|
||||
- **Prompt Cards** (purple accent) - Raw user prompts with timestamp and project
|
||||
|
||||
**Card Features:**
|
||||
- Click to expand/collapse full details
|
||||
- Type indicators (🔴 bugfix, 🟣 feature, 🔄 refactor, etc.)
|
||||
- Concept tags (clickable for future filtering)
|
||||
- File references with paths
|
||||
- Timestamps in relative format ("2 hours ago")
|
||||
|
||||
### Using Project Filters
|
||||
|
||||
1. **Open Sidebar**: Click hamburger menu (☰) in top-left
|
||||
2. **View Stats**: See total observations, sessions, prompts
|
||||
3. **Select Project**: Click project name to filter
|
||||
4. **View Counts**: Numbers show records per project
|
||||
5. **Clear Filter**: Click "All Projects" to reset
|
||||
|
||||
### Changing Theme
|
||||
|
||||
1. **Open Theme Toggle**: Click theme icon in header
|
||||
2. **Select Mode**:
|
||||
- ☀️ Light mode
|
||||
- 🌙 Dark mode
|
||||
- 💻 System (follows OS)
|
||||
3. **Auto-Save**: Preference saved immediately
|
||||
4. **Smooth Transition**: CSS transitions between themes
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
**Viewer Not Loading:**
|
||||
```bash
|
||||
# Check worker status
|
||||
npm run worker:logs
|
||||
|
||||
# Restart worker
|
||||
npm run worker:restart
|
||||
|
||||
# Check if port 37777 is available
|
||||
lsof -i :37777
|
||||
```
|
||||
|
||||
**SSE Connection Issues:**
|
||||
- Check browser console for connection errors
|
||||
- Verify no proxy/firewall blocking EventSource
|
||||
- Auto-reconnect attempts every 1-5s with exponential backoff
|
||||
|
||||
**Theme Not Persisting:**
|
||||
- Check localStorage: `localStorage.getItem('theme-preference')`
|
||||
- Verify `/api/settings` endpoint responding
|
||||
- Clear browser cache if stale
|
||||
|
||||
**Infinite Scroll Not Triggering:**
|
||||
- Scroll to 80% of feed height
|
||||
- Check browser console for fetch errors
|
||||
- Verify `/api/{type}` endpoints responding with data
|
||||
|
||||
## Development
|
||||
|
||||
### Building the Viewer
|
||||
|
||||
```bash
|
||||
# Build viewer UI
|
||||
npm run build
|
||||
|
||||
# Output: plugin/ui/viewer.html (self-contained)
|
||||
```
|
||||
|
||||
### Adding New Features
|
||||
|
||||
**Example: Add a new card component**
|
||||
|
||||
1. Create component:
|
||||
```typescript
|
||||
// src/ui/viewer/components/cards/MyCard.tsx
|
||||
export function MyCard({ data }: { data: MyData }) {
|
||||
return (
|
||||
<div className="card">
|
||||
<div className="card-header">{data.title}</div>
|
||||
<div className="card-body">{data.content}</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
2. Add to Feed component:
|
||||
```typescript
|
||||
// src/ui/viewer/components/Feed.tsx
|
||||
import { MyCard } from './cards/MyCard';
|
||||
|
||||
// In render:
|
||||
{myData.map(item => <MyCard key={item.id} data={item} />)}
|
||||
```
|
||||
|
||||
3. Rebuild:
|
||||
```bash
|
||||
npm run build
|
||||
npm run sync-marketplace
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
### Testing Changes
|
||||
|
||||
1. Make changes to `src/ui/viewer/`
|
||||
2. Rebuild: `npm run build`
|
||||
3. Restart worker: `npm run worker:restart`
|
||||
4. Refresh browser (http://localhost:37777)
|
||||
5. Check browser console for errors
|
||||
|
||||
## API Integration
|
||||
|
||||
The viewer consumes these worker service endpoints:
|
||||
|
||||
### Data Retrieval
|
||||
|
||||
```typescript
|
||||
// Get paginated observations
|
||||
GET /api/observations?offset=0&limit=20&project=myproject
|
||||
Response: { observations: Observation[], hasMore: boolean }
|
||||
|
||||
// Get paginated summaries
|
||||
GET /api/summaries?offset=0&limit=20&project=myproject
|
||||
Response: { summaries: Summary[], hasMore: boolean }
|
||||
|
||||
// Get paginated prompts
|
||||
GET /api/prompts?offset=0&limit=20&project=myproject
|
||||
Response: { prompts: UserPrompt[], hasMore: boolean }
|
||||
|
||||
// Get database stats
|
||||
GET /api/stats
|
||||
Response: { totalObservations: number, totalSessions: number, ... }
|
||||
```
|
||||
|
||||
### Real-Time Stream
|
||||
|
||||
```typescript
|
||||
// Server-Sent Events stream
|
||||
GET /stream
|
||||
|
||||
// Message format:
|
||||
event: observation
|
||||
data: {"type":"observation","data":{...}}
|
||||
|
||||
event: summary
|
||||
data: {"type":"summary","data":{...}}
|
||||
```
|
||||
|
||||
### Settings
|
||||
|
||||
```typescript
|
||||
// Get settings
|
||||
GET /api/settings
|
||||
Response: { sidebarOpen: boolean, selectedProject: string, ... }
|
||||
|
||||
// Save settings
|
||||
POST /api/settings
|
||||
Body: { sidebarOpen: boolean, selectedProject: string, ... }
|
||||
Response: { success: boolean }
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Bundle Size
|
||||
- Self-contained HTML: ~150KB (gzipped)
|
||||
- No external dependencies loaded at runtime
|
||||
- Monaspace Radon font embedded (subset)
|
||||
|
||||
### Memory Management
|
||||
- Virtualization: Only renders visible cards
|
||||
- Deduplication: Prevents duplicate records in memory
|
||||
- Cleanup: Old records beyond pagination limit pruned
|
||||
|
||||
### Network Efficiency
|
||||
- SSE: Single long-lived connection for real-time updates
|
||||
- REST: Paginated requests (20 records per batch)
|
||||
- Debouncing: Settings saves debounced 500ms
|
||||
|
||||
### Rendering Performance
|
||||
- React.memo: Cards memoized to prevent unnecessary re-renders
|
||||
- useMemo: Data merging/filtering memoized
|
||||
- CSS transitions: GPU-accelerated for smooth animations
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Potential features for future versions:
|
||||
|
||||
- **Search**: Full-text search across observations, summaries, prompts
|
||||
- **Export**: Download data as JSON, CSV, or markdown
|
||||
- **Charts**: Visualize observation frequency, types, concepts over time
|
||||
- **Keyboard Shortcuts**: Navigate feed, toggle sidebar, switch themes
|
||||
- **Notifications**: Browser notifications for important observations
|
||||
- **Dark/Light Auto-Schedule**: Auto-switch theme based on time of day
|
||||
- **Custom Themes**: User-defined color schemes
|
||||
- **Multi-Project Views**: Compare multiple projects side-by-side
|
||||
|
||||
## Resources
|
||||
|
||||
- **Source Code**: `src/ui/viewer/`
|
||||
- **Built Output**: `plugin/ui/viewer.html`
|
||||
- **Worker Service**: `src/services/worker-service.ts`
|
||||
- **Build Script**: `scripts/build-viewer.js`
|
||||
- **Documentation**: This file
|
||||
|
||||
---
|
||||
|
||||
**Built with React + TypeScript** | **Powered by Server-Sent Events** | **Self-Contained HTML Bundle**
|
||||
Reference in New Issue
Block a user