Skip to content

Windows Hybrid Setup

Heinrich Krupp edited this page May 2, 2026 · 1 revision

Windows Hybrid Backend 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.

Prerequisites

  • Windows 10/11 with Python 3.11+ and uv installed
  • 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 .

Path Convention

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

Recommended Sync Owner

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=http

This is the recommended separation of concerns. The rest of this guide assumes it.

1. Claude Code (MCP Server)

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_vec here (not hybrid) because MCP_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.

2. Claude Desktop

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.

3. HTTP Dashboard Server

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=20000

Start:

cd <REPO_PATH>
uv run python scripts/server/run_http_server.py

Access:

The default port changed from 8888 to 8000 in v8.3.0. Update any saved bookmarks or hook configs to point at port 8000.

Verification

Memory counts

# 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=1

HTTP server health

curl http://127.0.0.1:8000/api/health

MCP connection

claude mcp list | findstr memory

Troubleshooting

"database is locked" errors

  • Verify MCP_MEMORY_SQLITE_PRAGMAS includes journal_mode=WAL in every config (Claude Code, Claude Desktop, HTTP server)
  • Without WAL, concurrent reads from MCP and HTTP servers will conflict

Cloudflare 401 / sync not running

  • Token rotated in dashboard but .env not 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

Local count lower than Cloudflare count after sync

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.

Port already in use

HTTP server defaults to 8000. To change:

MCP_HTTP_PORT=8080

Update Claude Code / Claude Desktop hook configs (C:\Users\<USERNAME>\.claude\hooks\config.json) to match.

Related

Clone this wiki locally