docs: improve first-time setup documentation and user experience (v6.13.1)

doobidoo · claude · doobidoo · commit 45facbadca68 · 2025-09-03T18:24:31.000+09:00
- Add prominent "First-Time Setup Expectations" section to README - Create comprehensive docs/first-time-setup.md guide - Enhance troubleshooting with first-time warnings section - Improve install.py with clear progress messages - Clarify that "No snapshots directory" warning is normal - Add Ubuntu 24-specific installation instructions Fixes #95: Users now understand that initial warnings are expected behavior during first run when models are being downloaded (~25MB). 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,32 @@ All notable changes to the MCP Memory Service project will be documented in this
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.13.1] - 2025-09-03
+
+### 📚 **Documentation & User Experience**
+
+#### First-Time Setup Documentation (Addresses Issue #95)
+- **Added First-Time Setup Section**: New prominent section in README.md explaining expected warnings on initial run
+- **Created Comprehensive Guide**: New `docs/first-time-setup.md` with detailed explanations of:
+  - Normal warnings vs actual errors
+  - Model download process (~25MB, 1-2 minutes)
+  - Success indicators and verification steps
+  - Ubuntu 24-specific installation instructions
+- **Enhanced Troubleshooting**: Updated `docs/troubleshooting/general.md` with first-time warnings section
+- **Improved Installer Messages**: Enhanced `install.py` with clear first-time setup expectations and progress indicators
+
+### 🐛 **Bug Fixes**
+
+#### User Experience Improvements
+- **Fixed Issue #95**: Clarified that "No snapshots directory" warning is normal on first run
+- **Addressed Confusion**: Distinguished between expected initialization warnings and actual errors
+- **Ubuntu 24 Support**: Added specific documentation for Ubuntu 24 installation issues
+
+### 📝 **Changes**
+- Added clear messaging that warnings disappear after first successful run
+- Included estimated download times and model sizes in documentation
+- Improved installer output to set proper expectations for first-time users
+
 ## [6.13.0] - 2025-08-25
 
 ### ⚡ **Major Features**
diff --git a/README.md b/README.md
@@ -38,6 +38,16 @@ docker-compose -f docker-compose.http.yml up -d
 npx -y @smithery/cli install @doobidoo/mcp-memory-service --client claude
 ```
 
+## ⚠️ First-Time Setup Expectations
+
+On your first run, you'll see some warnings that are **completely normal**:
+
+- **"WARNING: Failed to load from cache: No snapshots directory"** - The service is checking for cached models (first-time setup)
+- **"WARNING: Using TRANSFORMERS_CACHE is deprecated"** - Informational warning, doesn't affect functionality
+- **Model download in progress** - The service automatically downloads a ~25MB embedding model (takes 1-2 minutes)
+
+These warnings disappear after the first successful run. The service is working correctly! For details, see our [First-Time Setup Guide](docs/first-time-setup.md).
+
 ## 📚 Complete Documentation
 
 **👉 Visit our comprehensive [Wiki](https://github.com/doobidoo/mcp-memory-service/wiki) for detailed guides:**
diff --git a/docs/first-time-setup.md b/docs/first-time-setup.md
@@ -0,0 +1,174 @@
+# 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)
+
+## 🐧 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.
diff --git a/docs/troubleshooting/general.md b/docs/troubleshooting/general.md
@@ -2,6 +2,38 @@
 
 This guide covers common issues and their solutions when working with the MCP Memory Service.
 
+## First-Time Setup Warnings (Normal Behavior)
+
+### Expected Warnings on First Run
+
+The following warnings are **completely normal** during first-time setup:
+
+#### "No snapshots directory" Warning
+```
+WARNING:mcp_memory_service.storage.sqlite_vec:Failed to load from cache: No snapshots directory
+```
+- **Status:** ✅ Normal - Service is checking for cached models
+- **Action:** None required - Model will download automatically
+- **Duration:** Appears only on first run
+
+#### "TRANSFORMERS_CACHE deprecated" Warning  
+```
+WARNING: Using TRANSFORMERS_CACHE is deprecated
+```
+- **Status:** ✅ Normal - Informational warning from Hugging Face
+- **Action:** None required - Doesn't affect functionality
+- **Duration:** May appear on each run (can be ignored)
+
+#### Model Download Messages
+```
+Downloading model 'all-MiniLM-L6-v2'...
+```
+- **Status:** ✅ Normal - One-time model download (~25MB)
+- **Action:** Wait 1-2 minutes for download to complete
+- **Duration:** First run only
+
+For detailed information, see the [First-Time Setup Guide](../first-time-setup.md).
+
 ## Common Installation Issues
 
 [Content from installation.md's troubleshooting section - already well documented]
diff --git a/install.py b/install.py
@@ -640,7 +640,8 @@ def install_pytorch_macos_arm64():
         subprocess.check_call(cmd)
         
         # Install sentence-transformers
-        print_info("Installing sentence-transformers...")
+        print_info("Installing sentence-transformers (for embedding generation)...")
+        print_info("Note: Models will be downloaded on first use (~25MB)")
         cmd = [
             sys.executable, '-m', 'pip', 'install',
             'sentence-transformers>=2.2.2'
@@ -1236,7 +1237,8 @@ def install_package(args):
                 subprocess.check_call(cmd, env=env)
                 
                 # Install core dependencies except torch/sentence-transformers
-                print_info("Installing core dependencies except ML libraries...")
+                print_info("Installing core dependencies (without ML libraries for compatibility)...")
+                print_info("Note: First run will download embedding models automatically (~25MB)")
                 
                 # Create a list of dependencies to install
                 dependencies = [
@@ -2866,6 +2868,18 @@ def main():
     
     print_header("Installation Complete")
     
+    # First-time setup notice
+    print_info("")
+    print_info("⚠️  FIRST-TIME SETUP EXPECTATIONS:")
+    print_info("On first run, you may see these NORMAL warnings:")
+    print_info("  • 'No snapshots directory' - Model will download automatically (~25MB)")
+    print_info("  • 'TRANSFORMERS_CACHE deprecated' - Informational, doesn't affect operation")
+    print_info("  • Model download progress - One-time download (1-2 minutes)")
+    print_info("")
+    print_info("These warnings disappear after the first successful run.")
+    print_info("See docs/first-time-setup.md for details.")
+    print_info("")
+    
     # Get final storage backend info for multi-client setup determination
     if system_info["is_macos"] and system_info["is_x86"] and system_info.get("has_homebrew_pytorch"):
         final_backend = 'sqlite_vec'
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mcp-memory-service"
-version = "6.13.0"
+version = "6.13.1"
 description = "Universal MCP memory service with semantic search, multi-client support, and autonomous consolidation for Claude Desktop, VS Code, and 13+ AI applications"
 readme = "README.md"
 requires-python = ">=3.10"
diff --git a/src/mcp_memory_service/__init__.py b/src/mcp_memory_service/__init__.py
@@ -47,7 +47,7 @@ def setup_offline_mode():
 # Setup offline mode immediately when this module is imported
 setup_offline_mode()
 
-__version__ = "6.13.0"
+__version__ = "6.13.1"
 
 from .models import Memory, MemoryQueryResult
 from .storage import MemoryStorage
