# Windsurf

Installing SurrealDB Agent Memory as an MCP server in Windsurf.

Windsurf's Cascade agent supports MCP servers natively. Installing SurrealDB Agent Memory gives Cascade persistent memory - it can recall decisions, project context, and user preferences across sessions without requiring you to re-explain your codebase on every invocation.

## Install

The MCP server lives at `/mcp` on your SurrealDB Agent Memory instance. On **SurrealDB Cloud** the base is your context host from SurrealDB Studio **API keys**; self-hosted, it is your server's base URL. Point Windsurf at it with [`install-mcp`](https://github.com/supermemoryai/install-mcp):

```bash
npx install-mcp https://<your-context-host>/mcp \
  --client windsurf \
  --header "Authorization: Bearer <your-api-key>" \
  --oauth no
```

The URL is the first argument; auth is passed with `--header`, and `--oauth no` skips the OAuth prompt (SurrealDB Agent Memory uses a static Bearer key). The installer writes the configuration to Windsurf's global MCP config file and merges it with any existing entries.

### Config file location

| Platform | Path |
|---|---|
| macOS | `~/.codeium/windsurf/mcp_config.json` |
| Windows | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |
| Linux | `~/.codeium/windsurf/mcp_config.json` |

### What gets written

```json
{
  "mcpServers": {
    "spectron": {
      "serverUrl": "https://<your-context-host>/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>",
        "X-Spectron-Context": "acme-prod"
      }
    }
  }
}
```

Windsurf uses `serverUrl` rather than `url`. The `install-mcp` command writes the correct key automatically.

## Scope on tool calls

Pass a **`scope`** argument on each tool (slash paths, for example `["org/acme/user/alice"]`). The install helper does not set default scope; register paths with `spectron scopes create` before first use.

## Verify the installation

1. Restart Windsurf
2. Open the Cascade panel
3. Run a prompt: "What MCP tools do you have access to?" - Cascade should report the seven SurrealDB Agent Memory tools
4. Alternatively, open **Windsurf → Settings → MCP** to see a list of configured servers and their connection status

If SurrealDB Agent Memory does not appear or shows as disconnected, check that the config file is valid JSON and that the API key and URL are correct.

## Usage examples

### Storing project conventions

At the start of a new project or codebase:

> "Remember that this project uses domain-driven design with bounded contexts. The `orders` and `inventory` contexts must never share a database table directly - communication is via events only."

Cascade calls `remember`. The architectural constraint is available in all future sessions and is recalled automatically when Cascade encounters related code.

### Recalling previous decisions

Before suggesting a solution:

> "What do you remember about how we handle authentication in this codebase?"

Cascade calls `recall` and returns relevant stored context before composing its response.

### Querying the knowledge base

If your internal documentation is synced into SurrealDB Agent Memory's authoritative knowledge store:

> "What does our runbook say about rolling back a failed deployment?"

Cascade calls `recall` and retrieves the relevant runbook section.

### Building a persistent project brief

Ask Cascade to save a comprehensive project brief at the start of an engagement:

> "Store the following as project context: we are building a multi-tenant SaaS platform in Go, using SurrealDB for application data, deployed on Kubernetes in AWS eu-west-1."

Cascade calls `remember` with the full brief. Subsequent sessions recall this context automatically via `recall`.

## Updating the configuration

To change the API key or context host, edit `~/.codeium/windsurf/mcp_config.json` directly or re-run the install command:

```bash
npx install-mcp https://<your-context-host>/mcp \
  --client windsurf \
  --header "Authorization: Bearer <your-api-key>" \
  --oauth no
```

Re-running the command merges the updated values over the existing configuration entry.

## Removing SurrealDB Agent Memory

Open `~/.codeium/windsurf/mcp_config.json` and delete the `"spectron"` key from `mcpServers`. Restart Windsurf to apply the change.