Skip to main content
Session hierarchy adds forking, snapshots, and revert on top of file-backed sessions — safe when multiple workers share one directory.
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

2

Snapshot, fork, or revert

​
Multi-Worker Safety

Multiple processes can share one session directory — public reads always reload from disk, so cross-instance writes are visible immediately.
get_extended_session() returns fresh data on every call — do not rely on object identity (session_a is session_b). The in-process cache stays coherent, but the same read may return a newly constructed ExtendedSessionData object.

​
Cache Semantics

Public reads always reload from disk; internal helpers reuse a cache guarded by a file lock. invalidate_cache() only matters if your own code caches ExtendedSessionData references; the public read path never needs it.

​
Cross-instance reads

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

​
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