Hardened SQLite Storage

Every SQLite store PraisonAI ships uses a hardened connection factory that keeps agent memory and session data intact even on network and container filesystems, without any user configuration. An agent running on Docker Desktop, NFS, or a Kubernetes volume keeps its memory without a single line of configuration.

Quick Start

Simple Usage

Nothing to configure — hardening is automatic for any SQLite-backed store.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are helpful.",
    memory=True,
)
agent.start("Remember my favourite colour is blue")

Custom Store

Build your own SQLite-backed store with the hardened factory.

from praisonaiagents.storage import sqlite_connect

conn = sqlite_connect("./state.db")  # WAL where supported, DELETE where not
conn.execute("CREATE TABLE IF NOT EXISTS t (x INTEGER)")

How It Works

The factory tries WAL first, then probes the on-disk header before ever falling back — so a database another connection wrote in WAL is never downgraded.

Filesystem	Journal mode chosen	Notes
ext4/APFS/NTFS (local)	`WAL`	Concurrent readers with a writer
Docker Desktop (gRPC-FUSE)	`DELETE` (fresh DB) or `WAL` (existing WAL header)	Silent fallback, no corruption
NFS/SMB home dir	`DELETE`	Byte-range locking honoured
Fly.io / K8s network volume	`DELETE`	No `-shm` sidecar issues
`:memory:`	`WAL`	No fallback needed
Pre-existing WAL file on hostile FS	`WAL` (preserved)	Never downgraded — peer commits protected

Configuration Options

The sqlite_connect factory forwards unknown keyword arguments to sqlite3.connect.

Option	Type	Default	Description
`path`	`str \| os.PathLike`	required	DB path or `":memory:"`
`check_same_thread`	`bool`	`False`	Forwarded to `sqlite3.connect`; core stores share connections under their own lock
`isolation_level`	`Optional[str]`	`""` (sqlite3 default)	`None` for autocommit
`busy_timeout_ms`	`int`	`5000`	`PRAGMA busy_timeout` in milliseconds
`synchronous`	`str`	`"FULL"`	`PRAGMA synchronous`; pass `"NORMAL"` for throughput under WAL

Common Patterns

Docker / Kubernetes / NFS deployments need no special handling — the default Agent(memory=True) already survives them.

from praisonaiagents import Agent

agent = Agent(name="Assistant", instructions="You are helpful.", memory=True)

Build a custom SQLite-backed store on top of the same hardening.

from praisonaiagents.storage import sqlite_connect

conn = sqlite_connect("./custom.db", busy_timeout_ms=10000)

Favour throughput over the last-transaction durability window with synchronous="NORMAL" (safe under WAL against process crashes).

from praisonaiagents.storage import sqlite_connect

conn = sqlite_connect("./fast.db", synchronous="NORMAL")

Choosing a `synchronous` Level

Scope

The core memory (STM/LTM), session, transcript, and generic SQLiteBackend stores use the hardened factory today. The bot/gateway wrapper stores (_outbox, _dlq, _ingress, approval, delivery-control, and kanban) are not wired in yet.

Best Practices

Let the factory choose the journal mode

Do not run PRAGMA journal_mode=WAL yourself — sqlite_connect picks WAL where it works and DELETE where it does not.

Keep synchronous=FULL unless you measured a bottleneck

FULL survives an OS or power crash. Switch to NORMAL only after profiling shows a durability-vs-throughput trade-off worth making.

Use sqlite_connect for custom stores

For any SQLite-backed store you build, call sqlite_connect instead of sqlite3.connect to inherit the fallback and durability defaults.

Expect DELETE on hostile filesystems

On Docker Desktop, NFS, or network volumes the on-disk journal mode may be DELETE. This is correct behaviour, not a regression, and does not change any API.

SQLite Persistence

Local file database for conversations

SQLite Transcript Store

Concurrent gateway session persistence

Memory

Short- and long-term agent memory

Session Store

Cross-session search and recall

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Hardened SQLite Storage

Quick Start

How It Works

Configuration Options

Common Patterns

Choosing a `synchronous` Level

Scope

Best Practices

SQLite Persistence

SQLite Transcript Store

Memory

Session Store

​Quick Start

​How It Works

​Configuration Options

​Common Patterns

​Choosing a synchronous Level

​Scope

​Best Practices

​Related

SQLite Persistence

SQLite Transcript Store

Memory

Session Store

Quick Start

How It Works

Configuration Options

Common Patterns

Choosing a `synchronous` Level

Scope

Best Practices

Related