Add memory to Windsurf

Windsurf's Cascade agent speaks MCP, so giving it persistent memory is a few lines in a config file. Add the server, refresh, and Cascade can store and recall named memory across sessions.

What you get

Persistent memory that survives across Windsurf sessions: named values you store once and recall later, shared memory for multi-agent work, temporal memory for facts that change over time, and no vector database to run. It is fifteen tools in total, and they show up as tools Cascade calls directly during a task. For the concepts underneath, see the MCP integration overview.

Prerequisites

• An AgentRAM API key. Create one free.
• Windsurf installed, and Node.js 18+ (node -v).

Add the server

Windsurf reads MCP servers from mcp_config.json. The quickest way in is the UI: open Windsurf Settings, go to Tools, and under Windsurf Settings use Add Server, then View Raw Config to edit the file directly. Or open it yourself:

• macOS and Linux: ~/.codeium/windsurf/mcp_config.json
• Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

Add AgentRAM under the mcpServers object:

{
  "mcpServers": {
    "agentram": {
      "command": "npx",
      "args": ["-y", "agentram-mcp"],
      "env": { "AGENTRAM_API_KEY": "agentram_your_key_here" }
    }
  }
}

Save the file, then press the refresh button on the Cascade MCP panel (or restart Windsurf) so the tools load.

If MCP is turned off, enable it first: Settings, Advanced Settings, the Cascade section, then toggle MCP on and restart. Config paths and the settings layout can shift between Windsurf versions; if the server does not appear, check Windsurf's current MCP docs. The server command and env var stay the same.

Quick start

Refresh the Cascade MCP panel (or restart Windsurf) so it picks up the server, then in Cascade try:

Store my test command as "npm run test:ci" under the key test_cmd.

Later, in a new session:

Recall test_cmd from AgentRAM.

It reads the value back instead of starting from nothing. To see the temporal side, ask it to store a fact that changes, like a plan or a status, update it later, and then ask for the history.

Smoke test and troubleshooting

• Tools do not appear. Press refresh on the Cascade MCP panel after editing mcp_config.json, or restart Windsurf. Confirm MCP is enabled in Advanced Settings, and that agentram shows in the panel.
• 401 or auth error. Check AGENTRAM_API_KEY is set correctly in the config and starts with agentram_.
• npx cannot find agentram-mcp. Node is older than 18, or you are offline. Check node -v.
• On a Teams or Enterprise plan? An admin may need to whitelist the server before it will connect. Check with whoever manages your Windsurf org.