Module compact 

Context management and compaction for agent conversations.

As conversations grow, they approach the model’s context window limit. Infrastructure to detect when compaction is needed and to carry it out through a pluggable strategy.

Architecture

The design separates when to compact from how to compact:

1. ContextManager monitors token usage, checks thresholds, and decides when to trigger compaction.
2. ContextCompactor is the trait that defines the compaction strategy. Plug in truncation, summarization, or any custom approach.

Provided Compactors

• TruncatingCompactor — drops the oldest messages, keeping the system prompt and a configurable number of recent messages. No LLM calls required.

Agent-side compactors (LLM-based summarization, Q&A extraction, etc.) live outside the framework and implement ContextCompactor against their own API client.

Supporting Types

• TokenSplitter — splits a conversation at turn boundaries for coherent compaction.
• CompactTelemetry — telemetry data for compaction operations.
• CompactionOutcome — result of a single compaction pass.
• CompactionContext — input context passed to compactors.

Quick Start

use loopctl::compact::{ContextManager, TruncatingCompactor};
use std::sync::Arc;

let compactor = TruncatingCompactor::new()
    .with_preserve_recent(4)
    .with_min_messages(6);

let manager = ContextManager::new(Arc::new(compactor))
    .with_context_window(200_000)
    .with_threshold(80);

assert_eq!(manager.context_window(), 200_000);
assert_eq!(manager.threshold(), 80);

Integration with BareLoop

The engine’s BareLoop accepts an optional ContextManager. When present, it checks token usage after each turn and triggers compaction automatically when usage exceeds the threshold.

Re-exports

pub use truncating::SplitResult;

pub use truncating::TokenSplitter;

pub use truncating::TruncatingCompactor;

pub use types::CompactReason;

pub use types::CompactTelemetry;

pub use types::CompactionContext;

pub use types::CompactionOutcome;

pub use types::ContextOverflow;

pub use types::EnsureContextResult;

pub use types::PostCompactStats;

pub use types::PreCompactStats;

Modules

truncating

Truncating compactor and token splitter.

types

Supporting types for context compaction.

Structs

ContextManager

Manages context window usage and triggers compaction when needed.

HeuristicTokenCounter

A zero-dependency token estimator using a characters-per-token ratio.

Enums

CompactBase

Determines the base used to calculate the compaction target.

Traits

ContextCompactor

Implementations define how to reduce a message list — truncation, summarization, Q&A extraction, etc. The framework calls compact when the ContextManager determines compaction is needed.

TokenCounter

Strategy for estimating the token cost of a message slice.