Chat History & Persistence
Relevant source files
The following files were used as context for generating this wiki page:
The Chat History & Persistence system provides a robust mechanism for storing, retrieving, and managing user conversations locally within the browser. By leveraging IndexedDB, the system ensures that chat sessions, including message content and associated metadata, persist across browser refreshes and sessions.
This module is central to the user experience, allowing users to revisit previous projects, resume conversations, and manage their local database of AI-powered development sessions. It integrates deeply with the Chat interface and the Workbench store to capture the state of artifacts and code modifications generated during a session.
Data Architecture & Storage
The persistence layer is built on IndexedDB, utilizing a database named boltHistory. It specifically uses an object store called chats to house all session data.
Database Schema
The chats object store uses an id as the primary key and maintains secondary indexes for efficient lookups.
| Field | Type | Description |
|---|---|---|
id | string | Primary unique identifier for the chat session. |
urlId | string | A unique, URL-friendly identifier used for routing (e.g., /chat/some-id). |
description | string | A human-readable title or description, often derived from the first artifact's title. |
messages | Message[] | An array of message objects containing the conversation content. |
timestamp | string | ISO string representing when the session was last updated. |
Sources: app/lib/persistence/db.ts:13-22, app/lib/persistence/useChatHistory.ts:11-17
Entity Relationship Diagram
The following diagram illustrates the structure of the chat history entries within the IndexedDB storage.
Core Components & Logic
useChatHistory Hook
The useChatHistory hook serves as the primary interface between the UI components and the persistence layer. It manages the initialization of chat state from the database and provides the storeMessageHistory function to persist new messages.
- Initialization: When a
mixedIdis provided (via URL parameters), the hook fetches the corresponding messages from IndexedDB and populates the globalchatIdanddescriptionatoms. - Automatic Navigation: If a new chat starts, the system automatically generates a
urlIdand updates the browser history without a full page reload to reflect the persistent session.
Sources: app/lib/persistence/useChatHistory.ts:25-95
Message Persistence Flow
The system triggers a save operation whenever the message array length increases. This ensures that every exchange between the user and the assistant is recorded.
History Management & UI
Sidebar Menu
The Menu.client.tsx component handles the display and management of the chat history list. It retrieves all entries from the database and organizes them into categories (e.g., "Today", "Yesterday") using date binning.
- Deletion: Users can delete specific chat entries. If the deleted chat is the one currently active, the application performs a hard navigation to
/to clear all internal stores. - Persistence Toggle: Persistence can be disabled via the
VITE_DISABLE_PERSISTENCEenvironment variable.
Sources: app/components/sidebar/Menu.client.tsx:47-104, app/lib/persistence/useChatHistory.ts:20
Key Functions for Database Operations
| Function | File | Description |
|---|---|---|
openDatabase | db.ts | Initializes the IndexedDB instance and creates the chats store. |
setMessages | db.ts | Performs a put operation to save or update a chat session. |
getMessages | db.ts | Retrieves a chat by either its primary id or its urlId. |
getNextId | db.ts | Calculates the next numerical ID by finding the maximum existing ID in the store. |
deleteById | db.ts | Removes a specific chat entry from the database. |
Sources: app/lib/persistence/db.ts:11-105
Integration with Workbench
The persistence system relies on the workbenchStore to provide context for the chat's metadata. When the first artifact is generated (e.g., a file creation or shell command), its ID is used to generate a unique urlId, and its title becomes the chat session's description. This creates a direct link between the code generated in the Workbench and the saved history item.
Sources: app/lib/persistence/useChatHistory.ts:70-79, app/lib/stores/workbench.ts:199-216
Summary
The Chat History & Persistence system ensures that user progress is never lost by automatically saving every message and artifact to a local IndexedDB. It manages the transition from a fresh chat to a persistent session through automatic ID generation and URL management, providing a seamless experience for managing long-term development projects within the browser.