# MCP Memory Service Troubleshooting Guide

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

## Python 3.13 sqlite-vec Issues

### Problem: sqlite-vec Installation Fails on Python 3.13
**Error:** `Failed to install SQLite-vec: Command ... returned non-zero exit status 1`

**Cause:** sqlite-vec doesn't have pre-built wheels for Python 3.13 yet, and no source distribution is available on PyPI.

**Solutions:**

1. **Automatic Fallback (v6.13.2+)**
   - The installer now automatically tries multiple installation methods
   - It will attempt: uv pip, standard pip, source build, and GitHub installation
   - If all fail, you'll be prompted to switch to ChromaDB

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

3. **Switch to ChromaDB Backend**
   ```bash
   python install.py --storage-backend chromadb
   ```

4. **Manual Installation Attempts**
   ```bash
   # Force source build
   pip install --no-binary :all: sqlite-vec
   
   # Install from GitHub
   pip install git+https://github.com/asg017/sqlite-vec.git#subdirectory=python
   
   # Alternative: pysqlite3-binary
   pip install pysqlite3-binary
   ```

5. **Report Issue**
   - Check for updates: https://github.com/asg017/sqlite-vec/issues
   - sqlite-vec may add Python 3.13 support in future releases

## macOS SQLite Extension Issues

### Problem: `AttributeError: 'sqlite3.Connection' object has no attribute 'enable_load_extension'`
**Error:** Python 3.12 (and other versions) on macOS failing with sqlite-vec backend

**Cause:** Python on macOS is not compiled with `--enable-loadable-sqlite-extensions` by default. The system SQLite library doesn't support extensions.

**Platform:** Affects macOS (all versions), particularly with system Python

**Solutions:**

1. **Use Homebrew Python (Recommended)**
   ```bash
   # Install Homebrew Python (includes extension support)
   brew install python
   hash -r  # Refresh shell command cache
   python3 --version  # Verify Homebrew version
   
   # Reinstall MCP Memory Service
   python3 install.py
   ```

2. **Use pyenv with Extension Support**
   ```bash
   # Install pyenv
   brew install pyenv
   
   # Install Python with extension support
   PYTHON_CONFIGURE_OPTS="--enable-loadable-sqlite-extensions" \
   LDFLAGS="-L$(brew --prefix sqlite)/lib" \
   CPPFLAGS="-I$(brew --prefix sqlite)/include" \
   pyenv install 3.12.0
   
   pyenv local 3.12.0
   python install.py
   ```

3. **Switch to ChromaDB Backend**
   ```bash
   # ChromaDB doesn't require SQLite extensions
   export MCP_MEMORY_STORAGE_BACKEND=chromadb
   python install.py --storage-backend chromadb
   ```

4. **Verify Extension Support**
   ```bash
   python3 -c "
   import sqlite3
   conn = sqlite3.connect(':memory:')
   if hasattr(conn, 'enable_load_extension'):
       try:
           conn.enable_load_extension(True)
           print('✅ Extension support working')
       except Exception as e:
           print(f'❌ Extension support disabled: {e}')
   else:
       print('❌ No enable_load_extension attribute')
   "
   ```

**Why this happens:**
- Security: Extension loading disabled by default
- Compilation: System Python not built with extension support
- Library: macOS bundled SQLite lacks extension loading capability

**Detection:** The installer now automatically detects this issue and provides guidance.

## Common Installation Issues

[Content from installation.md's troubleshooting section - already well documented]

## MCP Protocol Issues

### Method Not Found Errors

If you're seeing "Method not found" errors or JSON error popups in Claude Desktop:

#### Symptoms
- "Method not found" errors in logs
- JSON error popups in Claude Desktop
- Connection issues between Claude Desktop and the memory service

#### Solution
1. Ensure you have the latest version of the MCP Memory Service
2. Verify your server implements all required MCP protocol methods:
   - resources/list
   - resources/read
   - resource_templates/list
3. Update your Claude Desktop configuration using the provided template

[Additional content from MCP_PROTOCOL_FIX.md]

## Windows-Specific Issues

[Content from WINDOWS_JSON_FIX.md and windows-specific sections]

## Performance Optimization

### Memory Issues
[Content from installation.md's performance section]

### Acceleration Issues
[Content from installation.md's acceleration section]

## Debugging Tools

[Content from installation.md's debugging section]

## Getting Help

[Content from installation.md's help section]
