RAG Assistant stores data in different locations depending on how you're running it:

When using the desktop application, data is stored in two locations:

1. Application Data (Electron-managed, platform-specific):

   • macOS: ~/Library/Application Support/RAG Assistant/
   • Windows: %APPDATA%\RAG Assistant\
   • Linux: ~/.config/rag-assistant/ (venv only)
   • Stores: Window state, app preferences, temporary files

2. Profile Data (Backend-managed, same on all platforms):

   • All Platforms: ~/.zotero-llm/
   • Stores: API keys, settings, chat history, vector databases
   • This location is consistent across all platforms for the backend

When running from source code, only ~/.zotero-llm/ is used for all user data.

The following sensitive files and directories are excluded from version control (see .gitignore):

• ~/.zotero-llm/ - Your entire profile directory containing:
  • API keys for LLM providers
  • Local file paths specific to your machine
  • Chat history and sessions
  • Vector database indices
  • Profile settings

• .env - Contains environment-specific configuration
• settings.json - User settings with API credentials
• active_profile.json - Current active profile

• vector_db/ - ChromaDB embeddings database
• *.sqlite3 - Local database files
• __pycache__/ - Python bytecode cache

~/.zotero-llm/
 active_profile.json          # Current active profile
 profiles/
     default/                 # Profile ID
         profile.json         # Profile metadata
         settings.json        # Settings with API keys
         sessions.json        # Chat history
         chroma/             # Vector database

API Keys and Credentials (~/.zotero-llm/profiles/{profile}/settings.json):

• OpenAI API key
• Anthropic API key
• Mistral API key
• Google API key
• Groq API key
• OpenRouter API key
• Ollama base URL

Local Paths (profile settings):

• Zotero database path (e.g., /Users/you/Zotero/zotero.sqlite)
• ChromaDB storage path
• PDF attachment locations

Personal Data (~/.zotero-llm/profiles/{profile}/sessions.json):

• Chat conversations
• Research queries
• Generated summaries
• Session metadata

Vector Embeddings (~/.zotero-llm/profiles/{profile}/chroma/):

• Embedded PDF content
• Metadata indices
• BM25 indices

./setup.sh

This script:

1. Creates Python virtual environment
2. Installs all dependencies
3. Creates .env from template
4. Initializes profile directory structure
5. Creates default settings files

1. Create environment file:

   cp .env.example .env

2. Edit .env with your paths:

   ZOTERO_DB_PATH=/path/to/your/Zotero/zotero.sqlite

3. Initialize profile directory:

   mkdir -p ~/.zotero-llm/profiles/default/chroma

4. The application will auto-generate:

   • Default settings on first run
   • Profile metadata
   • Active profile marker

5. Configure API keys via Settings UI after starting the app

1. Never commit:

   • .env files with real values
   • settings.json with API keys
   • Any file from ~/.zotero-llm/
   • Personal Zotero database paths

2. Always commit:

   • .env.example with placeholder values
   • setup.sh initialization script
   • Documentation about setup process
   • Default configuration templates

3. Before committing:

   git status  # Check what's staged
   git diff    # Review changes
   # Verify no sensitive data is included

1. Backup your data:

   # Desktop app users: Backup profile data (chat history, settings, vector DB)
   tar -czf zotero-llm-backup.tar.gz ~/.zotero-llm/
   
   # Optional: Backup app preferences (if needed)
   # macOS: ~/Library/Application Support/RAG Assistant/
   # Windows: %APPDATA%\RAG Assistant\
   # Linux: ~/.config/rag-assistant/

2. Restore from backup:

   tar -xzf zotero-llm-backup.tar.gz -C ~/

3. Switch machines:

   • Desktop app: Just install the app on new machine, reconfigure settings
   • Don't need to copy .zotero-llm directory (profiles will be recreated)
   • Reconfigure API keys via Settings UI
   • Re-index library (database will be rebuilt)
   • Source users: Use setup.sh on new machine

4. Secure your API keys:

   • Never share screenshots of Settings page
   • Don't commit or share .env or settings.json
   • Rotate keys if accidentally exposed

• All data stays on your device
• No cloud sync by default
• No telemetry or tracking
• API calls go directly to provider (not through our servers)

• Each profile has separate:
  • Settings and API keys
  • Chat history
  • Vector database
  • Zotero library connection

• Delete profiles to remove all associated data
• Export chat history as JSON or Markdown
• Clear vector database without losing settings

• Source code (via Git)
• Documentation
• Feature requests and bug reports
• General configuration templates

• Your .zotero-llm/ directory
• API keys
• .env file with real values
• Settings JSON with credentials
• Chat history or sessions
• Vector database files

If working on a team:

1. Each developer has their own .zotero-llm/ directory
2. Share code via Git (sensitive data excluded)
3. Use .env.example to document required variables
4. Test with personal/test API keys
5. Never commit real credentials

# Reinitialize profile structure
./setup.sh

• Check Settings UI and add API keys
• Or set in .env file
• Verify ~/.zotero-llm/profiles/default/settings.json exists

# Reinstall dependencies if needed
source .venv/bin/activate
pip install -r requirements.txt
cd frontend && npm install

# Your settings are preserved (not in Git)
# No need to reconfigure

# Desktop app users: Remove profile data
rm -rf ~/.zotero-llm/
# App will recreate profiles on next launch
# Reconfigure settings via UI

# Source/development users: Full reset
rm -rf ~/.zotero-llm/
./setup.sh
# Reconfigure settings via UI

1. API Key Management:

   • Use environment-specific keys (dev/prod)
   • Rotate keys periodically
   • Monitor API usage for anomalies

2. File Permissions:

   # Restrict profile directory access
   chmod 700 ~/.zotero-llm/

3. Git Safety:

   # Verify .gitignore is working
   git status --ignored
   
   # Check for accidentally tracked sensitive files
   git ls-files | grep -E '\.env$|settings\.json|\.zotero-llm'

4. Before Publishing:

   # Search for potential secrets in history
   git log -p | grep -i "api.key\|password\|secret"

• Check docs/profile_system_guide.md for profile details
• See docs/multi_provider_system.md for provider configuration
• Open an issue for security concerns