# Agent Memory on SurrealDB Cloud

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

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://app.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 Playground, Memory, 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 |
| Playground (live chat + memory updates) | Yes |
| Memory explorer (entities, relations, traces) | 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 Playground, Memory, and Documents in a context that already exists.

### 1. Deploy a context

1. In [SurrealDB Studio](https://studio.surrealdb.com), open **Contexts** 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. **US West** is the region available today.
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 Playground

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

1. Open **Playground** 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]
> Playground 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 **Memory** from the left sidebar. Review the entities SurrealDB Agent Memory stores and the traces behind your Playground messages.

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)