# JavaScript SDK reference

Package layout and configuration for @surrealdb/spectron.

> [!NOTE]
> `Spectron` was the project name for SurrealDB Agent Memory. These type names
> will be renamed in a future release.

| Item | Value |
| --- | --- |
| npm package | `@surrealdb/spectron` |
| Source | [`surrealdb.js/packages/spectron`](https://github.com/surrealdb/surrealdb.js/tree/main/packages/spectron) |
| OpenAPI input | `packages/spectron/spec/openapi.json` |

## Install

```bash
npm install @surrealdb/spectron
```

## Configuration

```typescript
import { Spectron } from "@surrealdb/spectron";

const client = new Spectron({
  endpoint: process.env.SPECTRON_ENDPOINT!,
  context: "acme-prod",
  apiKey: process.env.SPECTRON_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 |
| --- | --- |
| `SpectronError` | Base |
| `AuthError` | 401 |
| `ScopeError` | 403 |
| `NotFoundError` | 404 |
| `ValidationError` | 400 / 422 |
| `RateLimitError` | 429 (`retryAfter` when provided) |
| `ServerError` | 5xx |
| `ConnectionError` | Network / timeout |

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

## Harness adapter

```bash
npm install @surrealdb/spectron-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)