mnesis.models.snapshot

snapshot

Per-turn context snapshot models for session.history().

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.