Windsurf Setup

User-level MCP config for Windsurf AI editor

Prerequisite: Install the engram binary first via Homebrew or binary download.

Setup

Add to ~/.windsurf/mcp.json (Windows: %USERPROFILE%\.windsurf\mcp.json):

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

1. Install engram binary

   brew install gentleman-programming/tap/engram
   
2. Create MCP config

   Create ~/.windsurf/mcp.json:

   {
     "mcpServers": {
       "engram": {
         "command": "engram",
         "args": ["mcp"]
       }
     }
   }
   
3. Restart Windsurf

   Reload the window or restart Windsurf.

Adding the Memory Protocol (Recommended)

Add the Memory Protocol to .windsurfrules file to teach the agent when to use memory.

Create or edit .windsurfrules in your project root:

# Engram Persistent Memory

You have access to Engram persistent memory (mem_save, mem_search, mem_context).

- Save proactively after significant work (bugfixes, decisions, discoveries, patterns).
- After context resets, call mem_context to recover state.
- Before ending session, call mem_session_summary.

See Memory Protocol for the full text.

Platform-Specific Notes

Windows

Config path: %USERPROFILE%\.windsurf\mcp.json

Make sure engram.exe is in your PATH. Windsurf resolves MCP commands from the system PATH.

Check:

where engram

macOS

Config path: ~/.windsurf/mcp.json

If you installed via Homebrew, engram is automatically in PATH:

which engram

Linux

Config path: ~/.windsurf/mcp.json

If you installed via Homebrew:

which engram

If you downloaded a binary, move it to /usr/local/bin or add its directory to PATH.

Windsurf Rules File

The .windsurfrules file is Windsurf’s project-level instruction file. It’s similar to:

• .cursorrules (Cursor)
• .clauderules (Claude Code)
• CLAUDE.md (Claude Code)
• GEMINI.md (Gemini CLI)

Anything you put in .windsurfrules is injected into the agent’s system prompt.

Memory Protocol Behavior

With the Memory Protocol in .windsurfrules, the agent:

• Saves proactively after bugfixes, decisions, discoveries, patterns
• Searches reactively when you say “remember” or “what did we do”
• Searches proactively when starting work that might overlap past sessions
• Closes sessions with mem_session_summary before saying “done”
• Recovers state after compaction with mem_context

Troubleshooting

MCP tools not showing up

Check that ~/.windsurf/mcp.json exists:

# macOS/Linux
cat ~/.windsurf/mcp.json

# Windows
type %USERPROFILE%\.windsurf\mcp.json

Verify the format matches the example above.

Binary not found

Windsurf can’t find engram command:

# Check PATH
echo $PATH

# Check binary location
which engram  # macOS/Linux
where engram  # Windows

If missing, install via Homebrew or binary download.

Agent doesn’t use memory

Check that .windsurfrules includes the Memory Protocol:

cat .windsurfrules

If missing, add the minimal version from the “Adding the Memory Protocol” section above.

Next Steps

• Learn about the Memory Protocol
• Explore MCP Tools
• Set up Git Sync for team memory sharing