Skip to content

first-time-setup.md

Latest commit

 

History

History
269 lines (204 loc) · 7.35 KB

first-time-setup.md

File metadata and controls

269 lines (204 loc) · 7.35 KB

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)

# 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

python install.py --storage-backend chromadb

Option 3: Manual sqlite-vec Installation

# 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)

# 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

# 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

# ChromaDB doesn't require SQLite extensions
python3 install.py --storage-backend chromadb

Verification

Check if your Python supports extensions:

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

# 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

# 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:

pip install sentence-transformers torch

Issue: Permission Denied

Solution:

# 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: 
    rm -rf ~/.mcp_memory_service
uv run memory server

✅ Verification

To verify successful setup:

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

# Or using the CLI
uv run memory health

Expected response:

{
  "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:

📝 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

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