SurrealDB Agent Memory on SurrealDB Cloud is a managed data plane per context, orchestrated by the SurrealDB Cloud API and surfaced in SurrealDB Studio.
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 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.
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
In SurrealDB Studio, open Agent Memory from the left sidebar.
Click Deploy new context at the top of the screen.
Give the context a name. Any name works.
Select a region.
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.
Open Workbench from the left sidebar.
Describe facts, entities, and relationships in plain language. SurrealDB Agent Memory extracts them and stores them.
Ask SurrealDB Agent Memory a question. It answers from what it has learned.
Watch the Graph panel on the right. It fills out as SurrealDB Agent Memory ingests your conversations and documents.
Open the Activity panel on the right. It shows what SurrealDB Agent Memory recalls and learns from one message to the next.
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.
3. Add documents and inspect memory
Open Documents from the left sidebar. Upload files for SurrealDB Agent Memory to ingest.
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.
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.
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.