Skip to main content
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.
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
# Set session.persist: true in gateway.yaml so this agent's session survives restarts
The user returns later; persisted session state reloads so the agent remembers prior turns.

​
Quick Start

1

Enable persistence

gateway:
  host: "127.0.0.1"
  port: 8765
  session:
    persist: true

praisonai gateway start --config gateway.yaml
Default storage: ~/.praisonai/sessions/
2

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))
3

Full configuration

gateway:
  session:
    persist: true
    persist_path: ~/.praisonai/sessions/
    resume_window: 86400
    timeout: 3600
    max_messages: 1000

​
What gets persisted

The on-disk record under persist_path is the JSON returned by GatewaySession.to_dict(). Key fields:
KeyTypePurpose
session_idstrStable identifier; used on resume
event_cursorintPosition in the event log for replay
sequenceintMonotonic outbound sequence (gap detection)
protocol_versionintProtocol version negotiated at the last handshake
capabilitiesList[str]Capability tokens advertised by the client (streaming, presence, ack, …)
eventsList[GatewayEvent]Last 100 events (for replay)
pending_inboxList[...]In-flight inbound queue snapshot
is_executingboolMid-turn flag for Session Continuity
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

RoleResponsibility
ClientTrack highest cursor; send since on reconnect
GatewayRehydrate sessions; emit replay frames
SessionStorePersist state to disk
TTL cleanupHourly 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

OptionTypeDefaultDescription
persistboolfalseEnable persistent session storage
persist_pathstr~/.praisonai/sessions/Storage directory
resume_windowint86400Seconds a detached session stays resumable (24 h)
timeoutint3600Active session expiry in seconds
max_messagesint1000History cap per session

​
Common patterns

Python override: 
from praisonai.gateway.server import WebSocketGateway
from praisonaiagents.session.store import DefaultSessionStore

gateway = WebSocketGateway(
    port=8765,
    session_store=DefaultSessionStore("./sessions"),
)
Choosing resume_window: minutes for ephemeral chat, 24 h for support bots, up to 7 days for long tasks.

​
Best Practices

Without since, the client may miss events between disconnect and resume.
Too short loses conversations; too long grows disk usage.
Session files should be included in normal backup rotation.
Do not share storage between two gateway processes — see Gateway Overview single-instance guidance.

Gateway Overview

Gateway setup and configuration

Bot vs Gateway

When to use gateway vs direct bots