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

​
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.
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"))

​
Core Exports

ExportPurpose
DefaultSessionStoreJSON-on-disk default backend
SessionMessage, SessionDataTyped message and session payloads
CompactionCheckpointPersisted compaction summary + resume anchor — see Compaction Checkpoints
get_default_session_store()Process-wide store accessor
SessionStoreProtocolImplement for Redis, Postgres, S3 — see Session Protocol
HierarchicalSessionStore, get_hierarchical_session_store()Forks, snapshots, parent-child — see Session Hierarchy
IdentityResolverProtocol, FileIdentityResolverMap anonymous → known user IDs across sessions
SessionContext, set_session_context(), get_session_context()Task-local session context for async flows

​
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

MethodDescription
append_compaction_checkpoint(session_id, summary, *, role="system", tokens_before=0, tokens_after=0, metadata=None)Persist a checkpoint anchored to the current end of the transcript. Returns bool; a blank/whitespace summary is a no-op returning False.
get_working_history(session_id, max_messages=None)Canonical read path — uses the checkpoint when present (summary + tail), falls back to raw chat history when not.

​
SessionData additions

SessionData.last_compaction holds the latest CompactionCheckpoint (or None). Two helpers support cheap resume:
MemberDescription
last_compactionOptional[CompactionCheckpoint] — the persisted checkpoint, serialised into the session JSON
trim_messages(max_messages)Trim the transcript head, shifting the checkpoint anchor so the retained tail stays aligned
get_working_history(max_messages=None)Reconstruct [summary_message, *tail]; falls back to get_chat_history with no checkpoint
set_chat_history() and clear_session() both clear last_compaction — replacing or clearing the transcript invalidates the anchor.

​
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

Let Agent(memory={"session_id": "..."}) handle persistence — use the store directly only for admin, migration, or custom backends.
Switch to get_hierarchical_session_store() when you need branching conversations or revert — see Session Hierarchy.
Call set_session_context() at the start of each async task so downstream code reads the correct session without threading IDs through every call.

Session Persistence

Agent-centric session_id usage

Session Hierarchy

Forking and snapshots