MCP Memory Service

# MCP Memory Service v8.5.3 Installation Summary **Installation Date:** 2025-10-12 **System:** Linux (Ubuntu/Debian) **Configuration:** Hybrid Backend (SQLite-vec + Cloudflare) ## 🚀 Quick Start ```bash # Start the HTTP server with hybrid backend ./start_hybrid_server.sh # Server will be available at: # - HTTP: http://localhost:8000 # - HTTPS: https://localhost:8443 (if configured) ``` ## 📋 Installation Steps Performed ### 1. Git Update ```bash git stash push # Saved local changes git pull origin main # Updated from v6.23.0 to v8.5.3 # Result: 168 files changed, 9654 insertions(+), 4124 deletions(-) ``` ### 2. Environment Configuration Created `.env` file with hybrid backend settings: ```bash # Core Configuration MCP_CONSOLIDATION_ENABLED=true MCP_MEMORY_STORAGE_BACKEND=hybrid # Cloudflare Credentials CLOUDFLARE_API_TOKEN=Y9qwW1rYkwiE63iWYASxnzfTQlIn-mtwCihRTwZa CLOUDFLARE_ACCOUNT_ID=be0e35a26715043ef8df90253268c33f CLOUDFLARE_D1_DATABASE_ID=f745e9b4-ba8e-4d47-b38f-12af91060d5a CLOUDFLARE_VECTORIZE_INDEX=mcp-memory-index # Hybrid Backend Settings MCP_HYBRID_SYNC_INTERVAL=300 # Sync every 5 minutes MCP_HYBRID_BATCH_SIZE=50 # Process 50 items per sync MCP_HYBRID_SYNC_ON_STARTUP=true # Initial sync on startup # HTTP Server Configuration MCP_HTTP_ENABLED=true MCP_HTTPS_ENABLED=true MCP_OAUTH_ENABLED=false # Disabled for development ``` ### 3. Package Installation ```bash python scripts/installation/install.py \ --storage-backend sqlite_vec \ --with-ml \ --install-natural-triggers # Installed Components: # - MCP Memory Service v8.5.3 # - PyTorch 2.7.1+cpu # - sentence-transformers 5.0.0 # - SQLite-vec extension # - authlib, cryptography (OAuth support) # - Natural Memory Triggers v8.5.3 (installed to ~/.claude/hooks/) ``` **Note:** `--storage-backend sqlite_vec` is used because the installer doesn't have a "hybrid" option. The hybrid backend is activated via the `MCP_MEMORY_STORAGE_BACKEND=hybrid` environment variable in `.env`. ### 4. Server Startup Script Created `start_hybrid_server.sh`: ```bash #!/bin/bash # Start MCP Memory Service HTTP server with hybrid backend # Load and export environment variables from .env set -a # automatically export all variables source .env set +a # turn off automatic export # Start the server python scripts/server/run_http_server.py ``` Made executable: ```bash chmod +x start_hybrid_server.sh ``` ## 🎯 Key Features in v8.5.3 ### Natural Memory Triggers v8.5.3 - **85%+ Trigger Accuracy**: Intelligent automatic memory retrieval - **Dynamic Weight Adjustment**: Auto-calibration for stale memory detection - **Critical Bug Fixes**: - Empty semantic query handling - Time-based search patterns - 4 missing `await` keywords in hybrid.py - Port consistency (8000 vs 8443) ### Hybrid Backend Architecture - **Primary Storage**: SQLite-vec (local, ~5ms read/write) - **Secondary Storage**: Cloudflare (cloud persistence) - **Background Sync**: Automatic bidirectional sync every 5 minutes - **Graceful Offline**: Works without internet, syncs when available - **Zero Latency**: All user operations hit local SQLite ### Embedding Model - **Model**: all-MiniLM-L6-v2 - **Dimension**: 384 - **Device**: CPU (PyTorch 2.7.1+cpu) ## 📊 Initial Sync Status On first startup, the system performed an initial sync: - **Cloudflare Memories**: 1,426 - **Local Memories**: 25 - **To Sync**: 1,401 memories from Cloudflare → Local SQLite ## 🔧 Troubleshooting ### Check Server Status ```bash # View server logs tail -f /tmp/mcp-hybrid-final.log # Check process ps aux | grep run_http_server.py # Test health endpoint curl http://localhost:8000/api/health ``` ### Common Issues 1. **Server shows sqlite_vec instead of hybrid** - Verify `.env` file exists in project root - Ensure `start_hybrid_server.sh` sources `.env` correctly - Check logs for "Using storage backend: hybrid" 2. **OAuth errors** - Set `MCP_OAUTH_ENABLED=false` in `.env` for development - Restart server after changes 3. **Cloudflare connection issues** - Verify API token and credentials in `.env` - Check internet connectivity - System will fall back to SQLite-only mode 4. **Memory storage from Claude Code fails** - Check hostname resolution for MCP server - Verify Claude Code MCP configuration - Check logs for connection errors ## 🔗 API Endpoints - **Health Check**: `http://localhost:8000/api/health` - **Store Memory**: `POST http://localhost:8000/api/memories` - **Search Memories**: `GET http://localhost:8000/api/memories?query=...` - **Dashboard**: `http://localhost:8000/` (Web UI) ## 📚 Additional Resources - **Documentation**: See `CLAUDE.md` for comprehensive guide - **Changelog**: See `CHANGELOG.md` for v8.5.3 changes - **Wiki**: https://github.com/doobidoo/mcp-memory-service/wiki - **Configuration Guide**: `docs/quick-setup-cloudflare-dual-environment.md` ## ✅ Installation Verification Run these commands to verify the installation: ```bash # 1. Check backend configuration curl http://localhost:8000/api/health | jq '.storage_backend' # Should return: "hybrid" # 2. Verify Cloudflare connection curl http://localhost:8000/api/health | jq '.cloudflare' # Should return: {"status": "connected"} # 3. Check sync status curl http://localhost:8000/api/sync/status | jq # Should show sync statistics # 4. Test memory storage curl -X POST http://localhost:8000/api/memories \ -H "Content-Type: application/json" \ -d '{"content": "Test memory from v8.5.3 installation"}' ``` ## 🎉 Success Criteria ✅ Package updated to v8.5.3 ✅ Hybrid backend configured with Cloudflare credentials ✅ HTTP server running with proper .env loading ✅ Natural Memory Triggers v8.5.3 installed ✅ Initial sync started (1,401 memories) ✅ OAuth disabled for development ✅ Reusable startup script created ## 📝 Notes - **Installation completed**: 2025-10-12 - **Server PID**: 1265948 (check `/tmp/mcp-hybrid-final.pid`) - **Log file**: `/tmp/mcp-hybrid-final.log` - **Configuration**: Synchronized with macOS installation using same Cloudflare credentials ## 🔄 Next Steps (Optional) 1. Monitor initial sync completion 2. Test all API endpoints 3. Verify Natural Memory Triggers functionality 4. Set up systemd service for production (if needed) 5. Fix MCP hostname resolution for Claude Code memory storage