# Kotlin SDK reference

Package layout, configuration, and error model for the SurrealDB Agent Memory Kotlin client.

> [!NOTE]
> `Spectron` was the project name for SurrealDB Agent Memory. These type names
> will be renamed in a future release.

| Item | Value |
| --- | --- |
| Package | `com.surrealdb.kotlin.spectron` |
| Distribution | Bundled in `com.surrealdb:kotlin` |
| Models | `com.surrealdb.kotlin.spectron.model` |
| Sub-clients | `com.surrealdb.kotlin.spectron.ns` |

The SurrealDB Agent Memory client ships inside the [SurrealDB Kotlin SDK](/docs/reference/kotlin.md) - there is no separate artifact. It is independent of the SurrealDB RPC engine and speaks SurrealDB Agent Memory's HTTP API directly.

## Constructor

```kotlin
import com.surrealdb.kotlin.spectron.Spectron
import kotlin.time.Duration.Companion.seconds

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

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `contextId` | `String` | required | The context to operate in. |
| `apiKey` | `String` | required | Bearer token; mutable `var`, applied on next request. |
| `endpoint` | `String` | required | Base URL; mutable `var`. |
| `timeout` | `Duration` | `30s` | Per-request timeout. |
| `maxRetries` | `Int` | `3` | GET-only retries. |
| `httpClient` | `HttpClient?` | `null` | Inject a Ktor client. |
| `json` | `Json` | lenient | `ignoreUnknownKeys = true`, `explicitNulls = false`. |

Authentication uses the **`Authorization: Bearer`** header. Call `close()` to release the HTTP client.

## Surface

Top-level `suspend` verbs on `Spectron`: `remember`, `rememberMany`, `recall`, `queryContext`, `state`, `profile`, `reflect`, `forget`, `chat`, `consolidate`, `elaborate`, `inspect`, `audit`, `whoami`, `health`.

Namespaced sub-clients:

| Property | Type | Purpose |
| --- | --- | --- |
| `documents` | `SpectronDocuments` | Upload, query, chunk, and manage documents (plus `documents.keywords`). |
| `sessions` | `SpectronSessions` | Create and drive chat sessions. |
| `entities` | `SpectronEntities` | List, fetch, and delete extracted entities. |
| `lifecycle` | `SpectronLifecycle` | Expire, decay, and `fsck` maintenance. |
| `traces` | `SpectronTraces` | Inspect decision traces and stats. |
| `principals` | `SpectronPrincipals` | List grants and grant/revoke access. |
| `scopes` | `SpectronScopes` | Register and manage scope nodes. |
| `keys` | `SpectronKeys` | Self-service API key creation and rotation. |

## Scopes and delegation

Scopes are hierarchical `key/value` slash-paths passed as a `List<String>`; an empty list targets the caller's default write region. Build them with `scopePaths`:

```kotlin
import com.surrealdb.kotlin.spectron.scopePaths

scopePaths(listOf("org/acme"))                 // ["org/acme"]
scopePaths(mapOf("org" to "acme"))             // ["org/acme"]
scopePaths("team" to "eng", "org" to "acme")   // ["team/eng", "org/acme"]
```

Every method takes an optional `onBehalfOf: String?`, sent as the `X-Spectron-On-Behalf-Of` header so a privileged caller acts as another principal.

## Retries

GET requests retry on connection errors and 5xx responses with 250 ms / 500 ms / 1 s backoff, capped at `maxRetries` (default 3). Writes are never retried.

## Errors

All failures throw a subclass of the sealed `SpectronException`, modelled on RFC 7807 problem details. Each carries `status`, `title`, `detail`, `typeUri`, `instance`, and `extensions: Map<String, JsonElement>`.

| Exception | HTTP status |
| --- | --- |
| `SpectronAuthException` | 401 |
| `SpectronScopeException` | 403 |
| `SpectronNotFoundException` | 404 |
| `SpectronValidationException` | 400, 422 |
| `SpectronRateLimitException` | 429 (with `retryAfter: Duration?`) |
| `SpectronServerException` | 5xx and unmatched |
| `SpectronTransportException` | 0 (connection or parse failure) |

## Models

Response and request types live under `com.surrealdb.kotlin.spectron.model`, all `@Serializable`:

- **Enums** - `QueryMode`, `DocumentStatus`, `TurnRole`, `MemoryCategory`, `InferMode`, `GraphEdgeKind`, and others.
- **Facts** - `Triple`, `TripleEntity`, `BatchMessage`, `FactsResponseJson`, `FactsBatchResponseJson`.
- **Documents** - `DocumentJson`, `ChunkJson`, `KeywordJson`, `QueryFilter`, `UploadResponse`, `QueryResponseJson`.
- **Memory** - `ChatResponseJson`, `QueryMemoryResponseJson`, `ContextQueryResponseJson`, `StateResponseJson`, `ProfileResponseJson`.
- **Governance** - `PrincipalJson`, `EffectiveGrantsJson`, `WhoamiResponse`, `ScopeNodeJson`, `AuditRowJson`.
- **Maintenance** - `ConsolidateResponseJson`, `ElaborateResponseJson`, `InspectResponseJson`, `FsckReportJson`.
- **Keys** - `MintedKey` (secret returned once), `KeyDetail`.

## User guide

→ [Kotlin SDK](/docs/agent-memory/integrations/sdks/kotlin.md)