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

# Bot Session Reset

> Automatically reset bot sessions based on idle time or daily schedule

<Note>
  Bot platform adapters now ship in the `praisonai-bot` package. `praisonai bot serve` still works exactly as documented here; for a standalone install see [praisonai-bot Migration](/docs/guides/praisonai-bot-migration).
</Note>

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, BotConfig

agent = Agent(name="assistant", instructions="You are a helpful assistant.")
config = BotConfig(session_reset_hours=24)
agent.start("Reset sessions after 24 hours of inactivity.")
```

The user returns after idle time; session reset clears stale history so the agent starts fresh.

Session reset policies automatically clear bot conversation history after inactivity or at a scheduled time, preventing unbounded context growth.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    U[User message] --> M[BotSessionManager]
    M --> R{_should_reset?}
    R -->|Yes| C[Clear history]
    R -->|No| H[Load history]
    C --> A[Agent]
    H --> A
    A --> U

    classDef user fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff

    class U user
    class M process
    class R decision
    class C,H,A agent

```

## Quick Start

<Steps>
  <Step title="Idle reset after 30 minutes">
    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    channels:
      telegram:
        token: ${TELEGRAM_BOT_TOKEN}
        session:
          reset:
            mode: idle
            idle_minutes: 30
    ```
  </Step>

  <Step title="Daily reset at 04:00">
    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    channels:
      discord:
        token: ${DISCORD_BOT_TOKEN}
        session:
          reset:
            mode: daily
            at_hour: 4
    ```
  </Step>

  <Step title="Combined idle + daily">
    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    channels:
      slack:
        token: ${SLACK_BOT_TOKEN}
        app_token: ${SLACK_APP_TOKEN}
        session:
          max_history: 100
          reset:
            mode: both
            idle_minutes: 60
            at_hour: 4
    ```
  </Step>
</Steps>

***

## How It Works

Reset checks run in `BotSessionManager._load_history()` **before** reusing existing history:

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Bot
    participant Manager as BotSessionManager
    participant Agent

    User->>Bot: Message
    Bot->>Manager: _load_history()
    Manager->>Manager: _should_reset_session()
    alt Reset needed
        Manager->>Manager: _clear_session_data()
        Manager-->>Bot: []
    else Continue session
        Manager-->>Bot: existing history
    end
    Bot->>Agent: run with history
    Agent-->>User: response
```

Idle timestamps are tracked **per user**. Idle timeout uses monotonic time; daily reset uses wall-clock hour.

***

## Reset Modes

| Mode    | Behaviour                                          |
| ------- | -------------------------------------------------- |
| `none`  | No automatic reset (default — backward compatible) |
| `idle`  | Reset after N minutes of inactivity                |
| `daily` | Reset at a specific hour each day (0–23)           |
| `both`  | Combine idle and daily reset                       |

***

## Configuration Options

| Option         | Type  | Default  | Description                                                              |
| -------------- | ----- | -------- | ------------------------------------------------------------------------ |
| `mode`         | `str` | `"none"` | One of `none`, `idle`, `daily`, `both`                                   |
| `idle_minutes` | `int` | `60`     | Minutes of inactivity before reset (≥1). Used when mode includes `idle`. |
| `at_hour`      | `int` | `None`   | Daily reset hour (0–23). **Required** when mode is `daily` or `both`.    |
| `max_history`  | `int` | `100`    | Maximum history entries (parent `session` block).                        |

Configure under each channel's `session.reset` block in `gateway.yaml` or `bot.yaml`.

***

## Common Patterns

**Customer support** — drop stale conversations when the customer leaves:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
session:
  reset:
    mode: idle
    idle_minutes: 30
```

**Daily briefing bot** — fresh start each midnight:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
session:
  reset:
    mode: daily
    at_hour: 0
```

**Compliance bot** — idle timeout plus nightly sweep:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
session:
  reset:
    mode: both
    idle_minutes: 15
    at_hour: 2
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Session Reset vs Session Reaper">
    **Session Reset Policy** (this feature) clears a user's *conversation history* based on idle or scheduled time — configured per channel in YAML.

    **Session Reaper** (`session_ttl` on `BotConfig`) prunes the *in-memory session record* of stale users. They solve different problems; use both for long-running bots.
  </Accordion>

  <Accordion title="Pair with max_history and session compaction">
    Combine `session.max_history` with reset policies to cap context size and cost. Reset clears history entirely; `max_history` trims retained turns during an active session; `session.compaction` summarises older turns instead of dropping them. See [Bot Session Compaction](/features/bot-session-compaction).
  </Accordion>

  <Accordion title="Manual /new command">
    Users can always send `/new` for an immediate reset. Manual reset works alongside automatic policies — see [Bot Commands](/docs/features/bot-commands).
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Messaging Bots" icon="comments" href="/docs/features/messaging-bots">
    Multi-platform bot setup and YAML config
  </Card>

  <Card title="Bot Commands" icon="terminal" href="/docs/features/bot-commands">
    Built-in /new, /help, and /status commands
  </Card>

  <Card title="Sessions" icon="clock-rotate-left" href="/docs/features/sessions">
    Agent-level session management
  </Card>

  <Card title="Session Persistence" icon="database" href="/docs/features/session-persistence">
    Persisting session state to disk
  </Card>

  <Card title="Bot Session Compaction" icon="compress" href="/docs/features/bot-session-compaction">
    Summarise old turns instead of dropping them
  </Card>
</CardGroup>