Storage Configuration

Configure the storage input passed to the active image. The image resolves this input into DextoStores with storage.createStores(...).

Complete Reference

For complete field documentation and all storage options, see agent.yml → Storage.

Overview

Core services use typed stores such as conversations, sessions, artifacts, memories, workspaces, and tool state. Core does not construct low-level storage backends directly.

The local image accepts a storage config with cache/database/blob sections and uses it internally to build a DextoStores implementation. Hosted images can accept the same shape, a narrower shape, or ignore YAML storage entirely and inject hosted stores.

Storage Types

For @dexto/image-local, the storage input supports:

Component	Options	Use Case
Cache	in-memory, redis	Temporary data, sessions
Database	in-memory, sqlite, postgres	Persistent data, memories
Blob	in-memory, local	Files, images, large objects

Cache

Temporary, high-speed data access.

in-memory

Data lost when process terminates:

storage:
  cache:
    type: in-memory

Use for: Development, testing

redis

High-performance caching:

storage:
  cache:
    type: redis
    host: localhost
    port: 6379
    maxConnections: 50

Use for: Production

Database

Persistent data storage.

in-memory

Non-persistent:

storage:
  database:
    type: in-memory

Use for: Testing

sqlite

File-based persistence:

storage:
  database:
    type: sqlite
    path: ./data/my-agent.db

Use for: Single-instance, simple deployments

postgres

Production-grade database:

storage:
  database:
    type: postgres
    host: db.example.com
    port: 5432
    database: dexto_prod
    password: $DB_PASSWORD

Use for: Production, multi-instance

Blob

Binary data storage.

in-memory

storage:
  blob:
    type: in-memory
    maxBlobSize: 5242880      # 5MB

Use for: Development

local

Filesystem storage:

storage:
  blob:
    type: local
    storePath: "${{dexto.agent_dir}}/blobs"
    maxBlobSize: 104857600     # 100MB
    cleanupAfterDays: 60

Use for: Production, persistent files

Example Configurations

Development (Default)

# No storage config needed - defaults to in-memory for all components
storage:
  cache:
    type: in-memory
  database:
    type: in-memory
  blob:
    type: in-memory

CLI Auto-Configuration

When using the local Dexto CLI image, SQLite and local artifact paths are automatically provided at:

• SQLite: ~/.dexto/database/<agent-id>.db
• Artifacts: ~/.dexto/blobs/<agent-id>/

You don't need to specify these paths manually unless you want custom locations.

Production (Redis + PostgreSQL)

storage:
  cache:
    type: redis
    url: $REDIS_URL
  database:
    type: postgres
    url: $POSTGRES_URL
  blob:
    type: local
    storePath: /var/data/blobs

Simple (SQLite)

storage:
  database:
    type: sqlite
    # path: automatically provided by CLI as ~/.dexto/database/<agent-id>.db
  blob:
    type: local
    # storePath: automatically provided by CLI as ~/.dexto/blobs/<agent-id>/

Or with explicit paths:

storage:
  database:
    type: sqlite
    path: ./data/my-agent.db
  blob:
    type: local
    storePath: ./data/blobs

When to Use

Scenario	Cache	Database	Blob
Development	in-memory	in-memory	in-memory
Simple Production	redis	sqlite	local
Scalable Production	redis	postgres	local
Testing	in-memory	sqlite	in-memory

Best Practices

1. Use environment variables - Store passwords and connection strings as $VAR
2. Treat storage as image-owned - Core receives DextoStores; images decide how config maps to backends
3. Set appropriate limits - Configure maxConnections, maxBlobSize based on load
4. Use hosted stores in hosted runtimes - Cloud/server hosts should inject their own store implementations when needed