Hosted quickstart

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.

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

1. 1.

   Sign in to SurrealDB Cloud in SurrealDB Studio.

2. 2.

   Open your organisation → Contexts (requires SurrealDB Agent Memory access on your profile).

3. 3.

   Subscribe to a SurrealDB Agent Memory plan (owner) if needed, then Create context - name and region.

4. 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.

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

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:

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

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

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

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.

Next steps

• •

  SurrealDB Agent Memory on SurrealDB Cloud - Cloud API vs data plane

• •

  Sessions and turns

• •

  Contexts and scope

• •

  Uploading documents