Windsurf Agent Persistent Memory

Configure local-first, zero-knowledge persistent memory inside your Windsurf editor. The Cascade AI assistant in Windsurf can use the store_memory and recall_memory tools to remember decisions and preferences across your project workspaces.

Installation

To configure sovseal in Windsurf:

1. Open your Windsurf IDE.
2. Open the Windsurf Settings (Cmd+, or Ctrl+,).
3. Navigate to MCP (Model Context Protocol).
4. Click Add Server or edit the configuration block.
5. Enter the following settings:
   • Name: sovseal-memory
   • Type: stdio
   • Command: npx
   • Arguments: ["-y", "@sovseal/mcp-server"]
6. Click Save.

If you prefer editing JSON configuration files directly, add the server to your Windsurf configuration path:

• Location: ~/.codeium/windsurf/mcp.json

{
  "mcpServers": {
    "sovseal-memory": {
      "command": "npx",
      "args": ["-y", "@sovseal/mcp-server"]
    }
  }
}

Directing Cascade with Custom Instructions

To ensure Windsurf's Cascade model proactively searches your memory store, create a .codeium/instructions.txt or .windsurfinstructions file at the root of your project workspace:

Always query the `recall_memory` tool first when starting a session or working on a new feature to retrieve relevant project context, past developer decisions, and stack preferences.
Call `store_memory` whenever the user establishes a new convention, configuration path, or coding style preference.

Project-Scoped Memory Isolation

You can isolate your memory directory per project to prevent context leakage between different codebases. To do this, configure the SOVSEAL_DB_DIR environment variable inside your project-specific mcp.json:

{
  "mcpServers": {
    "sovseal-memory": {
      "command": "npx",
      "args": ["-y", "@sovseal/mcp-server"],
      "env": {
        "SOVSEAL_DB_DIR": "./.sovseal/db"
      }
    }
  }
}

This ensures Cascade only has access to memories stored in the local project's database.