Hardened SQLite Storage

WAL-with-safe-fallback SQLite connector with opt-in corruption detection and repair — keeps agent memory intact on Docker, NFS, and Kubernetes volumes

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

1. 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")

2. 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.

Integrity Guard

When guard=True, the connector runs a cheap quick_check on open and — on a malformed file — forensically backs up the bad bytes and attempts a bounded, least-destructive repair before returning a usable connection. SqliteSessionStore and SqliteTranscriptStore opt in by default so a corrupt sessions.db no longer takes the durable path down.

Corruption on open

A malformed database is detected, backed up, and repaired in place — or quarantined so a fresh empty DB opens instead of crashing.

The guard treats a transient database is locked / database is busy on the probe as healthy-but-busy — a peer momentarily holding the file is left exactly as-is, with no backup and no repair.

What lands on disk

The forensic backup fails closed on low disk — it needs 2 × file_size + 1 MiB free, so a corruption event never itself fills the disk. Backups are retention-capped at _MAX_FORENSIC_BACKUPS = 3 per file, and repairs are bounded at _MAX_REPAIR_ATTEMPTS = 3 per file (tracked in the .repair sidecar) so a boot-loop cannot churn a permanently-bad file. These are internal capacity constants — reason about them, but don’t override them.

Public helpers

sqlite_quick_check is a cheap PRAGMA quick_check(1) wrapper that returns False on any malformed-image / I/O error and re-raises transient lock/busy errors so callers can tell “locked” (leave alone) apart from “corrupt” (back up + repair).

from praisonaiagents.storage import sqlite_quick_check
import sqlite3

conn = sqlite3.connect("./state.db")
if not sqlite_quick_check(conn):
    print("This file failed the structural probe — consider guard=True on connect.")

Should I turn guard on?

Configuration Options

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

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

Best Practices