1. Home
  2. Basic Memory
  3. Basic Memory for Windsurf: Setup & Config

Data as of

Basic Memory for Windsurf: Setup & Config

Windsurf: Basic Memory gives AI clients persistent knowledge stored as Markdown that people can also edit.

What you can do with Basic Memory in Windsurf

Persistent AI knowledge in editable Markdown, with local ownership and optional cloud teamwork.

  • Search notes by meaning rather than exact wording.
  • Share team notes through the optional cloud workspace.

Before you start: Basic Memory in Windsurf

  • Python 3.12+
  • uv / uvx
  • An MCP-compatible client

This is the local client configuration from the README. Notes default to ~/basic-memory. Optional cloud onboarding is separate; no cloud MCP endpoint is specified in the supplied README.

Basic Memory Windsurf configuration

  1. Choose Windsurf configuration scope

    For Basic Memory, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

  2. Add Basic Memory to Windsurf

    Use the basic-memory entry below in mcpServers. Keep Basic Memory's documented stdio connection fields and your other Windsurf entries.

  3. Check Basic Memory in Windsurf

    Basic Memory: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json

Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

JSON
{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ],
      "env": {}
    }
  }
}

Basic Memory tools available to Windsurf

Basic Memory's stored tool list documents 7 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

search

After refreshing Basic Memory in Windsurf settings, check Cascade's tool list for search.

Search knowledge through the documented ChatGPT-compatible action interface.

fetch

After refreshing Basic Memory in Windsurf settings, check Cascade's tool list for fetch.

Retrieve knowledge through the documented ChatGPT-compatible action interface.

schema_infer

After refreshing Basic Memory in Windsurf settings, check Cascade's tool list for schema_infer.

schema_validate

After refreshing Basic Memory in Windsurf settings, check Cascade's tool list for schema_validate.

Check knowledge against its schema.

schema_diff

After refreshing Basic Memory in Windsurf settings, check Cascade's tool list for schema_diff.

edit_note

After refreshing Basic Memory in Windsurf settings, check Cascade's tool list for edit_note.

write_note

After refreshing Basic Memory in Windsurf settings, check Cascade's tool list for write_note.

Write a note with protection against unintended overwrites.

Basic Memory: full stored tool descriptions

Troubleshooting Basic Memory in Windsurf

  • Check uvx basic-memory (from uv, for Python tools) on the machine running Windsurf's MCP integration for Basic Memory; refresh MCP and inspect Cascade's tools.
  • Basic Memory uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
  • Known limitation: Local users manage their own backups and cross-device sync.
  • Known limitation: Cloud hosting is a paid option.
  • Known limitation: The local install requires Python.
  • General Windsurf troubleshooting lives in the /clients/windsurf guide.

Basic Memory — details. Windsurf guide

Frequently asked questions

Windsurf reads Basic Memory under mcpServers in ~/.codeium/windsurf/mcp_config.json on macOS/Linux; Windows uses %USERPROFILE%\.codeium\windsurf\mcp_config.json.

Windsurf's basic-memory example uses stdio.

Basic Memory's Windsurf configuration invokes uvx basic-memory (from uv, for Python tools).

Basic Memory's stored list contains 7 tools, including search, fetch, schema_infer. Compare those names with Windsurf's connected tool list; the stored list is not a live check.

No. The local engine is free and supports offline, air-gapped use.

The README gives ~/basic-memory as the default location.

The README identifies AGPL-3.0 for both local and cloud source code.