# First-Time Setup Guide

This guide explains what to expect when running MCP Memory Service for the first time.

## 🎯 What to Expect on First Run

When you start the MCP Memory Service for the first time, you'll see several warnings and messages. **This is completely normal behavior** as the service initializes and downloads necessary components.

## 📋 Normal First-Time Warnings

### 1. Snapshots Directory Warning
```
WARNING:mcp_memory_service.storage.sqlite_vec:Failed to load from cache: No snapshots directory
```

**What it means:** 
- The service is checking for previously downloaded embedding models
- On first run, no cache exists yet, so this warning appears
- The service will automatically download the model

**This is normal:** ✅ Expected on first run

### 2. TRANSFORMERS_CACHE Warning
```
WARNING: Using TRANSFORMERS_CACHE is deprecated
```

**What it means:**
- This is an informational warning from the Hugging Face library
- It doesn't affect the service functionality
- The service handles caching internally

**This is normal:** ✅ Can be safely ignored

### 3. Model Download Progress
```
Downloading model 'all-MiniLM-L6-v2'...
```

**What it means:**
- The service is downloading the embedding model (approximately 25MB)
- This happens only once on first setup
- Download time: 1-2 minutes on average internet connection

**This is normal:** ✅ One-time download

## 🚦 Success Indicators

After successful first-time setup, you should see:

```
INFO: SQLite-vec storage initialized successfully with embedding dimension: 384
INFO: Memory service started on port 8443
INFO: Ready to accept connections
```

## 📊 First-Time Setup Timeline

| Step | Duration | What's Happening |
|------|----------|-----------------|
| 1. Service Start | Instant | Loading configuration |
| 2. Cache Check | 1-2 seconds | Checking for existing models |
| 3. Model Download | 1-2 minutes | Downloading embedding model (~25MB) |
| 4. Model Loading | 5-10 seconds | Loading model into memory |
| 5. Database Init | 2-3 seconds | Creating database structure |
| 6. Ready | - | Service is ready to use |

**Total first-time setup:** 2-3 minutes

## 🔄 Subsequent Runs

After the first successful run:
- No download warnings will appear
- Model loads from cache (5-10 seconds)
- Service starts much faster (10-15 seconds total)

## 🐍 Python 3.13 Compatibility

### Known Issues
Python 3.13 users may encounter installation issues with **sqlite-vec** due to missing pre-built wheels. The installer now includes automatic fallback methods:

1. **Automatic Retry Logic**: Tries multiple installation strategies
2. **Source Building**: Attempts to build from source if wheels unavailable
3. **GitHub Installation**: Falls back to installing directly from repository
4. **Backend Switching**: Option to switch to ChromaDB if sqlite-vec fails

### Recommended Solutions
If you encounter sqlite-vec installation failures on Python 3.13:

**Option 1: Use Python 3.12 (Recommended)**
```bash
# macOS
brew install python@3.12
python3.12 -m venv .venv
source .venv/bin/activate
python install.py

# Ubuntu/Linux
sudo apt install python3.12 python3.12-venv
python3.12 -m venv .venv
source .venv/bin/activate
python install.py
```

**Option 2: Use ChromaDB Backend**
```bash
python install.py --storage-backend chromadb
```

**Option 3: Manual sqlite-vec Installation**
```bash
# Try building from source
pip install --no-binary :all: sqlite-vec

# Or install from GitHub
pip install git+https://github.com/asg017/sqlite-vec.git#subdirectory=python
```

## 🍎 macOS SQLite Extension Issues

### Problem: `AttributeError: 'sqlite3.Connection' object has no attribute 'enable_load_extension'`

This error occurs on **macOS with system Python** because it's not compiled with SQLite extension support.

**Why this happens:**
- macOS system Python lacks `--enable-loadable-sqlite-extensions`
- The bundled SQLite library doesn't support loadable extensions
- This is a security-focused default configuration

**Solutions:**

**Option 1: Homebrew Python (Recommended)**
```bash
# Install Python via Homebrew (includes extension support)
brew install python
hash -r  # Refresh command cache
python3 --version  # Verify you're using Homebrew Python

# Then install MCP Memory Service
python3 install.py
```

**Option 2: pyenv with Extension Support**
```bash
# Install pyenv if not already installed
brew install pyenv

# Install Python with extension support
PYTHON_CONFIGURE_OPTS="--enable-loadable-sqlite-extensions" pyenv install 3.12.0
pyenv local 3.12.0

# Verify extension support
python3 -c "import sqlite3; conn=sqlite3.connect(':memory:'); conn.enable_load_extension(True); print('Extensions supported!')"
```

**Option 3: Use ChromaDB Backend**
```bash
# ChromaDB doesn't require SQLite extensions
python3 install.py --storage-backend chromadb
```

### Verification
Check if your Python supports extensions:
```bash
python3 -c "
import sqlite3
conn = sqlite3.connect(':memory:')
print('✅ Extension support available' if hasattr(conn, 'enable_load_extension') else '❌ No extension support')
"
```

## 🐧 Ubuntu/Linux Specific Notes

For Ubuntu 24 and other Linux distributions:

### Prerequisites
```bash
# System dependencies
sudo apt update
sudo apt install python3.10 python3.10-venv python3.10-dev python3-pip
sudo apt install build-essential libblas3 liblapack3 liblapack-dev libblas-dev gfortran
```

### Recommended Setup
```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install the service
python install.py

# Start the service
uv run memory server
```

## 🔧 Troubleshooting First-Time Issues

### Issue: Download Fails
**Solution:**
- Check internet connection
- Verify firewall/proxy settings
- Clear cache and retry: `rm -rf ~/.cache/huggingface`

### Issue: "No module named 'sentence_transformers'"
**Solution:**
```bash
pip install sentence-transformers torch
```

### Issue: Permission Denied
**Solution:**
```bash
# Fix permissions
chmod +x scripts/*.sh
sudo chown -R $USER:$USER ~/.mcp_memory_service/
```

### Issue: Service Doesn't Start After Download
**Solution:**
1. Check logs: `uv run memory server --debug`
2. Verify installation: `python scripts/verify_environment.py`
3. Restart with clean state: 
   ```bash
   rm -rf ~/.mcp_memory_service
   uv run memory server
   ```

## ✅ Verification

To verify successful setup:

```bash
# Check service health
curl -k https://localhost:8443/api/health

# Or using the CLI
uv run memory health
```

Expected response:
```json
{
  "status": "healthy",
  "storage_backend": "sqlite_vec",
  "model_loaded": true
}
```

## 🎉 Setup Complete!

Once you see the success indicators and the warnings have disappeared on subsequent runs, your MCP Memory Service is fully operational and ready to use!

### Next Steps:
- [Configure Claude Desktop](../README.md#claude-desktop-integration)
- [Store your first memory](../README.md#basic-usage)
- [Explore the API](https://github.com/doobidoo/mcp-memory-service/wiki)

## 📝 Notes

- The model download is a one-time operation
- Downloaded models are cached in `~/.cache/huggingface/`
- The service creates a database in `~/.mcp_memory_service/`
- All warnings shown during first-time setup are expected behavior
- If you see different errors (not warnings), check the [Troubleshooting Guide](troubleshooting/general.md)

---

Remember: **First-time warnings are normal!** The service is working correctly and setting itself up for optimal performance.