How to Add Memory to Windsurf IDE
Codeium's Windsurf is a fantastic AI IDE, and its Cascade agent is incredibly capable. But like all AI tools, it suffers from amnesia between sessions. This guide shows you how to give Windsurf persistent, structured memory using Memstate MCP — so Cascade remembers your architecture and preferences forever.
What You Need
- Windsurf IDE installed
- Node.js 18+ installed on your machine
- A free Memstate AI account (no credit card required)
Step-by-Step Setup
1Get your Memstate API Key
Sign up at memstate.ai for free. Go to Dashboard → API Keys and create a new key. Copy it to your clipboard.
2Open Windsurf MCP Settings
In Windsurf, open the Command Palette (Cmd/Ctrl + Shift + P) and search for Windsurf: Open MCP Settings. This will open the mcp.json file located in your ~/.codeium/windsurf/ directory.
3Add the Memstate Server
Add the Memstate server configuration to the JSON file, pasting your API key where indicated:
{
"mcpServers": {
"memstate": {
"command": "npx",
"args": ["-y", "@memstate/mcp"],
"env": {
"MEMSTATE_API_KEY": "your-api-key-here"
}
}
}
}4Verify the Connection
Save the file. Open the Cascade panel in Windsurf and click the MCP icon (the plug) at the top. You should see Memstate listed and active. You can test it by asking Cascade:
What MCP tools do you have access to?
Crucial: Tell Cascade When to Use Memory
Just giving Cascade the MCP tools is not enough; you need to tell it when to use them. The best way to do this is by creating a .windsurfrules file in your project root, or running our init command to generate it for you:
npx @memstate/mcp init
This ensures Cascade automatically checks memory before starting a task, and saves a summary after completing one.
Related Guides
Supercharge Windsurf Cascade
Get structured, versioned memory that never gets confused.