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

# JavaScript SDK reference

Package layout and configuration for @surrealdb/memory.

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`](https://github.com/surrealdb/surrealdb.js/tree/main/packages/memory) |
| OpenAPI input | `packages/memory/spec/openapi.json` |

## Install

```bash
npm install @surrealdb/memory
```

## Configuration

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

→ [Errors and retries](/docs/agent-memory/integrations/sdks/javascript-and-typescript.md#errors-and-retries)

## Harness adapter

```bash
npm install @surrealdb/agent-memory-vercel-ai
```

→ [Vercel AI SDK](/docs/agent-memory/integrations/ai-sdks/vercel-ai-sdk.md)

## User guide

→ [JavaScript and TypeScript SDK](/docs/agent-memory/integrations/sdks/javascript-and-typescript.md)