Session Hierarchy

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

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

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 use an mtime-checked cache, so a write that changes the file on disk is visible on the next read.

Operation	Safe under concurrency
`get_extended_session()`	Yes — mtime-checked cache; a changed file is re-read, so cross-instance writes are visible on the next read
`add_message()`	Yes — locked read-modify-write
`fork_session()`	Yes — reloads parent first
`create_snapshot()` / `revert_to_snapshot()`	Yes — atomic under lock

Object identity is not a stable API — expect either a fresh ExtendedSessionData object or a cached one. When the file on disk is unchanged, consecutive get_extended_session() calls can return the same cached object; when it has changed, you get a fresh one. Use the returned data, not session_a is session_b. Changed in PR #4958.

Pass force_reload=True for the rare case a caller needs the old unconditional-reread behaviour:

from praisonaiagents.session import get_hierarchical_session_store

store = get_hierarchical_session_store()
session = store.get_extended_session(session_id, force_reload=True)  # bypass cache

Cache Semantics

get_extended_session() now shares the same mtime-checked cache as the internal helpers — a read hits the cache when the file is unchanged and re-reads when its mtime bumps.

Method	Cache behaviour
`get_extended_session(force_reload=False)` / `get_chat_history()` / `get_session()`	mtime-checked cache — cached when the file is unchanged, re-read when it changes; pass `force_reload=True` to always re-read
`_load_extended_session()` (used internally by `fork_session`, `revert_to_snapshot`, `get_children`)	Same mtime-checked cache, safe because the caller holds a `FileLock`
`invalidate_cache(session_id=None)`	Clears both in-memory caches — rarely needed on the read path

invalidate_cache() only matters if your own code caches ExtendedSessionData references; the read path never needs it.

Cross-instance reads

A write from a second store instance on the same directory changes the file’s mtime, so it is seen by the first store’s next read — no manual invalidate_cache() required.

from praisonaiagents.session import get_hierarchical_session_store, HierarchicalSessionStore

store = get_hierarchical_session_store()
session_id = store.create_session(title="Cross-worker")
store.add_message(session_id, "user", "first")

# A second store instance pointing at the same session_dir
other = HierarchicalSessionStore(session_dir=store.session_dir)
other.add_message(session_id, "user", "second")

seen = store.get_extended_session(session_id)
assert [m.content for m in seen.messages] == ["first", "second"]

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.

Session Store

Default and hierarchical store APIs

Session Protocol

Custom Redis/Postgres backends

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

Multi-Worker Safety

Cache Semantics

Cross-instance reads

Best Practices

Session Store

Session Protocol

​Quick Start

​Multi-Worker Safety

​Cache Semantics

​Cross-instance reads

​Best Practices

​Related

Session Store

Session Protocol

Quick Start

Multi-Worker Safety

Cache Semantics

Cross-instance reads

Best Practices

Related