Viewer UI
Relevant source files
The following files were used as context for generating this wiki page:
The Viewer UI provides a browser-based interface for exploring and managing stored memory. It runs as a local web server on 127.0.0.1 and displays sessions, summaries, and observations through a multi-tabbed dashboard. Sources: src/view.rs:1-8, assets/viewer/index.html
System Architecture
The Viewer UI follows a client-server architecture where a Rust backend serves a single-page application (SPA).
Backend Server
The backend uses standard Rust TcpListener and the httparse crate to handle HTTP requests. It manages a small JSON API that interfaces with the SQLite storage. Every API request requires a per-launch token for authentication. Sources: src/view.rs:1-8, src/view.rs:114-122
Frontend Application
The frontend is a vanilla JavaScript module that renders data using text nodes to prevent HTML injection from model-written text. It uses CSS variables for theme support and manages application state locally. Sources: assets/viewer/app.js:1-5, assets/viewer/app.css:1-15
The diagram shows the communication flow between the browser components, the Rust backend, and the database. Sources: src/view.rs, assets/viewer/app.js
Navigation and Views
The UI organizes data into four primary views accessible via navigation tabs. Sources: assets/viewer/index.html:32-37
| View | Function | API Endpoint |
|---|---|---|
| Feed | Displays a chronological list of recent entries across sessions. | /api/feed |
| Sessions | Shows a timeline of distinct interaction sessions. | /api/timeline |
| Context | Shows the exact text handed to an agent starting a new session. | /api/context |
| Stats | Displays metrics on sessions, knowledge, and provider performance. | /api/stats |
Sources: assets/viewer/app.js:203-205, src/view.rs:240-278
Security Model
The Viewer UI implements several security layers to protect sensitive memory data:
- Per-Launch Token: The server generates a random 16-byte token at startup. The UI reads this token from the URL fragment (
#t=...) and sends it in theX-Oboete-Tokenheader. Sources: src/view.rs:117-122, assets/viewer/app.js:4-5 - Host Validation: The server only accepts requests where the
Hostheader is127.0.0.1orlocalhost. Sources: src/view.rs:194-201 - Strict CSP: Content Security Policy headers block all external scripts, styles, and framing. Sources: src/view.rs:43-45
- No Request Bodies: The server rejects any request carrying a body to prevent smuggling attacks. Sources: src/view.rs:188-192
The sequence diagram illustrates the token-based authentication process for API requests. Sources: src/view.rs:210-216
Data Rendering and Interactions
Entry Cards
Observations and summaries are rendered as "Cards". Each card displays a glyph representing its kind (e.g., 🎯 for summary, ⚖ for decision). Sources: assets/viewer/app.js:52-58
Text Folding
Long text entries are folded by default to the first 8 lines or 600 characters. Users can click "Show all" to expand the full content. Sources: assets/viewer/app.js:125-139
Live Updates
The UI polls the /api/version endpoint every 3 seconds. The server returns a version string derived from the count and maximum IDs of sessions and observations. If the version changes, the UI automatically refreshes the current view. Sources: assets/viewer/app.js:338-348, src/view.rs:293-301
Deletion Workflow
The UI uses a two-click "arming" pattern for deletions. Clicking "Delete" changes the button to "Confirm delete" for five seconds before resetting. Sources: assets/viewer/app.js:98-118
API Endpoints
The Viewer backend serves the following internal JSON API:
| Endpoint | Method | Parameters | Description |
|---|---|---|---|
/api/repos | GET | None | Lists all repositories with recorded sessions. |
/api/search | GET | q, repo, limit | Performs full-text search with snippets. |
/api/doc | GET | id | Retrieves a single document by its ID. |
/api/doc | DELETE | id | Removes a document from the store. |
/api/session | DELETE | id | Deletes a session and all its associated documents. |
Sources: src/view.rs:218-283
Theme Support
The UI supports auto, light, and dark themes. The auto setting follows the system preference using the prefers-color-scheme CSS media query. Themes are enforced by setting a data-theme attribute on the document root. Sources: assets/viewer/app.css:1-35, assets/viewer/app.js:39-48
Summary: The Viewer UI is a secure, localized web interface that allows developers to browse their memory store, search across repositories, and monitor agent performance stats in real-time. Sources: src/view.rs:1-8