Gateway Session Persistence

The gateway now ships in the praisonai-bot package. praisonai serve gateway still works exactly as documented here; for a standalone install see praisonai-bot Migration.

Persistent sessions keep conversation state alive across gateway restarts and let clients resume mid-conversation with event replay.

This page covers agent session persistence (messages, events, cursors). Gateway sessions additionally preserve pending_inbox and is_executing across disconnects and graceful shutdown — see Gateway Session Continuity.

Gateway Memory-Pressure Eviction relies on this — an unflushed transcript is never evicted, because only a durably persisted cache can be losslessly rebuilt on the next turn.

Channel-originated sessions get a proactive “interrupted — resuming” notice after a gateway restart — see Restart Continuation.

Durable by default (as of PR #3595). session.persist now defaults to true, so a gateway started from the out-of-the-box path writes to ~/.praisonai/sessions/sessions.db on first boot and remembers conversations across restarts. Set session.persist: false in gateway.yaml to keep the old ephemeral, in-memory behaviour.

When a durable write does fail (disk-full / corruption / permission), the turn is not lost — it’s salvaged to ~/.praisonai/state/session_spill/ and re-folded on the next load. Subscribe to the observe-only SESSION_PERSIST_FAILED hook to alert/metric on the failure. See Write-failure salvage for the full spill + re-ingest flow.Similarly, if a session file is found corrupt on the next load (malformed JSON / invalid UTF-8), the corrupt bytes are quarantined to <file>.json.corrupt-<ts> before a fresh session starts, and the same SESSION_PERSIST_FAILED hook fires with the quarantine path in spilled. See Corruption-quarantine on load.

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
# Persistence is on by default — this agent's session survives gateway restarts

The user returns later; persisted session state reloads so the agent remembers prior turns.

Quick Start

Persistence is on by default

No session: block is required — persistence engages automatically:

gateway:
  host: "127.0.0.1"
  port: 8765

praisonai gateway start --config gateway.yaml

Default storage: ~/.praisonai/sessions/sessions.dbOpt out for ephemeral, in-memory sessions:

# Ephemeral sessions (explicit opt-out)
gateway:
  session:
    persist: false

As of PraisonAI PR #3595, session.persist itself defaults to true, so the SqliteTranscriptStore (WAL SQLite, one row per session, indexed lookups) engages out-of-the-box. Set session.store: file to keep the legacy per-session JSON layout. See SQLite Transcript Store for the full picture.

Resume as a client

import asyncio
import json
import websockets

async def resume(session_id: str, since: int):
    async with websockets.connect("ws://127.0.0.1:8765") as ws:
        await ws.send(json.dumps({
            "type": "join",
            "agent_id": "assistant",
            "session_id": session_id,
            "since": since,
        }))
        while True:
            msg = json.loads(await ws.recv())
            if msg.get("type") == "joined" and msg.get("resumed"):
                print("Resumed at cursor", msg.get("cursor"))
            if msg.get("type") == "replay":
                print("Replay:", msg.get("event"))

asyncio.run(resume("abc-123", 42))

Full configuration

gateway:
  session:
    persist: true          # default — shown here for completeness
    persist_path: ~/.praisonai/sessions/
    resume_window: 86400
    timeout: 3600
    max_messages: 1000
    max_inbox: 256

When the SQLite and file-store paths can’t be opened (e.g. a read-only or absent $HOME), the gateway degrades to in-memory sessions instead of aborting startup. persist: true therefore never crashes on a constrained host — sessions are kept in memory for the run and lost on restart. If the doctor or logs report an in-memory fallback, $HOME is unwritable.

What gets persisted

The on-disk record under persist_path is the JSON returned by GatewaySession.to_dict(). Key fields:

Key	Type	Purpose
`session_id`	`str`	Stable identifier; used on resume
`event_cursor`	`int`	Position in the event log for replay
`sequence`	`int`	Monotonic outbound sequence (gap detection)
`protocol_version`	`int`	Protocol version negotiated at the last handshake
`capabilities`	`List[str]`	Capability tokens advertised by the client (`streaming`, `presence`, `ack`, …)
`events`	`List[GatewayEvent]`	Last 100 events (for replay)
`pending_inbox`	`List[...]`	In-flight inbound queue snapshot
`is_executing`	`bool`	Mid-turn flag for Session Continuity
`channel_target`	`str \| None`	`"channel:target"` origin used by Restart Continuation to notify channel users; `None` for direct-client sessions

capabilities and protocol_version are restored on resume so server-side code that branches on either keeps working without re-handshake. A persisted record from before the upgrade (no capabilities key) restores cleanly to [] — no migration required.

How it works

Role	Responsibility
Client	Track highest `cursor`; send `since` on reconnect
Gateway	Rehydrate sessions; emit replay frames
SessionStore	Persist state to disk
TTL cleanup	Hourly purge of expired sessions

Reconnect protocol

Client join (resume):

{ "type": "join", "agent_id": "assistant", "session_id": "abc-123", "since": 42 }

Server joined:

{ "type": "joined", "session_id": "abc-123", "agent_id": "assistant", "resumed": true, "cursor": 57 }

Replay frames:

{ "type": "replay", "event": { "...": "..." } }

Every response, message, stream_end, and error frame includes a monotonic cursor. Track the highest value for the next reconnect.

Configuration options

Option	Type	Default	Description
`persist`	`bool`	`true`	Persist session state. Defaults to `true` — an out-of-the-box gateway remembers conversations across restarts via the SQLite transcript store. Set `false` to opt into ephemeral, in-memory sessions
`persist_path`	`str`	`~/.praisonai/sessions/`	Storage directory
`store`	`str`	`"sqlite"`	Transcript backend — `"sqlite"` (SQLite Transcript Store) or `"file"` (legacy JSON)
`resume_window`	`int`	`86400`	Seconds a detached session stays resumable (24 h)
`timeout`	`int`	`3600`	Active session expiry in seconds
`max_messages`	`int`	`1000`	History cap per session
`max_inbox`	`int`	`256`	Bounded per-session queue size; `0` = unlimited
`mirror_runtime_state`	`bool`	`false`	Opt-in runtime-state mirroring for native transcript replay

Common patterns

Python override:

from praisonai.gateway.server import WebSocketGateway
from praisonaiagents.session.store import DefaultSessionStore

gateway = WebSocketGateway(
    port=8765,
    session_store=DefaultSessionStore("./sessions"),
)

An explicit session_store always wins over the YAML/default derivation. CLI opt-out now honoured: session.persist: false in gateway.yaml is re-read on start_with_config, so the multi-bot CLI now actually runs ephemeral (previously the flag was silently ignored). Choosing resume_window: minutes for ephemeral chat, 24 h for support bots, up to 7 days for long tasks.

Best Practices

Opt out only when you need to

The default is durable because most conversational bots want continuity. Only set persist: false for stateless, single-shot flows or ephemeral CI runs.

Confirm the on-disk store engaged

Expect the transcript DB at ~/.praisonai/sessions/sessions.db. If the doctor or logs report an in-memory fallback, $HOME is unwritable.

Always send since on reconnect

Without since, the client may miss events between disconnect and resume.

Match resume_window to user behaviour

Too short loses conversations; too long grows disk usage.

Back up persist_path

Session files should be included in normal backup rotation.

One gateway per persist_path

Do not share storage between two gateway processes — see Gateway Overview single-instance guidance.

Gateway Overview

Gateway setup and configuration

SQLite Transcript Store

The default persistence backend, engaged out-of-the-box

Gateway Session Continuity

Preserve pending inbox and mid-turn state across disconnects

Restart Continuation

Notify channel users after a gateway restart

Write-failure salvage

Spill + re-ingest when a durable session write fails

​Quick Start

​What gets persisted

​How it works

​Reconnect protocol

​Configuration options

​Common patterns

​Best Practices

​Related

Gateway Overview

SQLite Transcript Store

Gateway Session Continuity

Restart Continuation

Write-failure salvage

Quick Start

What gets persisted

How it works

Reconnect protocol

Configuration options

Common patterns

Best Practices

Related