Web Viewer UI
Relevant source files
The following files were used as context for generating this wiki page:
The Web Viewer UI is a React-based interface that provides a real-time memory stream and visualization for the claude-mem project. It allows users to browse persistent memory, including tool usage observations, user prompts, and session summaries, providing transparency into the context injected into AI sessions.
The interface is hosted by the Worker Service on port 37777 and serves as a headless extension for the open-source core, enabling users to monitor their project history and AI interactions through a browser-based feed.
Sources: CLAUDE.md:19, README.md:104, src/services/worker/README.md:12
Architecture and Integration
The Web Viewer UI follows a decoupled architecture where the front-end React application communicates with the Worker Service via a set of dedicated HTTP endpoints. The build process uses esbuild to bundle the React components from src/ui/viewer/index.tsx into a single JavaScript file, which is then embedded into the viewer.html template.
Data Flow Architecture
The UI relies on three primary data acquisition methods: initial page load for static assets, paginated HTTP requests for historical data, and a Server-Sent Events (SSE) stream for real-time updates.
The diagram shows the interaction between the React UI and the Worker Service route handlers.
Sources: src/services/worker/README.md:25-50, scripts/build-viewer.js:15-25
Core Components and Layout
The UI utilizes a responsive layout designed for both desktop and mobile devices. Key layout elements include:
- Main Column: Contains the primary feed of memory cards.
- Sidebar: Houses settings, project filters, and database statistics.
- Header: Features the
claude-memlogomark, connection status indicators, and global theme toggles.
Sources: src/ui/viewer-template.html:260-310, plugin/ui/viewer.html:260-310
Memory Feed and Visualization
The central feature of the UI is the "Feed," which renders different types of memory entries as distinct cards. Each card is styled according to its data type (e.g., Prompt, Observation, or Summary).
Card Types
The UI distinguishes between three primary card types through color coding and badges:
| Card Type | CSS Class | Purpose | Style Reference |
|---|---|---|---|
| Prompt | .prompt-card | User-submitted prompts | Purple badge/border |
| Observation | .observation-card | Captured tool usage or code changes | Blue badge/border |
| Summary | .summary-card | AI-generated session progress summaries | Yellow/Gold badge/border |
Sources: src/ui/viewer-template.html:1010-1045, plugin/ui/viewer.html:1010-1045
Summary Card Structure
Summary cards provide a high-level view of session progress, organized into specific editorial sections.
The diagram illustrates the hierarchical data structure of a session summary card.
Sources: src/ui/viewer-template.html:640-690, plugin/ui/viewer.html:640-690
Worker Service API Endpoints
The Web Viewer UI interacts with the following specific endpoints exposed by the Worker Service to populate its views:
Viewer and Stream Endpoints
| Endpoint | Method | Description |
|---|---|---|
/ | GET | Serves the main viewer.html UI |
/health | GET | Connection health check for the UI status dot |
/stream | GET | SSE stream for live observation updates |
Data Retrieval Endpoints
| Endpoint | Method | Description |
|---|---|---|
/observations | GET | Paginated list of tool observations |
/summaries | GET | Paginated list of session summaries |
/prompts | GET | Paginated list of user prompts |
/stats | GET | Database statistics (total counts, disk usage) |
/projects | GET | List of all active projects for the filter dropdown |
Sources: src/services/worker/README.md:34-60
Context and Settings Management
The UI includes a Context Settings Modal that allows users to configure how memory is injected into AI sessions. This feature provides a live preview of the context template and controls for filtering memory types.
Configuration Options
Users can modify settings that affect both the UI and the underlying memory system:
- Theme: Toggle between Light and Dark modes.
- Project Filter: Scope the feed to specific repositories or projects.
- Context Injection: Control the number of observations and summaries injected per session.
- MCP Toggling: Enable or disable the Model Context Protocol search server.
Sources: src/ui/viewer-template.html:920-960, plugin/ui/viewer.html:920-960, src/services/worker/README.md:95-103
Theming System
The UI uses CSS variables to manage themes, supporting system-level preferences and manual overrides.
/* Example Variable Usage */
:root, [data-theme="light"] {
--color-bg-primary: #ffffff;
--color-bg-summary: #fffbf0;
--color-accent-primary: #0969da;
}
[data-theme="dark"] {
--color-bg-primary: #1a1916;
--color-bg-summary: #2a2724;
--color-accent-primary: #58a6ff;
}
Sources: src/ui/viewer-template.html:20-100, plugin/ui/viewer.html:20-100
Conclusion
The Web Viewer UI is the primary observational layer of the claude-mem system. By centralizing real-time data from SQLite and Chroma via the Worker Service, it enables developers to visualize the "memory stream" of their AI interactions. Its architecture ensures a clean separation between the persistent storage logic and the presentation layer, facilitating both local development monitoring and pro-feature extensions.
Sources: CLAUDE.md:19, src/services/worker/README.md:12