MCP Knowledge Graph for Windsurf: Setup & Config

What you can do with MCP Knowledge Graph in Windsurf

Choose it for local relational memory with separate project, global, and topic-specific stores.

• Separate work and personal memories using named databases.
• Look up known entities or search observations by keyword.

Before you start: MCP Knowledge Graph in Windsurf

• Node.js 22 or newer
• An MCP-compatible AI platform

Replace the sample global memory path with your chosen directory. A project-root directory named exactly .aim takes priority when detected. Named contexts create additional JSONL databases automatically.

MCP Knowledge Graph Windsurf configuration

1. Choose Windsurf configuration scope

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

2. Add MCP Knowledge Graph to Windsurf

   Use the mcp-knowledge-graph entry below in mcpServers. Keep MCP Knowledge Graph's documented stdio connection fields and your other Windsurf entries.

3. Check MCP Knowledge Graph in Windsurf

   MCP Knowledge Graph: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "mcp-knowledge-graph": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/.aim"
      ],
      "env": {}
    }
  }
}

MCP Knowledge Graph tools available to Windsurf

MCP Knowledge Graph's stored tool list documents 10 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

aim_memory_store

After refreshing MCP Knowledge Graph in Windsurf settings, check Cascade's tool list for aim_memory_store.

aim_memory_link

After refreshing MCP Knowledge Graph in Windsurf settings, check Cascade's tool list for aim_memory_link.

aim_memory_add_facts

After refreshing MCP Knowledge Graph in Windsurf settings, check Cascade's tool list for aim_memory_add_facts.

aim_memory_forget

After refreshing MCP Knowledge Graph in Windsurf settings, check Cascade's tool list for aim_memory_forget.

Delete entities together with their associated relationships.

aim_memory_remove_facts

After refreshing MCP Knowledge Graph in Windsurf settings, check Cascade's tool list for aim_memory_remove_facts.

Remove selected observations without deleting their entity.

aim_memory_unlink

After refreshing MCP Knowledge Graph in Windsurf settings, check Cascade's tool list for aim_memory_unlink.

aim_memory_read_all

After refreshing MCP Knowledge Graph in Windsurf settings, check Cascade's tool list for aim_memory_read_all.

aim_memory_search

After refreshing MCP Knowledge Graph in Windsurf settings, check Cascade's tool list for aim_memory_search.

Match keywords against entity names, types, and observations without case sensitivity.

aim_memory_get

After refreshing MCP Knowledge Graph in Windsurf settings, check Cascade's tool list for aim_memory_get.

Retrieve entities by exact name and include relationships between the selected records.

aim_memory_list_stores

After refreshing MCP Knowledge Graph in Windsurf settings, check Cascade's tool list for aim_memory_list_stores.

Discover project and global databases and report the current storage location.

MCP Knowledge Graph: full stored tool descriptions

Troubleshooting MCP Knowledge Graph in Windsurf

• Check npx mcp-knowledge-graph (Node.js/npm) on the machine running Windsurf's MCP integration for MCP Knowledge Graph; refresh MCP and inspect Cascade's tools.
• MCP Knowledge Graph uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires Node.js 22 or newer.
• Known limitation: Project detection depends on the exact .aim directory name.
• Known limitation: Inconsistent context naming can create redundant databases.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions