Getting started | SurrealDB Docs

Create a Spectron context in Surrealist, try the Playground, inspect memories, add knowledge, and call the API with a key.

How to find your contexts

Your contexts live inside the Surrealist dashboard right next to your SurrealDB Cloud instances and are thus visible the moment you select your organisation from the front menu.

To create your first context, choose Create context, give it a name, and select a region where it will be deployed.

Note

Context names cannot be changed, so be sure to make them as descriptive as needed.

Adding conversational knowledge

The easiest way to begin experimenting with a context is by opening up the Playground. This allows you to chat with the agent and watch as memories are formed. You will be able to see a stream of new memories, along with retrieved memories that show what has been recalled by the agent as you chat.

Viewing memories

Once your chat is done, open Memories from the sidebar, where you can inspect the memory graph built from your conversation with the agent.

Adding knowledge

From the sidebar, open Knowledge to go beyond chat-only data to add source-backed knowledge. Inside this view you will see the kinds of sources you can plug in, for example:

PDF
Markdown
JSON
Documents
Web pages
Images
Audio
Media

If you don't have any knowledge sources off hand that you'd like to add, try copying this sample mini dataset in JSON format containing some information on various musical instruments.

{
  "instruments": [
    {
      "id": "violin",
      "name": "Violin",
      "family": "Strings",
      "type": "Bowed string",
      "size": "Small",
      "range": "G3–A7",
      "origin": "Italy",
      "typical_usage": ["Orchestra", "Chamber music", "Solo"],
      "related_instruments": ["viola", "cello"],
      "description": "A high-pitched string instrument played with a bow, known for its expressive tone."
    },
    {
      "id": "cello",
      "name": "Cello",
      "family": "Strings",
      "type": "Bowed string",
      "size": "Large",
      "range": "C2–A5",
      "origin": "Italy",
      "typical_usage": ["Orchestra", "Chamber music", "Solo"],
      "related_instruments": ["violin", "double_bass"],
      "description": "A deep-toned string instrument played seated, valued for its rich and warm sound."
    },
    {
      "id": "flute",
      "name": "Flute",
      "family": "Woodwinds",
      "type": "Aerophone",
      "size": "Small",
      "range": "C4–C7",
      "origin": "Global",
      "typical_usage": ["Orchestra", "Solo", "Band"],
      "related_instruments": ["piccolo", "clarinet"],
      "description": "A high-pitched woodwind instrument that produces sound from air blown across an opening."
    },
    {
      "id": "clarinet",
      "name": "Clarinet",
      "family": "Woodwinds",
      "type": "Single-reed",
      "size": "Medium",
      "range": "E3–C7",
      "origin": "Germany",
      "typical_usage": ["Orchestra", "Jazz", "Band"],
      "related_instruments": ["flute", "oboe"],
      "description": "A versatile woodwind instrument with a wide range and warm tone."
    },
    {
      "id": "trumpet",
      "name": "Trumpet",
      "family": "Brass",
      "type": "Lip-vibrated",
      "size": "Medium",
      "range": "F#3–D6",
      "origin": "Ancient civilisations",
      "typical_usage": ["Orchestra", "Jazz", "Band"],
      "related_instruments": ["trombone", "horn"],
      "description": "A bright and powerful brass instrument commonly used for fanfares and melodies."
    },
    {
      "id": "trombone",
      "name": "Trombone",
      "family": "Brass",
      "type": "Slide brass",
      "size": "Large",
      "range": "E2–F5",
      "origin": "Europe",
      "typical_usage": ["Orchestra", "Jazz", "Band"],
      "related_instruments": ["trumpet", "tuba"],
      "description": "A brass instrument with a telescoping slide used to vary pitch."
    },
    {
      "id": "piano",
      "name": "Piano",
      "family": "Keyboard",
      "type": "Hammered string",
      "size": "Large",
      "range": "A0–C8",
      "origin": "Italy",
      "typical_usage": ["Solo", "Accompaniment", "Composition"],
      "related_instruments": ["harpsichord"],
      "description": "A versatile keyboard instrument capable of playing melody and harmony simultaneously."
    },
    {
      "id": "guitar",
      "name": "Guitar",
      "family": "Strings",
      "type": "Plucked string",
      "size": "Medium",
      "range": "E2–E6",
      "origin": "Spain",
      "typical_usage": ["Solo", "Band", "Accompaniment"],
      "related_instruments": ["bass_guitar", "ukulele"],
      "description": "A popular string instrument used across many genres, played by plucking or strumming."
    },
    {
      "id": "drum_kit",
      "name": "Drum Kit",
      "family": "Percussion",
      "type": "Membranophone",
      "size": "Large",
      "range": "Varies",
      "origin": "Global",
      "typical_usage": ["Band", "Jazz", "Rock"],
      "related_instruments": ["snare_drum", "cymbals"],
      "description": "A collection of percussion instruments played together to provide rhythm."
    },
    {
      "id": "harp",
      "name": "Harp",
      "family": "Strings",
      "type": "Plucked string",
      "size": "Large",
      "range": "C1–G7",
      "origin": "Ancient civilisations",
      "typical_usage": ["Orchestra", "Solo"],
      "related_instruments": ["lyre"],
      "description": "A large string instrument with strings stretched vertically, played by plucking."
    }
  ]
}

API keys

To add knowledge to your context outside of the Surrealist UI, you will want to go to the API keys page to get an API key. This will allow you to interact with a context through cURL commands or your preferred SDK language.

Inside this window you can see your base Spectron url, a random ID for your context (06eqs1luktt4d505nfchtdrfmo, for example) and a section to manage your API keys. While you can create multiple API keys, the actual key will only be displayed once so be sure to save it.

The easiest way to experiment with a new API key is to click on the cURL section, which contains a few examples that only require you to paste in your API key to use. They can then be pasted into a terminal window to see the result.

# Add a memory
curl -X POST https://... \
-H "Authorization: Token sk-ctx-..." \
-H "Content-Type: application/json" \
-d '{
  "messages": [{"role": "user", "content": "I prefer dark mode."}],
  "user_id": "user-123"
}'

# Search memories
curl -X POST https://... \
-H "Authorization: Token sk-ctx-..." \
-H "Content-Type: application/json" \
-d '{
  "query": "What are the user preferences?",
  "filters": {"AND": [{"user_id": "user-123"}]}
}'

The same section includes sample queries of the same nature for various programming languages such as JavaScript, Python, and Rust.

Endpoints

The endpoints available to work with your context through an API key are as follows:

add_memory
create_memory_field
delete_memory
get_memory
get_memory_llm_usage
health_check
is_memory_ingesting
list_memories
list_memory_fields
query