Davendra Patel 2e3e12f38b docs: add pre-rendered diagram PNGs and update AGENTS.md with architecture overview

Add 32 rendered PNG diagram images alongside existing Mermaid source
blocks (wrapped in collapsible details) across documentation pages.
Update AGENTS.md with architecture overview section and single-test
command. Update README hero banner to use rendered diagram.

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

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

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

Diagram source (Mermaid)

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.7 KiB Raw Blame History Unescape Escape