Key Design Principle
Session memory type is selected at RUNTIME, not at init time. The same Memory instance can be shared across Agent, Team, and Workflow. When methods are called (save, get), the caller passessession_type and Memory routes to the correct session memory implementation.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
storage | Storage | Required | Storage backend to use for persistence |
session_id | Optional[str] | None | Session ID for session-based memory features (auto-generated if None) |
user_id | Optional[str] | None | User ID for user-specific memory features (auto-generated if None) |
full_session_memory | bool | False | Enable full session memory storage (chat history persistence) |
summary_memory | bool | False | Enable session summary generation and storage |
user_analysis_memory | bool | False | Enable user trait analysis and profile building |
user_profile_schema | Optional[Type[BaseModel]] | None | Custom Pydantic schema for user profile data structure |
dynamic_user_profile | bool | False | Enable dynamic user profile schema generation |
num_last_messages | Optional[int] | None | Limit conversation history to last N messages |
model | Optional[Union[Model, str]] | None | Model provider for memory analysis tasks (summary generation, user profile extraction). Required if summary_memory or user_analysis_memory is enabled |
debug | bool | False | Enable debug logging |
debug_level | int | 1 | Debug verbosity level (1-3). Only used when debug=True |
feed_tool_call_results | bool | False | Include tool call results in memory analysis |
user_memory_mode | Literal['update', 'replace'] | 'update' | Mode for updating user memory (‘update’ to merge with existing profile, ‘replace’ to overwrite) |
Properties
user_memory
Returns the user memory instance if user_analysis_memory is enabled, otherwise None.
Type: Optional[BaseUserMemory]
Methods
get_session_memory
Get or create session memory for the given session type. This is the runtime selection method - called when Agent/Team/Workflow invokes save or get operations.
IMPORTANT: Session memory is ALWAYS created if storage is available. This is required for HITL (Human-in-the-Loop) checkpointing to work. Even when full_session_memory and summary_memory are disabled, incomplete runs (paused, error, cancelled) MUST be saved to storage to enable cross-process resumption.
Parameters:
session_type(SessionType): The type of session (AGENT, TEAM, WORKFLOW)
Optional[BaseSessionMemory]: The appropriate session memory instance, or None if no storage available
prepare_inputs_for_task
Gather all relevant memory data before task execution. This method prepares:
- Message history (from session memory)
- Context injection (session summary)
- System prompt injection (user profile)
- Metadata injection (session + agent metadata)
session_type(Optional[SessionType]): The session type (defaults to AGENT)agent_metadata(Optional[Dict[str, Any]]): Optional metadata from the caller to inject
Dict[str, Any]: Dictionary containing:message_history: List of message historycontext_injection: Context string for session summarysystem_prompt_injection: System prompt injection for user profilemetadata_injection: Metadata string with session and agent information
save_session_async
Save session to storage. This is the centralized method for ALL session saving operations.
For INCOMPLETE runs (paused, error, cancelled):
- Saves checkpoint state for HITL resumption
- Does NOT process memory features (summary, user profile)
- Saves the completed run output
- Processes memory features if enabled:
- Generates session summary (if
summary_memoryenabled) - Analyzes user profile (if
user_analysis_memoryenabled)
- Generates session summary (if
output(AgentRunOutput): The run output (AgentRunOutput, TeamRunOutput, etc.)session_type(Optional[SessionType]): The session type (defaults to AGENT)agent_id(Optional[str]): Optional agent identifier
get_session_async / get_session
Get the current session from storage.
Returns:
Optional[Session]: The current session, or None if not found
get_messages_async / get_messages
Get messages from the current session.
Returns:
list: List of messages from the current session, or empty list if no session
set_metadata_async / set_metadata
Set metadata on the current session.
Parameters:
metadata(Dict[str, Any]): Dictionary of metadata to set/update
get_metadata_async / get_metadata
Get metadata from the current session.
Returns:
Optional[Dict[str, Any]]: Session metadata, or None if no session
list_sessions_async / list_sessions
List sessions, optionally filtered by user_id.
Parameters:
user_id(Optional[str]): Optional user ID to filter by (defaults to instance user_id)
list: List of sessions
find_session_async / find_session
Find a specific session by session_id.
Parameters:
session_id(Optional[str]): Session ID to find (defaults to instance session_id)
Optional[Session]: The session if found, None otherwise
delete_session_async / delete_session
Delete the current or specified session.
Parameters:
session_id(Optional[str]): Session ID to delete (defaults to instance session_id)
bool: True if deleted successfully, False otherwise
load_resumable_run_async / load_resumable_run
Load a resumable run from storage by run_id. Resumable runs include:
paused: External tool execution pauseerror: Durable execution (error recovery)cancelled: Cancel run resumption
run_id(str): The run ID to search forsession_type(Optional[SessionType]): The session type (defaults to AGENT)agent_id(Optional[str]): Optional agent_id to search across sessions
Optional[RunData]: RunData if found and resumable, None otherwise
load_run_async / load_run
Load a run from storage by run_id (regardless of status). Unlike load_resumable_run_async, this returns any run regardless of status. Used for checking if a run is completed before attempting to continue.
Parameters:
run_id(str): The run ID to search forsession_type(Optional[SessionType]): The session type (defaults to AGENT)agent_id(Optional[str]): Optional agent_id to search across sessions
Optional[RunData]: RunData if found, None otherwise