Compaction Strategies

The 5 available compaction strategies.

Overview

Strategy	Speed	LLM Calls	Best For
sliding_window	Fast	None	Simple chats
summarize_older	Slow	Yes	Long research
selective_pruning	Fast	None	Tool-heavy
importance_scoring	Slow	Yes	Mixed content
hybrid	Medium	Maybe	General use

Usage

from mamba_agents import CompactionConfig

# Select strategy via config
config = CompactionConfig(strategy="sliding_window")
config = CompactionConfig(strategy="summarize_older")
config = CompactionConfig(strategy="selective_pruning")
config = CompactionConfig(strategy="importance_scoring")
config = CompactionConfig(strategy="hybrid")

API Reference

SlidingWindowStrategy

Bases: CompactionStrategy

Remove oldest messages beyond a count threshold.

This is the simplest compaction strategy. It removes messages from the beginning of the conversation until the token count is below the target.

SummarizeOlderStrategy

SummarizeOlderStrategy(
    summarization_agent: Agent[Any, str] | None = None,
)

Bases: CompactionStrategy

Summarize older messages while keeping recent ones verbatim.

Uses an LLM to create a summary of older conversation turns, replacing them with a single summary message.

Initialize the summarization strategy.

PARAMETER	DESCRIPTION
summarization_agent	Agent to use for summarization. If None, a default will be created. TYPE: Agent[Any, str] | None DEFAULT: None

Source code in src/mamba_agents/context/compaction/summarize.py

def __init__(
    self,
    summarization_agent: Agent[Any, str] | None = None,
) -> None:
    """Initialize the summarization strategy.

    Args:
        summarization_agent: Agent to use for summarization.
                            If None, a default will be created.
    """
    self._agent = summarization_agent

SelectivePruningStrategy

Bases: CompactionStrategy

Remove completed tool call/result pairs.

This strategy identifies tool calls that have been completed (have corresponding results) and removes both the call and result, keeping only a summary of what was done.

ImportanceScoringStrategy

ImportanceScoringStrategy(
    scoring_agent: Agent[Any, str] | None = None,
)

Bases: CompactionStrategy

Score messages by importance and prune lowest scored.

Uses an LLM to score messages by their importance to the conversation, then removes the lowest-scored messages.

Initialize the importance scoring strategy.

PARAMETER	DESCRIPTION
scoring_agent	Agent to use for scoring. If None, uses heuristic scoring. TYPE: Agent[Any, str] | None DEFAULT: None

Source code in src/mamba_agents/context/compaction/importance.py

def __init__(
    self,
    scoring_agent: Agent[Any, str] | None = None,
) -> None:
    """Initialize the importance scoring strategy.

    Args:
        scoring_agent: Agent to use for scoring.
                      If None, uses heuristic scoring.
    """
    self._agent = scoring_agent

HybridStrategy

HybridStrategy(
    strategies: list[CompactionStrategy] | None = None,
)

Bases: CompactionStrategy

Combination of strategies with configurable weights.

Applies multiple strategies in sequence, using each one to progressively reduce context size.

Note: This strategy overrides compact() rather than implementing _do_compact() because it needs to track which sub-strategies were used and build a composite strategy name.

Initialize the hybrid strategy.

PARAMETER	DESCRIPTION
strategies	Strategies to apply in order. If None, uses default combination. TYPE: list[CompactionStrategy] | None DEFAULT: None

Source code in src/mamba_agents/context/compaction/hybrid.py

def __init__(
    self,
    strategies: list[CompactionStrategy] | None = None,
) -> None:
    """Initialize the hybrid strategy.

    Args:
        strategies: Strategies to apply in order.
                   If None, uses default combination.
    """
    if strategies is None:
        self._strategies = [
            SelectivePruningStrategy(),
            SlidingWindowStrategy(),
        ]
    else:
        self._strategies = strategies

compact async

compact(
    messages: list[dict[str, Any]],
    target_tokens: int,
    preserve_recent: int = 0,
) -> CompactionResult

Compact using multiple strategies.

PARAMETER	DESCRIPTION
messages	Messages to compact. TYPE: list[dict[str, Any]]
target_tokens	Target token count. TYPE: int
preserve_recent	Number of recent messages to preserve. TYPE: int DEFAULT: 0

RETURNS	DESCRIPTION
CompactionResult	CompactionResult with compacted messages.

Source code in src/mamba_agents/context/compaction/hybrid.py

async def compact(
    self,
    messages: list[dict[str, Any]],
    target_tokens: int,
    preserve_recent: int = 0,
) -> CompactionResult:
    """Compact using multiple strategies.

    Args:
        messages: Messages to compact.
        target_tokens: Target token count.
        preserve_recent: Number of recent messages to preserve.

    Returns:
        CompactionResult with compacted messages.
    """
    tokens_before = self._count_tokens(messages)

    if tokens_before <= target_tokens:
        return self._no_compaction_result(messages, tokens_before)

    current_messages = messages
    total_removed = 0
    strategies_used: list[str] = []

    for strategy in self._strategies:
        if self._count_tokens(current_messages) <= target_tokens:
            break

        result = await strategy.compact(
            current_messages,
            target_tokens,
            preserve_recent,
        )

        current_messages = result.messages
        total_removed += result.removed_count
        strategies_used.append(strategy.name)

    tokens_after = self._count_tokens(current_messages)

    return CompactionResult(
        messages=current_messages,
        removed_count=total_removed,
        tokens_before=tokens_before,
        tokens_after=tokens_after,
        strategy=f"{self.name}({'+'.join(strategies_used)})",
    )