> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Hierarchical Sessions"
        P[📝 Parent Session] --> F[🌿 Fork]
        P --> S[📸 Snapshot]
        F --> C[🔀 Child Session]
        S --> R[⏪ Revert]
    end

    classDef session fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef op fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class P,C session
    class F,S op
    class R result
```

<Note>
  For basic persistence, use `Agent(memory={"session_id": "my-session"})`. See [Session Persistence](/features/session-persistence).
</Note>

## Quick Start

<Steps>
  <Step title="Create a session and chat">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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")
    ```
  </Step>

  <Step title="Snapshot, fork, or revert">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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)
    ```
  </Step>
</Steps>

***

## Multi-Worker Safety

Multiple processes can share one session directory — reads reload when the on-disk file changes.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant A as Worker A
    participant D as session.json
    participant B as Worker B

    A->>D: add_message
    B->>D: get_extended_session
    D-->>B: includes Worker A write
```

| 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

<AccordionGroup>
  <Accordion title="Snapshot before risky edits">
    Call `create_snapshot()` before experimental branches or bulk rewrites. `revert_to_snapshot()` restores the parent in one step.
  </Accordion>

  <Accordion title="Fork for parallel exploration">
    Use `fork_session(..., from_message_index=N)` to branch from a specific turn without losing the parent transcript.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Session Store" icon="database" href="/docs/features/session-store">
    Default and hierarchical store APIs
  </Card>

  <Card title="Session Protocol" icon="plug" href="/docs/features/session-protocol">
    Custom Redis/Postgres backends
  </Card>
</CardGroup>