MCP Memory Service

# Storage Backends - Complete Reference ## Backend Comparison | Backend | Performance | Use Case | Installation | |---------|-------------|----------|--------------| | **Hybrid** ⚡ | **Fast (5ms read)** | **🌟 Production (Recommended)** | `install.py --storage-backend hybrid` | | **Cloudflare** ☁️ | Network dependent | Cloud-only deployment | `install.py --storage-backend cloudflare` | | **SQLite-Vec** 🪶 | Fast (5ms read) | Development, single-user local | `install.py --storage-backend sqlite_vec` | ## Hybrid Backend (v6.21.0+) - RECOMMENDED The **Hybrid backend** provides the best of both worlds - **SQLite-vec speed with Cloudflare persistence**. ### Configuration ```bash # Enable hybrid backend export MCP_MEMORY_STORAGE_BACKEND=hybrid # Hybrid-specific configuration export MCP_HYBRID_SYNC_INTERVAL=300 # Background sync every 5 minutes export MCP_HYBRID_BATCH_SIZE=50 # Sync 50 operations at a time export MCP_HYBRID_SYNC_ON_STARTUP=true # Initial sync on startup # Drift detection configuration (v8.25.0+) export MCP_HYBRID_SYNC_UPDATES=true # Enable metadata sync (default: true) export MCP_HYBRID_DRIFT_CHECK_INTERVAL=3600 # Seconds between drift checks (default: 1 hour) export MCP_HYBRID_DRIFT_BATCH_SIZE=100 # Memories to check per scan (default: 100) # Requires Cloudflare credentials (same as cloudflare backend) export CLOUDFLARE_API_TOKEN="your-token" export CLOUDFLARE_ACCOUNT_ID="your-account" export CLOUDFLARE_D1_DATABASE_ID="your-d1-id" export CLOUDFLARE_VECTORIZE_INDEX="mcp-memory-index" ``` ### Key Benefits - ✅ **5ms read/write performance** (SQLite-vec speed) - ✅ **Zero user-facing latency** - Cloud sync happens in background - ✅ **Multi-device synchronization** - Access memories everywhere - ✅ **Graceful offline operation** - Works without internet, syncs when available - ✅ **Automatic failover** - Falls back to SQLite-only if Cloudflare unavailable - ✅ **Drift detection (v8.25.0+)** - Automatic metadata sync prevents data loss ### Architecture - **Primary Storage**: SQLite-vec (all user operations) - **Secondary Storage**: Cloudflare (background sync) - **Background Service**: Async queue with retry logic and health monitoring ## Database Lock Prevention (v8.9.0+) **CRITICAL**: After adding `MCP_MEMORY_SQLITE_PRAGMAS` to `.env`, you **MUST restart all servers**: ```bash # Add to .env MCP_MEMORY_SQLITE_PRAGMAS=busy_timeout=15000,cache_size=20000 # Restart HTTP server kill <PID> uv run python scripts/server/run_http_server.py # Restart MCP servers # Use /mcp in Claude Code to reconnect, or restart Claude Desktop # Verify # Check logs for: "Custom pragma from env: busy_timeout=15000" ``` **Why restart is required**: SQLite pragmas are **per-connection**, not global. Long-running servers (days/weeks old) won't pick up new `.env` settings automatically. **Symptoms of missing pragmas:** - "database is locked" errors despite v8.9.0+ installation - `PRAGMA busy_timeout` returns `0` instead of `15000` - Concurrent HTTP + MCP access fails ## Graph Table Architecture (v8.51.0+) ### Graph Table: Local-Only (NOT Synced to Cloudflare) **Rationale:** - **Derived data**: Graph associations can be reconstructed from memory metadata - **Performance**: Local graph queries are 30x faster (5ms vs 150ms) - **Complexity**: Cloudflare doesn't have native graph capabilities (no recursive CTEs in D1) - **Restoration**: Can rebuild graph table locally from association metadata in memories **Implementation:** - Graph table exists only in SQLite-vec backend - Associations stored as regular memories with `tags=['association', 'discovered']` - Memory metadata contains: `{similarity, connection_types, source_hash, target_hash}` - Cloudflare syncs the **memory objects**, NOT the graph table ### Cluster Summaries: Sync to Cloudflare **Rationale:** - **User-facing content**: Summaries contain valuable semantic information - **Multi-device access**: Users should see cluster summaries on all devices - **Restoration strategy**: Graph table can be rebuilt from synced association memories **Recovery Process** (new device or SQLite database deleted): 1. Pull all memories from Cloudflare (including associations and cluster summaries) 2. Extract association memories (tag='association') 3. Rebuild graph table locally from association metadata (~2-3 seconds for 1,435 associations) 4. Graph queries immediately functional (5ms performance restored) ## Installer Enhancements (v6.16.0+) - **Interactive backend selection** with usage-based recommendations - **Automatic Cloudflare credential setup** and `.env` file generation - **Connection testing** during installation to validate configuration - **Graceful fallbacks** from cloud to local backends if setup fails ## Multi-PC Configuration See [`.claude/directives/README.md`](README.md) for multi-PC sync guidelines. Key points: **Must match across all PCs:** - Cloudflare credentials (API token, account ID, database ID, vectorize index) - Content length limits (5000 for both Cloudflare and Hybrid) - Graph storage mode (graph_only) **Can differ per PC:** - SQLite pragmas (adjust per machine specs) - Archive paths (OS-specific) - Cache directories (local storage)