Skip to main content
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.

​
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

​
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