mnesis.models¶
Mnesis data models.
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 compactionmax_compaction_rounds— cap on condensation rounds and on summarisation passes per compaction runcondensation_enabled— whether to merge accumulated summary nodes
class-attribute
instance-attribute
¶
Whether to automatically trigger compaction when overflow is detected.
class-attribute
instance-attribute
¶
Whether to run tool output pruning before compaction.
class-attribute
instance-attribute
¶
Whether to attempt Level 2 (aggressive) compaction before falling back to Level 3.
Bases: BaseModel
Configuration for large file handling.
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},
)
Bases: BaseModel
Resolved model metadata used for budget calculations.
classmethod
¶
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.
Bases: BaseModel
Configuration for LLMMap and AgenticMap operators.
Bases: BaseModel
Configuration for session-level behaviour.
Bases: BaseModel
Configuration for the SQLite persistence layer.
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.
instance-attribute
¶
1 = selective LLM, 2 = aggressive LLM, 3 = deterministic fallback.
instance-attribute
¶
Raw messages summarised by the run, cumulative across its summarisation passes.
instance-attribute
¶
Tokens of the summary content the run produced: the sum over its leaf summaries, or the resulting condensed node's tokens when condensation then merged them.
instance-attribute
¶
Size of the active context window before the run, on the same basis as tokens_after.
instance-attribute
¶
Size of the active context window after the run, including older live summaries. For sessions this is the measure the soft/hard thresholds use (system prompt included).
class-attribute
instance-attribute
¶
Number of tool output parts tombstoned by the ToolOutputPruner during this run.
class-attribute
instance-attribute
¶
Tokens reclaimed by pruning tool outputs during this run.
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.
instance-attribute
¶
SHA-256 hex digest of the file content. Used as cache key.
instance-attribute
¶
Detected MIME type or language identifier (e.g. 'python', 'application/json').
instance-attribute
¶
Deterministic structural description of the file (classes, functions, keys, etc.).
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.
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).
class-attribute
instance-attribute
¶
True if the same tool call (name and input) has now been recorded
doom_loop_threshold times consecutively.
Bases: BaseModel
A streamed text chunk emitted by MnesisSession.stream().
Yielded progressively as the LLM produces output. Consumers can
concatenate event.text across all TextDelta events to reconstruct
the full assistant response before the final :class:TurnComplete.
Attributes:
| Name | Type | Description |
|---|---|---|
type |
Literal['text_delta']
|
Discriminator literal — always |
text |
str
|
The text fragment for this chunk. |
Bases: BaseModel
A plain text segment of a message.
Bases: BaseModel
Token counts for a single LLM response or cumulative session usage.
Return total, computing from parts when the explicit total is zero.
Bases: BaseModel
The final event emitted by MnesisSession.stream().
Always the last event in the stream. Carries the full
:class:TurnResult so callers can inspect token usage, compaction
status, and finish reason after the turn completes.
Attributes:
| Name | Type | Description |
|---|---|---|
type |
Literal['turn_complete']
|
Discriminator literal — always |
result |
TurnResult
|
The complete :class: |
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.
instance-attribute
¶
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;textcontains the error description, not a model response. Do not pass this text to the model as if it were a real reply.
instance-attribute
¶
Estimated USD cost of this turn. Always 0.0 — not yet implemented.
class-attribute
instance-attribute
¶
True if the context window after this turn crossed the soft threshold and a
background compaction was scheduled. The turn does not wait for it. False
when a compaction was already in flight (no second one is scheduled).
class-attribute
instance-attribute
¶
Result of a compaction that ran before this turn's LLM call.
Populated only when the context was over the hard threshold, so send()
had to wait for compaction to finish. It is None otherwise: background
(soft-threshold) compactions never block a turn, so their results arrive
later via the COMPACTION_COMPLETED event instead.
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 |
total |
int
|
Grand total — equals |
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 |
role |
Literal['user', 'assistant']
|
The role of the turn that was just completed. Always
|
context_tokens |
ContextBreakdown
|
Token breakdown of the context window after this turn. |
compaction_triggered |
bool
|
|
compact_result |
CompactionResult | None
|
The :class: |
Bases: BaseModel
A contiguous span of messages not yet covered by any SummaryNode.