# Hosted quickstart

Get up and running with SurrealDB Agent Memory on SurrealDB Cloud in five minutes.

This guide takes you from a blank terminal to your first **remember** and **recall** calls against **SurrealDB Agent Memory on SurrealDB Cloud**. Cloud runs the SurrealDB Agent Memory data plane, SurrealDB, and object store per context - you do not provision infrastructure yourself.

> [!NOTE]
> `Spectron` was the project name for SurrealDB Agent Memory. These type names
> will be renamed in a future release.

> [!NOTE]
> SurrealDB Agent Memory contexts are created in **[SurrealDB Studio](https://app.surrealdb.com)** (organisation → **Contexts**). See [SurrealDB Agent Memory on SurrealDB Cloud](/docs/agent-memory/quickstarts/surrealdb-cloud.md) for context setup and API keys. This page assumes you already have a **context host**, **context id**, and **API key** from the **API keys** view.

## Step 1 - Create a Context and API key (SurrealDB Studio)

1. Sign in to SurrealDB Cloud in SurrealDB Studio.
2. Open your organisation → **Contexts** (requires SurrealDB Agent Memory access on your profile).
3. Subscribe to a SurrealDB Agent Memory plan (owner) if needed, then **Create context** - name and region.
4. Open the context → **API keys** → create a key. Copy the secret immediately.

For a click-by-click version of this step, plus the Playground, Documents, and Memory views, see [Create your first context](/docs/agent-memory/quickstarts/surrealdb-cloud.md#create-your-first-context).

You will use:

- **Host** - shown as the endpoint, e.g. `https://abc123.spectron.cloud…` (per context, not a single global URL)
- **Context ID** - the context identifier
- **API key** - `sk-ctx-…` shown once at creation

## Step 2 - Set environment variables

```bash
export SPECTRON_URL="https://<your-context-host>"
export SPECTRON_CONTEXT_ID="<your-context-id>"
export SPECTRON_API_KEY="sk-ctx-..."
```

Use the exact **host** from SurrealDB Studio settings or API keys - not a generic placeholder domain.

## Step 2b - Register scope paths

Scoped writes require registered paths. With the CLI pointed at your context:

```bash
spectron scopes create org/acme \
  --url "$SPECTRON_URL" --api-key "$SPECTRON_API_KEY" --context-id "$SPECTRON_CONTEXT_ID"

spectron scopes create org/acme/user/alice \
  --url "$SPECTRON_URL" --api-key "$SPECTRON_API_KEY" --context-id "$SPECTRON_CONTEXT_ID"
```

Org admins can also register scopes through the SurrealDB Cloud API admin proxy when building custom tooling.

## Step 3 - Remember a fact

```bash
curl -sS "$SPECTRON_URL/api/v1/$SPECTRON_CONTEXT_ID/facts" \
  -H "Authorization: Bearer $SPECTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I was just promoted to CTO.",
    "infer": "full",
    "scope": ["org/acme/user/alice"]
  }'
```

The response includes a nested **`extraction`** object (entities, attributes, relations, …) plus `sessionId` and `turnId`.

## Step 4 - Recall

```bash
curl -sS "$SPECTRON_URL/api/v1/$SPECTRON_CONTEXT_ID/query" \
  -H "Authorization: Bearer $SPECTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is Alice'\''s role?",
    "scope": ["org/acme/user/alice"]
  }'
```

Check **`tier`** in the response - tier 1 or 2 hits avoid a full LLM synthesis pass. Use **`trace.traceId`** to fetch the full retrieval trace.

## Step 5 - Optional chat

```bash
curl -sS "$SPECTRON_URL/api/v1/$SPECTRON_CONTEXT_ID/chat" \
  -H "Authorization: Bearer $SPECTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarise what you know about me",
    "scope": ["org/acme/user/alice"]
  }'
```

## SDKs

Official clients: **`surrealdb`** (Python, includes `Spectron` / `AsyncSpectron`) and **`@surrealdb/spectron`** (TypeScript). Point them at `endpoint: process.env.SPECTRON_URL` (your context host). See [Integrations](/docs/agent-memory/integrations.md).

## Next steps

- [SurrealDB Agent Memory on SurrealDB Cloud](/docs/agent-memory/quickstarts/surrealdb-cloud.md) - Cloud API vs data plane
- [Sessions and turns](/docs/agent-memory/mental-model/sessions-and-turns.md)
- [Contexts and scope](/docs/agent-memory/mental-model/contexts-and-scope.md)
- [Uploading documents](/docs/agent-memory/ingest/authoritative/uploading-documents.md)