`mnesis.models`¶

models ¶

Mnesis data models.

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 summarise+condense cycles
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.

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.

OperatorConfig ¶

Bases: BaseModel

Configuration for LLMMap and AgenticMap operators.

SessionConfig ¶

Bases: BaseModel

Configuration for session-level behaviour.

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.

CompactionResult ¶

Bases: BaseModel

The result of a compaction run.

Records which escalation level succeeded, how many messages were compressed, the token savings achieved, and how many tool outputs were pruned.

level_used `instance-attribute` ¶

level_used: int

1 = selective LLM, 2 = aggressive LLM, 3 = deterministic fallback.

pruned_tool_outputs `class-attribute` `instance-attribute` ¶

pruned_tool_outputs: int = 0

Number of tool output parts tombstoned by the ToolOutputPruner during this run.

pruned_tokens `class-attribute` `instance-attribute` ¶

pruned_tokens: int = 0

Tokens reclaimed by pruning tool outputs during this run.

FileRefPart ¶

Bases: BaseModel

A content-addressed reference to a large file stored outside the context window.

When the LargeFileHandler intercepts a file that exceeds the inline threshold, it stores it externally and replaces the content with this reference object. The ContextBuilder renders this as a structured [FILE: ...] block.

content_id `instance-attribute` ¶

content_id: str

SHA-256 hex digest of the file content. Used as cache key.

path `instance-attribute` ¶

path: str

Original file path as provided by the caller.

file_type `instance-attribute` ¶

file_type: str

Detected MIME type or language identifier (e.g. 'python', 'application/json').

token_count `instance-attribute` ¶

token_count: int

Estimated token count of the full file content.

exploration_summary `instance-attribute` ¶

exploration_summary: str

Deterministic structural description of the file (classes, functions, keys, etc.).

FinishReason ¶

Bases: StrEnum

Why the LLM stopped generating.

String enum so result.finish_reason == "stop" comparisons work without importing the enum.

Important — FinishReason.ERROR: when finish_reason is FinishReason.ERROR (or "error"), the LLM call failed. TurnResult.text contains an error description, not a model response. Always check finish_reason before processing text.

MessageWithParts ¶

Bases: BaseModel

A message together with its ordered list of typed parts.

model_id `property` ¶

model_id: str

The model that produced this message (empty string for user messages).

tokens `property` ¶

tokens: TokenUsage | None

Token usage for this message (None for user messages or before streaming completes).

text_content ¶

text_content() -> str

Concatenate text from all TextPart objects in this message.

RecordResult ¶

Bases: BaseModel

The result of a MnesisSession.record() call.

Records the IDs of the persisted user and assistant messages so callers can reference them later (e.g. for event subscriptions or debugging).

TextPart ¶

Bases: BaseModel

A plain text segment of a message.

TokenUsage ¶

Bases: BaseModel

Token counts for a single LLM response or cumulative session usage.

effective_total ¶

effective_total() -> int

Return total, computing from parts when the explicit total is zero.

ToolPart ¶

Bases: BaseModel

A tool call and its result within an assistant message.

compacted_at `property` ¶

compacted_at: int | None

Convenience accessor for the pruning tombstone timestamp.

is_protected `property` ¶

is_protected: bool

Protected tools are never pruned by ToolOutputPruner.

TurnResult ¶

Bases: BaseModel

The result of a single MnesisSession.send() call.

Contains the assistant's text response, token usage, finish reason, and indicators for compaction and doom loop detection.

Important — finish_reason == "error": When finish_reason is "error", the LLM call failed and text contains an error description, not an LLM response. Do not treat the text as a model reply in this case. Always check finish_reason before processing text.

finish_reason `instance-attribute` ¶

finish_reason: FinishReason | str

Why the LLM stopped generating.

Type is FinishReason | str: known values are the FinishReason enum members; providers may return additional string values.

FinishReason.STOP / "stop" — natural end of response.
FinishReason.MAX_TOKENS / "max_tokens" — output token limit reached.
FinishReason.LENGTH / "length" — alias used by some providers.
FinishReason.TOOL_CALLS / "tool_calls" — model requested tool execution.
FinishReason.ERROR / "error" — the LLM call failed; text contains the error description, not a model response. Do not pass this text to the model as if it were a real reply.

cost `instance-attribute` ¶

cost: float

Estimated USD cost of this turn. Always 0.0 — not yet implemented.

ContextBreakdown ¶

Bases: BaseModel

Token counts by component for a single context window state.

All counts are estimates produced by :class:~mnesis.tokens.estimator.TokenEstimator. They reflect the context window as assembled immediately after a turn is persisted — that is, the exact token budget breakdown that would be used on the next LLM call if one were made immediately after this turn.

Attributes:

Name	Type	Description
`system_prompt`	`int`	Tokens consumed by the system prompt.
`summary`	`int`	Tokens consumed by compaction summaries injected into context.
`messages`	`int`	Tokens consumed by raw (non-summary) message history.
`tool_outputs`	`int`	Subset of `messages` attributable to tool call parts. This is always `<= messages`.
`total`	`int`	Grand total — equals `system_prompt + summary + messages`.

TurnSnapshot ¶

Bases: BaseModel

Per-turn record of context window state and compaction activity.

One TurnSnapshot is appended to the internal list after every :meth:~mnesis.session.MnesisSession.send and every :meth:~mnesis.session.MnesisSession.record call. Retrieve the full list with :meth:~mnesis.session.MnesisSession.history.

Typical use-cases:

Debugging — inspect exact context composition at each turn.
Research — plot sawtooth token-usage curves, measure compaction level distribution, or analyse information-retention across compaction boundaries.

Attributes:

Name	Type	Description
`turn_index`	`int`	0-based counter incremented on every `send()` / `record()` call.
`role`	`Literal['user', 'assistant']`	The role of the turn that was just completed. Always `"assistant"` because a snapshot is captured after the full user + assistant exchange is persisted.
`context_tokens`	`ContextBreakdown`	Token breakdown of the context window after this turn.
`compaction_triggered`	`bool`	`True` if compaction was scheduled (background or foreground) during or immediately after this turn.
`compact_result`	`CompactionResult \| None`	The :class:`~mnesis.models.message.CompactionResult` from the most recent explicit :meth:`~mnesis.session.MnesisSession.compact` call that completed before this snapshot was captured. Background compactions triggered automatically by :meth:`~mnesis.session.MnesisSession.send` or :meth:`~mnesis.session.MnesisSession.record` are not reflected here. `None` when no explicit `compact()` call has been made yet or when one was still in flight when the snapshot was captured.

MessageSpan ¶

Bases: BaseModel

A contiguous span of messages not yet covered by any SummaryNode.

mnesis.models¶

models ¶

CompactionConfig ¶

Advanced tuning¶

auto class-attribute instance-attribute ¶

prune class-attribute instance-attribute ¶

level2_enabled class-attribute instance-attribute ¶

FileConfig ¶

MnesisConfig ¶

ModelInfo ¶

from_model_string classmethod ¶

OperatorConfig ¶

SessionConfig ¶

StoreConfig ¶

wal_mode class-attribute instance-attribute ¶

connection_timeout class-attribute instance-attribute ¶

CompactionResult ¶

level_used instance-attribute ¶

pruned_tool_outputs class-attribute instance-attribute ¶

pruned_tokens class-attribute instance-attribute ¶

FileRefPart ¶

content_id instance-attribute ¶

path instance-attribute ¶

file_type instance-attribute ¶

token_count instance-attribute ¶

exploration_summary instance-attribute ¶

FinishReason ¶

MessageWithParts ¶

model_id property ¶

tokens property ¶

text_content ¶

RecordResult ¶

TextPart ¶

TokenUsage ¶

effective_total ¶

ToolPart ¶

compacted_at property ¶

is_protected property ¶

TurnResult ¶

finish_reason instance-attribute ¶

cost instance-attribute ¶

ContextBreakdown ¶

TurnSnapshot ¶

MessageSpan ¶

`mnesis.models`¶

auto `class-attribute` `instance-attribute` ¶

prune `class-attribute` `instance-attribute` ¶

level2_enabled `class-attribute` `instance-attribute` ¶

from_model_string `classmethod` ¶

wal_mode `class-attribute` `instance-attribute` ¶

connection_timeout `class-attribute` `instance-attribute` ¶

level_used `instance-attribute` ¶

pruned_tool_outputs `class-attribute` `instance-attribute` ¶

pruned_tokens `class-attribute` `instance-attribute` ¶

content_id `instance-attribute` ¶

path `instance-attribute` ¶

file_type `instance-attribute` ¶

token_count `instance-attribute` ¶

exploration_summary `instance-attribute` ¶

model_id `property` ¶

tokens `property` ¶

compacted_at `property` ¶

is_protected `property` ¶

finish_reason `instance-attribute` ¶

cost `instance-attribute` ¶