MemoryGraph Setup for Windsurf

Get persistent memory working in Windsurf in under 2 minutes.

Prerequisites

• Windsurf IDE (latest version)
• Python 3.10+
• pipx installed (pip install --user pipx && pipx ensurepath)

Choose Your Backend

MemoryGraph supports two backend options:

Feature	Local (SQLite)	Cloud
Setup	Zero-config	API key required
Data Location	~/.memorygraph/	memorygraph.dev
Multi-device	No	Yes
Team sharing	No	Yes
Offline	Yes	No
Cost	Free	Free tier available

New users: We recommend starting with Cloud for multi-device sync, or Local for single-machine use.

---

Quick Start (Local Backend)

1. Install MemoryGraph

pipx install memorygraphMCP

Verify installation:

memorygraph --version

2. Configure Windsurf

Option A: Via Settings UI

1. Open Windsurf Settings (Cmd/Ctrl + ,)
2. Search for "MCP" or navigate to Extensions > MCP Servers
3. Click Add MCP Server
4. Configure:
   • Name: memorygraph
   • Command: memorygraph
   • Transport: stdio

Option B: Via Configuration File

Windsurf uses a similar configuration format to other MCP clients. Create or edit your MCP configuration:

{
  "mcpServers": {
    "memorygraph": {
      "command": "memorygraph",
      "args": [],
      "env": {}
    }
  }
}

Location varies by OS:

• macOS: ~/Library/Application Support/Windsurf/mcp.json
• Linux: ~/.config/Windsurf/mcp.json
• Windows: %APPDATA%\Windsurf\mcp.json

3. Restart Windsurf

Close and reopen Windsurf to load the MCP server.

4. Verify Connection

In Windsurf's AI chat, ask:

What memory tools do you have available?

You should see MemoryGraph tools listed.

First Memory

Store your first memory:

Store this for later: Use pnpm instead of npm for this monorepo

Retrieve it later:

What package manager should I use for this project?

---

Quick Start (Cloud Backend)

Cloud backend syncs memories across all your devices and enables team collaboration.

1. Get Your API Key

1. Sign up at app.memorygraph.dev
2. Copy your API key (starts with mg_)

2. Install MemoryGraph

pipx install memorygraphMCP

3. Configure Windsurf with Cloud Backend

Create or edit your MCP configuration file:

macOS: ~/Library/Application Support/Windsurf/mcp.json Linux: ~/.config/Windsurf/mcp.json Windows: %APPDATA%\Windsurf\mcp.json

{
  "mcpServers": {
    "memorygraph": {
      "command": "memorygraph",
      "args": ["--backend", "cloud"],
      "env": {
        "MEMORYGRAPH_API_KEY": "mg_your_api_key_here"
      }
    }
  }
}

4. Restart Windsurf and Verify

1. Close and reopen Windsurf
2. Ask in AI chat: "What memory tools do you have available?"

---

Migrating from Local to Cloud

Already using local SQLite and want to switch to cloud?

Step 1: Export Local Memories

# Export all memories to JSON
memorygraph export --output memories-backup.json

Step 2: Import to Cloud

# Set your cloud API key
export MEMORYGRAPH_API_KEY=mg_your_key_here

# Import to cloud backend
memorygraph import --backend cloud --input memories-backup.json

Step 3: Update Windsurf Configuration

Update your mcp.json to use cloud backend:

{
  "mcpServers": {
    "memorygraph": {
      "command": "memorygraph",
      "args": ["--backend", "cloud"],
      "env": {
        "MEMORYGRAPH_API_KEY": "mg_your_api_key_here"
      }
    }
  }
}

Step 4: Restart Windsurf

Close and reopen Windsurf to apply the new configuration.

See CLOUD_BACKEND.md for detailed migration options and troubleshooting.

---

Configuration Options

Extended Mode (Pattern Recognition)

{
  "mcpServers": {
    "memorygraph": {
      "command": "memorygraph",
      "args": ["--profile", "extended"]
    }
  }
}

Custom Database Location

{
  "mcpServers": {
    "memorygraph": {
      "command": "memorygraph",
      "env": {
        "MEMORY_SQLITE_PATH": "/path/to/your/memory.db"
      }
    }
  }
}

Project-Specific Memory

Create .windsurf/mcp.json in your project root:

{
  "mcpServers": {
    "memorygraph": {
      "command": "memorygraph",
      "env": {
        "MEMORY_SQLITE_PATH": "./.windsurf/memory.db"
      }
    }
  }
}

Troubleshooting

Server Not Connecting

1. Check that memorygraph is installed and in PATH:

   which memorygraph
   memorygraph --version
   

2. If not found, ensure pipx bin is in your PATH:

   pipx ensurepath
   # Restart terminal
   

3. Use full path in configuration:

   {
     "command": "/Users/yourname/.local/bin/memorygraph"
   }
   

MCP Tools Not Appearing

1. Verify MCP server status in Windsurf settings
2. Check for error messages in the server logs
3. Restart Windsurf completely (not just reload)

Test Server Manually

echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}},"id":1}' | memorygraph

You should see a JSON response with capabilities.

SSE Transport (If Required)

If Windsurf requires SSE transport instead of stdio, you may need to run MemoryGraph with an SSE wrapper. Check Windsurf documentation for current requirements.

Tips for Windsurf Users

1. Leverage Windsurf's features - Combine MemoryGraph with Windsurf's code understanding
2. Store architectural decisions - Remember why you made certain choices
3. Track what works - Store successful patterns for future reference
4. Query before coding - Check if you've solved similar problems

Recommended: Memory Protocol

Add this to .windsurfrules or your project's rules file for automatic memory usage:

## Memory Protocol

### REQUIRED: Before Starting Work
You MUST use `recall_memories` before any task. Query by project, tech, or task type.

### REQUIRED: Automatic Storage Triggers
Store memories on ANY of:
- **Git commit** → what was fixed/added
- **Bug fix** → problem + solution
- **Version release** → summarize changes
- **Architecture decision** → choice + rationale
- **Pattern discovered** → reusable approach

### Timing Mode (default: on-commit)
`memory_mode: immediate | on-commit | session-end`

### Memory Fields
- **Type**: solution | problem | code_pattern | fix | error | workflow
- **Title**: Specific, searchable (not generic)
- **Content**: Accomplishment, decisions, patterns
- **Tags**: project, tech, category (REQUIRED)
- **Importance**: 0.8+ critical, 0.5-0.7 standard, 0.3-0.4 minor
- **Relationships**: Link related memories when they exist

Do NOT wait to be asked. Memory storage is automatic.

File locations:

• Project-specific: .windsurfrules in project root
• Global: Windsurf Settings > AI Rules

Windsurf-Specific Features

Windsurf has a rich feature set. MemoryGraph complements these by:

• Persisting context - Remember discussions across sessions
• Tracking solutions - Know what worked in past projects
• Building relationships - Connect problems to their solutions

Next Steps

• Full Configuration Reference
• All Tool Profiles
• Troubleshooting Guide

---

Works with: Windsurf (all versions with MCP support) Transport: stdio (SSE may be supported) Profiles: core (9 tools), extended (11 tools)