Skip to main content
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.
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

Build docs developers (and LLMs) love

Get started for freeTalk to us