MARM v2.20.0 - Memory Accurate Response Mode Complete Windows installation guide

• Quick Start (5 Minutes)
• System Requirements
• Installation Options
• Client Connections
• Verification & Testing
• Updating & Reinstalling
• Troubleshooting
• Configuration
• Windows-Specific Features
• Windows Performance Tips

🚀 Fastest Path to MARM Memory on Windows:

1. Install MARM: Choose ⭐ pip install (Recommended) or ⚡ virtualenv (Clean) from options below
2. Connect Claude: claude mcp add --transport http marm-memory http://localhost:8001/mcp
3. Test: Ask Claude to recall a memory, MARM initializes automatically on the first tool call

That's it! You now have AI memory that saves across sessions and platforms.

• OS: Windows 10/11 (64-bit)
• Python: 3.10 or higher (Download Python)
• Memory: 1GB RAM available
• Storage: ~500MB disk space
• Network: Internet connection for initial setup

• PowerShell (Recommended) - Better Unicode support, modern features
• Command Prompt - Works but may have encoding issues with emojis

pip install marm-mcp-server
python -m marm_mcp_server

python -m venv marm-env
marm-env\Scripts\activate
pip install marm-mcp-server
python -m marm_mcp_server

If you prefer the marm-mcp-stdio CLI script, add the Python Scripts folder to your PATH first:

# Run once to add permanently (replace (username) with your Windows username and Python3XX with your Python version, e.g. Python312)
[System.Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\Users\(username)\AppData\Roaming\Python\Python3XX\Scripts", "User")

Then restart your terminal.

git clone https://github.com/Lyellr88/marm-memory.git
cd marm-memory\marm-mcp-server
pip install -e ".[dev]"
python -m marm_mcp_server

For shared HTTP servers running multiple AI agents, use a preset flag:

python -m marm_mcp_server --swarm        # 200 RPM, write queue on
python -m marm_mcp_server --swarm-max    # 600 RPM, write queue on
python -m marm_mcp_server --trusted      # rate limiting off, write queue on
python -m marm_mcp_server --rate-limit-rpm 150  # custom RPM

Use one MARM HTTP process per SQLite database. Multi-process Uvicorn/Gunicorn workers (--workers N) are not supported yet because MARM's write queue, scheduler, and protocol/session coordination are process-local.

Server starts on: http://localhost:8001 MCP Endpoint: http://localhost:8001/mcp API Documentation: http://localhost:8001/docs

HTTP Connection (Standard):

claude mcp add --transport http marm-memory http://localhost:8001/mcp

Note: Claude Code currently supports HTTP, SSE, and STDIO through claude mcp add; use HTTP for MARM.

Verified with VS Code's native MCP support. Add this to .vscode\mcp.json in your workspace. Use marm-memory-local for direct Python installs; use marm-memory-docker when running Docker or exposed/key mode.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "marm-api-key",
      "description": "MARM API Key for Docker or exposed server mode",
      "password": true
    }
  ],
  "servers": {
    "marm-memory-local": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    },
    "marm-memory-docker": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer ${input:marm-api-key}"
      }
    }
  }
}

Open .vscode\mcp.json, click Start above the server you want, then use Copilot Agent or any VS Code extension that consumes VS Code's native MCP registry. Third-party extensions that do not use VS Code's MCP registry may require their own setup.

Verified with Cursor MCP. Add this to .cursor\mcp.json in your workspace. Use marm-memory-local for direct Python installs; use marm-memory-docker when running Docker or exposed/key mode.

{
  "mcpServers": {
    "marm-memory-local": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    },
    "marm-memory-docker": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MARM_API_KEY}"
      }
    }
  }
}

Cursor uses mcpServers, not VS Code's servers root. For Docker/key mode, launch Cursor with MARM_API_KEY set in the environment.

xAI's official Grok MCP integration uses Remote MCP Tools through the xAI API. Only Streaming HTTP and SSE transports are supported.

Because xAI connects to the MCP server from its own infrastructure, localhost will not work for Grok Remote MCP. Expose MARM behind HTTPS and set MARM_API_KEY.

{
  "type": "mcp",
  "server_url": "https://your-marm-domain.example.com/mcp",
  "server_label": "marm-memory",
  "authorization": "Bearer your-generated-key"
}

Codex uses codex mcp add or TOML config at %USERPROFILE%\.codex\config.toml, not settings.json.

# Direct Python install - no key needed
codex mcp add marm-memory --url http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required
$env:MARM_API_KEY="your-generated-key"
codex mcp add marm-memory --url http://localhost:8001/mcp --bearer-token-env-var MARM_API_KEY

[mcp_servers."marm-memory"]
url = "http://localhost:8001/mcp"
enabled = true
bearer_token_env_var = "MARM_API_KEY"

Gemini CLI supports STDIO, SSE, and streamable HTTP MCP transports. Use HTTP for MARM.

# Direct Python install - no key needed
gemini mcp add --transport http marm-memory http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required
gemini mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

Equivalent %USERPROFILE%\.gemini\settings.json or project .gemini\settings.json:

{
  "mcpServers": {
    "marm-memory": {
      "httpUrl": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

Qwen Code supports STDIO, SSE, and streamable HTTP MCP transports. Use HTTP for MARM. Project scope writes to .qwen\settings.json; user scope writes to %USERPROFILE%\.qwen\settings.json.

# Direct Python install - no key needed
qwen mcp add --transport http marm-memory http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required
qwen mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

Equivalent .qwen\settings.json or %USERPROFILE%\.qwen\settings.json:

{
  "mcpServers": {
    "marm-memory": {
      "httpUrl": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

Invoke-WebRequest -Uri http://localhost:8001/health

Expected Health Response:

{
  "status": "healthy",
  "service": "MARM MCP Server",
  "version": "2.20.0",
  "timestamp": "2026-01-01T00:00:00+00:00",
  "database": "connected",
  "semantic_search": "available"
}

Standard Update Process:

1. Stop MARM Server: Ctrl+C or stop Docker container

2. Backup Your Data (Recommended):

   Copy-Item -Recurse "$env:USERPROFILE\.marm" "$env:USERPROFILE\.marm_backup_$(Get-Date -Format yyyyMMdd)"

3. Update package:

   pip install marm-mcp-server --upgrade

4. Restart Server: python -m marm_mcp_server

🐳 Docker Update:

docker pull lyellr88/marm-mcp-server:latest
docker stop marm-mcp-server
docker rm marm-mcp-server
docker run -d --name marm-mcp-server -p 127.0.0.1:8001:8001 -e SERVER_HOST=0.0.0.0 -e MARM_API_KEY=your-generated-key -v ${HOME}\.marm:/home/marm/.marm --restart unless-stopped lyellr88/marm-mcp-server:latest

Warning: This will delete all your memories, sessions, and notebooks.

# Stop server, then delete data directory
Remove-Item -Recurse -Force "$env:USERPROFILE\.marm"

# Fresh installation
pip install marm-mcp-server
python -m marm_mcp_server

• Database schema is compatible - no migration needed
• New tools automatically available after restart
• Docker images are backward compatible with persistent volumes

Data Preservation:

• All memories stored in %USERPROFILE%\.marm\marm_memory.db
• Notebooks stored in same database
• Analytics data stored in %USERPROFILE%\.marm\marm_usage_analytics.db (override with MARM_ANALYTICS_DB_PATH)

# Check what went wrong
Get-Content server.log | Select-Object -Last 20

# Check if port is in use
netstat -ano | findstr :8001

• Port 8001 busy: Find and kill process: netstat -ano | findstr :8001 → taskkill /PID <id> /F
• Permission denied: Run PowerShell as Administrator
• Unicode/emoji errors: Set encoding: $env:PYTHONIOENCODING="utf-8"
• Python not found: Reinstall Python and check "Add to PATH" option

Set environment variables in PowerShell:

$env:SERVER_PORT="8002"
python -m marm_mcp_server

Or permanently via System Properties:

1. Search "Environment Variables" in Start Menu
2. Click "Environment Variables..." button
3. Add under "User variables"

Create start_marm.bat for easy startup:

@echo off
python -m marm_mcp_server
pause

STDIO logs write to %USERPROFILE%\.marm\logs\marm-stdio.log automatically when using local pip STDIO mode. Docker STDIO does not expose this file on the host.

# View full log
Get-Content "$env:USERPROFILE\.marm\logs\marm-stdio.log"

# Live tail (watch tool calls as they happen)
Get-Content "$env:USERPROFILE\.marm\logs\marm-stdio.log" -Wait -Tail 20

Set MARM_STDIO_LOG_LEVEL=DEBUG for additional detail (session names, query lengths, result counts). Memory content is never written to the log.

MARM works in Windows Subsystem for Linux:

# In WSL terminal
pip install marm-mcp-server
python3 -m marm_mcp_server

Access from Windows: http://localhost:8001

• Close unnecessary programs before starting MARM
• Use Task Manager to monitor memory usage
• Consider WSL2 for better performance on older systems

Add MARM folder to antivirus exclusions to prevent:

• Slow startup times
• File access issues
• False positive detections

Common paths to exclude:

• C:\Users\{username}\.marm\

MARM Windows Guide - Universal memory intelligence for AI agents

For usage instructions, see README.md
For Docker deployment, see INSTALL-DOCKER.md