The @surrealdb/memory package is the JavaScript and TypeScript client for SurrealDB Agent Memory. This page covers installing it and configuring a client.
| Item | Value |
|---|---|
| npm package | @surrealdb/memory |
| Source | surrealdb.js/packages/memory |
| OpenAPI input | packages/memory/spec/openapi.json |
Install
npm install @surrealdb/memoryConfiguration
import { AgentMemory } from "@surrealdb/memory";
const client = new AgentMemory({
endpoint: process.env.AGENT_MEMORY_ENDPOINT!,
context: "acme-prod",
apiKey: process.env.AGENT_MEMORY_API_KEY!,
timeoutMs: 30000,
maxRetries: 3,
});timeoutMs defaults to 30000 and maxRetries to 3. The older timeout option is deprecated and is ignored when timeoutMs is also set.
Uses Authorization: Bearer header authentication.
Memory verbs (REST mapping)
| Method | HTTP |
|---|---|
remember(...) | POST /api/v1/{ctx}/facts |
rememberMany(...) | POST /api/v1/{ctx}/facts/batch |
recall(...) | POST /api/v1/{ctx}/query |
forget(...) | POST /api/v1/{ctx}/forget |
chat(...) | POST /api/v1/{ctx}/chat (SSE when stream: true) |
consolidate(...) | POST /api/v1/{ctx}/consolidate |
reflect(...) | POST /api/v1/{ctx}/reflect |
elaborate(...) | POST /api/v1/{ctx}/elaborate |
context(...) | POST /api/v1/{ctx}/context |
inspect(...) | GET /api/v1/{ctx}/inspect |
state() | GET /api/v1/{ctx}/state |
profile() | GET /api/v1/{ctx}/profile |
audit(...) | GET /api/v1/{ctx}/audit |
fsck(...) | POST /api/v1/{ctx}/fsck |
lookup(...) | POST /api/v1/{ctx}/lookup |
whoami() | GET /api/v1/{ctx}/me |
health() | GET /api/v1/health |
Python names query_context as context here.
onBehalfOf(principalId) returns a client that sends every request with the X-Spectron-On-Behalf-Of delegation header. The original client is left unchanged.
Namespaces
| Namespace | Highlights |
|---|---|
documents | upload, get, delete, list, query, raw, reprocess, recomputeLinks, chunks, keywords.* |
sessions | create → Session with .turns(), .context(), .close() |
entities | list, get, history, delete |
facts | attributes, relations, actions, with allAttributes, allRelations, allActions and allEdgesOf to walk every page |
uncertainty | list, listAll, count, resolve |
keys | create, list, listAll, delete, rotate (self-service keys for the caller's own principal) |
scopes | register, list, delete, forget |
principals | list, get, effective, grant, revoke |
traces | list, get, stats |
lifecycle | decay, expire |
Errors
| Class | Typical cause |
|---|---|
AgentMemoryError | Base |
AuthError | 401 |
ScopeError | 403 |
NotFoundError | 404 |
ValidationError | 400 / 422 |
RateLimitError | 429 (retryAfter when provided) |
ServerError | 5xx |
ConnectionError | Network / timeout |
StreamError | A streamed response failed part of the way through |
CancelledError | The caller aborted the request through its signal |
Harness adapter
npm install @surrealdb/agent-memory-vercel-ai