| Item | Value |
|---|---|
| PyPI package | 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
Memory(context: str, endpoint: str, api_key: str,
timeout: float = 30.0, max_retries: int = 3)
AsyncMemory(...) # same arguments; methods are asyncRequests 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.
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 |