Skip to main content
Every agent in LarAgent has a Context that manages multiple storage instances — chat history, usage tracking, identity storage, and any custom storages you register. You can configure which storage drivers these use at the agent level.

​
Configuration Hierarchy

Storage drivers are resolved in the following order (highest priority first):
  1. Storage-specific method (e.g., historyStorageDrivers())
  2. Storage-specific property (e.g., $history)
  3. Agent default method (defaultStorageDrivers())
  4. Agent default property ($storage)
  5. Provider configuration (config/laragent.php)
  6. Global configuration (config/laragent.php)

​
Default Storage Drivers

Set default drivers for all storages in an agent’s context using the $storage property or defaultStorageDrivers() method.

​
Using Property

use LarAgent\Agent;
use LarAgent\Context\Drivers\CacheStorage;
use LarAgent\Context\Drivers\FileStorage;

class SupportAgent extends Agent
{
    protected $instructions = 'You are a helpful support agent.';
    
    // Default drivers for all storages (chat history, usage, custom, etc.)
    protected $storage = [
        CacheStorage::class,  // Primary
        FileStorage::class,   // Fallback
    ];
}

​
Using Method Override

For dynamic configuration, override the defaultStorageDrivers() method: 
use LarAgent\Agent;
use LarAgent\Context\Drivers\CacheStorage;
use LarAgent\Context\Drivers\EloquentStorage;

class SupportAgent extends Agent
{
    protected $instructions = 'You are a helpful support agent.';
    
    protected function defaultStorageDrivers(): array
    {
        // Use database in production, cache in development
        if (app()->environment('production')) {
            return [
                new EloquentStorage(),
            ];
        }
        
        return [
            new CacheStorage('redis'),
        ];
    }
}

​
Storage-Specific Drivers

Override the default for specific storage types when you need different persistence strategies.

​
Chat History Storage

Use $history property or historyStorageDrivers() method: 
class SupportAgent extends Agent
{
    // Default for all storages
    protected $storage = [CacheStorage::class];
    
    // Override for chat history only
    protected $history = 'database';
}
For chat history-specific configuration like truncation strategies, metadata storage, and force read/save flags, see the Chat History documentation.

​
Usage Storage

Use $usageStorage property or usageStorageDrivers() method: 
class SupportAgent extends Agent
{
    protected $storage = [CacheStorage::class];

    protected $trackUsage = true;
    
    // Override for usage tracking only
    protected $usageStorage = [EloquentStorage::class];
}
For detailed usage tracking configuration, cost calculation, and custom models, see the Usage Tracking documentation.

​
String Aliases

Both $usageStorage and $history properties accept string aliases for convenience: 
class SupportAgent extends Agent
{
    // Using alias for usage
    protected $usageStorage = 'cache';
    
    // Using alias for history
    protected $history = 'database';
}
AliasDriver Class
'in_memory'InMemoryStorage
'session'SessionStorage
'cache'CacheStorage
'file' or 'json'FileStorage
'database'EloquentStorage
'database-simple'SimpleEloquentStorage
For detailed information about each driver’s constructor arguments, custom model examples, and the fallback pattern, see the Storage Drivers reference.

​
Configuration Examples

​
Simple: Single Driver for Everything

use LarAgent\Context\Drivers\CacheStorage;
use LarAgent\Context\Drivers\EloquentStorage;

class SupportAgent extends Agent
{
    protected $instructions = 'You are a helpful support agent.';
    
    // All storages use cache and database drivers
    protected $storage = [
        CacheStorage::class,
        EloquentStorage::class,
    ];
}

​
Mixed: Different Drivers per Storage Type

use LarAgent\Context\Drivers\CacheStorage;
use LarAgent\Context\Drivers\EloquentStorage;

class SupportAgent extends Agent
{
    protected $instructions = 'You are a helpful support agent.';
    
    // Default: cache for most storages
    protected $storage = [CacheStorage::class];
    
    // Chat history: database for queryability
    protected $history = 'database';
    
    // Usage tracking: database for analytics
    protected $usageStorage = 'database-simple';
}

​
High Availability: Fallback Chain

use LarAgent\Context\Drivers\CacheStorage;
use LarAgent\Context\Drivers\FileStorage;
use LarAgent\Context\Drivers\EloquentStorage;

class SupportAgent extends Agent
{
    protected $instructions = 'You are a helpful support agent.';
    
    // Cache with file fallback for general storages
    protected $storage = [
        CacheStorage::class,
        FileStorage::class,
    ];
    
    // Database for chat history (no fallback needed)
    protected $history = [
        EloquentStorage::class
    ];
}

​
Dynamic: Environment-Based Configuration

class SupportAgent extends Agent
{
    protected $instructions = 'You are a helpful support agent.';
    
    protected function defaultStorageDrivers(): array
    {
        return match (app()->environment()) {
            'testing' => [new InMemoryStorage()],
            'local' => [new CacheStorage()],
            default => [
                new CacheStorage('redis'),
                new FileStorage('s3', 'agent_backup'),
            ],
        };
    }
    
    protected function historyStorageDrivers(): string|array
    {
        // Always use database for chat history in non-test environments
        if (app()->environment('testing')) {
            return [new InMemoryStorage()];
        }
        
        return [new EloquentStorage()];
    }

    protected function usageStorageDrivers(): string|array
    {
        // Always use database for chat history in non-test environments
        if (app()->environment('testing')) {
            return [new InMemoryStorage()];
        }
        
        return [new EloquentStorage()];
    }
}

​
How It Works

When a storage is created (e.g., ChatHistoryStorage), it resolves drivers in this order: 
historyStorageDrivers() → $history → defaultStorageDrivers() → $storage → config
This allows you to:
  1. Set sensible defaults at the agent level ($storage / defaultStorageDrivers())
  2. Override specific storages when needed ($history / historyStorageDrivers())
  3. Fall back to global config if nothing is specified
Use $storage for simple cases and defaultStorageDrivers() when you need dynamic logic like environment checks or custom driver instances.

​
Custom Storages

Beyond chat history and usage tracking, you can create custom storages for any data your agent needs to persist — customer notes, session metadata, conversation tags, and more. Custom storages use:
  • DataModel — Typed, structured data classes for your storage items
  • Storage — Abstract base class that handles persistence, lazy loading, and dirty tracking
  • Storage Drivers — Pluggable backends (cache, file, database, etc.)

Custom Storage

Create custom storages with DataModels for type-safe persistence.

Custom Storage Driver

Build custom storage drivers for specialized backends.

​
Next Steps

Storage Drivers

Learn about all available storage drivers and their configuration options.

Chat History

Configure chat history storage and truncation strategies.

Usage Tracking

Track token usage and costs across agent interactions.

Context Overview

Understand the Context and Identity system for storage isolation.