> ## Documentation Index > Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt > Use this file to discover all available pages before exploring further. # Memory The Memory class orchestrates session and user memory operations with runtime session type selection. It serves as the central coordinator for memory operations in the Upsonic agent framework. ## 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 passes `session_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) **Returns:** * `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) **Parameters:** * `session_type` (`Optional[SessionType]`): The session type (defaults to AGENT) * `agent_metadata` (`Optional[Dict[str, Any]]`): Optional metadata from the caller to inject **Returns:** * `Dict[str, Any]`: Dictionary containing: * `message_history`: List of message history * `context_injection`: Context string for session summary * `system_prompt_injection`: System prompt injection for user profile * `metadata_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) **For COMPLETED runs**: * Saves the completed run output * Processes memory features if enabled: * Generates session summary (if `summary_memory` enabled) * Analyzes user profile (if `user_analysis_memory` enabled) **Parameters:** * `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) **Returns:** * `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) **Returns:** * `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) **Returns:** * `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 pause * `error`: Durable execution (error recovery) * `cancelled`: Cancel run resumption **Parameters:** * `run_id` (`str`): The run ID to search for * `session_type` (`Optional[SessionType]`): The session type (defaults to AGENT) * `agent_id` (`Optional[str]`): Optional agent\_id to search across sessions **Returns:** * `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 for * `session_type` (`Optional[SessionType]`): The session type (defaults to AGENT) * `agent_id` (`Optional[str]`): Optional agent\_id to search across sessions **Returns:** * `Optional[RunData]`: RunData if found, None otherwise