Gateway Session Portability

Back up, migrate, and restore gateway conversation sessions

Export gateway conversations to a portable JSON file so you can back them up, move them between hosts, or restore them after disaster.

Quick Start

1. Back up and restore from the CLI

   Export every session to one file, then restore it on any host.

   praisonai gateway sessions export --out backup.json
   praisonai gateway sessions import --in backup.json   # inert until re-bound

2. Do it from Python

   The gateway helpers wrap the same store the gateway runs on.

   from praisonai_bot.gateway.preflight import export_gateway_sessions, import_gateway_sessions
   
   payload = export_gateway_sessions()
   report  = import_gateway_sessions(payload)
   print(report["imported"], report["skipped_count"])

How It Works

Export reads live sessions into a versioned payload; import writes them back and resets live routing fields so restored state stays inert until the gateway re-binds it.

from praisonaiagents import Agent
from praisonaiagents.session import SqliteSessionStore

store = SqliteSessionStore(db_path="~/.praisonai/sessions.db")
agent = Agent(name="Gateway", session_store=store)

# Session is bound to a gateway event and handles a conversation
agent.start("Hello", session_id="chat-42")
store.set_gateway_info("chat-42", gateway_session_id="gw-abc", agent_id="support")

# Operator clears the active window to start a fresh chat for the same user
store.clear_session("chat-42")

# The next inbound gateway event still routes to the same local session —
# the route index survives clear_session (PR #5681).
same = store.get_by_gateway_session("gw-abc")   # SessionData for "chat-42"
assert same.session_id == "chat-42"

Choosing the right options

Pick a scope, decide on lineage, and choose whether to overwrite.

CLI Reference

praisonai gateway sessions export [OPTIONS]

Examples:
  praisonai gateway sessions export --out backup.json
  praisonai gateway sessions export -s bot_slack_U123 -o one.json
  praisonai gateway sessions export -s bot_slack_U123 --no-lineage

praisonai gateway sessions import [OPTIONS]

Examples:
  praisonai gateway sessions import --in backup.json
  praisonai gateway sessions import -i backup.json --overwrite
  praisonai gateway sessions import -i backup.json --keep-live-fields --max-sessions 500 --json

Python API Reference

The same surface exists on the store and as thin gateway helpers.

from praisonaiagents.session import DefaultSessionStore, ImportReport

store = DefaultSessionStore()

# Export
payload = store.export_session("bot_slack_U123", include_lineage=True)  # {"version": 1, "sessions": [...]}
payload = store.export_all()                                            # {"version": 1, "sessions": [...]}

# Import
report: ImportReport = store.import_sessions(
    payload,
    max_sessions=10_000,
    reset_live_fields=True,
    overwrite=False,
)

Gateway helpers target the store the gateway actually runs on:

from praisonai_bot.gateway.preflight import export_gateway_sessions, import_gateway_sessions

payload = export_gateway_sessions(session_id=None, include_lineage=True)
report  = import_gateway_sessions(payload, max_sessions=10_000, reset_live_fields=True, overwrite=False)

DefaultSessionStore, SqliteSessionStore, and SqliteTranscriptStore (the default gateway backend) all implement PortableSessionStoreProtocol. The payload format is identical across all three — a backup from one restores cleanly into another.

ImportReport is JSON-serialisable via as_dict():

{
  "imported": 3,
  "skipped": [{"session_id": "s1", "reason": "already exists (use overwrite)"}],
  "skipped_count": 1,
  "version": 1
}

Payload format

The envelope is versioned and symmetric across the built-in stores.

{
  "version": 1,
  "sessions": [
    { "session_id": "bot_slack_U123", "messages": [], "metadata": {} }
  ]
}

Each session dict is the SessionData.to_dict() shape, so SessionData.from_dict() reconstructs it verbatim on import.

Concurrency & no-clobber guarantee

Concurrent importers racing on the same session_id are safe: one wins, the other is reported — never silently overwritten.

from praisonaiagents.session import SqliteSessionStore

store = SqliteSessionStore(db_path="~/.praisonai/sessions.db")

# Safe: concurrent importers cannot clobber each other.
# One wins; the other sees it in report.skipped.
report = store.import_sessions(payload, overwrite=False)
print(report.imported, report.skipped)

Both DefaultSessionStore and SqliteSessionStore enforce this guarantee identically.

overwrite=False is checked twice. The import loop first scans with session_exists, then _save_imported_session rechecks os.path.exists inside the per-file write lock — so a peer that creates the same session between the two checks still cannot be clobbered.

sequenceDiagram
    participant A as Importer A
    participant B as Peer writer B
    participant S as Store (lock + disk)

    A->>S: session_exists("shared")? false
    B->>S: write "shared" (creates file)
    A->>S: _save_imported_session("shared", overwrite=False)
    Note over S: acquire FileLock
    S-->>A: FileExistsError (recheck inside lock)
    Note over S: release lock
    A-->>A: skip with reason "already exists (use overwrite)"

    classDef importer fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef lock fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef outcome fill:#10B981,stroke:#7C90A0,color:#fff

    class A,B importer
    class S lock

The loser lands in ImportReport.skipped as {"session_id": "shared", "reason": "already exists (use overwrite)"}. As of PraisonAI PR #5631, SqliteSessionStore honours overwrite end-to-end, so this protection holds identically whether the destination is JSON-on-disk or the SQLite-indexed store.

Common Patterns

Daily backup — schedule a cron job that writes one dated file per day.

praisonai gateway sessions export --out /var/backups/gw-$(date +%F).json

Staging → production migration — export from staging, then overwrite only the ids being cut over.

praisonai gateway sessions export -s bot_slack_U123 -o cutover.json   # on staging
praisonai gateway sessions import -i cutover.json --overwrite         # on production

Move one user’s conversation between hosts — export a single lineage-aware session, plain-import on the new host.

praisonai gateway sessions export -s bot_slack_U123 -o one.json   # old host
praisonai gateway sessions import -i one.json                     # new host

Restore after disaster — import a backup; live fields reset by default, so sessions stay inert until the gateway re-binds them.

praisonai gateway sessions import --in backup.json

Best Practices

Troubleshooting

Related