SurrealDB

Persist Agno sessions and other data in SurrealDB.

SurrealDb stores Agent, Team, and Workflow sessions, memories, knowledge, evaluations, and traces in SurrealDB.

See the SurrealDB documentation for server and connection setup.

Usage

Start in a virtual environment.

Install Agno, SQLAlchemy, the SurrealDB driver, and the OpenAI client:

uv pip install agno sqlalchemy surrealdb openai

Run SurrealDB

Install Docker Desktop, then start SurrealDB on port 8000:

docker run --rm --pull always -p 8000:8000 surrealdb/surrealdb:latest start --user root --pass root

This development server uses temporary storage. Its data is lost when the server stops. To retain data across server or container replacement, configure a mounted volume and an on-disk backend as described in the SurrealDB Docker guide.

surrealdb_for_agent.py
from agno.agent import Agent
from agno.db.surrealdb import SurrealDb

SURREALDB_URL = "ws://localhost:8000"
SURREALDB_USER = "root"
SURREALDB_PASSWORD = "root"
SURREALDB_NAMESPACE = "agno"
SURREALDB_DATABASE = "surrealdb_for_agent"

credentials = {"username": SURREALDB_USER, "password": SURREALDB_PASSWORD}
db = SurrealDb(
    client=None,
    db_url=SURREALDB_URL,
    db_creds=credentials,
    db_ns=SURREALDB_NAMESPACE,
    db_db=SURREALDB_DATABASE,
)

agent = Agent(db=db)

Parameters

ParameterTypeDefaultDescription
idOptional[str]-Database ID. Derived deterministically from db_url and db_db when omitted.
clientOptional[Union[BlockingWsSurrealConnection, BlockingHttpSurrealConnection]]-A blocking connection, either HTTP or WebSocket.
db_urlstr-The SurrealDB connection URL.
db_credsdict[str, str]-Database credentials dictionary (username, password).
db_nsstr-The SurrealDB namespace to use.
db_dbstr-The SurrealDB database name to use.
session_tableOptional[str]-Name of the table to store Agent, Team and Workflow sessions.
runs_tableOptional[str]NoneStorage name for individual runs. Defaults to agno_runs, or <session_table>_runs when a custom session name is supplied.
memory_tableOptional[str]-Name of the table to store user memories.
metrics_tableOptional[str]-Name of the table to store metrics.
eval_tableOptional[str]-Name of the table to store evaluation runs data.
knowledge_tableOptional[str]-Name of the table to store knowledge documents data.
traces_tableOptional[str]-Name of the table to store traces.
spans_tableOptional[str]-Name of the table to store spans.