Skip to content

DATA_STORAGE.md

Latest commit

 

History

History
216 lines (149 loc) · 5.42 KB

DATA_STORAGE.md

File metadata and controls

216 lines (149 loc) · 5.42 KB

Chorus Data Storage Locations

This document describes where Chorus stores all application data on macOS.

Storage Location

All Chorus data is stored in the Application Support directory:

~/Library/Application Support/

Instance Types

Chorus can have multiple instances:

Production Instance

~/Library/Application Support/sh.chorus.app/

Development Instances

~/Library/Application Support/sh.chorus.app.dev.<instance-name>/

For example, the chicago development instance stores data at:

~/Library/Application Support/sh.chorus.app.dev.chicago/

Data Files and Directories

Each instance directory contains:

1. chats.db (SQLite Database)

  • Most important file - contains all your data
  • Stores:
    • All chat messages and conversation history
    • Projects and their metadata
    • Model configurations
    • API keys (encrypted in auth.dat, referenced in DB)
    • User preferences and settings
    • Attachments metadata
    • Cost tracking data
    • MCP server configurations
  • Size: Can be 60MB+ for active users
  • Location: chats.db in the instance directory

2. settings (Settings Store)

  • Application settings and preferences
  • Format: Tauri store format (JSON-like)
  • Contains:
    • Theme preferences (light/dark mode)
    • Quick chat settings
    • Keyboard shortcuts
    • UI preferences

3. settings.json (Legacy Settings)

  • Older settings format
  • May contain minimal data or be deprecated

4. auth.dat (Authentication Data)

  • Encrypted authentication token
  • Used for Chorus account login and backend communication
  • Small file (~64 bytes)

5. uploads/ (Uploaded Files Directory)

  • User-uploaded attachments
  • Files attached to chat messages
  • Includes:
    • Images (PNG, JPG, etc.)
    • PDFs
    • Text files
    • Other document types
  • Each file is stored with a unique identifier

6. generated_images/ (Generated Images Directory)

  • Images generated by AI models
  • May not exist if no images have been generated
  • Referenced by chat messages in the database

7. icons/ (Icon Cache)

  • Cached icons for UI elements
  • Typically minimal data
  • Can be regenerated if deleted

Finding Your Data

To see all Chorus instances on your system:

find ~/Library/Application\ Support/ -maxdepth 1 -type d -name "sh.chorus.app*"

To see the contents of your production instance:

ls -lh ~/Library/Application\ Support/sh.chorus.app/

Backup Your Data

Using the Backup Script

We've provided a comprehensive backup script at script/backup-chorus-data.sh:

# Backup production instance
./script/backup-chorus-data.sh prod

# Backup current development instance
./script/backup-chorus-data.sh dev

# Backup all instances
./script/backup-chorus-data.sh all

# Backup to specific directory
./script/backup-chorus-data.sh prod ~/Desktop/chorus-backups

Manual Backup

To manually backup, simply copy the entire instance directory:

# Backup production
cp -r ~/Library/Application\ Support/sh.chorus.app ~/Desktop/chorus-backup-$(date +%Y%m%d)

# Backup dev instance (chicago)
cp -r ~/Library/Application\ Support/sh.chorus.app.dev.chicago ~/Desktop/chorus-dev-backup-$(date +%Y%m%d)

Restore from Backup

  1. Close Chorus completely (Quit the application)
  2. Extract or copy your backup files
  3. Replace the instance directory: 
    # For production
rm -rf ~/Library/Application\ Support/sh.chorus.app
cp -r /path/to/backup ~/Library/Application\ Support/sh.chorus.app
  4. Restart Chorus

Important Notes

Before Database Migrations

Always backup before running database migrations!

The cost tracking feature adds new database migrations that modify the schema. While migrations are designed to be safe, it's always best to have a backup:

./script/backup-chorus-data.sh prod ~/Desktop/pre-migration-backup

API Keys Security

  • API keys are stored encrypted in the database
  • The auth.dat file contains sensitive authentication data
  • Keep backups secure - they contain your API keys and authentication tokens
  • Don't share backups publicly

Database Size

  • The chats.db file can grow large with extensive chat history
  • Regular backups are recommended, especially before updates
  • You can check database size with: 
    du -h ~/Library/Application\ Support/sh.chorus.app/chats.db

Development vs Production

  • Development instances are completely isolated from production
  • Each has its own database, settings, and files
  • Backing up one doesn't affect the other
  • You can safely delete dev instances without affecting production

Data Not Stored Locally

The following data is NOT stored locally:

  • Account information (stored on app.chorus.sh backend)
  • Billing information (stored on app.chorus.sh backend)
  • Model provider API responses (not cached, fetched real-time)

Cleanup

To completely remove Chorus data:

# Remove specific instance
rm -rf ~/Library/Application\ Support/sh.chorus.app.dev.chicago

# Remove all Chorus data (WARNING: This deletes everything!)
rm -rf ~/Library/Application\ Support/sh.chorus.app*

Platform Differences

This document is for macOS. On other platforms:

  • Windows: %APPDATA%\sh.chorus.app\
  • Linux: ~/.local/share/sh.chorus.app/ or $XDG_DATA_HOME/sh.chorus.app/