MCP Integration

HelixMind includes an MCP (Model Context Protocol) server that exposes your spiral memory to other AI tools.

Available MCP Tools

Tool	Description
spiral_context	Query spiral memory (L1–L3) for relevant context
spiral_store	Store new context in the spiral
spiral_status	Get memory metrics (node counts, storage)
spiral_compact	Trigger manual compaction
spiral_relate	Create manual relations between nodes

Setup by Editor

Claude Code

claude mcp add spiral-context -- npx -y spiral-context-mcp

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "spiral-context": {
      "command": "npx",
      "args": ["-y", "spiral-context-mcp"]
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "mcpServers": {
    "spiral-context": {
      "command": "npx",
      "args": ["-y", "spiral-context-mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "spiral-context": {
      "command": "npx",
      "args": ["-y", "spiral-context-mcp"]
    }
  }
}

Codex / JetBrains

Same JSON format. add to the respective MCP config file. For JetBrains: Settings → Tools → AI Assistant → MCP Servers.

Architecture

Your Editor (Claude Code / Cursor / VS Code)
    │
    ├── MCP Protocol (STDIO)
    │
    └── spiral-context-mcp Server
            ├── Spiral Engine (SQLite + sqlite-vec + MiniLM embeddings)
            └── 5 MCP Tools (context, store, status, compact, relate)

Key Points

Feature	Detail
Initialization	Non-blocking. basic tools work instantly, search after ~2-3s
Shared memory	MCP server + CLI share the same spiral.db
Cross-tool	Analyze in CLI → knowledge available in Cursor via MCP
Team sharing	Export from Dev A → import on Dev B → MCP has all knowledge

Troubleshooting

Issue	Solution
Server not connecting	Test npx -y spiral-context-mcp directly
Slow initialization	First run downloads embedding model (~22MB), cached after
Database locked	Ensure only one MCP server per project, check for zombie processes