Sessions & Memory - Vizra ADK

Sessions provide conversation context while memory enables long-term knowledge retention. Together, they create intelligent, personalized agent interactions that improve over time!

Understanding Sessions

Think of sessions as your agent’s short-term memory during a conversation!

Conversation History

Every message between your agent and user is tracked

Context Preservation

State persists across multiple interactions

State Storage

Keep track of important conversation data

Memory Links

Connect to long-term agent memory

Creating and Managing Sessions

Using Sessions with Agents

Let’s see how easy it is to maintain conversations across multiple interactions!

app/Http/Controllers/ChatController.php

use App\Agents\CustomerSupportAgent;

// Start a conversation with a session
$response = CustomerSupportAgent::run('I need help with my order')
    ->forUser($user)
    ->withSession($sessionId)
    ->go();

// Continue in the same session - agent remembers!
$response2 = CustomerSupportAgent::run('The order number is #12345')
    ->forUser($user)
    ->withSession($sessionId)
    ->go();

Session Models

Sessions are first-class citizens in Vizra, stored safely in your database!

use Vizra\VizraADK\Models\AgentSession;
use Vizra\VizraADK\Models\AgentMessage;

// Sessions are stored in the database
$session = AgentSession::where('session_id', $sessionId)->first();

// Access session messages
$messages = $session->messages()->get();

// Access session state
$stateData = $session->state_data;

AgentContext Magic

The AgentContext is your Swiss Army knife for session management!

app/Agents/MyAgent.php

// AgentContext provides session state management
public function run(string $input, AgentContext $context): mixed
{
    // Get session ID
    $sessionId = $context->getSessionId();

    // Store state in session
    $context->setState('order_id', '#12345');

    // Retrieve state
    $orderId = $context->getState('order_id');

    // Get conversation history
    $history = $context->getConversationHistory();
}

Memory System

Give your agents the gift of memory! Vizra provides persistent memory across sessions through the powerful AgentMemory model and MemoryManager service:

Session State

Short-term context stored in AgentContext during a conversation - like working memory!

Agent Memory

Long-term memory with learnings, facts, and session summaries - like permanent storage!

Using Persistent Memory

Agent Memory API

Every agent now has a built-in memory system that’s super easy to use!

app/Agents/SupportAgent.php

class SupportAgent extends BaseLlmAgent
{
    protected string $name = 'support_agent';

    public function afterLlmResponse(Response|Generator $response, AgentContext $context): mixed
    {
        // Extract insights from the conversation
        if (str_contains($response, 'prefer email')) {
            $this->memory()->addLearning('User prefers email communication');
        }

        // Store facts
        if ($this->detectAccountType($response)) {
            $this->memory()->addFact('Customer has premium account', 0.9);
        }

        // Add preferences
        $this->memory()->addPreference('Email notifications', 'communication');

        // Update summary periodically
        if ($this->shouldUpdateSummary()) {
            $this->memory()->updateSummary(
                'Premium customer who prefers email, interested in API features'
            );
        }

        return $response;
    }

    protected function buildSystemPrompt(): string
    {
        // Automatically include memory context in prompts!
        $memoryContext = $this->memory()->getContext(1000);

        return $this->instructions . "\n\nUser Context:\n" . $memoryContext;
    }
}

Memory Methods

The agent memory API provides specialized methods for different types of information:

// Inside any agent method, access memory via $this->memory()

// Learnings - Insights gained from interactions
$this->memory()->addLearning('User works in healthcare', [
    'confidence' => 'high',
    'source' => 'direct_mention'
]);

// Facts - Immutable truths about the user
$this->memory()->addFact('Located in New York', 1.0); // confidence score

// Preferences - User likes and dislikes
$this->memory()->addPreference('Detailed explanations', 'communication_style');

// Summary - Overall user profile (replaces previous)
$this->memory()->updateSummary('Tech-savvy healthcare professional in NYC');

// Recall - Search through memories
$learnings = $this->memory()->getLearnings();
$facts = $this->memory()->getFacts();
$preferences = $this->memory()->getPreferences('communication_style');
$summary = $this->memory()->getSummary();

// Context - Get formatted memory for prompts
$context = $this->memory()->getContext(1500); // max tokens

Memory Manager Service

For advanced use cases, you can still access the Memory Manager directly:

app/Services/AgentService.php

use Vizra\VizraADK\Services\MemoryManager;

// Get or create memory for an agent
$memory = $memoryManager->getOrCreateMemory('support_agent', $userId);

// Add a learning
$memoryManager->addLearning(
    'support_agent',
    'User prefers email communication',
    $userId
);

// Add a fact
$memoryManager->addFact(
    'support_agent',
    'preferred_contact',
    'email',
    $userId
);

// Update memory summary
$memoryManager->updateSummary(
    'support_agent',
    'Customer is a premium member who prefers email contact',
    $userId
);

Using Memory Tool

Agents can manage their own memory - how cool is that?

app/Agents/SupportAgent.php

// Agents can use the MemoryTool to manage their own memory
class SupportAgent extends BaseLlmAgent
{
    protected array $tools = [
        MemoryTool::class,
    ];

    protected string $instructions = '...
    Use the manage_memory tool to:
    - Add important learnings about the user
    - Store facts for future reference
    - Retrieve context from previous conversations
    ';
}

Memory Context in Instructions

Inject past memories into your agent’s instructions for truly personalized interactions!

// Get memory context to include in agent instructions
$memoryContext = $memoryManager->getMemoryContext(
    'support_agent',
    $userId,
    1000 // max length
);

// Memory context includes:
// - Previous Knowledge (summary)
// - Key Learnings (last 5)
// - Important Facts (up to 10)

Memory Model Structure

Let’s peek under the hood! The AgentMemory model is beautifully organized:

Memory Properties

database/agent_memories table

// AgentMemory model structure
{
    "agent_name": "support_agent",
    "user_id": 123,
    "memory_summary": "Previous conversation summaries",
    "memory_data": {                  // Facts stored as key-value pairs
        "preferred_contact": "email",
        "account_type": "premium"
    },
    "key_learnings": [              // Array of learnings with timestamps
        {
            "learning": "User prefers detailed explanations",
            "learned_at": "2024-01-15T10:30:00Z"
        }
    ],
    "total_sessions": 42,
    "last_session_at": "2024-01-15T10:30:00Z"
}

Accessing Memory Data

Working with memory data is a breeze! Check out these handy methods:

use Vizra\VizraADK\Models\AgentMemory;

// Find memory for agent and user
$memory = AgentMemory::where('agent_name', 'support_agent')
    ->where('user_id', $userId)
    ->first();

// Get context summary for agent instructions
$contextSummary = $memory->getContextSummary(1000);

// Add a learning
$memory->addLearning('User works in healthcare industry');

// Update memory data
$memory->updateMemoryData([
    'industry' => 'healthcare',
    'timezone' => 'EST'
]);

// Record a new session
$memory->recordSession();

Session and Memory Integration

Automatic Memory Updates

The magic happens automatically! Sessions and memory work together seamlessly:

// Sessions automatically link to memory
$session = AgentSession::find($id);
$memory = $session->getOrCreateMemory();

// Update memory from session
$session->updateMemory([
    'learnings' => [
        'User is interested in API integration',
        'Prefers Python code examples'
    ],
    'facts' => [
        'programming_language' => 'Python',
        'api_experience' => 'intermediate'
    ]
]);

Memory Extraction

Watch as Vizra intelligently extracts insights from conversations!

// MemoryManager automatically extracts insights from sessions
$memoryManager->updateMemoryFromSession($session);

// This automatically:
// - Records the session in memory
// - Extracts preferences ("I like/prefer...")
// - Extracts personal info ("My name is...")
// - Updates session count and timestamps

Memory Lifecycle

Session Summarization

Keep memories fresh and relevant with intelligent summarization!

// Summarize recent sessions into memory
$memoryManager->summarizeMemory(
    $memory,
    10 // Number of recent sessions to summarize
);

// Get recent conversations
$recentConversations = $memoryManager->getRecentConversations(
    'support_agent',
    $userId,
    5 // Limit
);

Memory Cleanup

Keep your database tidy with smart cleanup strategies!

// Clean up old memories
$deletedCount = $memoryManager->cleanupOldMemories(
    90,    // Days old
    1000   // Max sessions
);

// Clean up old sessions while preserving memory
$deletedSessions = $memoryManager->cleanupOldSessions(
    'support_agent',
    30 // Days old
);

Implementation Examples

Customer Support Agent

A complete example of a memory-aware support agent that learns and adapts!

app/Agents/CustomerSupportAgent.php

class CustomerSupportAgent extends BaseLlmAgent
{
    protected string $name = 'customer_support';
    protected string $instructions = 'You are a helpful customer support agent...';

    public function afterLlmResponse(Response|Generator $response, AgentContext $context): mixed
    {
        $responseText = $response instanceof Response ? $response->text : '';

        // Extract and store contact preferences
        if (preg_match('/prefer.*(email|phone|chat)/i', $responseText, $matches)) {
            $this->memory()->addPreference(
                "Prefers {$matches[1]} communication",
                'contact'
            );
        }

        // Detect product interests
        if (str_contains($responseText, 'API') || str_contains($responseText, 'integration')) {
            $this->memory()->addLearning('Interested in API/integration features');
        }

        // Store important facts
        if (preg_match('/order\s*#?(\d+)/i', $responseText, $matches)) {
            $this->memory()->addFact("Recent order: #{$matches[1]}", 1.0);
        }

        return $response;
    }

    protected function buildSystemPrompt(): string
    {
        // Include all relevant memory context
        $memory = $this->memory();
        $summary = $memory->getSummary();
        $preferences = $memory->getPreferences('contact');
        $recentFacts = $memory->getFacts()->take(5);

        $prompt = $this->instructions;

        if ($summary) {
            $prompt .= "\n\nCustomer Profile: " . $summary;
        }

        if ($preferences->isNotEmpty()) {
            $prompt .= "\n\nCommunication Preferences:";
            foreach ($preferences as $pref) {
                $prompt .= "\n- " . $pref->content;
            }
        }

        if ($recentFacts->isNotEmpty()) {
            $prompt .= "\n\nRecent Information:";
            foreach ($recentFacts as $fact) {
                $prompt .= "\n- " . $fact->content;
            }
        }

        return $prompt;
    }
}

Educational Tutor Agent

An agent that tracks learning progress and adapts teaching style!

app/Agents/TutorAgent.php

class TutorAgent extends BaseLlmAgent
{
    protected string $name = 'tutor_agent';

    public function afterLlmResponse(Response|Generator $response, AgentContext $context): mixed
    {
        // Track topics covered
        if ($topic = $this->extractTopic($response)) {
            $this->memory()->addLearning("Studied topic: {$topic}", [
                'timestamp' => now()->toIso8601String(),
                'session_id' => $context->getSessionId()
            ]);
        }

        // Detect learning style preferences
        $this->detectLearningStyle($response, $context);

        // Update progress summary
        $learnings = $this->memory()->getLearnings();
        if ($learnings->count() % 5 === 0) { // Every 5 learnings
            $topics = $learnings->pluck('content')->take(10)->implode(', ');
            $this->memory()->updateSummary(
                "Student has covered: {$topics}. Shows strong interest in practical examples."
            );
        }

        return $response;
    }

    private function detectLearningStyle($response, $context): void
    {
        $userInput = $context->getLastUserMessage();

        if (str_contains($userInput, 'example') || str_contains($userInput, 'show me')) {
            $this->memory()->addPreference('Prefers examples', 'learning_style');
        }

        if (str_contains($userInput, 'why') || str_contains($userInput, 'explain')) {
            $this->memory()->addPreference('Likes detailed explanations', 'learning_style');
        }

        if (str_contains($userInput, 'quick') || str_contains($userInput, 'summary')) {
            $this->memory()->addPreference('Prefers concise answers', 'learning_style');
        }
    }
}

Memory-Aware Agent Base Class

Create a reusable base class for all memory-aware agents:

app/Agents/MemoryAwareAgent.php

abstract class MemoryAwareAgent extends BaseLlmAgent
{
    protected bool $autoExtractPreferences = true;
    protected bool $includeMemoryInPrompt = true;

    protected function buildSystemPrompt(): string
    {
        $prompt = $this->instructions;

        if ($this->includeMemoryInPrompt) {
            $memoryContext = $this->memory()->getContext(800);
            if ($memoryContext) {
                $prompt .= "\n\nUser Context:\n" . $memoryContext;
            }
        }

        return $prompt;
    }

    public function afterLlmResponse(Response|Generator $response, AgentContext $context): mixed
    {
        if ($this->autoExtractPreferences) {
            $this->extractPreferences($response, $context);
        }

        // Let child classes add their own memory logic
        $this->updateMemory($response, $context);

        return $response;
    }

    /**
     * Override this in child classes to add custom memory updates
     */
    protected function updateMemory(Response|Generator $response, AgentContext $context): void
    {
        // Child classes implement their specific memory logic
    }

    private function extractPreferences($response, $context): void
    {
        $text = $response instanceof Response ? $response->text : '';
        $userInput = $context->getLastUserMessage();

        // Common preference patterns
        $patterns = [
            '/I (?:prefer|like|want|need) (.+?)(?:\.|,|$)/i' => 'general',
            '/(?:call|email|text|message) me/i' => 'contact',
            '/I (?:work in|am in|from) (.+?)(?:\.|,|$)/i' => 'location',
            '/my (?:job|role|position) is (.+?)(?:\.|,|$)/i' => 'occupation'
        ];

        foreach ($patterns as $pattern => $category) {
            if (preg_match($pattern, $userInput, $matches)) {
                $preference = isset($matches[1]) ? $matches[1] : $matches[0];
                $this->memory()->addPreference(trim($preference), $category);
            }
        }
    }
}

Session State Management

Store complex data structures in session state - it’s that flexible!

// Store complex state in sessions
$context->setState('cart_items', [
    ['id' => 123, 'quantity' => 2],
    ['id' => 456, 'quantity' => 1]
]);

// Load all state
$allState = $context->getAllState();

// Merge new state
$context->loadState([
    'preferences' => $userPreferences,
    'settings' => $userSettings
]);

Memory Best Practices

Short-term Memory

Use AgentContext for session state

Long-term Memory

Store important facts in AgentMemory

Auto-summarization

Let MemoryManager handle summaries

Agent Control

Use MemoryTool for self-management

Cleanup Strategy

Implement cleanup for old sessions

Context Injection

Include memory in instructions

Next: Workflows

Learn about agent workflows and multi-step processes

Next: Dynamic Prompts

Learn about dynamic prompt versioning and variants

Documentation Index

​Understanding Sessions

Conversation History

Context Preservation

State Storage

Memory Links

​Creating and Managing Sessions

​Using Sessions with Agents

​Session Models

​AgentContext Magic

​Memory System

Session State

Agent Memory

​Using Persistent Memory

​Agent Memory API

​Memory Methods

​Memory Manager Service

​Using Memory Tool

​Memory Context in Instructions

​Memory Model Structure

​Memory Properties

​Accessing Memory Data

​Session and Memory Integration

​Automatic Memory Updates

​Memory Extraction

​Memory Lifecycle

​Session Summarization

​Memory Cleanup

​Implementation Examples

​Customer Support Agent

​Educational Tutor Agent

​Memory-Aware Agent Base Class

​Session State Management

​Memory Best Practices

Short-term Memory

Long-term Memory

Auto-summarization

Agent Control

Cleanup Strategy

Context Injection

Next: Workflows

Next: Dynamic Prompts

Understanding Sessions

Creating and Managing Sessions

Using Sessions with Agents

Session Models

AgentContext Magic

Memory System

Using Persistent Memory

Agent Memory API

Memory Methods

Memory Manager Service

Using Memory Tool

Memory Context in Instructions

Memory Model Structure

Memory Properties

Accessing Memory Data

Session and Memory Integration

Automatic Memory Updates

Memory Extraction

Memory Lifecycle

Session Summarization

Memory Cleanup

Implementation Examples

Customer Support Agent

Educational Tutor Agent

Memory-Aware Agent Base Class

Session State Management

Memory Best Practices