JavaScript SDK reference | Agent Memory reference

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/spectron`
OpenAPI input	`packages/spectron/spec/openapi.json`

Install

npm install @surrealdb/memory

Configuration

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!,
  timeout: 30000,
  maxRetries: 3,
});

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`
`health()`	`GET /api/v1/health`

Python names query_context as context here. Python exposes whoami() and keys.*; the JavaScript client does not include those methods - use REST for those endpoints.

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

→ Errors and retries

Harness adapter

npm install @surrealdb/spectron-vercel-ai

→ Vercel AI SDK

User guide

→ JavaScript and TypeScript SDK