Skip to main content
Long-lived bot conversations get a compact summary of older turns instead of having them silently dropped.

​
Quick Start

1

Enable with one line

channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    session:
      compaction:
        enabled: true
2

Tune the budget

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

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

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

StrategyUse when
summarize (default)Long-running support bots / personal assistants.
truncateExplicit opt-out — same behaviour as no compaction config.
slidingFixed-window conversations (e.g. customer chat queues).
smartProduction default when you want a balanced trade-off.
pruneTool-heavy agents that produce noisy intermediate messages.
llm_summarizeHighest fidelity summary; uses an extra LLM call.

​
Configuration Options

OptionTypeDefaultDescription
enabledboolfalseMaster switch. When false the legacy tail-slice truncation runs.
strategystr"summarize"One of truncate, sliding, summarize, smart, prune, llm_summarize. Invalid values raise at schema-validation time.
max_messagesint100Approximate compaction threshold. Converted to a token budget (max_messages × 80) when max_tokens is not set. Must be ≥ 1.
max_tokensintnullOptional explicit token budget. Overrides max_messages when set.
keep_recentint10Number 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.

Bot Session Reset

Clear history on idle or daily schedule

Session Persistence

How bot sessions are stored and restored

Messaging Bots

Multi-platform bot setup and YAML config

Context Compaction

Agent-level context compaction (core ContextCompactor API)