Skip to main content

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.

The Memory system in Upsonic provides comprehensive, configurable memory management for AI agents, enabling them to maintain context across conversations, build user profiles, and store session summaries.

​
Memory System Overview

The Memory class serves as a centralized module for managing different types of memory and respects the specific data formats and logic established in the original application design for handling chat history.

​
Key Features

  • Session Memory: Full conversation history storage and retrieval
  • Summary Memory: Automatic conversation summarization
  • User Analysis Memory: Dynamic user profile building and trait analysis
  • Flexible Storage: Support for various storage backends (SQLite, etc.)
  • Context Injection: Automatic injection of relevant memory into system prompts

​
Setting Up Memory with SQLite

Here’s how to set up memory with SQLite storage: 
from upsonic import Agent, Task
from upsonic.storage import Memory, SqliteStorage
from upsonic.models.anthropic import AnthropicModel

# Create storage backend
storage = SqliteStorage(db_file="agent_memory.db")

# Create memory system
memory = Memory(
    storage=storage,
    session_id="banking_session_001",
    user_id="user_001",
    full_session_memory=True,
    summary_memory=True,
    user_analysis_memory=True,
    model=AnthropicModel(model_name="claude-sonnet-4-5")
)

# Create agent with memory
agent = Agent(
    model="anthropic/claude-sonnet-4-5",
    name="BankingAssistant",
    memory=memory,
    feed_tool_call_results=True
)

task = Task("My name is Alice")

result = agent.do(task)
print(result)

task2 = Task("What is my name?")

result2 = agent.do(task2)
print(result2)

​
Memory Configuration Options

​
Basic Memory Setup

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

# Create storage backend
storage = SqliteStorage(db_file="basic_memory.db")

# Basic memory configuration
memory = Memory(
    storage=storage,
    session_id="session_001",
    user_id="user_001"
)

# Create agent with memory
agent = Agent(
    model="anthropic/claude-sonnet-4-5",
    memory=memory
)

# Test memory
task = Task("Hello, my name is Bob")
result = agent.do(task)
print(result)

​
Full Memory Configuration

from upsonic import Agent, Task
from upsonic.storage import Memory, SqliteStorage
from upsonic.models.anthropic import AnthropicModel

# Create storage and model
storage = SqliteStorage(db_file="full_memory.db")
model = AnthropicModel(model_name="claude-sonnet-4-5")

# Full memory configuration with all options
memory = Memory(
    storage=storage,
    session_id="advanced_session",
    user_id="user_001",
    full_session_memory=True,        # Store complete conversation history
    summary_memory=True,             # Generate conversation summaries
    user_analysis_memory=True,       # Build user profiles and traits
    user_profile_schema=None,        # Custom user profile schema
    dynamic_user_profile=False,      # Use dynamic profile generation
    num_last_messages=None,          # Limit conversation history
    model=model,                     # LLM for analysis tasks
    debug=False,                     # Enable debug logging
    feed_tool_call_results=False,    # Include tool results in memory
    user_memory_mode='update'        # 'update' or 'replace' user profiles
)

# Create agent with full memory
agent = Agent(
    model="anthropic/claude-sonnet-4-5",
    name="AdvancedMemoryAgent",
    memory=memory
)

# Test conversation with memory
task = Task("I prefer conservative investments and my goal is retirement savings")
result = agent.do(task)
print(result)

​
Memory Types Explained

​
Full Session Memory

Stores complete conversation history for context retrieval: 
from upsonic import Agent, Task
from upsonic.storage import Memory, SqliteStorage

# Create storage
storage = SqliteStorage(db_file="session_memory.db")

# Memory with full session history
memory = Memory(
    storage=storage,
    session_id="session_001",
    full_session_memory=True
)

# Create agent
agent = Agent(model="anthropic/claude-sonnet-4-5", memory=memory)

# First message
result1 = agent.do(Task("My favorite color is blue"))
print(result1)

# Second message - agent should remember the first
result2 = agent.do(Task("What is my favorite color?"))
print(result2)

​
Summary Memory

Automatically generates and maintains conversation summaries: 
from upsonic import Agent, Task
from upsonic.storage import Memory, SqliteStorage
from upsonic.models.anthropic import AnthropicModel

# Create storage
storage = SqliteStorage(db_file="summary_memory.db")

# Memory with automatic summarization
memory = Memory(
    storage=storage,
    session_id="session_001",
    summary_memory=True,
    model=AnthropicModel(model_name="claude-sonnet-4-5")
)

# Create agent
agent = Agent(model="anthropic/claude-sonnet-4-5", memory=memory)

# Have a conversation that will be summarized
task = Task("Tell me about the benefits of cloud computing")
result = agent.do(task)
print(result)

​
User Analysis Memory

Builds and maintains user profiles based on interactions: 
from upsonic import Agent, Task
from upsonic.storage import Memory, SqliteStorage
from upsonic.models.anthropic import AnthropicModel

# Create storage
storage = SqliteStorage(db_file="user_analysis_memory.db")

# Memory with user profile analysis
memory = Memory(
    storage=storage,
    session_id="session_001",
    user_id="user_001",
    user_analysis_memory=True,
    model=AnthropicModel(model_name="claude-sonnet-4-5")
)

# Create agent
agent = Agent(model="anthropic/claude-sonnet-4-5", memory=memory)

# Share user preferences
task = Task("I'm a software developer interested in AI and machine learning")
result = agent.do(task)
print(result)

​
Using Memory in Task Execution

Once configured, memory automatically integrates with your agent: 
from upsonic import Agent, Task
from upsonic.storage import Memory, SqliteStorage
from upsonic.models.anthropic import AnthropicModel

# Setup storage and memory
storage = SqliteStorage(db_file="task_execution_memory.db")
memory = Memory(
    storage=storage,
    session_id="investment_session",
    user_id="investor_001",
    full_session_memory=True,
    user_analysis_memory=True,
    model=AnthropicModel(model_name="claude-sonnet-4-5")
)

# Create agent with memory
agent = Agent(
    model="anthropic/claude-sonnet-4-5",
    name="InvestmentAdvisor",
    memory=memory
)

# Create a task - memory will automatically be used
task = Task(
    description="Analyze the user's investment portfolio and provide recommendations based on their risk tolerance and previous conversations."
)

# Execute with memory context
result = agent.do(task)
print(result)
The memory system will:
  1. Inject relevant user profile information into the system prompt
  2. Include conversation summaries for context
  3. Provide full conversation history if needed
  4. Update user profiles based on the interaction

​
Memory Management Methods

​
Accessing Memory Data

import asyncio
from upsonic import Agent, Task
from upsonic.storage import Memory, SqliteStorage
from upsonic.models.anthropic import AnthropicModel

async def main():
    # Create storage and memory
    storage = SqliteStorage(db_file="access_memory.db")
    memory = Memory(
        storage=storage,
        session_id="session_001",
        user_id="user_001",
        full_session_memory=True,
        user_analysis_memory=True,
        summary_memory=True,
        model=AnthropicModel(model_name="claude-sonnet-4-5")
    )

    # Create agent with memory
    agent = Agent(model="anthropic/claude-sonnet-4-5", memory=memory)

    # First, have a conversation to build memory
    task = Task("My name is John and I'm interested in technology stocks")
    result = agent.do(task)
    print("Agent response:", result)

    # Access session data via memory
    session = await agent.memory.get_session_async()
    if session:
        print("Session ID:", session.session_id)
        print("Messages count:", len(session.messages) if session.messages else 0)
        print("Session summary:", session.summary)

    # Access user memory via storage
    user_memory = storage.get_user_memory(user_id="user_001")
    if user_memory:
        print("User memory:", user_memory.user_memory)

# Run the async function
asyncio.run(main())

​
Memory Configuration in Agent

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

# Create storage and memory
storage = SqliteStorage(db_file="advisor_memory.db")
memory = Memory(
    storage=storage,
    session_id="advisor_session",
    user_id="client_001",
    full_session_memory=True
)

# Create agent with memory configuration
agent = Agent(
    model="anthropic/claude-sonnet-4-5",
    name="FinancialAdvisor",
    memory=memory,
    feed_tool_call_results=True,  # Include tool results in memory
    debug=True                    # Enable memory debug logging
)

# Test the agent
task = Task("What investment strategies do you recommend for a 30-year-old?")
result = agent.do(task)
print(result)

​
Advanced Memory Features

​
Custom User Profile Schema

from upsonic import Agent, Task
from upsonic.storage import Memory, SqliteStorage
from upsonic.models.anthropic import AnthropicModel
from pydantic import BaseModel, Field
from typing import List

# Define custom user profile schema
class CustomUserTraits(BaseModel):
    risk_tolerance: str = Field(description="User's risk tolerance level")
    investment_goals: str = Field(description="User's investment objectives")
    preferred_assets: List[str] = Field(default=[], description="User's preferred asset classes")

# Create storage and model
storage = SqliteStorage(db_file="custom_profile_memory.db")
model = AnthropicModel(model_name="claude-sonnet-4-5")

# Create memory with custom profile schema
memory = Memory(
    storage=storage,
    session_id="session_001",
    user_id="user_001",
    user_analysis_memory=True,
    user_profile_schema=CustomUserTraits,
    model=model
)

# Create agent
agent = Agent(model="anthropic/claude-sonnet-4-5", memory=memory)

# Share investment preferences
task = Task("I have a high risk tolerance and I'm interested in tech stocks and crypto")
result = agent.do(task)
print(result)

​
Dynamic User Profile Generation

from upsonic import Agent, Task
from upsonic.storage import Memory, SqliteStorage
from upsonic.models.anthropic import AnthropicModel

# Create storage and model
storage = SqliteStorage(db_file="dynamic_profile_memory.db")
model = AnthropicModel(model_name="claude-sonnet-4-5")

# Memory with dynamic profile generation
memory = Memory(
    storage=storage,
    session_id="session_001",
    user_id="user_001",
    user_analysis_memory=True,
    dynamic_user_profile=True,  # Automatically generate profile schema
    model=model
)

# Create agent
agent = Agent(model="anthropic/claude-sonnet-4-5", memory=memory)

# The agent will dynamically build a profile based on the conversation
task = Task("I'm a retired teacher looking for safe investments with steady income")
result = agent.do(task)
print(result)

​
Memory with Limited History

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

# Create storage
storage = SqliteStorage(db_file="limited_history_memory.db")

# Memory with limited conversation history
memory = Memory(
    storage=storage,
    session_id="session_001",
    full_session_memory=True,
    num_last_messages=10  # Keep only last 10 conversation turns
)

# Create agent
agent = Agent(model="anthropic/claude-sonnet-4-5", memory=memory)

# Test limited history
task = Task("Remember that my favorite number is 42")
result = agent.do(task)
print(result)

​
Storage Configuration Options

The SqliteStorage class accepts the following parameters: 
from upsonic.storage import SqliteStorage

# Full configuration example
storage = SqliteStorage(
    db_file="agent_data.db",           # Path to SQLite database file
    session_table="custom_sessions",    # Custom session table name (optional)
    user_memory_table="custom_users",   # Custom user memory table name (optional)
    id="storage_instance_1"             # Unique storage instance ID (optional)
)

​
Best Practices

  1. Choose Appropriate Memory Types: Enable only the memory types you need to optimize performance
  2. Set Session IDs: Always provide meaningful session IDs for proper memory isolation
  3. User ID Management: Use consistent user IDs for proper profile building
  4. Model Provider: Provide a model provider for summary and analysis features
  5. Storage Backend: Choose appropriate storage backend based on your deployment needs
  6. Memory Limits: Use num_last_messages to prevent memory from growing too large
  7. Debug Mode: Enable debug mode during development to understand memory behavior
  8. Tool Results: Consider whether to include tool call results in memory based on your use case
The Memory system provides a robust foundation for building conversational AI applications that can maintain context, learn from interactions, and provide personalized experiences.