> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Agent Memory on SurrealDB Cloud

How contexts, authentication and the APIs work on SurrealDB Cloud. For SurrealDB Agent Memory.

SurrealDB Agent Memory on **SurrealDB Cloud** is a managed data plane per **context**, orchestrated by the **SurrealDB Cloud API** and surfaced in **[SurrealDB Studio](https://studio.surrealdb.com)**.

## Two planes

| Plane | Base URL | Who uses it | Purpose |
| --- | --- | --- | --- |
| **Cloud API** | `https://api.surrealdb.com/v1/…` | SurrealDB Studio, your automation | Context lifecycle, billing, API keys, admin proxies |
| **SurrealDB Agent Memory data API** | `https://{context.host}/api/v1/…` | Your app, SDKs, MCP | Memory, knowledge, chat, documents |

Customers integrate against the **context host** and **`sk-ctx-…` API keys** from SurrealDB Studio. They do **not** receive SurrealDB Agent Memory root management keys or `SPECTRON_*` node configuration.

## Organisation roles

| Role | Typical Cloud capabilities |
| --- | --- |
| **Owner** | Subscribe to SurrealDB Agent Memory plans, billing, delete contexts |
| **Admin** | Create contexts, mint API keys, call admin proxy routes (principals, scopes, grants, usage) |
| **Member** | Use Workbench, Lookup, Knowledge graph, Documents, and Scopes in SurrealDB Studio; broker a short-lived access token for SDK use |

Admin proxy routes return **403** for members. See [Key policy](/docs/agent-memory/reference/configuration.md#key-policy) for how self-service and Cloud-brokered keys are governed.

## What SurrealDB Studio exposes

| Feature | In SurrealDB Studio |
| --- | --- |
| Context list, deploy, billing, delete | Yes |
| API keys + per-context endpoint | Yes |
| Overview (principal, access, and what lives in the context) | Yes |
| Workbench (chat, tune retrieval, inspect what a reply recalled and learned) | Yes |
| Lookup (ask what the context knows about one thing) | Yes |
| Knowledge graph (everything the context knows as one navigable graph) | Yes |
| Documents (upload, browse, search) | Yes |
| Scopes (register and browse paths) | Yes |
| Integration snippets (SDK, REST, MCP, frameworks) | Yes |
| Settings - users, configuration, usage | Admins and owners |

For terminal-first **remember** / **recall**, see [Hosted quickstart](/docs/agent-memory/quickstarts/hosted.md).

## Create your first context

This walkthrough uses SurrealDB Studio only - no terminal and no API key. When you finish, you will have a live context that stores and recalls memory.

You need the **Owner** or **Admin** role to deploy a context. Members can use the Workbench, Lookup, and Documents in a context that already exists.

### 1. Deploy a context

1. In [SurrealDB Studio](https://studio.surrealdb.com), open **Agent Memory** from the left sidebar.
2. Click **Deploy new context** at the top of the screen.
3. Give the context a name. Any name works.
4. Select a region.
5. Click **Create context**. Provisioning takes a minute or two.

When provisioning finishes, Studio opens the context screen. The context is ready to use.

### 2. Explore in the Workbench

The Workbench is a chat surface that writes to memory as you use it.

1. Open **Workbench** from the left sidebar.
2. Describe facts, entities, and relationships in plain language. SurrealDB Agent Memory extracts them and stores them.
3. Ask SurrealDB Agent Memory a question. It answers from what it has learned.
4. Watch the **Graph** panel on the right. It fills out as SurrealDB Agent Memory ingests your conversations and documents.
5. Open the **Activity** panel on the right. It shows what SurrealDB Agent Memory recalls and learns from one message to the next.

> [!NOTE]
> Workbench turns are durable memory in this context, and they compete with your own data at retrieval time. For a clean evaluation run, use a separate context. See [Contexts and scope](/docs/agent-memory/mental-model/contexts-and-scope.md).

### 3. Add documents and inspect memory

1. Open **Documents** from the left sidebar. Upload files for SurrealDB Agent Memory to ingest.
2. Open **Lookup** from the left sidebar and ask what the context knows about a topic. It answers from the facts it holds on that topic, drawn from your Workbench turns and the documents you uploaded.
3. Open **Knowledge graph** to see everything the context knows as one navigable graph, rather than one topic at a time.

Your context is now live and learning. To move from Studio to code, create an API key in the context's **API keys** view, then follow the [Hosted quickstart](/docs/agent-memory/quickstarts/hosted.md).

## Scope on Cloud

Data-plane **scope** uses hierarchical slash paths - for example `[["org/acme/user/alice"]]` on writes and **`lens`** on reads. Register paths in SurrealDB Studio **Scopes**, via the CLI, or through the Cloud admin scopes proxy.

## Related reading

- [Hosted quickstart](/docs/agent-memory/quickstarts/hosted.md)
- [Contexts and scope](/docs/agent-memory/mental-model/contexts-and-scope.md)
- [REST API](/docs/agent-memory/reference/rest-api.md)