Repository navigation
Windows Hybrid Setup
End-to-end configuration for running MCP Memory Service in hybrid mode (local SQLite-Vec + Cloudflare sync) on Windows. Covers all three Claude entry points: Claude Code, Claude Desktop, and the HTTP Dashboard server.
Why hybrid? Local SQLite-Vec gives ~5 ms reads. Cloudflare provides multi-device sync. The MCP server reads/writes locally; the HTTP server runs the background Cloudflare sync. See Hybrid_Setup_Configuration for the architectural rationale.
- Windows 10/11 with Python 3.11+ and
uvinstalled - Cloudflare account with: API token, account ID, D1 database ID, Vectorize index named
mcp-memory-index - Cloned repo at a stable path, e.g.
C:\Repositories\mcp-memory-service - Editable install:
uv pip install -e .
Replace <USERNAME> with your Windows account name and <REPO_PATH> with the absolute path to your clone.
| Item | Convention used in this guide |
|---|---|
| Repo |
<REPO_PATH> (e.g. C:\Repositories\mcp-memory-service) |
| User profile | C:\Users\<USERNAME> |
| SQLite database | C:\Users\<USERNAME>\AppData\Local\mcp-memory\backups\sqlite_vec.db |
| Backups directory | C:\Users\<USERNAME>\AppData\Local\mcp-memory\backups |
Set this so only the HTTP server syncs to Cloudflare. The MCP server (Claude Code / Claude Desktop) then runs SQLite-Vec only and needs no Cloudflare credentials:
MCP_HYBRID_SYNC_OWNER=httpThis is the recommended separation of concerns. The rest of this guide assumes it.
Config file: C:\Users\<USERNAME>\.claude.json
{
"mcpServers": {
"memory": {
"type": "stdio",
"command": "uv",
"args": [
"--directory", "<REPO_PATH>",
"run", "python", "-m", "mcp_memory_service.server"
],
"env": {
"MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec",
"MCP_MEMORY_SQLITE_PATH": "C:\\Users\\<USERNAME>\\AppData\\Local\\mcp-memory\\backups\\sqlite_vec.db",
"MCP_MEMORY_BACKUPS_PATH": "C:\\Users\\<USERNAME>\\AppData\\Local\\mcp-memory\\backups",
"MCP_MEMORY_SQLITE_PRAGMAS": "journal_mode=WAL,busy_timeout=15000,cache_size=20000"
}
}
}
}Storage backend is
sqlite_vechere (nothybrid) becauseMCP_HYBRID_SYNC_OWNER=http(set globally or in the HTTP server's.env) reserves Cloudflare sync for the HTTP server. Claude Code reads/writes the local SQLite file directly.
Verify: claude mcp list | findstr memory should show the server connected.
Config file: C:\Users\<USERNAME>\AppData\Roaming\Claude\claude_desktop_config.json
{
"mcpServers": {
"memory": {
"command": "uv",
"args": [
"--directory", "<REPO_PATH>",
"run", "python", "-m", "mcp_memory_service.server"
],
"env": {
"MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec",
"MCP_MEMORY_SQLITE_PATH": "C:\\Users\\<USERNAME>\\AppData\\Local\\mcp-memory\\backups\\sqlite_vec.db",
"MCP_MEMORY_BACKUPS_PATH": "C:\\Users\\<USERNAME>\\AppData\\Local\\mcp-memory\\backups",
"MCP_MEMORY_SQLITE_PRAGMAS": "journal_mode=WAL,busy_timeout=15000,cache_size=20000"
}
}
}
}Restart Claude Desktop after saving.
This is the process that owns Cloudflare sync.
Config file: <REPO_PATH>\.env
MCP_MEMORY_STORAGE_BACKEND=hybrid
MCP_HYBRID_SYNC_OWNER=http
# Cloudflare credentials
CLOUDFLARE_API_TOKEN=<your-token>
CLOUDFLARE_ACCOUNT_ID=<your-account-id>
CLOUDFLARE_D1_DATABASE_ID=<your-d1-id>
CLOUDFLARE_VECTORIZE_INDEX=mcp-memory-index
# Hybrid tuning
MCP_HYBRID_SYNC_INTERVAL=300
MCP_HYBRID_BATCH_SIZE=50
MCP_HYBRID_SYNC_ON_STARTUP=true
# Storage paths (must match the MCP server config above)
MCP_MEMORY_SQLITE_PATH=C:\Users\<USERNAME>\AppData\Local\mcp-memory\backups\sqlite_vec.db
MCP_MEMORY_BACKUPS_PATH=C:\Users\<USERNAME>\AppData\Local\mcp-memory\backups
MCP_MEMORY_SQLITE_PRAGMAS=journal_mode=WAL,busy_timeout=15000,cache_size=20000Start:
cd <REPO_PATH>
uv run python scripts/server/run_http_server.pyAccess:
- Dashboard: http://localhost:8000/
- Health: http://localhost:8000/api/health
- API docs: http://localhost:8000/api/docs
The default port changed from 8888 to 8000 in v8.3.0. Update any saved bookmarks or hook configs to point at port 8000.
# Local SQLite count
python -c "import sqlite3; conn = sqlite3.connect(r'C:\Users\<USERNAME>\AppData\Local\mcp-memory\backups\sqlite_vec.db'); cur = conn.cursor(); cur.execute('SELECT COUNT(*) FROM memories'); print(f'Local: {cur.fetchone()[0]}'); conn.close()"
# Dashboard API count
curl http://127.0.0.1:8000/api/memories?page=1^&page_size=1curl http://127.0.0.1:8000/api/healthclaude mcp list | findstr memory- Verify
MCP_MEMORY_SQLITE_PRAGMASincludesjournal_mode=WALin every config (Claude Code, Claude Desktop, HTTP server) - Without WAL, concurrent reads from MCP and HTTP servers will conflict
- Token rotated in dashboard but
.envnot updated → re-paste token, restart HTTP server - Token IP allowlist only has IPv4 but Python prefers IPv6 → either add your IPv6 /64 to the token's Client IP Address Filtering, or remove IP filtering
- See cloudflare-ipv6-issue on the wiki
This is expected behavior of the early-break system designed to prevent infinite sync loops:
-
MCP_HYBRID_MAX_EMPTY_BATCHES=20— stops after 20 consecutive batches with no new memories -
MCP_HYBRID_MIN_CHECK_COUNT=1000— processes at least 1,000 memories before early-break is allowed
If you need a forced full re-sync, raise both thresholds temporarily and restart the HTTP server.
HTTP server defaults to 8000. To change:
MCP_HTTP_PORT=8080Update Claude Code / Claude Desktop hook configs (C:\Users\<USERNAME>\.claude\hooks\config.json) to match.
- Hybrid_Setup_Configuration — architectural overview
- Cloudflare-Backup-Sync-Setup — Cloudflare provisioning
- 02-Platform-Setup-Guide — broader Windows setup notes
- 07-TROUBLESHOOTING — general troubleshooting