mnesis.models.config

config

Configuration models for Mnesis sessions and components.

CompactionConfig

Bases: BaseModel

Configuration for the compaction engine.

Everyday knobs::

CompactionConfig(
    auto=True,
    compaction_output_budget=20_000,
    compaction_model="anthropic/claude-haiku-4-5-20251001",
)

Advanced tuning

The following fields control internal compaction behaviour and should only be changed with a thorough understanding of the compaction loop:

• soft_threshold_fraction — when to start early background compaction
• max_compaction_rounds — cap on condensation rounds and on summarisation passes per compaction run
• condensation_enabled — whether to merge accumulated summary nodes

auto class-attribute instance-attribute

auto: bool = True

Whether to automatically trigger compaction when overflow is detected.

prune class-attribute instance-attribute

prune: bool = True

Whether to run tool output pruning before compaction.

level2_enabled class-attribute instance-attribute

level2_enabled: bool = True

Whether to attempt Level 2 (aggressive) compaction before falling back to Level 3.

FileConfig

Bases: BaseModel

Configuration for large file handling.

StoreConfig

Bases: BaseModel

Configuration for the SQLite persistence layer.

wal_mode class-attribute instance-attribute

wal_mode: bool = True

Use WAL journal mode for better concurrent read performance.

connection_timeout class-attribute instance-attribute

connection_timeout: float = 30.0

Seconds to wait for the database connection before raising.

OperatorConfig

Bases: BaseModel

Configuration for LLMMap and AgenticMap operators.

RetryConfig

Bases: BaseModel

Configuration for automatic retry of transient LLM errors in send() and in compaction (summarisation and condensation) calls.

Retry is opt-in: the default max_retries=0 means send() fails immediately on any LLM error, preserving the pre-0.3.0 behaviour.

Differences from OperatorConfig.max_retries

OperatorConfig.max_retries handles per-item validation errors inside LLMMap and AgenticMap operators — a different failure domain. This RetryConfig handles transient LLM transport errors (rate limits, server errors, timeouts, connection failures) in the send() call path.

AgenticMap sub-sessions

Each AgenticMap sub-session has its own independent RetryConfig. The effective maximum LLM calls per sub-agent is (max_retries + 1) * max_turns. Plan capacity accordingly.

litellm num_retries interaction

send() always passes num_retries=0 to litellm.acompletion(). For compaction calls:

• max_retries > 0: Mnesis retries compaction calls and disables LiteLLM retries (num_retries=0) to avoid double-retrying. All retry logic is owned by Mnesis: backoff and jitter (send() also publishes LLM_RETRY events and its backoff is cancellable via close()).
• max_retries == 0 (default): compaction uses LiteLLM/provider default retries.

A hard-limit send() waits for compaction, so with retries enabled it can wait through compaction retries, and so can session.close(), which waits for an in-flight compaction including its backoffs. Keep max_retries and max_delay small to bound the wait, or call session.close(abort_compaction=True) to end an in-flight compaction's backoff immediately. If a compaction call outlasts its retries (an outage), that run skips its remaining LLM levels.

SessionConfig

Bases: BaseModel

Configuration for session-level behaviour.

MnesisConfig

Bases: BaseModel

Top-level configuration for an Mnesis session.

All sub-configs have sensible defaults and can be overridden individually.

Example::

config = MnesisConfig(
    compaction=CompactionConfig(
        compaction_output_budget=30_000,
        compaction_model="anthropic/claude-haiku-4-5-20251001",
    ),
    file=FileConfig(inline_threshold=5_000),
)

To override model context/output limits without constructing ModelInfo directly, use model_overrides::

config = MnesisConfig(
    model_overrides={"context_limit": 128_000, "max_output_tokens": 16_384},
)

ModelInfo

Bases: BaseModel

Resolved model metadata used for budget calculations.

from_model_string classmethod

from_model_string(model: str) -> ModelInfo

Create a ModelInfo by heuristically parsing a model string.

Supports litellm-style strings like anthropic/claude-opus-4-6, gpt-4o, openai/gpt-4-turbo, etc.

check_compaction_budget

check_compaction_budget(
    compaction: CompactionConfig, model: ModelInfo
) -> None

Validate compaction_output_budget against model's window.

Usable tokens are context_limit - max_output_tokens - compaction_output_budget.

Parameters:

Name	Type	Description	Default
compaction	CompactionConfig	Compaction settings holding the budget.	required
model	ModelInfo	Resolved model info (including model_overrides).	required

Raises:

Type	Description
ValueError	If usable tokens would be zero or negative: no context fits and level-3 compaction cannot produce a valid summary.

A warning is logged when the budget is at least as large as the usable window itself (the reserved headroom exceeds what can be filled).