Storage Backends

CUGA persists three things: policies (vectors + metadata), knowledge documents (vectors + metadata + uploaded files), and knowledge tasks/settings. The [storage].mode setting selects a single backend stack used for all three.

Modes

[storage]
mode = "local"        # "local" | "prod"
local_db_path = ""    # default DBS_DIR/cuga.db when empty
postgres_url = ""     # required when mode = "prod"

DBS_DIR defaults to the package's dbs/ directory, or to the value of CUGA_DBS_DIR if set. persist_dir can be overridden in knowledge_settings.toml.

Local mode (default)

Best for development, single-user demos, and small deployments.

[storage]
mode = "local"

No external services required. SQLite + sqlite-vec keeps everything in a single file, so you can ship a working agent with git-cloneable state.

Production mode

Best for shared deployments, multi-replica services, or anywhere you need transactional guarantees and proper backups.

[storage]
mode = "prod"
postgres_url = "postgresql+psycopg://cuga:secret@db.internal:5432/cuga"

Postgres must have the pgvector extension enabled:

CREATE EXTENSION IF NOT EXISTS vector;

CUGA creates the policy and knowledge tables on first startup. Uploaded knowledge files (the originals, not the parsed chunks) continue to live under persist_dir/files/ — mount that directory on persistent storage in container deployments.

Embeddings

Embeddings live in [storage.embedding] and are independent of the backend mode:

[storage.embedding]
provider = "local"                       # "openai" | "local" | "auto"
model = "BAAI/bge-small-en-v1.5"
dim = 384                                # 1536 for OpenAI, 384 for the BAAI model
base_url = ""                            # optional OpenAI-compatible endpoint
api_key = ""                             # falls back to OPENAI_API_KEY

provider = "auto" tries OpenAI and falls back to the local model if no API key is configured — handy when the same settings.toml ships across dev and prod.