Spectron

https://surrealdb.com/docs/spectron
Admin
Spectron is a memory and knowledge layer for AI agents, offering a horizontally scalable application...
Tokens:164,006
Snippets:2,068
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### 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 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]"
```

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

### 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 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
```

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

### Install spectron-crewai

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

Install the required package via pip.

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

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

### 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
```

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

### 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
```

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

### 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
```

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

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

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

### 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
```

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

### 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()
```

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

### 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',
);
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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?"
```

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

### 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"
```

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

### 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
```

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

### 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())
```

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

### 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?"))
```

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

### 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}
```

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

### 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
```

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

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

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

### 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"}
```

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

### 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>]
```

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

### 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
```

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

### 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…
```
Tokens:
Raw