Python SDK

The Spectron client ships inside the main SurrealDB Python package (surrealdb). Install one package and import Spectron or AsyncSpectron alongside the database driver.

Package naming: On PyPI, the Spectron client ships in the surrealdb package alongside the database driver — use pip install surrealdb. The bare name spectron belongs to an unrelated project; do not install it for SurrealDB Spectron.

Installation

pip install surrealdb

Python 3.10+ recommended.

Clients

Spectron is synchronous (uses requests). AsyncSpectron is async (uses aiohttp). Both expose the same method names — add await on the async client.

from surrealdb import Spectron, AsyncSpectron

with Spectron(
    context="acme-prod",
    endpoint="https://api.spectron.example",
    api_key="sk-spec-...",
) as memory:
    memory.remember("Alice was promoted to CTO.")
    hits = memory.recall("What is Alice's role?", k=10)
    for hit in hits.hits:
        print(hit.score, hit.text)

async with AsyncSpectron(
    context="acme-prod",
    endpoint="https://api.spectron.example",
    api_key="sk-spec-...",
) as memory:
    await memory.remember("Alice was promoted to CTO.")
    hits = await memory.recall("What is Alice's role?", k=10)

Both clients are pinned to one context and call /api/v1/{context}/…. Pass context, endpoint, and api_key explicitly — the SDK does not read environment variables.

Scope

On the wire, scope is a ScopeSet: an ordered array of slash-path strings (for example ["org/acme/user/alice"]). Register paths with spectron scopes create before first use — see Contexts and scope.

The Python client accepts:

• A single path: scope="org/acme/user/alice"

• A list of paths: scope=["org/acme/user/alice"]

Remember (facts)

memory.remember("Alice was promoted to CTO.", infer="full", scope=["org/acme/user/alice"])
memory.remember("Q3 board notes", labels=["topic=board"], memory_category="context")

memory.remember_many(
    [
        {"role": "user", "content": "I was promoted to CTO."},
        {"role": "assistant", "content": "Congratulations!"},
    ],
    extract="whole_conversation",
    scope=["org/acme/user/alice"],
)

remember and remember_many send an Idempotency-Key header (derived from method, path, body, and a 30-second bucket) so safe retries collapse server-side.

Recall and context

result = memory.recall(
    "What is Alice's role?",
    k=10,
    mode="hybrid",
    scope=["org/acme/user/alice"],
)

block = memory.query_context(
    "What is Alice's role?",
    k=10,
    scope=["org/acme/user/alice"],
)

Optional filters include labels, lens, scope_view (strict | merged | crossTeam), temporal bounds (as_of, valid_from, …), and geo location.

Documents

upload = memory.documents.upload(
    "policy.pdf",
    content_type="application/pdf",
    title="Returns policy",
    scope=["org/acme/team/eng"],
    labels=["team=eng"],
)
doc = memory.documents.get(upload.id)
hits = memory.documents.query("refund window", k=5, mode="hybrid")
chunks = memory.documents.chunks(upload.id)
memory.documents.keywords.search("returns policy", k=10)

Chat (including streaming)

reply = memory.chat("Summarise what you know about Alice", scope=["user/alice"])
print(reply.reply)

for chunk in memory.chat("Summarise what you know about Alice", stream=True):
    if chunk.delta:
        print(chunk.delta, end="", flush=True)
    if chunk.done:
        print("\n[trace]", chunk.trace_id)

Other verbs and namespaces

Top-level methods: consolidate, reflect, elaborate, forget, state, whoami, profile, inspect, audit, health.

Grouped resources: memory.documents, memory.sessions, memory.entities, memory.scopes, memory.principals, memory.keys, memory.traces, memory.lifecycle.

→ Full method tables: Python SDK reference

Response types

Typed dataclasses include RememberResponse, RecallResponse, RecallHit, ChatResponse, Document, Chunk, StateResponse, and others. Import from surrealdb.spectron when you need explicit types:

from surrealdb.spectron import RecallResponse, RecallHit

Harness adapter (zero prompt change)

For LangChain-style apps that should auto-record every turn:

pip install surrealdb spectron-langchain

→ LangChain

CLI alternative

The spectron binary exposes the same operations without the SDK:

spectron remember "Alice was promoted to CTO."
spectron recall "What is Alice's role?" --json

→ CLI reference · REST API