### Install the Spectron plugin

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/openclaw

Commands to install the plugin, initialize the setup, and restart the gateway.

```bash
openclaw plugins install @surrealdb/spectron-openclaw
openclaw spectron setup
openclaw gateway restart
```

--------------------------------

### Install dependencies

Source: https://surrealdb.com/docs/spectron/integrations/voice/livekit

Install the necessary LiveKit agent plugins and the Spectron client.

```bash
pip install "livekit-agents[openai,silero]" surrealdb
```

--------------------------------

### Install Dependencies

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/llamaindex

Install the required LlamaIndex and SurrealDB packages.

```bash
pip install llama-index surrealdb
```

--------------------------------

### Install dependencies

Source: https://surrealdb.com/docs/spectron/integrations/observability/agentops

Install the required packages for AgentOps, SurrealDB, and OpenAI.

```bash
pip install agentops surrealdb openai
```

--------------------------------

### Install dependencies

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/autogen

Install the required AutoGen and Spectron packages.

```bash
pip install autogen-agentchat autogen-ext[openai] surrealdb
```

--------------------------------

### Install and Import Spectron SDK

Source: https://surrealdb.com/docs/spectron/integrations/sdks/go

Commands to install the package and import it into your Go project.

```bash
go get github.com/surrealdb/surrealdb.go/spectron
```

```go
import "github.com/surrealdb/surrealdb.go/spectron"
```

--------------------------------

### Install dependencies

Source: https://surrealdb.com/docs/spectron/integrations/ai-sdks/tanstack-ai

Install the required Spectron and TanStack AI packages.

```bash
npm install @surrealdb/spectron @tanstack/ai @tanstack/ai-openai
```

--------------------------------

### Installing Spectron Framework Adapters

Source: https://surrealdb.com/docs/spectron/integrations/sdks/python

Install the necessary adapter packages to enable automatic turn recording for specific agent frameworks.

```bash
pip install spectron-crewai   # CrewAI
pip install spectron-openai-agents        # OpenAI Agents SDK
pip install spectron-strands              # Strands Agents
pip install spectron-google-adk           # Google ADK
```

--------------------------------

### Install Dependencies

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/camel-ai

Install the required packages for Camel AI and Spectron.

```bash
pip install camel-ai surrealdb
```

--------------------------------

### Install LangChain packages

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/langchain

Install the required SurrealDB LangChain and Spectron packages using bun.

```bash
bun add @surrealdb/langchain @surrealdb/langgraph @surrealdb/spectron
```

--------------------------------

### Initialize Spectron SDK

Source: https://surrealdb.com/docs/spectron/reference/agents

SDK initialization examples for Python and TypeScript environments.

```python
from surrealdb import Spectron

memory = Spectron(context="acme-prod",
    api_key=os.environ["SPECTRON_API_KEY"])
await memory.sessions.create(scope=["org/acme/user/alice"])
```

```typescript
import { Spectron } from "@surrealdb/spectron";

const memory = new Spectron({ context: "acme-prod",
    apiKey: process.env.SPECTRON_API_KEY });
```

--------------------------------

### Verifying Spectron installation

Source: https://surrealdb.com/docs/spectron/self-hosting/deployment/bare-metal

Check the installed version of the spectrond binary.

```bash
spectrond --version
```

--------------------------------

### Install dependencies

Source: https://surrealdb.com/docs/spectron/integrations/observability/respan

Install the required Python packages for SurrealDB and OpenAI.

```bash
pip install surrealdb openai
```

--------------------------------

### Install MCP Helper

Source: https://surrealdb.com/docs/spectron/reference/agents

Command to install the Spectron MCP client for specific environments.

```bash
npx install-mcp spectron --client cursor --context <context_id>
```

--------------------------------

### Install spectron-strands

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/strands-agents

Installation commands for the base package and optional Bedrock support.

```bash
pip install spectron-strands
```

```bash
pip install "spectron-strands[bedrock]"
```

--------------------------------

### Install spectron-google-adk

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/google-adk

Install the package to enable Spectron memory tools for Google ADK.

```bash
pip install spectron-google-adk
```

```bash
pip install "spectron-google-adk" "surrealdb[spectron]"
```

--------------------------------

### Spectron SDK Initialization

Source: https://surrealdb.com/docs/spectron/reference/agents

Examples for initializing the Spectron SDK in Python and TypeScript.

```APIDOC
## SDK Initialization

### Python
```python
from surrealdb import Spectron

memory = Spectron(context="acme-prod", api_key=os.environ["SPECTRON_API_KEY"])
await memory.sessions.create(scope=["org/acme/user/alice"])
```

### TypeScript
```typescript
import { Spectron } from "@surrealdb/spectron";

const memory = new Spectron({ 
  context: "acme-prod", 
  apiKey: process.env.SPECTRON_API_KEY 
});
```
```

--------------------------------

### Install Spectron for Claude Desktop

Source: https://surrealdb.com/docs/spectron/integrations/mcp-server/coding-assistants/claude-desktop-and-code

Use the npx installer to automatically configure Spectron for Claude Desktop.

```bash
npx install-mcp spectron --client claude-desktop --context acme-prod
```

--------------------------------

### Install Vercel AI SDK adapter

Source: https://surrealdb.com/docs/spectron/integrations/sdks/javascript-and-typescript

Use this command to install the SurrealDB adapter for the Vercel AI SDK.

```bash
npm install @surrealdb/vercel-ai
```

--------------------------------

### Install Spectron OpenAI Agents package

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/openai-agents

Install the required library via pip.

```bash
pip install spectron-openai-agents
```

--------------------------------

### Install Agno and Spectron dependencies

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/agno

Install the required packages for Agno, Spectron, and OpenAI integration.

```bash
pip install agno surrealdb openai
```

--------------------------------

### Install Spectron for Eve

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/eve

Install the required package and peer dependencies in an Eve project.

```bash
bun add @surrealdb/spectron-eve
# peers, already present in an Eve project:
bun add eve zod
```

--------------------------------

### Install Spectron SDK

Source: https://surrealdb.com/docs/spectron/integrations/ai-sdks/cloudflare-workers-ai

Install the required Spectron SDK package via npm.

```bash
npm install @surrealdb/spectron
```

--------------------------------

### Install Mastra integration

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/mastra

Install the SurrealDB Mastra integration package.

```bash
bun add @surrealdb/mastra-ai
```

--------------------------------

### Install spectron-crewai

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/crewai

Install the required package via pip.

```bash
pip install spectron-crewai
```

--------------------------------

### Install Spectron Vercel AI SDK

Source: https://surrealdb.com/docs/spectron/integrations/ai-sdks/vercel-ai-sdk

Install the required packages including the Spectron integration and your chosen model provider.

```bash
npm i @surrealdb/vercel-ai ai @surrealdb/spectron
# plus your model provider, e.g.
npm i @ai-sdk/openai
```

--------------------------------

### Start the Spectron stack

Source: https://surrealdb.com/docs/spectron/quickstarts/self-hosted

Initializes the Spectron service using Docker Compose.

```bash
docker compose up -d
```

--------------------------------

### Install SurrealDB dependency

Source: https://surrealdb.com/docs/spectron/integrations/automation/zo-computer

Install the required Python SDK for Spectron integration.

```bash
pip install surrealdb
```

--------------------------------

### Verify MCP installation

Source: https://surrealdb.com/docs/spectron/integrations/mcp-server/coding-assistants/codex

List all configured MCP servers to ensure Spectron is correctly installed.

```bash
codex mcp list
```

--------------------------------

### Start MCP Server

Source: https://surrealdb.com/docs/spectron/integrations

Command to initialize the native MCP server on the API port.

```bash
spectron mcp
```

--------------------------------

### Object Store URL Examples

Source: https://surrealdb.com/docs/spectron/self-hosting/deployment/architecture-overview

Supported URL formats for configuring the object store backend.

```text
Local| file:///absolute/path
Amazon S3| s3://bucket/prefix?region=us-east-1
Google Cloud Storage| gs://bucket/prefix
Azure| az://container/prefix
```

--------------------------------

### Install Spectron MCP Server

Source: https://surrealdb.com/docs/spectron/integrations/mcp-server/coding-assistants/vscode

Commands to install the Spectron MCP server for either the current workspace or globally.

```bash
npx install-mcp spectron --client vscode --context acme-prod
```

```bash
npx install-mcp spectron --client vscode --context acme-prod --global
```

--------------------------------

### Install Spectron Pydantic AI dependencies

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/pydantic-ai

Install the core package or the full suite including model providers and database drivers.

```bash
pip install spectron-pydantic-ai
```

```bash
pip install "spectron-pydantic-ai" "pydantic-ai-slim[openai]" "surrealdb[spectron]"
```

--------------------------------

### Install Zod dependency

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/mastra

Install Zod as a required dependency for the Spectron client.

```bash
bun add zod
```

--------------------------------

### Initialize and Chat with JavaScript SDK

Source: https://surrealdb.com/docs/spectron/agent-memory/sessions/chat-sessions

Basic setup for creating a session and sending a chat message using the JavaScript SDK.

```javascript
import { Spectron } from "@surrealdb/spectron";

const memory = new Spectron({ context: "acme-prod",
    apiKey: process.env.SPECTRON_API_KEY });
const session = await memory.sessions.create({ scope: ["org/acme/user/alice"] });

const reply = await session.chat({ message: "What do you know about me?" });

console.log(reply.reply);          // The model's response string
console.log(reply.memoryUpdates);  // Entities, attributes, relations,
    corrections
```

--------------------------------

### Manage systemd service lifecycle

Source: https://surrealdb.com/docs/spectron/self-hosting/deployment/bare-metal

Commands to reload systemd, enable, and start the service.

```bash
systemctl daemon-reload
systemctl enable spectron
systemctl start spectron
```

--------------------------------

### Install Spectron for Claude Code

Source: https://surrealdb.com/docs/spectron/integrations/mcp-server/coding-assistants/claude-desktop-and-code

Use the npx installer to automatically configure Spectron for Claude Code.

```bash
npx install-mcp spectron --client claude-code --context acme-prod
```

--------------------------------

### Install the Spectron package

Source: https://surrealdb.com/docs/spectron/integrations/sdks/dart

Add the dependency to your pubspec.yaml file and fetch the package.

```yaml
dependencies:
  surrealdb:
```

```bash
dart pub get
# or, in a Flutter project
flutter pub get
```

--------------------------------

### Install Spectron MCP server

Source: https://surrealdb.com/docs/spectron/integrations/mcp-server/coding-assistants/cursor

Run this command in your terminal to install the Spectron MCP server for Cursor, replacing the context ID as needed.

```bash
npx install-mcp spectron --client cursor --context acme-prod
```

--------------------------------

### Start Development Runtime

Source: https://surrealdb.com/docs/spectron/reference/cli

Runs the API, worker, and scheduler in a single process for local development.

```bash
spectrond dev start \
  --connection-string "$SURREALDB_CONNECTION" \
  --bind-address 0.0.0.0:9090
```

--------------------------------

### Configure provider keys and models via environment variables

Source: https://surrealdb.com/docs/spectron/self-hosting/operations/models-and-providers

Set these environment variables before starting the server to define global provider keys and default model assignments.

```bash
# Provider keys
SPECTRON_OPENAI_API_KEY=sk-…
SPECTRON_ANTHROPIC_API_KEY=sk-ant-…

# Model defaults (optional – these are the built-in defaults)
SPECTRON_MODEL_EXTRACTION=gpt-4o-mini
SPECTRON_MODEL_QUERY_UNDERSTANDING=gpt-4o-mini
SPECTRON_MODEL_RESPONSE=gpt-4o
SPECTRON_MODEL_REFLECTION=gpt-4o
SPECTRON_MODEL_BACKGROUND=gpt-4o-mini
SPECTRON_MODEL_EMBEDDING=text-embedding-3-small
```

--------------------------------

### Claude Code Usage Examples

Source: https://surrealdb.com/docs/spectron/integrations/mcp-server/coding-assistants/claude-desktop-and-code

Examples of interacting with Spectron tools via the Claude Code CLI.

```bash
claude "Remember that we have decided to use event sourcing for the orders service and that the aggregate root is OrderAggregate."
```

```bash
claude "What do you remember about our database schema decisions?"
```

--------------------------------

### Initialize Strands Agent with Spectron Tools

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/strands-agents

Basic setup to integrate Spectron memory tools into a Strands agent.

```python
from strands import Agent
from spectron_strands import spectron_tools

agent = Agent(tools=spectron_tools())

agent("Remember that we signed a contract with Meditech Solutions for 1.2M GBP.")
print(agent("What is the value of the Meditech Solutions contract?"))
```

--------------------------------

### Instruction profile structure

Source: https://surrealdb.com/docs/spectron/agent-memory/reasoning/instructions-and-uncertainties

Example JSON structure showing active instructions returned in a profile.

```json
{
  "instructions": [
    {
      "label": "Bullet-point responses",
      "description": "Always respond using bullet points, never flowing prose"
    }
  ]
}
```

--------------------------------

### Initialize session context

Source: https://surrealdb.com/docs/spectron/cookbooks/build/coding-agent-with-project-memory

Retrieve ongoing work, conventions, and decisions at the start of a session.

```text
Tool: context
→ Returns: ongoing work, conventions, decisions, preferences

Tool: recall (query = user's first message)
→ Returns: relevant documentation passages
```

--------------------------------

### Install Spectron Hermes Agent

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/hermes

Install the required package via pip to enable Spectron memory provider functionality.

```bash
pip install spectron-hermes-agent
```

--------------------------------

### Install Spectron MCP Server

Source: https://surrealdb.com/docs/spectron/integrations/mcp-server/coding-assistants/windsurf

Use the install-mcp command to automatically configure Spectron for Windsurf with a specific context.

```bash
npx install-mcp spectron --client windsurf --context acme-prod
```

--------------------------------

### Initialize the Spectron client

Source: https://surrealdb.com/docs/spectron/cookbooks/build/customer-support-agent

Set up the client and memory instance with a specific context ID.

```python
from surrealdb import Spectron

client = Spectron(api_key="sk-...")
memory = client.memory(context_id="support")
```

```javascript
import { Spectron } from "@surrealdb/spectron";

const client = new Spectron({ apiKey: "sk-..." });
const memory = client.memory({ contextId: "support" });
```

--------------------------------

### Example pipeline status output

Source: https://surrealdb.com/docs/spectron/agent-memory/ingest/authoritative/multimodal-content

Shows the sequence of stages for a video document processed with MultimodalFull.

```text
Stage: queued
Stage: extracting
Stage: transcribing
Stage: captioning
Stage: chunking
Stage: embedding
Stage: keywording
Stage: rendering
Stage: ready
```

--------------------------------

### List Documents

Source: https://surrealdb.com/docs/spectron/reference/rest-api

Example request for listing documents with pagination and filtering parameters.

```http
GET /api/v1/{context_id}/documents?pageSize=20&mimeType=application/pdf
```

--------------------------------

### Initialize Spectron Client and Tools

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/strands-agents

Manual configuration of the Spectron client or passing explicit arguments to the tools.

```python
from surrealdb import Spectron
from spectron_strands import spectron_tools

# From explicit arguments.
tools = spectron_tools(
    endpoint="https://api.spectron.example",
    api_key="your-bearer-token",
    context="acme-prod",
)

# Or reuse an existing client.
client = Spectron(context="acme-prod", endpoint="...", api_key="...")
tools = spectron_tools(client=client)
```

--------------------------------

### Setting up local object storage

Source: https://surrealdb.com/docs/spectron/self-hosting/deployment/bare-metal

Create and configure permissions for the local data directory if not using remote object storage.

```bash
mkdir -p /var/lib/docs/spectron/objects
chown spectron:spectron /var/lib/docs/spectron/objects
```

--------------------------------

### Start Production Roles

Source: https://surrealdb.com/docs/spectron/reference/cli

Commands for running specific Spectron server roles in a production environment.

```bash
spectrond api start …          # REST + MCP
spectrond worker start …       # job queue consumer
spectrond scheduler start …    # periodic background work
spectrond management start …   # management REST only
```

--------------------------------

### Upload Document

Source: https://surrealdb.com/docs/spectron/reference/rest-api

Example request for uploading a document using multipart/form-data.

```http
POST /api/v1/{context_id}/documents
Content-Type: multipart/form-data

file=<binary>
metadata={"title":"Returns Policy","scopes":[["org/acme/team/eng"]],"labels":["team=eng"],"observedAt":"2024-01-15T00:00:00Z"}
```

--------------------------------

### Install the SurrealDB dependency

Source: https://surrealdb.com/docs/spectron/integrations/sdks/elixir

Add the surrealdb package to your mix.exs file to include the SDK in your project.

```elixir
def deps do
  [
    {:surrealdb, "~> 0.1"}
  ]
end
```

--------------------------------

### Example Profile Summary Output

Source: https://surrealdb.com/docs/spectron/cookbooks/build/personal-ai-assistant

A sample representation of a synthesized user profile summary containing identity, knowledge, and preference data.

```text
The user is Alice Chen, Head of Platform at Acme Corp. They prefer \
  TypeScript over JavaScript. They live in London. They prefer \
  bullet-point responses and dislike filler phrases. They are \
  currently leading a migration from CommonJS to ESM.
```

--------------------------------

### Install Spectron MCP server

Source: https://surrealdb.com/docs/spectron/cookbooks/build/coding-agent-with-project-memory

Commands to register the Spectron MCP server in your editor, supporting both standard and repository-scoped configurations.

```bash
# Install for Cursor
npx install-mcp spectron --client cursor --context my-project

# With repository-scoped memory
npx install-mcp spectron \
    --client cursor \
    --context my-project \
    --scope org/acme/project/my-repo
```

--------------------------------

### Define environment variables

Source: https://surrealdb.com/docs/spectron/self-hosting/deployment/bare-metal

Example content for the environment file. Ensure sensitive keys are not committed to version control.

```text
# /etc/docs/spectron/env

SPECTRON_SURREALDB_URL=ws://127.0.0.1:8000
SPECTRON_OBJECT_STORE_URL=file:///var/lib/docs/spectron/objects
SPECTRON_BIND_ADDRESS=0.0.0.0:9090

OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...

SPECTRON_SURREALDB_USER=root
SPECTRON_SURREALDB_PASS=changeme
```

--------------------------------

### Initialize and Use Spectron Clients

Source: https://surrealdb.com/docs/spectron/integrations/sdks/python

Demonstrates usage of synchronous Spectron and asynchronous AsyncSpectron clients for memory operations. Requires explicit configuration of context, endpoint, and api_key.

```python
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)
```

--------------------------------

### Construct a Spectron Client

Source: https://surrealdb.com/docs/spectron/integrations/sdks/go

Initialize a new client instance with context, endpoint, and authentication credentials.

```go
client, err := spectron.New(
    "acme-prod",                    // context id
    "https://api.spectron.example", // endpoint
    "sk-spec-...",                  // api key
    spectron.WithTimeout(30*time.Second),
    spectron.WithMaxRetries(3),
)
if err != nil {
    return err
}
defer client.Close()
```

--------------------------------

### Install Kotlin SDK

Source: https://surrealdb.com/docs/spectron/integrations/sdks/kotlin

Add the SurrealDB Kotlin SDK dependency to your project's build configuration.

```kotlin
dependencies {
    implementation("com.surrealdb:kotlin:0.1.0-SNAPSHOT")
}
```

--------------------------------

### Define Spectron and SurrealDB in compose.yaml

Source: https://surrealdb.com/docs/spectron/self-hosting/deployment/docker

Use this configuration to start the full Spectron stack locally. Ensure a .env file is present for environment variables.

```yaml
services:
  surrealdb:
    image: surrealdb/surrealdb:latest
    working_dir: /data
    environment:
      SURREAL_PATH: rocksdb://surrealdb
    command: start --log info --user root --pass secret
    volumes:
      - surrealdb-data:/data
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD"
        "surreal"
        "isready"
        "--endpoint"
        "http://localhost:8000"]
      interval: 5s
      timeout: 5s
      retries: 10

  spectron:
    image: ghcr.io/surrealdb/spectron:latest
    depends_on:
      surrealdb:
        condition: service_healthy
    env_file:
      - .env
    environment:
      SPECTRON_SURREALDB_URL: ws://surrealdb:8000
      SPECTRON_OBJECT_STORE_URL: file:///var/docs/spectron/objects
    volumes:
      - spectron-objects:/var/docs/spectron/objects
    ports:
      - "9090:9090"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9090/health"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  surrealdb-data:
  spectron-objects:
```

--------------------------------

### MCP Resource URI Patterns

Source: https://surrealdb.com/docs/spectron/integrations/surfaces/filesystem-view

Example URI formats used to reference specific files within the virtual filesystem.

```text
spectron://fs/documents/architecture-spec.pdf.txt
spectron://fs/entities/alice/role.txt
```

--------------------------------

### Load project context

Source: https://surrealdb.com/docs/spectron/cookbooks/build/coding-agent-with-project-memory

Call the context tool at the start of a session to retrieve relevant project information.

```json
Tool: context
Arguments: {
  "query": "project conventions and active work for my-repo",
  "lens": ["org/acme/project/my-repo"]
}
```

--------------------------------

### Initialize the Spectron client

Source: https://surrealdb.com/docs/spectron/integrations/sdks/dart

Import the Spectron entry point and instantiate the client with your endpoint, context, and API key.

```dart
import 'package:surrealdb/spectron.dart';

final client = Spectron(
  endpoint: 'https://api.spectron.example',
  context: 'acme-prod',
  apiKey: 'sp-your-key',
);
```

--------------------------------

### Apply Manifests and Verify Status

Source: https://surrealdb.com/docs/spectron/self-hosting/deployment/kubernetes

Applies configuration files and monitors the deployment rollout status.

```bash
kubectl apply -f secret.yaml
kubectl apply -f surrealdb.yaml
kubectl apply -f spectron.yaml
kubectl apply -f hpa.yaml
```

```bash
kubectl rollout status deployment/spectron -n spectron
```

--------------------------------

### Python SDK Chat Implementation

Source: https://surrealdb.com/docs/spectron/agent-memory/sessions/chat-sessions

Example usage of the Spectron Python SDK to create a session and send a chat message.

```python
from surrealdb import Spectron

memory = Spectron(context="acme-prod",
    api_key=os.environ["SPECTRON_API_KEY"])
session = await memory.sessions.create(scope=["org/acme/user/alice"])

reply = await session.chat("What do you know about me?")

print(reply.reply)            # The model's response string
print(reply.memory_updates)   # Entities, attributes, relations,
    corrections
```

--------------------------------

### Create principals via CLI

Source: https://surrealdb.com/docs/spectron/self-hosting/security/principals

Create new principals using the spectrond CLI or the thin client. Requires management URL and API key configuration.

```bash
spectrond principals create demo "Planner bot" \
  --kind agent \
  --grant memory:read=team/eng \
  --grant memory:write=team/eng \
  --url "$SPECTRON_MANAGEMENT_URL" \
  --api-key "$SPECTRON_MANAGEMENT_API_KEY"
```

```bash
# thin client — reads SPECTRON_MANAGEMENT_URL, SPECTRON_MANAGEMENT_API_KEY, SPECTRON_CONTEXT_ID
spectron principals create "Planner bot" --kind agent -c demo \
  --grant memory:read=team/eng --grant memory:write=team/eng
```

--------------------------------

### Create a session using Python SDK

Source: https://surrealdb.com/docs/spectron/agent-memory/sessions/creating-sessions

Initialize the Spectron client and create a session with defined scopes and metadata.

```python
from surrealdb import Spectron

memory = Spectron(context="acme-prod", api_key=os.environ["SPECTRON_API_KEY"])

session = await memory.sessions.create(
    scope=["org/acme/user/alice"],
    metadata={"channel": "web-chat"}
)

print(session.id)       # session:01hx7…
print(session.scope)    # ["org/acme/user/alice"]
```

--------------------------------

### Provision a Context and agent key

Source: https://surrealdb.com/docs/spectron/self-hosting/security/multi-tenancy

Commands to create a new tenant context and generate a scoped agent key using spectronctl.

```bash
spectronctl contexts create tenant-acme \
  --namespace tenants --database acme \
  --api-key "$SPECTRON_MGMT_KEY"

spectronctl contexts tenant-acme keys create app-agent \
  --principal agent \
  --scope-floor 'org=acme' \
  --api-key "$SPECTRON_MGMT_KEY"
```

--------------------------------

### MCP Server Configuration

Source: https://surrealdb.com/docs/spectron/reference/mcp-tools

Example configuration for connecting an MCP client to the Spectron server using Bearer authentication and context headers.

```APIDOC
## MCP Server Configuration

### Description
Configure the MCP client to communicate with the Spectron server. Authentication is handled via Bearer tokens, and the context can be specified via headers.

### Configuration Example
```json
{
  "mcpServers": {
    "spectron": {
      "url": "https://spectron.example.com/mcp",
      "headers": {
        "Authorization": "Bearer sk-...",
        "X-Spectron-Context": "acme-prod"
      }
    }
  }
}
```
```

--------------------------------

### MCP server configuration block

Source: https://surrealdb.com/docs/spectron/integrations/mcp-server/install

Example JSON structure for defining the Spectron MCP server in client configuration files.

```json
{
  "mcpServers": {
    "spectron": {
      "url": "http://localhost:9090/mcp",
      "headers": {
        "Authorization": "Bearer <your-context-api-key>"
      }
    }
  }
}
```

--------------------------------

### Initialize SpectronToolset in ADK

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/google-adk

Demonstrates setting up an ADK agent with persistent memory using SpectronToolset.

```python
import asyncio
from google.adk.agents import Agent
from google.adk.runners import InMemoryRunner
from spectron_google_adk import SpectronToolset

async def main():
    toolset = SpectronToolset(
        context="acme-prod",
        endpoint="https://api.spectron.example",
        api_key="sk-spec-...",
    )

    agent = Agent(
        model="gemini-2.5-flash",
        name="assistant",
        description="An assistant with persistent memory.",
        instruction="Store durable facts with remember and look things up with recall.",
        tools=[toolset],
    )

    runner = InMemoryRunner(agent=agent)
    try:
        await runner.run_debug("Remember: Acme Corp, healthcare, 1.2M dollar contract.")
        events = await runner.run_debug("What healthcare contracts do we have?")
        for event in events:
            if event.is_final_response() and event.content:
                for part in event.content.parts:
                    if part.text:
                        print(part.text)
    finally:
        await runner.close()
        await toolset.close()

asyncio.run(main())
```

--------------------------------

### Spectron CLI commands

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/openclaw

Available CLI commands for managing the Spectron plugin, including setup, status checks, and memory operations.

```bash
openclaw spectron setup [--takeover]   # print config + required hook flags
openclaw spectron status               # config, slot mode, and identity
openclaw spectron health               # check the connection
openclaw spectron index                # seed workspace memory files
openclaw spectron recall <query>       # search memory
openclaw spectron reflect <query>      # synthesise an answer from memory
openclaw spectron forget <query>       # forget matching memories
```

--------------------------------

### Get a Context

Source: https://surrealdb.com/docs/spectron/reference/management-api

Returns the record for a specific Context.

```APIDOC
## GET /api/v1/contexts/{context_id}

### Description
Returns the Context record. Provider API key values are replaced with a providers_configured summary.

### Method
GET

### Endpoint
/api/v1/contexts/{context_id}

### Parameters
#### Path Parameters
- **context_id** (string) - Required - The unique identifier for the context
```

--------------------------------

### Get a Context

Source: https://surrealdb.com/docs/spectron/reference/management-api

Retrieves the record for a specific Context.

```http
GET /api/v1/contexts/{context_id}
```

--------------------------------

### GET /api/v1/health

Source: https://surrealdb.com/docs/spectron/integrations/surfaces/rest

Checks the liveness of the Spectron service.

```APIDOC
## GET /api/v1/health

### Description
Returns the liveness status of the service.

### Method
GET

### Endpoint
/api/v1/health
```

--------------------------------

### GET /documents

Source: https://surrealdb.com/docs/spectron/agent-memory/ingest/authoritative/uploading-documents

Lists documents with optional filters.

```APIDOC
## GET /documents

### Description
Lists documents available in the system, supporting filters.
```

--------------------------------

### Initialize Agent tools

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/langchain

Wire Spectron into an agent using query and reflection tools.

```typescript
import { SpectronQueryTool, SpectronReflectTool } from "@surrealdb/langchain/tools";

const tools = [
    new SpectronQueryTool({ client: spectron }),
    new SpectronReflectTool({ client: spectron }),
];
```

--------------------------------

### GET /api/v1/health

Source: https://surrealdb.com/docs/spectron/reference/rest-api

Performs an unauthenticated liveness check on the system.

```APIDOC
## GET /api/v1/health

### Description
Performs an unauthenticated liveness check on the system.

### Method
GET

### Endpoint
/api/v1/health
```

--------------------------------

### GET /api/v1/contexts

Source: https://surrealdb.com/docs/spectron/self-hosting/operations/contexts

Retrieves a list of all Contexts registered on the deployment.

```APIDOC
## GET /api/v1/contexts

### Description
Returns all Contexts registered on this deployment. Provider API key values are replaced with a `providers_configured` list in the response.

### Method
GET

### Endpoint
/api/v1/contexts
```

--------------------------------

### GET /traces/{traceId}

Source: https://surrealdb.com/docs/spectron/reference/agents

Fetches trace information for debugging.

```APIDOC
## GET /traces/{traceId}

### Description
Fetches trace details to debug agent resolution tiers.

### Method
GET

### Endpoint
/traces/{traceId}

### Parameters
#### Path Parameters
- **traceId** (string) - Required - The unique trace identifier
```

--------------------------------

### GET /api/v1/{ctx}/traces

Source: https://surrealdb.com/docs/spectron/architecture/surface-security-and-models

Retrieve trace information.

```APIDOC
## GET /api/v1/{ctx}/traces

### Description
List traces for the given context.

### Method
GET

### Endpoint
/api/v1/{ctx}/traces

### Parameters
#### Path Parameters
- **ctx** (string) - Required - The context identifier.
```

--------------------------------

### Create a Context via CLI

Source: https://surrealdb.com/docs/spectron/self-hosting/operations/contexts

Provisions a new context using the spectronctl command-line tool.

```bash
spectronctl contexts create acme-prod \
  --namespace acme \
  --database prod \
  --model-extraction openai/gpt-4o-mini \
  --token-limit 1000000 \
  --api-key mgmt-...
```

--------------------------------

### Build tools with SpectronToolset or get_spectron_tools

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/google-adk

Two methods for creating tools: using SpectronToolset for lifecycle management or get_spectron_tools for manual client control.

```python
toolset = SpectronToolset(config=SpectronConfig.from_env())
agent = Agent(model="gemini-2.5-flash", name="assistant", tools=[toolset])
```

```python
from surrealdb import AsyncSpectron
from spectron_google_adk import get_spectron_tools

client = AsyncSpectron(context="acme-prod", endpoint="...", api_key="sk-...")
tools = get_spectron_tools(client=client)
```

--------------------------------

### GET /api/v1/{context_id}/profile

Source: https://surrealdb.com/docs/spectron/reference/rest-api

Retrieves the profile for a specific context.

```APIDOC
## GET /api/v1/{context_id}/profile

### Description
Retrieves the profile for a specific context.

### Method
GET

### Endpoint
/api/v1/{context_id}/profile
```

--------------------------------

### GET /documents/{id}/raw

Source: https://surrealdb.com/docs/spectron/agent-memory/ingest/authoritative/uploading-documents

Retrieves the original bytes of a document.

```APIDOC
## GET /documents/{id}/raw

### Description
Retrieves the original raw bytes of a document.

### Method
GET

### Endpoint
/documents/{id}/raw

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the document.
```

--------------------------------

### GET /documents/{id}/chunks

Source: https://surrealdb.com/docs/spectron/agent-memory/ingest/authoritative/uploading-documents

Retrieves the parsed segments of a document.

```APIDOC
## GET /documents/{id}/chunks

### Description
Retrieves the parsed segments (chunks) of a specific document.

### Method
GET

### Endpoint
/documents/{id}/chunks

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the document.
```

--------------------------------

### GET /documents/{id}

Source: https://surrealdb.com/docs/spectron/agent-memory/ingest/authoritative/uploading-documents

Retrieves the status and metadata for a specific document.

```APIDOC
## GET /documents/{id}

### Description
Retrieves status and metadata for a document by its ID.

### Method
GET

### Endpoint
/documents/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the document.
```

--------------------------------

### Initialize Research Session

Source: https://surrealdb.com/docs/spectron/cookbooks/build/long-running-research-agent

Demonstrates session creation and profile retrieval for research agents.

```python
from surrealdb import AsyncSpectron

client = AsyncSpectron(
    context="acme-prod",
    endpoint="https://spectron.example.com",
    api_key="sk-...",
)

session = await client.sessions.create(scope=["org/acme/user/researcher-alice"])
profile = await client.profile()
system_prompt = f"""You are a research assistant working on a quantum computing survey.

Current research state:
{profile}

Continue from where we left off."""
# ... conduct research ...
```

```javascript
import { Spectron } from "@surrealdb/spectron";

const client = new Spectron({
    endpoint: process.env.SPECTRON_ENDPOINT!,
    context: "acme-prod",
    apiKey: process.env.SPECTRON_API_KEY!,
});

const session = await client.sessions.create({
    scope: ["org/acme/user/researcher-alice/project/quantum-computing-survey"],
});

const profile = await client.profile();
```

--------------------------------

### Operator Provisioning Commands

Source: https://surrealdb.com/docs/spectron/reference/cli

Commands for creating contexts and managing keys via the spectrond daemon.

```bash
spectron contexts create …
spectrond keys generate-key …
spectrond keys rotate <context_id> <key_name> [--expires-in <seconds>]
```

--------------------------------

### Configure environment file permissions

Source: https://surrealdb.com/docs/spectron/self-hosting/deployment/bare-metal

Sets up the directory and file permissions for the environment configuration to ensure only root and the spectron user have access.

```bash
mkdir -p /etc/spectron
touch /etc/docs/spectron/env
chmod 640 /etc/docs/spectron/env
chown root:spectron /etc/docs/spectron/env
```

--------------------------------

### List and show sessions via CLI

Source: https://surrealdb.com/docs/spectron/mental-model/sessions-and-turns

Use the CLI to list existing sessions or display details for a specific session.

```bash
spectron sessions list
spectron sessions show sess_01hw…
```

--------------------------------

### GET /api/v1/{context_id}/principals

Source: https://surrealdb.com/docs/spectron/reference/rest-api

Retrieves a list of principals for the specified context.

```APIDOC
## GET /api/v1/{context_id}/principals

### Description
Retrieves a list of principals for the specified context.

### Method
GET

### Endpoint
/api/v1/{context_id}/principals

### Parameters
#### Path Parameters
- **context_id** (string) - Required - The unique identifier for the context.
```

--------------------------------

### Spectron Initialization

Source: https://surrealdb.com/docs/spectron/reference/sdk-swift

How to initialize the Spectron client in Swift.

```APIDOC
## Spectron Initialization

### Description
Initializes the Spectron client with the required context, endpoint, and API key.

### Code Example
```swift
let memory = try Spectron(
    context: "acme-prod",
    endpoint: "https://api.spectron.example",
    apiKey: "sk-spec-..."
)
```
```

--------------------------------

### GET /api/v1/{context_id}/scopes

Source: https://surrealdb.com/docs/spectron/reference/rest-api

Retrieves a list of scopes for the specified context.

```APIDOC
## GET /api/v1/{context_id}/scopes

### Description
Retrieves a list of scopes for the specified context.

### Method
GET

### Endpoint
/api/v1/{context_id}/scopes

### Parameters
#### Path Parameters
- **context_id** (string) - Required - The unique identifier for the context.
```

--------------------------------

### GET /api/v1/{context_id}/entities

Source: https://surrealdb.com/docs/spectron/reference/rest-api

Retrieves a list of entities for a specific context.

```APIDOC
## GET /api/v1/{context_id}/entities

### Description
Retrieves a list of entities for a specific context.

### Method
GET

### Endpoint
/api/v1/{context_id}/entities
```

--------------------------------

### Bootstrap Spectron Server

Source: https://surrealdb.com/docs/spectron/reference/cli

Performs one-time control-plane initialization and outputs management and context API keys.

```bash
docker compose exec spectron spectrond bootstrap \
  --connection-string "ws://surrealdb:8000;root;root"
```

--------------------------------

### GET /api/v1/{context_id}/sessions/{session_id}

Source: https://surrealdb.com/docs/spectron/reference/rest-api

Retrieves details for a specific session.

```APIDOC
## GET /api/v1/{context_id}/sessions/{session_id}

### Description
Retrieves details for a specific session.

### Method
GET

### Endpoint
/api/v1/{context_id}/sessions/{session_id}

### Parameters
#### Path Parameters
- **context_id** (string) - Required - The context identifier.
- **session_id** (string) - Required - The session identifier.
```

--------------------------------

### Create a session using JavaScript SDK

Source: https://surrealdb.com/docs/spectron/agent-memory/sessions/creating-sessions

Initialize the Spectron client and create a session with defined scopes and metadata.

```javascript
import { Spectron } from "@surrealdb/spectron";

const memory = new Spectron({ context: "acme-prod", apiKey: process.env.SPECTRON_API_KEY });

const session = await memory.sessions.create({
    scopes: [["org/acme/user/alice"]],
    metadata: { channel: "web-chat" },
});

console.log(session.id);     // session:01hx7…
console.log(session.scopes);   // [["org/acme/user/alice"]]
```

--------------------------------

### GET /api/v1/contexts/{id}

Source: https://surrealdb.com/docs/spectron/self-hosting/operations/contexts

Retrieves the full configuration record for a specific context.

```APIDOC
## GET /api/v1/contexts/{id}

### Description
Returns the Context record including effective configuration.

### Method
GET

### Endpoint
/api/v1/contexts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the context.
```

--------------------------------

### Configure Spectron Client

Source: https://surrealdb.com/docs/spectron/reference/sdk-javascript

Initialize the Spectron client with endpoint, context, and authentication credentials.

```javascript
import { Spectron } from "@surrealdb/spectron";

const client = new Spectron({
  endpoint: process.env.SPECTRON_ENDPOINT!,
  context: "acme-prod",
  apiKey: process.env.SPECTRON_API_KEY!,
  timeout: 30000,
  maxRetries: 3,
});
```

--------------------------------

### Get keyword details

Source: https://surrealdb.com/docs/spectron/agent-memory/retrieve/keywords-and-bm25

Retrieves metadata for a specific keyword by its text string.

```python
detail = await memory.knowledge.keywords.get("RETURN POLICY")
print(detail.text)            # RETURN POLICY
print(detail.score)           # 1.8
print(detail.document_count)  # 12
print([d.id for d in detail.documents])
```

--------------------------------

### GET /api/v1/{context_id}/profile

Source: https://surrealdb.com/docs/spectron/agent-memory/retrieve/recall

Retrieves category-grouped attributes for prompt assembly.

```APIDOC
## GET /api/v1/{context_id}/profile

### Description
Returns category-grouped attributes (identity, knowledge, context, instructions) for prompt assembly.

### Method
GET

### Endpoint
/api/v1/{context_id}/profile
```

--------------------------------

### Install Spectron Dependency

Source: https://surrealdb.com/docs/spectron/integrations/sdks/swift

Add the Spectron product to your Swift package target dependencies.

```swift
.product(name: "Spectron", package: "surrealdb.swift")
```

--------------------------------

### Common Configuration Patch Examples

Source: https://surrealdb.com/docs/spectron/self-hosting/operations/contexts

Specific JSON payloads for common update operations.

```json
{ "config": { "providers": { "openai": "sk-new-key-..." } } }
```

```json
{ "config": { "token_limit": 5000000 } }
```

```json
{ "config": { "models": { "reflection": "anthropic/claude-opus-4-7" } } }
```

```json
{ "config": { "retention_days": 90 } }
```

--------------------------------

### Create a deployment context

Source: https://surrealdb.com/docs/spectron/self-hosting/deployment/docker

Create a new context for the Spectron deployment using the management API.

```bash
curl -s -X POST http://localhost:9090/api/v1/contexts \
  -H "Authorization: Bearer $SPECTRON_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "dev",
    "namespace": "spectron",
    "database": "dev",
    "config": {
      "models": {
        "extraction": "openai/gpt-4o-mini",
        "response": "openai/gpt-4o"
      }
    }
  }'
```

--------------------------------

### Initialize Spectron Admin Key

Source: https://surrealdb.com/docs/spectron/self-hosting/deployment/kubernetes

Executes the initialization command within a running pod to generate the admin management key.

```bash
kubectl exec -n spectron deploy/spectron -- spectron init --admin-key
```

--------------------------------

### Define instruction memory record

Source: https://surrealdb.com/docs/spectron/cookbooks/build/personal-ai-assistant

Example of an instruction record created by the extraction pipeline.

```json
{
  "category": "instructions",
  "key": "response_format",
  "value": "Use bullet points. Avoid filler phrases.",
  "source_turn": "turn:01jt4m...",
  "valid_from": "2024-11-15T10:23:00Z"
}
```

--------------------------------

### Configure Spectron Client

Source: https://surrealdb.com/docs/spectron/integrations/sdks/swift

Initialize the Spectron client with your context, endpoint, and API key.

```swift
let memory = try Spectron(
    context: "acme-prod",
    endpoint: "https://api.spectron.example",
    apiKey: "sk-spec-..."
)
```

--------------------------------

### Reflection Response Structure

Source: https://surrealdb.com/docs/spectron/agent-memory/operations/reflect

Example of the JSON response object returned when persistence is enabled.

```json
{
  "reflection": "Alice consistently prioritises fast feedback loops…",
  "evidence": ["Alice mentioned keyboard shortcuts three times", "…"],
  "persistedAttributes": [
    {
      "entityId": "['person', 'alice']",
      "key": "core_tool_values",
      "value": "Fast feedback loops, keyboard-driven workflows"
    }
  ],
  "traceId": "…"
}
```

--------------------------------

### Get Migration Status

Source: https://surrealdb.com/docs/spectron/reference/management-api

Returns a fleet-wide view of schema catch-up status for all Contexts.

```http
GET /api/v1/migrations
```

--------------------------------

### Python SDK: session.chat()

Source: https://surrealdb.com/docs/spectron/agent-memory/sessions/chat-sessions

Demonstrates how to use the Python SDK to create a session and send a chat message.

```APIDOC
## Python SDK: session.chat()

### Description
Use the Spectron Python SDK to initialize a memory context, create a session, and send a chat message.

### Code Example
```python
from surrealdb import Spectron

memory = Spectron(context="acme-prod",
    api_key=os.environ["SPECTRON_API_KEY"])
session = await memory.sessions.create(scope=["org/acme/user/alice"])

reply = await session.chat("What do you know about me?")

print(reply.reply)            # The model's response string
print(reply.memory_updates)   # Entities, attributes, relations, corrections
```
```

--------------------------------

### Ingestion Pipeline Failure Response

Source: https://surrealdb.com/docs/spectron/reference/errors

Example of a document object returned when asynchronous processing fails.

```json
{
  "id": "document:0197d8f2...",
  "status": "failed",
  "error": "PDF extraction failed: file is encrypted and no password was provided.",
  "processing_started_at": "2026-05-12T14:22:11Z",
  "processing_completed_at": "2026-05-12T14:22:14Z"
}
```

--------------------------------

### Construct the Spectron client

Source: https://surrealdb.com/docs/spectron/integrations/sdks/haskell

Initialize the client using defaultSpectronOptions with your context ID, API key, and endpoint.

```haskell
{-# LANGUAGE OverloadedStrings #-}

import Spectron

main :: IO ()
main = do
  client <- newSpectron
    (defaultSpectronOptions "acme-prod" "sk_your_api_key" "https://api.spectron.example")
  ...
```

--------------------------------

### Uncertainty state structure

Source: https://surrealdb.com/docs/spectron/agent-memory/reasoning/instructions-and-uncertainties

Example JSON structure showing unresolved uncertainties returned in the state.

```json
{
  "unknowns": [
    {
      "about": "job title",
      "reason": "User joked about being CEO, then appeared to correct themselves",
      "resolved": false
    }
  ]
}
```

--------------------------------

### Initialize Spectron Client

Source: https://surrealdb.com/docs/spectron/integrations/ai-sdks/vercel-ai-sdk

Configure the Spectron client using environment variables or an explicit client instance.

```typescript
import { createSpectron } from "@surrealdb/vercel-ai";

// From the environment, bound to one user by default.
const spectron = createSpectron({ defaultScopes: "user/tobie" });

// Or pass config / a preconstructed client explicitly:
import { Spectron } from "@surrealdb/vercel-ai";
const spectron = createSpectron({
    client: new Spectron({ endpoint, apiKey, context }),
});
```

--------------------------------

### GET /api/v1/{context_id}/audit

Source: https://surrealdb.com/docs/spectron/reference/rest-api

Returns audit logs filtered by kind and trace ID.

```APIDOC
## GET /api/v1/{context_id}/audit

### Description
Returns rows with a kind filter and traceId linking back to graph-resident traces.

### Method
GET

### Endpoint
/api/v1/{context_id}/audit

### Parameters
#### Path Parameters
- **context_id** (string) - Required - The unique identifier for the context.

#### Query Parameters
- **kind** (string) - Optional - Filter by 'decision', 'retrieval', or 'response'.
- **limit** (integer) - Optional - Limit the number of results.
```

--------------------------------

### GET /api/v1/{context_id}/documents

Source: https://surrealdb.com/docs/spectron/reference/rest-api

Lists documents within a context with support for pagination and filtering.

```APIDOC
## GET /api/v1/{context_id}/documents

### Description
Retrieves a list of documents. Pagination is zero-indexed.

### Method
GET

### Endpoint
/api/v1/{context_id}/documents

### Parameters
#### Path Parameters
- **context_id** (string) - Required - The context identifier.

#### Query Parameters
- **pageSize** (integer) - Optional - Number of items per page.
- **mimeType** (string) - Optional - Filter by MIME type.
- **page** (integer) - Optional - Page number (zero-indexed).
```

--------------------------------

### Configure Spectron Client

Source: https://surrealdb.com/docs/spectron/integrations/sdks/kotlin

Initialize the Spectron client with your context ID, API key, and endpoint URL.

```kotlin
import com.surrealdb.kotlin.spectron.Spectron

val memory = Spectron(
    contextId = "acme-prod",
    apiKey = "sk-spec-...",
    endpoint = "https://api.spectron.example",
)
```

--------------------------------

### GET /api/v1/{context_id}/traces/{traceId}

Source: https://surrealdb.com/docs/spectron/self-hosting/observability/tracing

Fetches details for a specific trace to assist in debugging.

```APIDOC
## GET /api/v1/{context_id}/traces/{traceId}

### Description
Fetches a specific trace by ID. Used to inspect resolutionTier, retrieval_trace, decision_trace, or response_trace for debugging agent behavior.

### Method
GET

### Endpoint
/api/v1/{context_id}/traces/{traceId}

### Parameters
#### Path Parameters
- **context_id** (string) - Required - The unique identifier for the context.
- **traceId** (string) - Required - The unique identifier for the trace.
```

--------------------------------

### Initialize Spectron client

Source: https://surrealdb.com/docs/spectron/reference/sdk-python

Constructs a new Spectron or AsyncSpectron client instance for interacting with the API.

```python
Spectron(context: str, endpoint: str, api_key: str,
    timeout: float = 30.0, max_retries: int = 3)
AsyncSpectron(...)  # same arguments; methods are async
```

--------------------------------

### GET /api/v1/{context_id}/traces/stats

Source: https://surrealdb.com/docs/spectron/self-hosting/observability/tracing

Returns operational aggregates for the requested scope and time window.

```APIDOC
## GET /api/v1/{context_id}/traces/stats

### Description
Returns operational aggregates for the requested scope and time window. Callers with grant:manage see context-wide totals, while others see zeroed aggregates outside their grant.

### Method
GET

### Endpoint
/api/v1/{context_id}/traces/stats

### Parameters
#### Path Parameters
- **context_id** (string) - Required - The unique identifier for the context.

#### Query Parameters
- **scope[org]** (string) - Optional - Filter stats by organization.
- **windowHours** (integer) - Optional - The rolling window in hours for the aggregates.
```

--------------------------------

### Verify Claude Code Installation

Source: https://surrealdb.com/docs/spectron/integrations/mcp-server/coding-assistants/claude-desktop-and-code

Commands to verify that Claude Code recognizes the Spectron MCP server.

```bash
claude "What MCP tools do you have access to?"
```

```bash
claude mcp list
```