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

# Python SDK reference

The SurrealDB Agent Memory client inside the surrealdb package. Package layout and configuration.

| Item | Value |
| --- | --- |
| PyPI package | [`surrealdb-memory`](https://pypi.org/project/surrealdb-memory/) (its own distribution, pulled in by the `surrealdb[memory]` extra) |
| Install | `pip install --pre 'surrealdb[memory]'` |
| Import | `from surrealdb.memory import Memory, AsyncMemory` |
| Submodule | `surrealdb.memory` (models, namespaces, errors) |

The client is versioned independently of the driver, so the extra pins `>=`, not `==`; `surrealdb` alone installs the driver without it.

## Constructor

```python
Memory(context: str, endpoint: str, api_key: str,
    timeout: float = 30.0, max_retries: int = 3)
AsyncMemory(...)  # 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.memory`:

| 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 |
| --- | --- |
| `MemoryServiceError` | Base |
| `MemoryAPIError` | Any non-2xx without a subclass (`status_code`, `message`, `trace_id`, `body`) |
| `MemoryAuthError` | 401 |
| `MemoryScopeError` | 403 |
| `MemoryNotFoundError` | 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)