Chat History Management

Relevant source files

The following files were used as context for generating this wiki page:

• app/lib/persistence/useChatHistory.ts
• app/lib/persistence/db.ts
• app/lib/persistence/fileSystem.ts
• app/lib/stores/workbench.ts
• app/components/chat/Chat.client.tsx
• app/routes/_index.tsx

The Chat History Management system in Bolt.new is a multi-layered persistence architecture designed to store, retrieve, and synchronize AI conversation data and associated project files. It leverages a combination of browser-based IndexedDB for structured message storage and the native File System Access API for local project directory synchronization.

The system ensures that conversations are preserved across sessions while maintaining a tight coupling between the chat messages and the actual files generated by the AI. This allows users to resume projects either from their browser's internal database or directly from a local folder containing the project code and history metadata.

Sources: app/lib/persistence/useChatHistory.ts, app/lib/persistence/fileSystem.ts

Architecture and Data Persistence

The persistence layer follows a hybrid approach where IndexedDB acts as the primary web-based storage, while the local file system provides a "bring your own directory" capability.

Storage Layers

1. IndexedDB (boltHistory): Stores chat sessions in a chats object store. Each entry includes the message array, metadata like descriptions, and unique identifiers.
2. Local File System: When a directory is selected, the system creates/reads a .boltnew metadata file and a {chatId}.boltnew.json file to store the session state.
3. Project Files: The system extracts file content from AI messages (using <boltAction type="file"> tags) and writes them directly to the user's selected local directory.

Sources: app/lib/persistence/db.ts:10-23, app/lib/persistence/fileSystem.ts:24-60

Data Models

The core data structure for a session is the ChatHistoryItem.

Field	Type	Description
id	string	Unique identifier for the chat session.
urlId	string (Optional)	SEO-friendly ID used in the application routing.
description	string (Optional)	A summary or title of the chat (often derived from the first artifact).
messages	Message[]	Array of AI and User messages from the ai SDK.
timestamp	string	ISO string of the last update.

Sources: app/lib/persistence/useChatHistory.ts:11-17, app/lib/persistence/db.ts:41-47

Data Flow: Initialization and Synchronization

When a user opens a chat or selects a directory, the system orchestrates a synchronization flow to ensure the UI and the workbench are up to date.

Initialization Sequence

The initialization logic prioritize the local folder content over IndexedDB to allow external modifications to be reflected in the app.

Periodic File Checks

The WorkbenchStore maintains synchronization by periodically checking for changes in the local file system that occurred outside the application.

Key Implementation Components

useChatHistory Hook

The primary interface for components to interact with the persistence layer. It provides initialMessages and a storeMessageHistory function that triggers dual-writes to both IndexedDB and the file system.

• storeMessageHistory(messages): Captures the current message state, updates the session description from the first available artifact title, and persists the data.
  Sources: app/lib/persistence/useChatHistory.ts:90-128

FileSystem Utilities

Directly interacts with the File System Access API.

• createProjectFiles(chatItem): Parses assistant messages for file actions and writes them to the disk.
• writeFile(filePath, content): Handles directory navigation and file creation within the selected handle, including subdirectories.
• selectDirectory(): Prompts the user to pick a folder and checks for existing Bolt metadata to resume sessions.
  Sources: app/lib/persistence/fileSystem.ts:16-56, app/lib/persistence/fileSystem.ts:91-131

Database Operations (db.ts)

Provides low-level wrappers for IndexedDB transactions.

• setMessages(...): A robust save operation that writes to IndexedDB and, if a handle is available, calls the FileSystem utility to update local JSON and project files.
• getMessages(...): A retrieval strategy that tries the File System first, then falls back to IndexedDB.
  Sources: app/lib/persistence/db.ts:50-80, app/lib/persistence/db.ts:82-104

Persistence Configuration

Persistence can be globally disabled via environment variables, typically for development or specific restricted environments.

Variable	Usage	Effect
VITE_DISABLE_PERSISTENCE	Boolean	If true, IndexedDB is not opened and db remains undefined.

Sources: app/lib/persistence/useChatHistory.ts:19-21

Conclusion

The Chat History Management system provides a seamless bridge between transient browser state and persistent local development. By combining the reliability of IndexedDB with the flexibility of the local File System Access API, it enables a robust development environment where AI-generated code and conversation context are always synchronized and accessible.