Session Store

Default JSON storage, hierarchical sessions, identity, and task-local context

Session stores persist chat history and metadata — swap the default JSON backend or use hierarchical forks without changing your agent code.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    memory={"session_id": "user-42-chat"},
)
agent.start("Remember I like tea.")
agent.start("What do I like?")  # History restored from ~/.praisonai/sessions/

The user chats across restarts; the session store persists history under ~/.praisonai/sessions/.

How It Works

Where sessions are stored

The session directory is resolved live from PRAISONAI_HOME, so relocating the store root works even after PraisonAI is imported (PraisonAI PR #4125).

Resolution order (highest priority first):

Set PRAISONAI_HOME before the first turn to redirect storage — it is honoured live, even after praisonaiagents is imported:

import os
os.environ["PRAISONAI_HOME"] = "/data/praisonai"   # honoured live, even after import

from praisonaiagents import Agent

agent = Agent(name="Assistant", memory={"session_id": "user-42-chat"})
agent.start("Remember I like tea.")   # saved under /data/praisonai/sessions/

On-disk filenames (collision-safe)

Two different session ids never share a file. Each user keeps their own history, even when ids differ only in ., @, :, /, +, or spaces.

from praisonaiagents import Agent

alice = Agent(name="Assistant", memory={"session_id": "alice.smith@example.com"})
other = Agent(name="Assistant", memory={"session_id": "alice_smith_example_com"})
# Separate files — neither agent sees the other's history.

Letters and digits include Unicode (café keeps café.json). Other ids use <readable[:64]>~<sha256(id)[:16]>.json: the readable prefix replaces unsafe characters with _ and is capped at 64 characters; the 16 hex digest of the full id keeps the mapping injective.

• Legacy migration — a file written by an older release under the old lossy name is moved to the new path on first read, only when its stored session_id equals the requested id. A legacy file owned by a different id is never adopted.
• Ownership check on read — if a loaded file’s stored session_id differs from the requested id, it is never returned. The store logs a warning, starts a fresh session, and moves the foreign file to its owner’s path (or sets it aside as <name>.json.corrupt-<ts> when that path is taken).
• Spill files from write-failure salvage use the same filename stem.

No code change is needed — existing sessions with safe ids keep their files. See PraisonAI issue #6024 and PR #6061.

Portable export/import

DefaultSessionStore, SqliteSessionStore, and SqliteTranscriptStore all implement PortableSessionStoreProtocol, so you can back up, migrate, or restore live conversation state as a versioned JSON payload.

from praisonaiagents.session import DefaultSessionStore

store = DefaultSessionStore()
payload = store.export_all()               # {"version": 1, "sessions": [...]}
report  = store.import_sessions(payload)   # ImportReport (imported / skipped)

• Portability is protocol-level, not store-level — any store that implements PortableSessionStoreProtocol gets the same backup/restore surface.
• Import resets live routing fields (gateway_session_id, agent_id) by default, so restored sessions stay inert until re-bound.

See Gateway Session Portability for the operator-facing backup / migrate / restore story.

Quick Start

1. Persist with session_id

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Assistant",
       memory={"session_id": "user-42-chat"},
   )
   agent.start("Remember I like tea.")
   agent.start("What do I like?")

   Default files live at ~/.praisonai/sessions/{session_id}.json for ids made of letters, digits, _ and - — see On-disk filenames for other ids.

2. Use the store directly

   from praisonaiagents import Agent
   from praisonaiagents.session import get_default_session_store
   
   store = get_default_session_store()
   session_id = "user-42-chat"
   
   agent = Agent(name="Assistant", memory={"session_id": session_id})
   store.add_message(session_id, "assistant", agent.start("Summarise our chat"))

Encryption at rest

Wrap any store — DefaultSessionStore, SqliteSessionStore, HierarchicalSessionStore, or a custom backend — with EncryptedSessionStore so message content and metadata are encrypted before they reach disk.

import os
from praisonaiagents.session import SqliteSessionStore, EncryptedSessionStore

store = EncryptedSessionStore(
    SqliteSessionStore(db_path="~/.praisonai/sessions.db"),
    key=os.environ["PRAISONAI_SESSION_KEY"],
)

See Encrypted Session Store for keys, honest limits, and migration.

Core Exports

DefaultSessionStore constructor

SqliteSessionStore

SqliteSessionStore is a drop-in subclass of DefaultSessionStore that keeps JSON transcripts as the durable record and maintains a stdlib sqlite3 index alongside them. It gives you two indexed hot paths instead of directory scans:

• Cross-session search — FTS5 index of message content, used by search() (Issue #2927).
• Gateway/agent routing — session_route index of gateway_session_id and agent_id, used by get_by_gateway_session() and list_sessions_by_gateway_agent() (Issue #2956).

Both stay independent of the number of stored sessions, so a long-lived gateway bot with thousands of sessions still routes an inbound message in a single indexed lookup.

SqliteSessionStore opens its underlying FTS5 index through sqlite_connect(..., guard=True), so a malformed index file is detected on open, forensically backed up, and repaired in place instead of crashing the store. See Hardened SQLite Storage → Integrity Guard.

from praisonaiagents import Agent
from praisonaiagents.session import SqliteSessionStore

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

from praisonaiagents import Agent
from praisonaiagents.session import SqliteSessionStore

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

# Long-lived gateway bot: inbound message arrives tagged with a gateway_session_id.
# Routing back to the right session is an indexed lookup, not a directory scan.
agent = Agent(name="Gateway", session_store=store)
agent.start("Handle inbound message", session_id="chat-42")

# Later — resolve the local session for an inbound gateway event:
session = store.get_by_gateway_session("gw-abc-123")
recent = store.list_sessions_by_gateway_agent("agent-support", limit=20)

Constructor

Behaviour

A long-lived gateway bot can reset the active window without losing its route:

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"

Fallback matrix

Sizing

• Each row in session_fts holds the flattened concatenation of a session’s message content (newline-joined). Large transcripts increase index size roughly linearly.
• Use ":memory:" for ephemeral tests; use the default disk path for gateway bots that need durability across restarts.

Bookends, automated demotion, and lineage dedup apply to results from both stores — see Cross-Session Recall.

Upgrade note: archived-history reindex

See Cross-Session Recall → Recall Across Compacted History for the caller-facing behaviour.

Compaction Checkpoints

When context compaction runs during a conversation, the store can persist the summary so a later resume replays the compacted working history (summary + retained tail) instead of the full raw transcript. See Compacted Session Resume for the end-to-end agent flow.

from praisonaiagents import CompactionCheckpoint
from praisonaiagents.session import DefaultSessionStore

store = DefaultSessionStore()
store.append_compaction_checkpoint("chat-42", "Earlier: we discussed X, Y, Z.")
history = store.get_working_history("chat-42")   # summary + tail

Store Methods

SessionData additions

SessionData.last_compaction holds the latest CompactionCheckpoint (or None). Two helpers support cheap resume:

Task-Local Context

from praisonaiagents.session import set_session_context, get_session_context

set_session_context(session_id="batch-job-1", user_id="operator")

ctx = get_session_context()
print(ctx.session_id)

Best Practices

Related