Gateway Session Persistence

Persistent gateway sessions that survive restarts, with reconnect and event replay

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

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

1. 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.db

   Opt out for ephemeral, in-memory sessions:

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

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          # default — shown here for completeness
       persist_path: ~/.praisonai/sessions/
       resume_window: 86400
       timeout: 3600
       max_messages: 1000
       max_inbox: 256

What gets persisted

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

How it works

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": { "...": "..." } }

Configuration options

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

Related