Skip to main content
Session hierarchy adds forking, snapshots, and revert on top of file-backed sessions — safe when multiple workers share one directory. 
from praisonaiagents import Agent
from praisonaiagents.session import get_hierarchical_session_store

store = get_hierarchical_session_store()
session_id = store.create_session(title="Planning chat")

agent = Agent(
    name="Assistant",
    instructions="Help me plan a trip",
    memory={"session_id": session_id},
)
agent.start("I want to visit Japan in spring")
The user forks or snapshots a chat session; hierarchical stores keep branches safe across workers.
For basic persistence, use Agent(memory={"session_id": "my-session"}). See Session Persistence.

​
Quick Start

1

Create a session and chat

from praisonaiagents import Agent
from praisonaiagents.session import get_hierarchical_session_store

store = get_hierarchical_session_store()
session_id = store.create_session(title="Planning chat")

agent = Agent(
    name="Assistant",
    instructions="Help me plan a trip",
    memory={"session_id": session_id},
)
agent.start("I want to visit Japan in spring")
2

Snapshot, fork, or revert

snapshot_id = store.create_snapshot(session_id, label="Before branch")
fork_id = store.fork_session(session_id, from_message_index=2, title="Alternate plan")

# Revert if the experimental path fails
store.revert_to_snapshot(session_id, snapshot_id)

​
Multi-Worker Safety

Multiple processes can share one session directory — reads reload when the on-disk file changes.
OperationSafe under concurrency
get_extended_session()Yes — mtime-checked cache
add_message()Yes — locked read-modify-write
fork_session()Yes — reloads parent first
create_snapshot() / revert_to_snapshot()Yes — atomic under lock

​
Best Practices

Call create_snapshot() before experimental branches or bulk rewrites. revert_to_snapshot() restores the parent in one step.
Use fork_session(..., from_message_index=N) to branch from a specific turn without losing the parent transcript.
Point every worker at the same session_dir. The hierarchical store reloads from disk under lock before fork or revert.

Session Store

Default and hierarchical store APIs

Session Protocol

Custom Redis/Postgres backends