# Claude

Connecting SurrealDB Agent Memory to Claude Code, Cowork, and Claude Desktop.

The official [SurrealDB plugin marketplace for Claude](https://github.com/surrealdb/ai-claude-plugin) ships a **`spectron`** plugin that connects Claude to your SurrealDB Agent Memory instance's `/mcp` endpoint and installs a usage skill. It supports **Claude Code**, **Cowork**, and **Claude Desktop**. There is no default URL - point it at your own instance (SurrealDB Cloud: your context host from SurrealDB Studio **API keys**; self-hosted: your server's base URL).

## Claude Code and Cowork

### Install the plugin

Add the marketplace, then install the `spectron` plugin:

```bash
/plugin marketplace add surrealdb/ai-claude-plugin
/plugin install spectron@surrealdb
```

Claude Code reads the plugin directly - the MCP server and the usage skill load automatically.

### Configure

The SurrealDB Agent Memory MCP has no default URL. Set your instance endpoint and a bearer token before launching Claude Code, then restart:

```bash
export SPECTRON_MCP_URL="https://<your-spectron-instance>/mcp"
export SPECTRON_MCP_TOKEN="<your-api-key>"
```

If `SPECTRON_MCP_URL` is unset, the server will not connect. The plugin's MCP entry expands these variables:

```json
{
  "mcpServers": {
    "spectron": {
      "type": "http",
      "url": "${SPECTRON_MCP_URL}",
      "headers": {
        "Authorization": "Bearer ${SPECTRON_MCP_TOKEN}"
      }
    }
  }
}
```

The bearer token is your SurrealDB Agent Memory context API key. Each key is bound to one Context, so `context_id` is optional on every tool call.

### Verify the installation

```bash
claude mcp list
```

You should see **spectron** connected. In a session, ask "What MCP tools do you have access to?" and Claude should list the SurrealDB Agent Memory tools: `remember`, `recall`, `context`, `reflect`, `forget`, `upload`, `inspect`.

### Usage examples

**Remember architectural decisions as you code:**

```bash
claude "Remember that we have decided to use event sourcing for the orders service and that the aggregate root is OrderAggregate."
```

Claude Code calls `remember`. The next time you start a session in this project, `recall` surfaces this decision before Claude answers questions about the orders service.

**Recall context before a coding task:**

```bash
claude "What do you remember about our database schema decisions?"
```

## Claude Desktop

Claude Desktop has no plugin/marketplace format, so set it up manually. Both options use your instance's `/mcp` URL and a bearer token; there is no default.

### Option A - Connectors UI (recommended)

Open **Settings → Connectors → Add custom connector** and add:

| Name | URL | Header |
|---|---|---|
| `spectron` | your SurrealDB Agent Memory `/mcp` endpoint (for example `https://<your-spectron-instance>/mcp`) | `Authorization: Bearer <your-api-key>` |

### Option B - Manual config

Merge the following into `claude_desktop_config.json`, then restart Claude Desktop:

| Platform | Path |
|---|---|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |

```json
{
  "mcpServers": {
    "spectron": {
      "type": "http",
      "url": "https://<your-spectron-instance>/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}
```

You can validate the file with `cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool`.

### Skill (optional)

Claude Desktop cannot load plugins, but you can add the SurrealDB Agent Memory usage skill by hand: open **Settings → Skills → Upload skill** and upload the `plugins/spectron/skills/mcp/` folder from the [plugin repo](https://github.com/surrealdb/ai-claude-plugin).

### Verify the installation

1. Restart Claude Desktop completely (quit and reopen)
2. Start a new conversation
3. Click the tools icon (the hammer symbol) in the composer - the seven SurrealDB Agent Memory tools should appear
4. Ask "What MCP tools do you have?" and Claude should describe the SurrealDB Agent Memory tools

## Scope on tool calls

Narrow reads and writes with the per-tool **`scope`** argument (slash paths, for example `["org/acme/user/alice"]` or `["org/acme/project/orders-service"]`). Register paths with `spectron scopes create` before first use. Use separate contexts or distinct scope paths to keep memory isolated per repository.

## Removing SurrealDB Agent Memory

**Claude Code / Cowork:** remove the `spectron` plugin from the `/plugin` menu, or run `claude mcp remove spectron`.

**Claude Desktop:** remove the `spectron` connector, or delete the `"spectron"` key from `claude_desktop_config.json`, then restart Claude Desktop.