> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Kotlin SDK reference

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

| Item | Value |
| --- | --- |
| Package | `com.surrealdb.kotlin.memory` |
| Distribution | Bundled in `com.surrealdb:kotlin` |
| Models | `com.surrealdb.kotlin.memory.model` |
| Sub-clients | `com.surrealdb.kotlin.memory.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.memory.AgentMemory
import kotlin.time.Duration.Companion.seconds

val memory = AgentMemory(
    contextId = "acme-prod",
    apiKey = "sp-...",
    endpoint = "https://api.memory.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 `AgentMemory`: `remember`, `rememberMany`, `recall`, `queryContext`, `state`, `profile`, `reflect`, `forget`, `chat`, `consolidate`, `elaborate`, `inspect`, `audit`, `whoami`, `health`.

Namespaced sub-clients:

| Property | Type | Purpose |
| --- | --- | --- |
| `documents` | `DocumentsNamespace` | Upload, query, chunk, and manage documents (plus `documents.keywords`). |
| `sessions` | `SessionsNamespace` | Create and drive chat sessions. |
| `entities` | `EntitiesNamespace` | List, fetch, and delete extracted entities. |
| `lifecycle` | `LifecycleNamespace` | Expire, decay, and `fsck` maintenance. |
| `traces` | `TracesNamespace` | Inspect decision traces and stats. |
| `principals` | `PrincipalsNamespace` | List grants and grant/revoke access. |
| `scopes` | `ScopesNamespace` | Register and manage scope nodes. |
| `keys` | `KeysNamespace` | 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.memory.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 `AgentMemoryException`, modelled on RFC 7807 problem details. Each carries `status`, `title`, `detail`, `typeUri`, `instance`, and `extensions: Map<String, JsonElement>`.

| Exception | HTTP status |
| --- | --- |
| `AgentMemoryAuthException` | 401 |
| `AgentMemoryScopeException` | 403 |
| `AgentMemoryNotFoundException` | 404 |
| `AgentMemoryValidationException` | 400, 422 |
| `AgentMemoryRateLimitException` | 429 (with `retryAfter: Duration?`) |
| `AgentMemoryServerException` | 5xx and unmatched |
| `AgentMemoryTransportException` | 0 (connection or parse failure) |

## Models

Response and request types live under `com.surrealdb.kotlin.memory.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)