Davendra Patel d9851627b2 docs: add 29 inline Mermaid diagrams across documentation

Add visual Mermaid diagrams to supplement existing text descriptions
throughout docs/. Diagrams cover architecture, message flows, agent
lifecycle, routing, queue modes, security layers, plugin discovery,
tool groups, session lifecycle, and onboarding flows. No existing
content removed or altered.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-29 16:02:09 +05:30

2.6 KiB

Raw Blame History

summary

read_when

Context window + compaction: how Moltbot keeps sessions under model limits

You want to understand auto-compaction and /compact

You are debugging long sessions hitting context limits

Context Window & Compaction

Every model has a context window (max tokens it can see). Long-running chats accumulate messages and tool results; once the window is tight, Moltbot compacts older history to stay within limits.

flowchart TD
    A[Session Messages Accumulate] --> B{Near Context Limit?}
    B -->|No| C[Continue Normally]
    B -->|Yes| D{Memory Flush Enabled?}
    D -->|Yes| E[Silent Memory Flush Turn\nWrite durable notes to disk]
    D -->|No| F[Skip Flush]
    E --> F
    F --> G[Auto-Compaction Triggered]
    G --> H[Summarize Older Messages]
    H --> I[Store Compaction Summary\nin Session JSONL]
    I --> J[Keep Recent Messages Intact]
    J --> K[Retry Original Request\nwith Compacted Context]
    K --> C

What compaction is

Compaction summarizes older conversation into a compact summary entry and keeps recent messages intact. The summary is stored in the session history, so future requests use:

The compaction summary
Recent messages after the compaction point

Compaction persists in the session’s JSONL history.

Configuration

See Compaction config & modes for the agents.defaults.compaction settings.

Auto-compaction (default on)

When a session nears or exceeds the model’s context window, Moltbot triggers auto-compaction and may retry the original request using the compacted context.

You’ll see:

🧹 Auto-compaction complete in verbose mode
/status showing 🧹 Compactions: <count>

Before compaction, Moltbot can run a silent memory flush turn to store durable notes to disk. See Memory for details and config.

Manual compaction

Use /compact (optionally with instructions) to force a compaction pass:

/compact Focus on decisions and open questions

Context window source

Context window is model-specific. Moltbot uses the model definition from the configured provider catalog to determine limits.

Compaction vs pruning

Compaction: summarises and persists in JSONL.
Session pruning: trims old tool results only, in-memory, per request.

See /concepts/session-pruning for pruning details.

Tips

Use /compact when sessions feel stale or context is bloated.
Large tool outputs are already truncated; pruning can further reduce tool-result buildup.
If you need a fresh slate, /new or /reset starts a new session id.

2.6 KiB Raw Blame History Unescape Escape