> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovseal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add sovseal Memory to Windsurf AI Editor

> Configure the sovseal MCP server in Windsurf so the Cascade AI assistant remembers project decisions and preferences across all your workspaces.

sovseal adds a persistent, local-first memory layer to Windsurf's Cascade AI assistant. Once configured, Cascade can store and retrieve design decisions, coding conventions, configuration paths, and developer preferences across project workspaces — no credentials or cloud setup required for local storage.

## Installation

<Tabs>
  <Tab title="Windsurf Settings UI">
    <Steps>
      <Step title="Open Windsurf Settings">
        Press **Cmd+,** (macOS) or **Ctrl+,** (Windows/Linux) to open the settings panel.
      </Step>

      <Step title="Navigate to MCP">
        Scroll to the **MCP (Model Context Protocol)** section and click **Add Server**.
      </Step>

      <Step title="Enter the server configuration">
        Fill in the following fields:

        | Field     | Value                    |
        | --------- | ------------------------ |
        | Name      | `sovseal-memory`         |
        | Type      | `stdio`                  |
        | Command   | `npx`                    |
        | Arguments | `-y @sovseal/mcp-server` |
      </Step>

      <Step title="Save and restart">
        Click **Save**, then close and reopen Windsurf. The `store_memory` and `recall_memory` tools will be available to Cascade in the chat panel.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Config file">
    Edit `~/.codeium/windsurf/mcp.json` directly and add the `sovseal-memory` block:

    ```json ~/.codeium/windsurf/mcp.json theme={null}
    {
      "mcpServers": {
        "sovseal-memory": {
          "command": "npx",
          "args": ["-y", "@sovseal/mcp-server"]
        }
      }
    }
    ```

    Save the file and restart Windsurf to pick up the new server.
  </Tab>
</Tabs>

## Direct Cascade with custom instructions

To make Cascade proactively search memory at the start of every session, create a `.windsurfinstructions` file at the root of your project (or `.codeium/instructions.txt`):

```text .windsurfinstructions theme={null}
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.
```

Cascade reads this file before each conversation, so the instruction takes effect automatically without any manual prompting.

## Project-scoped memory isolation

By default, sovseal stores memories globally at `~/.sovseal/db/memories.lance`. To prevent context from one codebase leaking into another, set `SOVSEAL_DB_DIR` in your project-level `mcp.json`:

```json .codeium/windsurf/mcp.json theme={null}
{
  "mcpServers": {
    "sovseal-memory": {
      "command": "npx",
      "args": ["-y", "@sovseal/mcp-server"],
      "env": {
        "SOVSEAL_DB_DIR": "./.sovseal/db"
      }
    }
  }
}
```

With this setting, Cascade only accesses memories stored inside the current project's folder. Memories from other projects remain completely separate.

<Note>
  On first launch, sovseal downloads the quantized embedding model (\~22 MB) to `~/.sovseal/models/`. Windsurf may show Cascade as "thinking" for up to 30 seconds during this one-time download. All subsequent sessions start instantly from the local cache.
</Note>