claude-mem/docs/VIEWER.md

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:

// 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:

// Theme preference stored in localStorage
localStorage.setItem('theme-preference', 'light' | 'dark' | 'system');

// CSS variables updated dynamically
document.documentElement.setAttribute('data-theme', resolvedTheme);

CSS Variables:

: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:

# 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

# 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:

// 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:

// src/ui/viewer/components/Feed.tsx
import { MyCard } from './cards/MyCard';

// In render:
{myData.map(item => <MyCard key={item.id} data={item} />)}

3. Rebuild:

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

// 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

// Server-Sent Events stream
GET /stream

// Message format:
event: observation
data: {"type":"observation","data":{...}}

event: summary
data: {"type":"summary","data":{...}}

Settings

// 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