Agno Database Backends for Agent Persistence: Complete Guide to 14+ Storage Options

Agno supports more than 14 database backends for agent persistence, including SQLite, PostgreSQL, MySQL, MongoDB, DynamoDB, Redis, SurrealDB, Firestore, and Google Cloud Storage, all unified under a pluggable BaseDb abstraction.

Agno (agno-agi/agno) is a lightweight framework for building autonomous agents and multi-agent workflows. Its database backends for agent persistence are architected as interchangeable modules, allowing developers to swap storage from local SQLite files to distributed cloud databases without modifying agent business logic.

How Agno's Persistence Architecture Works

The persistence layer centers on an abstract base class that enforces a consistent API across all storage implementations.

BaseDb (libs/agno/agno/db/base.py) defines the contract that every backend must implement, including methods like upsert_session(), get_session(), and delete_session(). This abstraction allows an Agent to persist sessions, memories, metrics, evaluations, and knowledge to any supported store via a single db parameter.

Backends are imported lazily through libs/agno/agno/db/__init__.py, ensuring that heavy dependencies (like PostgreSQL or MongoDB drivers) are only loaded when explicitly requested:

# libs/agno/agno/db/__init__.py pattern

if name == "PostgresDb":
    from agno.db.postgres import PostgresDb

Complete List of Supported Database Backends

Agno ships with production-ready implementations for relational, NoSQL, in-memory, and cloud-native storage systems. Each backend resides in its own module under libs/agno/agno/db/:

Relational Databases

• SQLite (libs/agno/agno/db/sqlite/sqlite.py) — File-based, serverless storage ideal for local development and small workloads.
• PostgreSQL (libs/agno/agno/db/postgres/postgres.py) — Full-featured relational database with ACID guarantees. Includes async support via async_postgres.py.
• MySQL (libs/agno/agno/db/mysql/mysql.py) — Compatible with MySQL and Aurora, suitable for existing enterprise infrastructure.

NoSQL and Document Stores

• MongoDB (libs/agno/agno/db/mongo/mongo.py) — Document-oriented storage for flexible, schema-less data models.
• DynamoDB (libs/agno/agno/db/dynamo/dynamo.py) — AWS-managed key-value and document database for serverless deployments.
• Firestore (libs/agno/agno/db/firestore/firestore.py) — Google Cloud document database with real-time sync and IAM integration.

Cache and Memory Stores

• Redis (libs/agno/agno/db/redis/redis.py) — In-memory data structure store with optional persistence, optimized for ultra-fast session writes.
• In-Memory (libs/agno/agno/db/in_memory/in_memory_db.py) — Pure Python dictionary implementation for testing or stateless deployments where persistence is deliberately disabled.

Cloud and File-Based Storage

• JSON File (libs/agno/agno/db/json/json_db.py) — Simple JSON file persistence for quick prototyping without database infrastructure.
• Google Cloud Storage JSON (libs/agno/agno/db/gcs_json/gcs_json_db.py) — Persists agent state as JSON blobs in GCS buckets for cloud-native pipelines.
• SurrealDB (libs/agno/agno/db/surrealdb/surrealdb.py) — Multi-model database supporting graph, relational, and document queries with built-in real-time capabilities.

Configuring Database Backends in Your Agents

All database backends expose the same initialization interface through the db parameter of the Agent class.

SQLite for Local Development

The most common starting point uses a local SQLite file:

from agno.agent import Agent
from agno.db import SqliteDb

sqlite_db = SqliteDb(db_path="agent_state.db")
agent = Agent(name="DemoAgent", db=sqlite_db)

response = agent.run("What is the capital of France?")

# Session automatically persisted to ./agent_state.db

PostgreSQL for Production

For production deployments requiring ACID compliance and concurrent access:

from agno.agent import Agent
from agno.db import PostgresDb

pg_db = PostgresDb(
    host="db.production.internal",
    port=5432,
    user="agno_service",
    password="secure_password",  # Use environment variables in production

    database="agno_prod"
)
agent = Agent(name="ProductionAgent", db=pg_db)

MongoDB for Flexible Schemas

When agent state varies dynamically or requires nested document structures:

from agno.agent import Agent
from agno.db import MongoDb

mongo_db = MongoDb(
    uri="mongodb+srv://user:pass@cluster.mongodb.net/agno",
    database="agno"
)
agent = Agent(name="MongoAgent", db=mongo_db)

In-Memory for Testing

For unit tests or ephemeral agents:

from agno.agent import Agent
from agno.db import InMemoryDb

mem_db = InMemoryDb()
agent = Agent(name="TestAgent", db=mem_db)

# No disk writes occur; state disappears when process exits

Advanced Architecture Features

Beyond basic CRUD operations, Agno's persistence layer provides enterprise-grade capabilities across all supported database backends.

Async Support for High-Concurrency Workloads

Backends with async drivers offer non-blocking variants prefixed with Async. For example, AsyncPostgresDb (libs/agno/agno/db/postgres/async_postgres.py) allows agents to run in async event loops without blocking the main thread:

from agno.db import AsyncPostgresDb

async_db = AsyncPostgresDb(host="...", database="...")

# Use with async Agent configurations

Unified Schema Management

All relational backends share table definitions located in libs/agno/agno/db/schemas/. The migration framework in libs/agno/agno/db/migrations/ ensures schema evolution remains consistent whether you migrate from SQLite to PostgreSQL or upgrade Agno versions.

Component-Level Persistence

The BaseDb contract extends beyond session storage to include:

• Memories: Long-term agent memory vectors and context
• Metrics: Performance and usage statistics
• Evaluations: Agent run evaluations and feedback
• Knowledge: RAG (Retrieval-Augmented Generation) document stores

Agents, Teams, and Workflows reuse a single database instance for all persistence needs, ensuring transactional consistency across components.

Summary

• Agno provides 14+ database backends for agent persistence, ranging from SQLite to cloud-native stores like DynamoDB and Firestore.
• All backends inherit from BaseDb (libs/agno/agno/db/base.py) and implement a unified API for sessions, memories, metrics, and knowledge.
• Lazy loading via libs/agno/agno/db/__init__.py ensures optional dependencies are only imported when needed.
• Async variants (e.g., AsyncPostgresDb) support non-blocking I/O for high-concurrency production environments.
• Schema definitions in libs/agno/agno/db/schemas/ and migrations in libs/agno/agno/db/migrations/ provide consistent data structures across all relational stores.

Frequently Asked Questions

What is the default database backend for Agno agents?

Agno does not enforce a default database backend; you must explicitly configure persistence by passing a db instance to the Agent constructor. However, SQLite is the most commonly used backend for local development and quick prototypes because it requires no external server and stores data in a single file.

Can I switch database backends without losing agent data?

Switching backends (e.g., from SQLite to PostgreSQL) requires migrating data between storage systems, as Agno's schema definitions are consistent but data is not automatically synchronized across different database types. You must export sessions and memories from the source backend and import them into the target backend. The migration utilities in libs/agno/agno/db/migrations/ can help ensure schema compatibility during this process.

Does Agno support async database operations?

Yes, Agno provides async variants for database backends that support asynchronous drivers. For example, AsyncPostgresDb (libs/agno/agno/db/postgres/async_postgres.py) and async versions of MongoDB and MySQL allow agents to perform non-blocking I/O operations. This is essential for high-throughput production environments where blocking database calls would degrade performance.

Which database backend should I use for production deployments?

PostgreSQL is the recommended relational backend for production due to its ACID compliance, mature async driver support, and robust handling of concurrent connections. If you operate in an AWS environment, DynamoDB offers serverless scaling. For Google Cloud deployments, Firestore or Cloud Storage JSON provide native integration. Choose Redis only if you prioritize speed over durability, and MongoDB if your agent state requires highly flexible, nested document structures.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}