> ## 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 Compaction
> Summarise older turns in long-lived bot sessions instead of dropping them
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).
Long-lived bot conversations get a compact summary of older turns instead of having them silently dropped.
This is the **bot-side** runtime context compactor. For the store-side, on-disk retention model (session-persistence retention policies), see [Session Persistence β Retention Policies](/docs/features/session-persistence#retention-policies).
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(name="assistant", instructions="Maintain context across a long Telegram thread.")
agent.start("Summarise what we discussed last week.")
```
The user continues a long-lived bot thread; older turns are summarised instead of being dropped silently.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Bot Session Compaction"
H[π Long history] --> C{π Over budget?}
C -->|No| K[π Keep verbatim]
C -->|Yes| S[π Summary + recent tail]
S --> P[πΎ Persist compacted form]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
class H input
class C decision
class K,S,P result
```
## Quick Start
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
channels:
telegram:
token: ${TELEGRAM_BOT_TOKEN}
session:
compaction:
enabled: true
```
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
channels:
telegram:
token: ${TELEGRAM_BOT_TOKEN}
session:
max_history: 500 # hard cap
compaction:
enabled: true
strategy: summarize # or truncate / sliding / smart / prune / llm_summarize
max_messages: 100 # approximate compaction threshold
keep_recent: 10 # keep the last 10 turns verbatim
```
***
## Agent-Centric Example
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonai.bots import TelegramBot
bot = TelegramBot(
token="YOUR_BOT_TOKEN",
agent=Agent(name="Assistant", instructions="Help users."),
session={
"compaction": {
"enabled": True,
"strategy": "summarize",
"max_messages": 100,
"keep_recent": 10,
}
},
)
bot.run()
```
***
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Bot
participant Manager as BotSessionManager
participant Compactor as ContextCompactor
participant Store
User->>Bot: Message #500
Bot->>Manager: _save_history(history)
Manager->>Compactor: needs_compaction(history)?
alt Over budget
Compactor-->>Manager: yes
Manager->>Compactor: compact(history)
Compactor-->>Manager: [summary, β¦recent tail]
Manager->>Store: set_chat_history(compacted)
else Under budget
Compactor-->>Manager: no
Manager->>Store: set_chat_history(history)
end
```
Compaction runs at save time. When history exceeds the budget, the manager summarises older turns into a single system message, appends the most-recent verbatim tail, and persists the compacted form. Bot restarts preserve the same memory.
The manager builds a fresh `ContextCompactor` per save call rather than sharing one instance. This prevents per-conversation summary state from leaking between users under concurrent saves.
***
## Choosing a Strategy
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q{What matters most?} -->|Long-term continuity| Summarize[summarize
default]
Q -->|Speed + low cost| Truncate[truncate
opt-out]
Q -->|Fixed window| Sliding[sliding]
Q -->|Balanced production| Smart[smart]
Q -->|Drop tool noise| Prune[prune]
Q -->|Highest quality summary| LLM[llm_summarize]
classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef option fill:#10B981,stroke:#7C90A0,color:#fff
class Q question
class Summarize,Truncate,Sliding,Smart,Prune,LLM option
```
| Strategy | Use when |
| --------------------- | ----------------------------------------------------------- |
| `summarize` (default) | Long-running support bots / personal assistants. |
| `truncate` | Explicit opt-out β same behaviour as no compaction config. |
| `sliding` | Fixed-window conversations (e.g. customer chat queues). |
| `smart` | Production default when you want a balanced trade-off. |
| `prune` | Tool-heavy agents that produce noisy intermediate messages. |
| `llm_summarize` | Highest fidelity summary; uses an extra LLM call. |
***
## Configuration Options
| Option | Type | Default | Description |
| -------------- | ------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `enabled` | `bool` | `false` | Master switch. When `false` the legacy tail-slice truncation runs. |
| `strategy` | `str` | `"summarize"` | One of `truncate`, `sliding`, `summarize`, `smart`, `prune`, `llm_summarize`. Invalid values raise at schema-validation time. |
| `max_messages` | `int` | `100` | Approximate compaction threshold. Converted to a token budget (`max_messages Γ 80`) when `max_tokens` is not set. Must be β₯ 1. |
| `max_tokens` | `int` | `null` | Optional explicit token budget. Overrides `max_messages` when set. |
| `keep_recent` | `int` | `10` | Number of most-recent messages kept verbatim (tail). Must be β₯ 0. |
Configure under `session.compaction` inside any channel block in `gateway.yaml` or `bot.yaml`.
***
## User Interaction Flow
> *A 3-week-old Telegram support bot conversation. Messages 1β400 covered the customer's account setup, billing decisions, and ongoing tickets. Message #500 arrives. **Without compaction:** the bot loads the most recent 100 messages and has no memory of the original setup β the customer has to re-explain everything. **With compaction:** the bot loads a one-line summary of decisions/facts from messages 1β490 followed by the last 10 verbatim turns. The agent answers the new question with full historical context. The compacted form is also persisted, so a bot restart preserves the memory.*
***
## Best Practices
Reset clears context on idle or daily schedule. Compaction keeps context across long sessions. `max_history Γ 4` is the hard cap in compaction mode β history cannot grow past that ceiling even if the token threshold has not tripped yet. Use all three together for production bots.
`enabled: true` alone is enough for most bots. The defaults (`strategy: summarize`, `max_messages: 100`, `keep_recent: 10`) work well out of the box.
When the most recent turns carry the context that matters β a multi-step purchase flow or live escalation β increase `keep_recent` so more verbatim turns survive the compaction cycle.
The manager builds a fresh compactor per save call, so per-conversation summary state never leaks between users sharing the same bot instance. This is safe for concurrent, high-traffic bots.
***
## Related
Clear history on idle or daily schedule
How bot sessions are stored and restored
Multi-platform bot setup and YAML config
Agent-level context compaction (core ContextCompactor API)