agents.memory_v2.memory_state_with_tokens

Memory state with integrated token tracking and summarization hooks.

This module extends MessagesStateWithTokenUsage to add memory-specific functionality with pre-hooks for summarization and token management.

Classes

MemoryStateWithTokens

MessagesState with memory and token-aware summarization hooks.

Module Contents

class agents.memory_v2.memory_state_with_tokens.MemoryStateWithTokens(/, **data)

Bases: haive.core.schema.prebuilt.messages.messages_with_token_usage.MessagesStateWithTokenUsage

MessagesState with memory and token-aware summarization hooks.

This state combines: - MessagesStateWithTokenUsage (automatic token tracking) - Memory management (current memories, retrieved memories) - Pre-hook system for summarization triggers - Token threshold monitoring with branching logic

Features: - Automatic token tracking from parent class - Memory storage and retrieval tracking - Pre-execution hooks that check token thresholds - Summarization triggers when thresholds are exceeded - Running summary maintenance - Branch decision logic for token management

Example

>>> state = MemoryStateWithTokens()
>>> state.add_message(user_message)
>>>
>>> # Pre-hook automatically checks tokens
>>> if state.should_trigger_summarization():
>>>     state.prepare_for_summarization()
>>>
>>> # Branch logic for routing
>>> route = state.get_memory_route()  # "process", "summarize", "rewrite"

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

add_message_with_hooks(message)

Add message with pre-hook processing.

This method: 1. Runs pre-message hook 2. Adds the message normally 3. Updates token tracking 4. Returns hook results for routing decisions

Parameters:

message (langchain_core.messages.AnyMessage) – Message to add

Returns:

Hook results for routing decisions

Return type:

dict[str, Any]

apply_summarization_result(summary, summarized_message_ids, summarized_memory_ids)

Apply results of summarization operation.

Parameters:

• summary (str) – Generated summary text

• summarized_message_ids (list[str]) – IDs of messages that were summarized

• summarized_memory_ids (list[str]) – IDs of memories that were summarized

Return type:

None

get_comprehensive_status()

Get comprehensive state status for debugging/monitoring.

Return type:

dict[str, Any]

get_memory_route()

Determine routing decision based on current state.

Returns:

Route name for graph branching logic

Return type:

str

pre_message_hook(message)

Pre-hook executed before adding any message.

This hook: 1. Checks current token usage 2. Determines if summarization is needed 3. Prepares summarization data if required 4. Returns decision for routing

Parameters:

message (langchain_core.messages.AnyMessage) – Message about to be added

Returns:

Dict with hook results and routing decisions

Return type:

dict[str, Any]

prepare_for_summarization()

Prepare state for summarization operation.

This method: 1. Identifies messages/memories to summarize 2. Preserves recent important content 3. Calculates target compression ratios 4. Prepares summarization context

Returns:

Dict with summarization preparation data

Return type:

dict[str, Any]

reset_for_new_session()

Reset state for new conversation session.

Return type:

None

should_trigger_summarization()

Check if summarization should be triggered.

Return type:

bool

property estimated_total_tokens: int

Estimate total tokens for messages + memories.

Return type:

int

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property token_status: str

Get current token status.

Return type:

str

property token_usage_ratio: float

Calculate current token usage as ratio of max.

Return type:

float

property total_memory_tokens: int

Calculate total tokens used by memories.

Return type:

int