Integrations

MCP Server

Expose Waystone's tools directly inside your AI editor via the Model Context Protocol.

Overview

The Waystone MCP server runs locally and exposes four tools to any MCP-compatible client:

• waystone_query — retrieve facts from a project most relevant to a task description
• waystone_extract — extract structured facts from a text snippet and merge them into a project
• waystone_stats — return node counts and graph statistics for a project
• waystone_list_projects — list all available projects

Your editor calls these tools automatically as context, or you can invoke them explicitly during a session. No API keys are required — the server reads your local ~/.waystone/config.yaml directly.

Starting the server

Run the MCP server from your terminal:

waystone mcp-serve

Or use the dedicated entry point (useful for process managers and editor launch configs):

waystone-mcp

The server communicates over stdio by default, which is the mode all major editors expect. It stays running in the foreground — open a new terminal for other work, or configure your editor to launch it automatically (recommended).

Project detection: When no project is specified, Waystone auto-detects the project from the current working directory passed by the editor. If you always work in one project, scope it explicitly with --project to skip detection.

Claude Code

Add Waystone to your Claude Code MCP config. Open or create ~/.claude/settings.json:

{
  "mcpServers": {
    "waystone": {
      "command": "waystone",
      "args": ["mcp-serve"],
      "env": {}
    }
  }
}

Restart Claude Code. You'll see waystone_query, waystone_extract, waystone_stats, and waystone_list_projects listed in the available tools. Claude will call waystone_query automatically at the start of sessions where memory is relevant.

Per-project config

To scope the server to a specific project, set it in the project-level .claude/settings.json:

{
  "mcpServers": {
    "waystone": {
      "command": "waystone",
      "args": ["mcp-serve", "--project", "my-project"]
    }
  }
}

Zero-friction hooks

Add hooks to ~/.claude/settings.json so Waystone context is automatically injected before every prompt — no manual tool calls required.

{
  "mcpServers": {
    "waystone": {
      "command": "waystone",
      "args": ["mcp-serve"]
    }
  },
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "waystone last-context --raw"
        }]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "waystone extract --from-session --delta"
        }]
      }
    ]
  }
}

UserPromptSubmit — injects the last queried Waystone context before each prompt. Stop — automatically extracts facts from the session when Claude finishes responding. Together these give you full automatic memory with no manual intervention.

Agent instructions (CLAUDE.md)

Add to your project's CLAUDE.md or system prompt so Claude knows to actively use memory:

## Memory (Waystone)
At the start of each session, call waystone_query with a description of the current task.
After completing significant work or before ending a session, call waystone_extract with
a summary of what was built, decided, or changed.
Do not write to MEMORY.md — use Waystone tools instead.

Cursor

Open Cursor → Settings → MCP or create ~/.cursor/mcp.json:

{
  "mcpServers": {
    "waystone": {
      "command": "waystone",
      "args": ["mcp-serve"]
    }
  }
}

Reload Cursor. The tools appear in the Model Context panel and are available to the Cursor AI in Composer and Chat.

Windsurf

Open Windsurf → Settings → Extensions → MCP and add:

{
  "waystone": {
    "command": "waystone",
    "args": ["mcp-serve"]
  }
}

Save and restart the AI engine. Waystone tools will be available to Cascade.

Continue.dev

Open or create ~/.continue/config.yaml (global) or .continue/config.yaml in your project root:

mcpServers:
  - name: waystone
    command: waystone
    args:
      - mcp-serve

If you're using the JSON format (~/.continue/config.json), add an mcpServers array:

{
  "mcpServers": [
    {
      "name": "waystone",
      "command": "waystone",
      "args": ["mcp-serve"]
    }
  ]
}

Reload the Continue extension. The tools appear in the context panel and are available in Chat and Edit modes.

OpenClaw

Add to your openclaw.json configuration file:

{
  "mcpServers": {
    "waystone": {
      "command": "waystone",
      "args": ["mcp-serve"],
      "env": {
        "WAYSTONE_PROJECT": "my-project"
      }
    }
  }
}

OpenClaw uses a MEMORY.md convention by default. Waystone replaces this with a persistent structured graph. To migrate:

1. Import your existing MEMORY.md into Waystone: waystone extract my-project MEMORY.md
2. Update your agent instructions: replace "write to MEMORY.md" with "call waystone_extract"
3. Add session-start instruction: "call waystone_query with a description of the current task"

See the full OpenClaw integration guide for a complete agent instructions template and MEMORY.md migration walkthrough.

Cline

Cline stores MCP config in VS Code's extension storage. Open or create:

~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

On Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

{
  "mcpServers": {
    "waystone": {
      "command": "waystone",
      "args": ["mcp-serve"],
      "env": {
        "WAYSTONE_PROJECT": "my-project"
      }
    }
  }
}

Restart Cline. The MCP tools appear in the Cline panel. Cline will call waystone_query automatically when you describe a task that references prior context.

Zed

Open your Zed settings (Zed → Settings → Open Settings or Cmd ,) and add a context_servers block:

{
  "context_servers": {
    "waystone": {
      "command": "waystone",
      "args": ["mcp-serve"]
    }
  }
}

Save the settings file. Zed will start the Waystone context server automatically and make its tools available in the Assistant panel.

Codex

OpenAI Codex CLI stores its MCP config at ~/.codex/config.yaml. Add an mcpServers block:

mcpServers:
  waystone:
    command: waystone
    args:
      - mcp-serve
    env:
      WAYSTONE_PROJECT: my-project

Save the file and restart Codex. The waystone_query, waystone_extract, waystone_stats, and waystone_list_projects tools will appear in the Codex tool list.

To use the hosted API, add the optional env vars:

mcpServers:
  waystone:
    command: waystone
    args:
      - mcp-serve
    env:
      WAYSTONE_PROJECT: my-project
      WAYSTONE_API_KEY: your-api-key
      WAYSTONE_REMOTE_URL: https://api.waystone.unbidden.ai

Recommended agent instructions to add to your Codex system prompt or AGENTS.md:

## Memory (Waystone)
At the start of each session, call waystone_query with a description of the
current task to retrieve relevant context from prior sessions.

After completing significant work, call waystone_extract with a summary of
what was built, decided, or changed. Waystone will structure and store the
facts automatically.

Aider

Create or edit ~/.aider/mcp.json (global) or .aider/mcp.json in your project root:

{
  "mcpServers": {
    "waystone": {
      "command": "waystone",
      "args": ["mcp-serve"],
      "env": {
        "WAYSTONE_PROJECT": "my-project"
      }
    }
  }
}

Launch Aider with the config:

aider --mcp-config ~/.aider/mcp.json

Or add to .aider.conf.yml to apply automatically in the project:

mcp-config: .aider/mcp.json

See the full Aider integration guide for system prompt instructions and project initialization.

Gemini CLI

Open or create ~/.gemini/settings.json and add an mcpServers block:

{
  "mcpServers": {
    "waystone": {
      "command": "waystone",
      "args": ["mcp-serve"],
      "env": {
        "WAYSTONE_PROJECT": "my-project"
      }
    }
  }
}

Restart Gemini CLI. The Waystone tools will appear in the available tool list.

See the full Gemini CLI integration guide for system prompt instructions and GEMINI.md migration.

Tool reference

waystone_query

Retrieve facts relevant to a task description. This is the primary tool — call it at the start of a session or whenever you need to recall past decisions.

waystone_query(task, project?, cwd?, hops?, top_k?)

waystone_extract

Extract structured facts from a text snippet and store them in the project graph. Use this at the end of a session to persist what was decided or learned.

waystone_extract(text, project?, cwd?, source_name?, verify?)

waystone_stats

Return node counts and graph statistics for a project. Useful for confirming extraction succeeded or understanding what's in memory.

waystone_stats(project?, cwd?)

waystone_list_projects

List all projects in ~/.waystone/projects/. Takes no parameters.

waystone_list_projects()

Troubleshooting