# Python SDK reference

Package layout and configuration for the SurrealDB Agent Memory client in surrealdb.

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

| Item | Value |
| --- | --- |
| PyPI package | [`surrealdb`](https://pypi.org/project/surrealdb/) (SurrealDB Agent Memory client bundled with the driver) |
| Install | `pip install --pre surrealdb` |
| Import | `from surrealdb import Spectron, AsyncSpectron` |
| Submodule | `surrealdb.spectron` (models, namespaces, errors) |

On PyPI, **`spectron`** is a different project. Install **`surrealdb`** for SurrealDB and SurrealDB Agent Memory - not `pip install spectron`.

## Constructor

```python
Spectron(context: str, endpoint: str, api_key: str,
    timeout: float = 30.0, max_retries: int = 3)
AsyncSpectron(...)  # same arguments; methods are async
```

Requests use `Authorization: Bearer <api_key>`. Optional `on_behalf_of` on every verb sets `X-Spectron-On-Behalf-Of` for delegation.

## Memory verbs (REST mapping)

| Method | HTTP |
| --- | --- |
| `remember(...)` | `POST /api/v1/{ctx}/facts` |
| `remember_many(...)` | `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` |
| `query_context(...)` | `POST /api/v1/{ctx}/context` |
| `inspect(ref, ...)` | `GET /api/v1/{ctx}/inspect` |
| `state()` | `GET /api/v1/{ctx}/state` |
| `whoami()` | `GET /api/v1/{ctx}/me` |
| `profile()` | `GET /api/v1/{ctx}/profile` |
| `audit(...)` | `GET /api/v1/{ctx}/audit` |
| `health()` | `GET /api/v1/health` (not context-scoped) |

## Namespaces

| Namespace | Methods |
| --- | --- |
| `documents` | `upload`, `get`, `delete`, `list`, `query`, `fetch_raw`, `reprocess`, `recompute_links`, `chunks` |
| `documents.keywords` | `list`, `get`, `search`, `for_document` |
| `sessions` | `create`, `delete`, `context`, `turns` |
| `entities` | `list`, `get`, `delete`, `history` |
| `scopes` | `register`, `list`, `delete`, `forget` |
| `principals` | `list`, `get`, `grant`, `revoke`, `effective` |
| `keys` | `create`, `list`, `delete`, `rotate` |
| `traces` | `list`, `get`, `stats` |
| `lifecycle` | `decay`, `expire`, `fsck` |

Full REST tables: [REST API](/docs/agent-memory/reference/rest-api.md).

## Response models

Import from `surrealdb.spectron`:

| Model | Used for |
| --- | --- |
| `RememberResponse`, `RememberBatchResponse`, `ExtractionResult` | Fact ingest |
| `RecallResponse`, `RecallHit` | Semantic recall |
| `ChatResponse`, `ChatChunk` | Chat (streaming chunks) |
| `ContextQueryResponse` | Composed context string |
| `StateResponse` | Working-memory snapshot |
| `UploadResponse`, `Document`, `DocumentPage`, `Chunk`, `ChunkPage` | Document corpus |
| `DocumentQueryResponse`, `DocumentQueryHit` | Document search |
| `Keyword`, `KeywordSearchResponse`, … | Keyword index |
| `Session`, `Turn`, `TurnListResponse` | Sessions |
| `EntityDetail`, `EntityListResponse`, … | Knowledge graph entities |
| `WhoamiResponse`, `ProfileResponse` | Caller identity |
| `TraceRecord`, `AuditResponse`, `FsckReport` | Observability / maintenance |

Nested graph and extraction payloads may remain `dict` values where the server shape evolves (“slim model” convention).

## Exceptions

| Class | HTTP |
| --- | --- |
| `SpectronError` | Base |
| `SpectronAPIError` | Any non-2xx without a subclass (`status_code`, `message`, `trace_id`, `body`) |
| `SpectronAuthError` | 401 |
| `SpectronScopeError` | 403 |
| `SpectronNotFoundError` | 404 |

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

## User guide

→ [Python SDK](/docs/agent-memory/integrations/sdks/python.md)