# MCP tools reference

Complete reference for all seven SurrealDB Agent Memory MCP tools.

SurrealDB Agent Memory exposes seven tools over the Model Context Protocol at `/mcp`: **`remember`**, **`recall`**, **`context`**, **`reflect`**, **`forget`**, **`upload`**, and **`inspect`**. All tools use the same **`Authorization: Bearer`** authentication as the REST API. Point the MCP URL at `https://<your-context-host>/mcp` on SurrealDB Cloud.

> [!NOTE]
> Older docs used names such as `memory_store`, `memory_recall`, and `knowledge_search`. Those prefixes are retired - use the short names above.

> [!NOTE]
> REST-aligned responses use **camelCase** (`queryMs`, `traceId`, `trace.traceId`). **Scope** arguments are slash paths (for example `org/acme/user/alice`). Register paths with `spectron scopes create` before use.

## Common fields

Tool responses correlate with graph-resident traces via **`traceId`** or **`trace.traceId`** (depending on the underlying endpoint). Use `GET .../traces/{traceId}` for the full record, or MCP **`inspect`** with `ref: "trace:<id>"`.

Every tool accepts an optional **`context_id`**. When omitted, the server uses the Context bound to the bearer API key. An explicit `context_id` that does not match that binding returns **`401`**.

---

## `remember`

Store a conversational exchange or free-text fact. SurrealDB Agent Memory auto-classifies content, reconciles against existing memory, and persists structured records.

**REST equivalent:** `POST /api/v1/{context_id}/facts`

### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `text` | string | Yes | Content to remember |
| `session_id` | string | No | Existing session to append to |
| `scope` | string[] or nested arrays | No | DNF write selector within `memory:write` |
| `labels` | string[] | No | Descriptive `key=value` labels |
| `infer` | `"full"` \| `"preview"` \| `"none"` | No | Default `full` |
| `context_id` | string | No | Omit to use the bearer key's Context |

### Output

Structured diff: entities, attributes, relations, instructions, uncertainties, corrections, plus a stand-in `trace_id`.

### Example

```
Tool: remember
Input: {
  "text": "I just got promoted to VP of Engineering and I'm moving to Singapore next month.",
  "scope": ["org/acme/user/alice"]
}
```

---

## `recall`

Unified search over experiential facts and document passages. Returns ranked hits (not a synthesised answer).

**REST equivalent:** `POST /api/v1/{context_id}/query`

### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string | Yes | Natural-language question |
| `k` | integer | No | Hit count (default 10, max 50) |
| `mode` | string | No | `vector` \| `bm25` \| `graph` \| `hybrid` |
| `lens` | string[] or nested arrays | No | DNF read lens |
| `labels` | string[] | No | Optional filters |
| `context_id` | string | No | Omit to use the bearer key's Context |

### Example

```
Tool: recall
Input: {
  "query": "What role does Alice have?",
  "k": 10,
  "lens": ["org/acme"]
}
```

---

## `context`

Assemble a markdown context block for prompt injection (profile + relevant facts).

**REST equivalent:** `POST /api/v1/{context_id}/context`

### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string | Yes | What context to assemble |
| `lens` | string[] or nested arrays | No | DNF read lens |
| `labels` | string[] | No | Optional filters |
| `context_id` | string | No | Omit to use the bearer key's Context |

---

## `reflect`

Synthesise insights across memory. Optionally persist with `persist: true`.

**REST equivalent:** `POST /api/v1/{context_id}/reflect`

### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string | Yes | Synthesis question |
| `persist` | boolean | No | Default `false` |
| `context_id` | string | No | Omit to use the bearer key's Context |

---

## `forget`

Soft-delete attributes that match a natural-language query. Use `purge: true` for permanent erasure including history.

**REST equivalent:** `POST /api/v1/{context_id}/forget`

### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string | Yes | What to stop believing |
| `purge` | boolean | No | Also erase supersession history |
| `context_id` | string | No | Omit to use the bearer key's Context |

---

## `upload`

Upload a document (base64). Processing is asynchronous - poll with `inspect` or REST.

**REST equivalent:** `POST /api/v1/{context_id}/documents`

### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `bytes_base64` | string | Yes | Document bytes (RFC 4648) |
| `title` | string | No | Display title |
| `source` | string | No | Provenance string |
| `mime_type` | string | No | MIME type |
| `filename` | string | No | Original filename |
| `scopes` | nested arrays | No | DNF write selector (`scope` alias accepted) |
| `labels` | string[] | No | Labels on the document |
| `context_id` | string | No | Omit to use the bearer key's Context |

### Example

```
Tool: upload
Input: {
  "bytes_base64": "aGVsbG8=",
  "title": "Team handbook",
  "scopes": [["org/acme/team/eng"]],
  "labels": ["team=eng"]
}
```

---

## `inspect`

Look up an entity, trace, or document by typed reference.

**REST equivalents:** `GET .../entities/...`, `GET .../traces/{id}`, `GET .../documents/{id}`

### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `ref` | string | Yes | `entity:<Type>/<Name>`, `trace:<id>`, or `document:<id>` |
| `context_id` | string | No | Omit to use the bearer key's Context |

### Example

```
Tool: inspect
Input: {
  "ref": "document:01hx9…"
}
```

---

## Errors

Operation failures return **`isError: true`** tool results with `structuredContent.error.status` mirroring REST (404, 403, 429, 401, 500). JSON-RPC **`error`** is reserved for protocol faults (bad params, unknown tool). Auth and missing-Context failures are masked as **401**. See [MCP tools - error handling](/docs/agent-memory/reference/mcp-tools.md#error-handling).