MCP Memory Service

# Quick Setup: Cloudflare Backend for Claude Desktop + Claude Code This guide provides streamlined instructions to configure Cloudflare backend for both Claude Desktop and Claude Code simultaneously. ## 🎯 Overview This setup ensures both environments use the same Cloudflare backend for consistent memory storage across Claude Desktop and Claude Code. **Expected Result:** - Claude Desktop: ✅ Cloudflare backend with 1000+ memories - Claude Code: ✅ Cloudflare backend with same memories - Health checks show: `"backend": "cloudflare"` and `"storage_type": "CloudflareStorage"` ## ⚡ Quick Setup (5 minutes) ### Step 1: Prepare Cloudflare Resources If you don't have Cloudflare resources yet: ```bash # Install wrangler CLI npm install -g wrangler # Login and create resources wrangler login wrangler vectorize create mcp-memory-index --dimensions=768 --metric=cosine wrangler d1 create mcp-memory-db # Note the database ID from output ``` ### Step 2: Create Environment Configuration Create `.env` file in the project root: ```bash cd C:/REPOSITORIES/mcp-memory-service # Create .env file with your Cloudflare credentials cat > .env << 'EOF' # MCP Memory Service Environment Configuration MCP_MEMORY_STORAGE_BACKEND=cloudflare # Cloudflare D1 Database Configuration CLOUDFLARE_API_TOKEN=your-api-token-here CLOUDFLARE_ACCOUNT_ID=your-account-id-here CLOUDFLARE_D1_DATABASE_ID=your-d1-database-id-here CLOUDFLARE_VECTORIZE_INDEX=mcp-memory-index # Backup paths (for fallback) MCP_MEMORY_BACKUPS_PATH=C:\Users\your-username\AppData\Local\mcp-memory\backups MCP_MEMORY_SQLITE_PATH=C:\Users\your-username\AppData\Local\mcp-memory\backups\sqlite_vec.db EOF ``` ### Step 3: Configure Claude Desktop Update `~/.claude.json` (or `%APPDATA%\Claude\claude_desktop_config.json` on Windows): ```json { "mcpServers": { "memory": { "command": "python", "args": ["-m", "mcp_memory_service.server"], "cwd": "C:/REPOSITORIES/mcp-memory-service", "env": { "MCP_MEMORY_STORAGE_BACKEND": "cloudflare", "CLOUDFLARE_API_TOKEN": "your-api-token-here", "CLOUDFLARE_ACCOUNT_ID": "your-account-id-here", "CLOUDFLARE_D1_DATABASE_ID": "your-d1-database-id-here", "CLOUDFLARE_VECTORIZE_INDEX": "mcp-memory-index", "MCP_MEMORY_BACKUPS_PATH": "C:\\Users\\your-username\\AppData\\Local\\mcp-memory\\backups", "MCP_MEMORY_SQLITE_PATH": "C:\\Users\\your-username\\AppData\\Local\\mcp-memory\\backups\\sqlite_vec.db" } } } } ``` ### Step 4: Configure Claude Code ```bash # Navigate to project directory cd C:/REPOSITORIES/mcp-memory-service # Add memory server with explicit environment variables claude mcp add memory python \ -e MCP_MEMORY_STORAGE_BACKEND=cloudflare \ -e CLOUDFLARE_API_TOKEN=your-api-token-here \ -e CLOUDFLARE_ACCOUNT_ID=your-account-id-here \ -e CLOUDFLARE_D1_DATABASE_ID=your-d1-database-id-here \ -e CLOUDFLARE_VECTORIZE_INDEX=mcp-memory-index \ -e MCP_MEMORY_BACKUPS_PATH="C:\Users\your-username\AppData\Local\mcp-memory\backups" \ -e MCP_MEMORY_SQLITE_PATH="C:\Users\your-username\AppData\Local\mcp-memory\backups\sqlite_vec.db" \ -- -m mcp_memory_service.server ``` ### Step 5: Verify Configuration **Test Claude Desktop:** 1. Restart Claude Desktop 2. Open a new conversation 3. Ask: "Check memory health" 4. Should show: `"backend": "cloudflare"` and `"storage_type": "CloudflareStorage"` **Test Claude Code:** ```bash # Check MCP server status claude mcp list # Should show: memory: python -m mcp_memory_service.server - ✓ Connected ``` ## 🔧 Configuration Templates ### Claude Desktop Template (`claude_desktop_config.json`) ```json { "mcpServers": { "memory": { "command": "python", "args": ["-m", "mcp_memory_service.server"], "cwd": "C:/REPOSITORIES/mcp-memory-service", "env": { "MCP_MEMORY_STORAGE_BACKEND": "cloudflare", "CLOUDFLARE_API_TOKEN": "YOUR_TOKEN_HERE", "CLOUDFLARE_ACCOUNT_ID": "YOUR_ACCOUNT_ID_HERE", "CLOUDFLARE_D1_DATABASE_ID": "YOUR_D1_DATABASE_ID_HERE", "CLOUDFLARE_VECTORIZE_INDEX": "mcp-memory-index", "MCP_MEMORY_BACKUPS_PATH": "C:\\Users\\USERNAME\\AppData\\Local\\mcp-memory\\backups", "MCP_MEMORY_SQLITE_PATH": "C:\\Users\\USERNAME\\AppData\\Local\\mcp-memory\\backups\\sqlite_vec.db" } } } } ``` ### Project Environment Template (`.env`) ```bash # Storage Backend Configuration MCP_MEMORY_STORAGE_BACKEND=cloudflare # Required Cloudflare Settings CLOUDFLARE_API_TOKEN=YOUR_TOKEN_HERE CLOUDFLARE_ACCOUNT_ID=YOUR_ACCOUNT_ID_HERE CLOUDFLARE_D1_DATABASE_ID=YOUR_D1_DATABASE_ID_HERE CLOUDFLARE_VECTORIZE_INDEX=mcp-memory-index # Optional Settings CLOUDFLARE_R2_BUCKET=mcp-memory-content CLOUDFLARE_EMBEDDING_MODEL=@cf/baai/bge-base-en-v1.5 CLOUDFLARE_LARGE_CONTENT_THRESHOLD=1048576 CLOUDFLARE_MAX_RETRIES=3 CLOUDFLARE_BASE_DELAY=1.0 # Backup Configuration MCP_MEMORY_BACKUPS_PATH=C:\Users\USERNAME\AppData\Local\mcp-memory\backups MCP_MEMORY_SQLITE_PATH=C:\Users\USERNAME\AppData\Local\mcp-memory\backups\sqlite_vec.db # Logging LOG_LEVEL=INFO ``` ## ✅ Validation Commands ### Quick Health Check ```bash # Test configuration loading cd C:/REPOSITORIES/mcp-memory-service python -c " from src.mcp_memory_service.config import STORAGE_BACKEND, CLOUDFLARE_API_TOKEN print(f'Backend: {STORAGE_BACKEND}') print(f'Token set: {bool(CLOUDFLARE_API_TOKEN)}') " # Test server initialization python scripts/validation/diagnose_backend_config.py ``` ### Expected Health Check Results **Cloudflare Backend (Correct):** ```json { "validation": { "status": "healthy", "message": "Cloudflare storage validation successful" }, "statistics": { "backend": "cloudflare", "storage_backend": "cloudflare", "total_memories": 1073, "vectorize_index": "mcp-memory-index", "d1_database_id": "f745e9b4-ba8e-4d47-b38f-12af91060d5a" }, "performance": { "server": { "storage_type": "CloudflareStorage" } } } ``` **SQLite-vec Fallback (Incorrect):** ```json { "statistics": { "backend": "sqlite-vec", "storage_backend": "sqlite-vec" }, "performance": { "server": { "storage_type": "SqliteVecMemoryStorage" } } } ``` ## 🚨 Troubleshooting ### Issue: Health Check Shows SQLite-vec Instead of Cloudflare **Root Cause:** Environment variables not loading properly in execution context. **Solutions:** 1. **Claude Desktop:** - Ensure `cwd` is set to project directory - Use explicit `env` variables in MCP configuration - Restart Claude Desktop after config changes 2. **Claude Code:** - Use explicit `-e` environment variables in `claude mcp add` - Ensure command runs from project directory - Remove and re-add memory server to pick up changes 3. **Both Environments:** - Verify `.env` file exists and contains correct values - Check API token permissions (Vectorize:Edit, D1:Edit, Workers AI:Read) - Test Cloudflare connectivity manually ### Issue: "Missing required environment variables" ```bash # Check if variables are being loaded cd C:/REPOSITORIES/mcp-memory-service python -c " import os from dotenv import load_dotenv load_dotenv('.env') print('CLOUDFLARE_API_TOKEN:', 'SET' if os.getenv('CLOUDFLARE_API_TOKEN') else 'NOT SET') print('CLOUDFLARE_ACCOUNT_ID:', os.getenv('CLOUDFLARE_ACCOUNT_ID', 'NOT SET')) " ``` ### Issue: Different Memory Counts Between Environments This indicates environments are using different backends: - **Same count (e.g., 1073):** Both using Cloudflare ✅ - **Different counts:** One using SQLite-vec fallback ❌ **Fix:** Follow troubleshooting steps above to ensure both use Cloudflare. ### Issue: Connection Failed or Authentication Errors 1. **Verify API Token:** ```bash curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` 2. **Check Resource IDs:** ```bash # List Vectorize indexes curl -X GET "https://api.cloudflare.com/client/v4/accounts/YOUR_ACCOUNT_ID/vectorize/v2/indexes" \ -H "Authorization: Bearer YOUR_API_TOKEN" # List D1 databases curl -X GET "https://api.cloudflare.com/client/v4/accounts/YOUR_ACCOUNT_ID/d1/database" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` ## 🔄 Migration from SQLite-vec If you have existing memories in SQLite-vec: ```bash # Export existing memories python scripts/export_sqlite_vec.py --output cloudflare_export.json # Switch to Cloudflare (follow setup above) # Import to Cloudflare python scripts/import_to_cloudflare.py --input cloudflare_export.json ``` ## 📝 Configuration Management ### Single Source of Truth - **Global Config:** `~/.claude.json` (Claude Desktop) - authoritative - **Project Config:** `.env` file (development) - for local development - **Avoid:** Multiple conflicting configurations ### Environment Variable Precedence 1. Explicit MCP server `env` variables (highest priority) 2. System environment variables 3. `.env` file variables 4. Default values (lowest priority) ## 🎯 Success Criteria Both Claude Desktop and Claude Code should show: ✅ **Health Check:** `"backend": "cloudflare"` ✅ **Storage Type:** `"CloudflareStorage"` ✅ **Memory Count:** Same number across environments ✅ **Database ID:** Same Cloudflare D1 database ID ✅ **Index:** Same Vectorize index name When successful, memories will be synchronized across both environments automatically!