Memory - Upsonic AI

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:

Loads the user’s profile (if you’re using user analysis memory)
Retrieves the conversation summary (if you’re using summary memory)
Pulls up previous messages (if you’re using conversation memory)
Gives all this context to your agent automatically

After Each Conversation:

Saves the new messages to history
Updates the conversation summary
Analyzes what the agent learned about the user
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="anthropic/claude-sonnet-4-5",            # 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 Type	When to Use	Requirements
Conversation Memory	Customer support, tutoring, detailed conversations	`session_id`
Summary Memory	Long conversations, cost reduction	`session_id`, `model`
User Analysis Memory	Personalization, user preferences	`user_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="anthropic/claude-sonnet-4-5"
)

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="anthropic/claude-sonnet-4-6"  # 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="anthropic/claude-sonnet-4-6"
)

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="anthropic/claude-sonnet-4-5"
)

# 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="anthropic/claude-sonnet-4-5"
)

# 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="anthropic/claude-sonnet-4-5"
)

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="anthropic/claude-sonnet-4-5"
)

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="anthropic/claude-sonnet-4-5"
)

# Support agent
agent = Agent(
    model="anthropic/claude-sonnet-4-5",
    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="anthropic/claude-sonnet-4-5"
)

agent_new = Agent(model="anthropic/claude-sonnet-4-5", 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:

Remembers the conversation - References previous login issues
Learns about the user - Builds a profile of the customer’s technical level and preferences
Maintains context - Knows about password reset attempts from earlier in the session
Persists across sessions - Recognizes the customer in a new session and recalls their history

Documentation Index

​Overview

​What is Memory?

​How Memory Works

​Attributes

​Choosing Right Memory Types

​What is The Selection Criteria?

​Making Combination of Memory

​Use Case for Conversation Memory

​Use Case for Summary Memory

​Use Case for User Analysis Memory

​Memory Types

​Conversation Memory

​What is Conversation Memory?

​Usage

​Params

​Summary Memory

​What is Summary Memory?

​Usage

​Params

​User Analysis Memory

​What is User Analysis Memory?

​Usage

​Params

​Storage Options

​InMemoryStorage

​Usage

​Params

​JSONStorage

​Usage

​Params

​SqliteStorage

​Usage

​Params

​PostgresStorage

​Usage

​Params

​RedisStorage

​Usage

​Params

​Mem0Storage

​Usage

​Params

​MongoStorage

​Usage

​Params

​Examples

​Basic Memory Example

​About Example Scenario

​Memory Configuration

​Full Code

Overview

What is Memory?

How Memory Works

Attributes

Choosing Right Memory Types

What is The Selection Criteria?

Making Combination of Memory

Use Case for Conversation Memory

Use Case for Summary Memory

Use Case for User Analysis Memory

Memory Types

Conversation Memory

What is Conversation Memory?

Usage

Params

Summary Memory

What is Summary Memory?

Usage

Params

User Analysis Memory

What is User Analysis Memory?

Usage

Params

Storage Options

InMemoryStorage

Usage

Params

JSONStorage

Usage

Params

SqliteStorage

Usage

Params

PostgresStorage

Usage

Params

RedisStorage

Usage

Params

Mem0Storage

Usage

Params

MongoStorage

Usage

Params

Examples

Basic Memory Example

About Example Scenario

Memory Configuration

Full Code