Session Hierarchy

Parent-child sessions, forking, snapshots, and revert — safe under concurrent writes

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.

Operation	Safe 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

Snapshot before risky edits

Call create_snapshot() before experimental branches or bulk rewrites. revert_to_snapshot() restores the parent in one step.

Fork for parallel exploration

Use fork_session(..., from_message_index=N) to branch from a specific turn without losing the parent transcript.

Share one store directory across workers

Point every worker at the same session_dir. The hierarchical store reloads from disk under lock before fork or revert.

---

Related

Session Store

Default and hierarchical store APIs

Session Protocol

Custom Redis/Postgres backends