Kotlin SDK reference | Agent Memory reference

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 - there is no separate artifact. It is independent of the SurrealDB RPC engine and speaks SurrealDB Agent Memory's HTTP API directly.

Constructor

import com.surrealdb.kotlin.memory.AgentMemory
import kotlin.time.Duration.Companion.seconds

val memory = AgentMemory(
    contextId = "acme-prod",
    apiKey = "sk-spec-...",
    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:

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