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

# Hierarchical Sessions

> Create parent-child session relationships for complex Agent workflows

Fork and nest agent sessions in a parent-child tree.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Root[Root Session] --> Child[Child Session]
    Child --> Leaf([Context])

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff

    class Root,Child agent
    class Leaf tool
    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff

```

Create session hierarchies for complex multi-Agent workflows. Child sessions inherit context from parents, enabling scoped conversations and forking.

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    import { HierarchicalSession, createHierarchicalSession } from 'praisonai';

    // Create parent session
    const parentSession = createHierarchicalSession({
      id: 'main-workflow'
    });

    // Add context to parent
    parentSession.setContext('goal', 'Build an AI application');
    parentSession.setContext('language', 'TypeScript');

    // Create child session (inherits parent context)
    const childSession = parentSession.fork({
      id: 'research-phase'
    });

    // Child can access parent context
    console.log(childSession.getContext('goal')); // 'Build an AI application'

    // Child can add its own context
    childSession.setContext('phase', 'research');
    ```
  </Step>

  <Step title="With Configuration">
    See the sections below for advanced options.
  </Step>
</Steps>

***

## Create Session Hierarchy

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { HierarchicalSession, createHierarchicalSession } from 'praisonai';

// Create parent session
const parentSession = createHierarchicalSession({
  id: 'main-workflow'
});

// Add context to parent
parentSession.setContext('goal', 'Build an AI application');
parentSession.setContext('language', 'TypeScript');

// Create child session (inherits parent context)
const childSession = parentSession.fork({
  id: 'research-phase'
});

// Child can access parent context
console.log(childSession.getContext('goal')); // 'Build an AI application'

// Child can add its own context
childSession.setContext('phase', 'research');
```

## Multi-Level Hierarchy

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { HierarchicalSession } from 'praisonai';

// Root session
const root = new HierarchicalSession({ id: 'project' });
root.setContext('project', 'AI Agent Framework');

// Level 1: Phase sessions
const planning = root.fork({ id: 'planning' });
const development = root.fork({ id: 'development' });

// Level 2: Task sessions
const research = planning.fork({ id: 'research' });
const design = planning.fork({ id: 'design' });

// Each level inherits from parents
console.log(research.getContext('project')); // 'AI Agent Framework'
```

## Context Inheritance & Scoping

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { HierarchicalSession } from 'praisonai';

const parent = new HierarchicalSession({ id: 'parent' });
parent.setContext('shared', 'visible-to-all');

const child = parent.fork({ 
  id: 'child',
  isolateContext: false  // Inherit parent context (default)
});

// Child sees parent context
console.log(child.getContext('shared')); // 'visible-to-all'

// Child modifications don't affect parent
child.setContext('local', 'child-only');
console.log(parent.getContext('local')); // undefined
```

## Session Forking

Create branches for parallel exploration:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { HierarchicalSession } from 'praisonai';

const main = new HierarchicalSession({ id: 'main' });
main.addMessage({ role: 'user', content: 'Help me design an API' });

// Fork for different approaches
const restApproach = main.fork({ id: 'rest-design' });
const graphqlApproach = main.fork({ id: 'graphql-design' });

// Each fork starts with same history but diverges
await restApproach.chat('Design REST endpoints');
await graphqlApproach.chat('Design GraphQL schema');

// Choose the best approach
const winner = restApproach; // Based on evaluation
main.merge(winner);  // Merge winning branch back
```

## Use with Agents

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, HierarchicalSession } from 'praisonai';

const projectSession = new HierarchicalSession({ id: 'project' });
projectSession.setContext('requirements', 'Build a chatbot');

// Research Agent with scoped session
const researchSession = projectSession.fork({ id: 'research' });
const researcher = new Agent({
  name: 'Researcher',
  instructions: 'Research best practices for the given requirements.',
  session: researchSession
});

// Implementation Agent with different scope
const implSession = projectSession.fork({ id: 'implementation' });
const implementer = new Agent({
  name: 'Implementer',
  instructions: 'Implement based on research findings.',
  session: implSession
});

// Each Agent works in its own scope but shares project context
await researcher.chat('Research chatbot frameworks');
await implementer.chat('Implement the chatbot');
```

## Session Tree Visualization

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { HierarchicalSession } from 'praisonai';

const root = new HierarchicalSession({ id: 'root' });
root.fork({ id: 'child-1' }).fork({ id: 'grandchild-1' });
root.fork({ id: 'child-2' });

// Get tree structure
const tree = root.getTree();
console.log(tree);
/*
root
├── child-1
│   └── grandchild-1
└── child-2
*/
```

## Related

<CardGroup cols={2}>
  <Card title="Sessions" icon="clock" href="/docs/js/sessions">
    Basic session management
  </Card>

  <Card title="Multi-Agent" icon="users" href="/docs/js/agents">
    Multi-Agent workflows
  </Card>

  <Card title="Memory" icon="brain" href="/docs/js/memory">
    Agent memory systems
  </Card>
</CardGroup>