mnesis.compaction.levels

levels

Three-level compaction escalation functions.

This module provides:

• Summarisation — converts raw messages into a leaf summary node. Three escalation levels: level 1 (structured LLM), level 2 (aggressive LLM), level 3 (deterministic truncation — always succeeds).

• Condensation — merges one or more existing summary nodes into a single condensed node. Three escalation levels mirror summarisation.

Both operations extract file_xxx identifiers from their inputs and append a [LCM File IDs: ...] footer to the output, preserving the "lossless" guarantee across compaction rounds.

Summarisation input cap: messages passed to the LLM summarizer are capped at MAX_SUMMARISATION_INPUT_FRACTION (75 %) of the compaction model's context window to prevent the compaction call itself from overflowing.

SummaryCandidate dataclass

SummaryCandidate(
    text: str,
    token_count: int,
    span_start_message_id: str,
    span_end_message_id: str,
    compaction_level: int,
    messages_covered: int,
)

A candidate compaction summary before it is committed to the store.

CondensationCandidate dataclass

CondensationCandidate(
    text: str,
    token_count: int,
    parent_node_ids: list[str] = list(),
    compaction_level: int = 1,
)

A candidate condensation of one or more existing summary nodes.

compaction_level class-attribute instance-attribute

compaction_level: int = 1

Condensation escalation level: 1 = normal, 2 = aggressive, 3 = deterministic.

level1_summarise async

level1_summarise(
    messages: list[MessageWithParts],
    model: str,
    budget: ContextBudget,
    estimator: TokenEstimator,
    llm_call: Any,
    compaction_prompt: str | None = None,
    model_context_limit: int = 200000,
) -> SummaryCandidate | None

Attempt Level 1 (selective) summarisation via LLM.

File IDs found in the input messages are automatically appended to the summary via a [LCM File IDs: ...] footer.

Input messages are capped at 75 % of the compaction model's context window to prevent the summarisation call itself from overflowing.

Parameters:

Name	Type	Description	Default
messages	list[MessageWithParts]	All non-summary messages in the session.	required
model	str	Model string to use for compaction.	required
budget	ContextBudget	Token budget for validation.	required
estimator	TokenEstimator	Token estimator for result validation.	required
llm_call	Any	Async callable (model, messages, max_tokens) -> str.	required
compaction_prompt	str | None	Custom system prompt override.	None
model_context_limit	int	Context window of the compaction model.	200000

Returns:

Type	Description
SummaryCandidate | None	SummaryCandidate if successful and fits budget, or None to escalate.

level2_summarise async

level2_summarise(
    messages: list[MessageWithParts],
    model: str,
    budget: ContextBudget,
    estimator: TokenEstimator,
    llm_call: Any,
    compaction_prompt: str | None = None,
    model_context_limit: int = 200000,
) -> SummaryCandidate | None

Attempt Level 2 (aggressive) summarisation via LLM.

Uses a more compressed prompt format and drops reasoning details. File IDs found in the input messages are propagated to the summary. Input is capped at 75 % of the compaction model's context window.

Parameters:

Name	Type	Description	Default
messages	list[MessageWithParts]	All non-summary messages in the session.	required
model	str	Model string to use for compaction.	required
budget	ContextBudget	Token budget for validation.	required
estimator	TokenEstimator	Token estimator for result validation.	required
llm_call	Any	Async callable.	required
compaction_prompt	str | None	Custom system prompt override.	None
model_context_limit	int	Context window of the compaction model.	200000

Returns:

Type	Description
SummaryCandidate | None	SummaryCandidate if successful and fits budget, or None to escalate.

level3_deterministic

level3_deterministic(
    messages: list[MessageWithParts],
    budget: ContextBudget,
    estimator: TokenEstimator,
) -> SummaryCandidate

Level 3 deterministic fallback (no LLM required).

Keeps the most recent messages that fit within 85% of the usable budget, prefixed with a truncation notice. This always produces a valid result.

File IDs found in all input messages (not just kept ones) are preserved in a [LCM File IDs: ...] footer even when their surrounding context is truncated — this is the lossless guarantee.

Parameters:

Name	Type	Description	Default
messages	list[MessageWithParts]	All non-summary messages in the session.	required
budget	ContextBudget	Token budget — result is guaranteed to fit within usable.	required
estimator	TokenEstimator	Token estimator.	required

Returns:

Type	Description
SummaryCandidate	SummaryCandidate that always fits within budget.usable.

condense_level1 async

condense_level1(
    nodes: list[SummaryNode],
    model: str,
    budget: ContextBudget,
    estimator: TokenEstimator,
    llm_call: Any,
) -> CondensationCandidate | None

Attempt Level 1 condensation: merge summary nodes via structured LLM prompt.

File IDs from all parent nodes are collected and appended to the condensed output via a [LCM File IDs: ...] footer.

Parameters:

Name	Type	Description	Default
nodes	list[SummaryNode]	Summary nodes to condense (must be non-empty).	required
model	str	LLM model string.	required
budget	ContextBudget	Token budget for the condensed result.	required
estimator	TokenEstimator	Token estimator.	required
llm_call	Any	Async callable (model, messages, max_tokens) -> str.	required

Returns:

Type	Description
CondensationCandidate | None	CondensationCandidate if successful and fits budget, or None to escalate.

condense_level2 async

condense_level2(
    nodes: list[SummaryNode],
    model: str,
    budget: ContextBudget,
    estimator: TokenEstimator,
    llm_call: Any,
) -> CondensationCandidate | None

Attempt Level 2 condensation: aggressive merge via compressed prompt.

Parameters:

Name	Type	Description	Default
nodes	list[SummaryNode]	Summary nodes to condense.	required
model	str	LLM model string.	required
budget	ContextBudget	Token budget.	required
estimator	TokenEstimator	Token estimator.	required
llm_call	Any	Async callable.	required

Returns:

Type	Description
CondensationCandidate | None	CondensationCandidate if successful and fits budget, or None to escalate.

condense_level3_deterministic

condense_level3_deterministic(
    nodes: list[SummaryNode], estimator: TokenEstimator
) -> CondensationCandidate

Level 3 deterministic condensation fallback (no LLM required).

Truncates the concatenated summary content to :data:_CONDENSE_LEVEL3_MAX_TOKENS tokens while always preserving all file IDs from every parent node.

Parameters:

Name	Type	Description	Default
nodes	list[SummaryNode]	Summary nodes to condense.	required
estimator	TokenEstimator	Token estimator.	required

Returns:

Type	Description
CondensationCandidate	CondensationCandidate that always succeeds.