Skip to main content

​
Overview

​
What is Memory?

Memory gives your agents the ability to remember. Without memory, every conversation starts fresh - your agent doesn’t remember what you talked about before or who you are. With memory, your agents can:
  • Remember conversations - Reference previous messages and maintain context
  • Learn about users - Understand preferences, expertise level, and communication style
  • Improve over time - Build a complete picture of each user across all interactions
  • Reduce repetition - Never ask for the same information twice

​
How Memory Works

Memory works in two phases - before and after each conversation: Before Each Conversation:
  1. Loads the user’s profile (if you’re using user analysis memory)
  2. Retrieves the conversation summary (if you’re using summary memory)
  3. Pulls up previous messages (if you’re using conversation memory)
  4. Gives all this context to your agent automatically
After Each Conversation:
  1. Saves the new messages to history
  2. Updates the conversation summary
  3. Analyzes what the agent learned about the user
  4. Stores everything for next time
You don’t have to do anything - memory handles it all automatically.

​
Attributes

The Memory class provides the following key attributes: 
from upsonic.storage import Memory, InMemoryStorage

memory = Memory(
    storage=storage,                    # Required: Storage backend
    session_id="session_123",          # Optional: For conversation/summary memory
    user_id="user_456",                # Optional: For user analysis memory
    full_session_memory=True,         # Enable complete chat history
    summary_memory=True,               # Enable conversation summaries
    user_analysis_memory=True,        # Enable user learning
    num_last_messages=10,             # Limit history to last N turns
    model="openai/gpt-4o",            # Model for analysis/summaries
    user_profile_schema=UserProfile,  # Custom user profile schema
    dynamic_user_profile=True,        # Let agent create custom fields
    user_memory_mode='update',        # 'update' or 'replace' mode
    feed_tool_call_results=False,     # Include tool calls in memory
    debug=True                        # Enable debug logging
)

​
Choosing Right Memory Types

​
What is The Selection Criteria?

Choose memory types based on your specific needs:
Memory TypeWhen to UseRequirements
Conversation MemoryCustomer support, tutoring, detailed conversationssession_id
Summary MemoryLong conversations, cost reductionsession_id, model
User Analysis MemoryPersonalization, user preferencesuser_id, model

​
Making Combination of Memory

You can use one type or combine all three for the most powerful memory system: 
# Basic conversation memory only
memory = Memory(
    storage=InMemoryStorage(),
    session_id="session_001",
    full_session_memory=True
)

# All three memory types
memory = Memory(
    storage=InMemoryStorage(),
    session_id="session_001",
    user_id="user_001",
    full_session_memory=True,
    summary_memory=True,
    user_analysis_memory=True,
    model="openai/gpt-4o"
)

​
Use Case for Conversation Memory

  • Customer Support: Maintain context across support tickets
  • Tutoring: Remember what topics have been covered
  • Long Conversations: Keep track of detailed discussions
  • Debugging Sessions: Remember error states and solutions

​
Use Case for Summary Memory

  • Long Sessions: Reduce token costs for very long conversations
  • Meeting Notes: Automatically summarize key points
  • Documentation: Create evolving summaries of complex topics
  • Cost Optimization: Maintain context without full history

​
Use Case for User Analysis Memory

  • Personalization: Adapt responses to user preferences
  • Learning Systems: Track user progress and expertise
  • Customer Profiles: Build comprehensive user understanding
  • Adaptive Interfaces: Customize experience based on user traits

​
Memory Types

​
Conversation Memory

​
What is Conversation Memory?

Conversation Memory stores the complete chat history for a session, allowing your agent to reference previous messages and maintain context throughout the conversation.

​
Usage

from upsonic.storage import Memory, InMemoryStorage

# Basic conversation memory
memory = Memory(
    storage=InMemoryStorage(),
    session_id="session_001",
    full_session_memory=True
)

# With message limiting
memory = Memory(
    storage=InMemoryStorage(),
    session_id="session_001",
    full_session_memory=True,
    num_last_messages=10  # Keep last 10 conversation turns
)

​
Params

  • full_session_memory: bool - Enable/disable conversation memory
  • session_id: str - Required identifier for the session
  • num_last_messages: int - Optional limit on conversation history
  • feed_tool_call_results: bool - Include/exclude tool calls from memory

​
Summary Memory

​
What is Summary Memory?

Summary Memory maintains an evolving, condensed summary of key conversation points, reducing costs while preserving important context.

​
Usage

from upsonic.storage import Memory, SqliteStorage

# Summary memory with model
memory = Memory(
    storage=SqliteStorage(sessions_table_name="sessions", profiles_table_name="profiles"),
    session_id="session_002",
    summary_memory=True,
    model="openai/gpt-4o-mini"  # Model for generating summaries
)

# Combined with conversation memory
memory = Memory(
    storage=SqliteStorage(sessions_table_name="sessions", profiles_table_name="profiles"),
    session_id="session_002",
    full_session_memory=True,
    summary_memory=True,
    model="openai/gpt-4o-mini"
)

​
Params

  • summary_memory: bool - Enable/disable summary generation
  • session_id: str - Required identifier for the session
  • model: str - Required model for generating summaries

​
User Analysis Memory

​
What is User Analysis Memory?

User Analysis Memory learns about users across all conversations, building comprehensive profiles that enable personalization and adaptive responses.

​
Usage

from upsonic.storage import Memory, InMemoryStorage
from pydantic import BaseModel, Field
from typing import Optional

# Default user analysis
memory = Memory(
    storage=InMemoryStorage(),
    session_id="session_003",
    user_id="user_001",
    user_analysis_memory=True,
    model="openai/gpt-4o"
)

# Custom user profile schema
class UserProfile(BaseModel):
    name: Optional[str] = Field(None, description="User's name")
    expertise: Optional[str] = Field(None, description="Technical expertise level")
    interests: Optional[list] = Field(None, description="Areas of interest")

memory = Memory(
    storage=InMemoryStorage(),
    session_id="session_003",
    user_id="user_001",
    user_analysis_memory=True,
    user_profile_schema=UserProfile,
    model="openai/gpt-4o"
)

# Dynamic user learning (agent creates custom fields)
memory = Memory(
    storage=InMemoryStorage(),
    session_id="session_003",
    user_id="user_001",
    user_analysis_memory=True,
    dynamic_user_profile=True,  # Agent creates custom profile fields
    model="openai/gpt-4o"
)

​
Params

  • user_analysis_memory: bool - Enable/disable user learning
  • user_id: str - Required identifier for the user
  • model: str - Required model for analyzing user traits
  • user_profile_schema: BaseModel - Optional custom profile schema
  • dynamic_user_profile: bool - Let agent create custom fields
  • user_memory_mode: str - ‘update’ (default) or ‘replace’ mode

​
Storage Options

​
InMemoryStorage

​
Usage

from upsonic.storage import InMemoryStorage

# Basic in-memory storage
storage = InMemoryStorage()

# With LRU cache limits
storage = InMemoryStorage(
    max_sessions=100,  # Keep max 100 sessions
    max_profiles=50    # Keep max 50 user profiles
)

​
Params

  • max_sessions: int - Optional limit on stored sessions (LRU cache)
  • max_profiles: int - Optional limit on stored profiles (LRU cache)

​
JSONStorage

​
Usage

from upsonic.storage import JSONStorage

# Basic JSON storage
storage = JSONStorage(directory_path="./memory_data")

# With custom formatting
storage = JSONStorage(
    directory_path="./memory_data",
    pretty_print=True  # Format JSON for readability
)

​
Params

  • directory_path: str - Path to directory for JSON files
  • pretty_print: bool - Format JSON for readability (default: True)

​
SqliteStorage

​
Usage

from upsonic.storage import SqliteStorage

# In-memory SQLite (temporary)
storage = SqliteStorage(
    sessions_table_name="sessions",
    profiles_table_name="profiles",
    db_file=None  # Use in-memory database
)

# Persistent SQLite
storage = SqliteStorage(
    sessions_table_name="sessions",
    profiles_table_name="user_profiles",
    db_file="./data/memory.db"
)

​
Params

  • sessions_table_name: str - Name of sessions table
  • profiles_table_name: str - Name of profiles table
  • db_file: str - Path to SQLite file (None for in-memory)

​
PostgresStorage

​
Usage

from upsonic.storage import PostgresStorage

# PostgreSQL with connection pooling
storage = PostgresStorage(
    sessions_table_name="agent_sessions",
    profiles_table_name="user_profiles",
    db_url="postgresql://user:pass@localhost:5432/agentdb",
    schema="public"
)

​
Params

  • sessions_table_name: str - Name of sessions table
  • profiles_table_name: str - Name of profiles table
  • db_url: str - PostgreSQL connection URL
  • schema: str - Database schema (default: “public”)

​
RedisStorage

​
Usage

from upsonic.storage import RedisStorage

# Redis storage for distributed systems
storage = RedisStorage(
    host="localhost",
    port=6379,
    db=0,
    password="your_password",
    prefix="upsonic:"
)

# Redis with custom configuration
storage = RedisStorage(
    host="redis.example.com",
    port=6379,
    db=1,
    ssl=True,
    prefix="prod:memory:"
)

​
Params

  • prefix: str - Key prefix for namespacing
  • host: str - Redis server hostname (default: “localhost”)
  • port: int - Redis server port (default: 6379)
  • db: int - Redis database number (default: 0)
  • password: str - Optional password for authentication
  • ssl: bool - Use SSL connection (default: False)
  • expire: int - Optional TTL in seconds for keys

​
Mem0Storage

​
Usage

from upsonic.storage import Mem0Storage

# Mem0 Platform integration
storage = Mem0Storage(
    api_key="your_mem0_api_key",
    org_id="your_org_id",
    project_id="your_project_id"
)

# Mem0 Open Source
storage = Mem0Storage(
    local_config={
        "vector_store": {
            "provider": "chroma",
            "config": {
                "path": "./chroma_db"
            }
        }
    }
)

​
Params

  • api_key: str - Mem0 Platform API key (for hosted service)
  • org_id: str - Organization ID for Mem0 Platform
  • project_id: str - Project ID for Mem0 Platform
  • local_config: dict - Configuration for Open Source Mem0
  • namespace: str - Application namespace (default: “upsonic”)
  • infer: bool - Enable LLM-based inference (default: False)
  • custom_categories: list - Additional custom categories
  • enable_caching: bool - Enable ID caching (default: True)
  • cache_ttl: int - Cache time-to-live in seconds (default: 300)

​
MongoStorage

​
Usage

from upsonic.storage import MongoStorage

# MongoDB storage for scalable systems
storage = MongoStorage(
    db_url="mongodb://localhost:27017",
    database_name="agent_memory",
    sessions_collection_name="interaction_sessions",
    profiles_collection_name="user_profiles"
)

# MongoDB with authentication
storage = MongoStorage(
    db_url="mongodb://user:password@localhost:27017/agentdb",
    database_name="production_memory",
    sessions_collection_name="sessions",
    profiles_collection_name="profiles"
)

​
Params

  • db_url: str - MongoDB connection string
  • database_name: str - Name of the database
  • sessions_collection_name: str - Name of sessions collection (default: “interaction_sessions”)
  • profiles_collection_name: str - Name of profiles collection (default: “user_profiles”)

​
Examples

​
Basic Memory Example

​
About Example Scenario

This example demonstrates a customer support agent that remembers conversations and learns about users across multiple sessions. The agent will maintain context within each support session and build a profile of each customer for personalized service.

​
Memory Configuration

from upsonic.storage import Memory, SqliteStorage

# Create persistent storage
storage = SqliteStorage(
    sessions_table_name="support_sessions",
    profiles_table_name="customers",
    db_file="./support_memory.db"
)

# Create memory for customer support
memory = Memory(
    storage=storage,
    session_id="support_session_001",
    user_id="customer_123",
    full_session_memory=True,      # Remember conversation history
    user_analysis_memory=True,     # Learn about the customer
    num_last_messages=10,          # Keep last 10 turns for context
    model="openai/gpt-4o"
)

​
Full Code

from upsonic import Agent, Task
from upsonic.storage import Memory, SqliteStorage

# Create persistent storage
storage = SqliteStorage(
    sessions_table_name="support_sessions",
    profiles_table_name="customers",
    db_file="./support_memory.db"
)

# Create memory for customer support
memory = Memory(
    storage=storage,
    session_id="support_session_001",
    user_id="customer_123",
    full_session_memory=True,      # Remember conversation history
    user_analysis_memory=True,     # Learn about the customer
    num_last_messages=10,          # Keep last 10 turns for context
    model="openai/gpt-4o"
)

# Support agent
agent = Agent(
    model="openai/gpt-4o",
    name="Support Agent",
    memory=memory
)

# Conversation 1
task1 = Task(description="I'm having trouble logging in to my account")
result1 = agent.do(task1)
print("Response 1:", result1)

# Conversation 2 - agent remembers context and user
task2 = Task(description="I tried resetting my password but didn't receive the email")
result2 = agent.do(task2)
print("Response 2:", result2)

# Next session - agent remembers customer history
memory_new_session = Memory(
    storage=storage,
    session_id="support_session_002",  # New session
    user_id="customer_123",            # Same customer
    full_session_memory=True,
    user_analysis_memory=True,         # Loads existing profile
    model="openai/gpt-4o"
)

agent_new = Agent(model="openai/gpt-4o", memory=memory_new_session)
task3 = Task(description="Hello, I'm back")
result3 = agent_new.do(task3)  # Agent knows customer's previous issues
print("Response 3:", result3)
This example shows how the agent:
  1. Remembers the conversation - References previous login issues
  2. Learns about the user - Builds a profile of the customer’s technical level and preferences
  3. Maintains context - Knows about password reset attempts from earlier in the session
  4. Persists across sessions - Recognizes the customer in a new session and recalls their history