Storage Drivers

LarAgent provides several storage drivers for persisting data. Each driver can be used with any storage type — chat history, usage tracking, identity storage, or custom storages.

Available Drivers

Driver	Use Case	Persistence	Performance
`InMemoryStorage`	Testing, single-request processing	None	Fastest
`SessionStorage`	Web requests, user sessions	Session lifetime	Fast
`CacheStorage`	Temporary storage with TTL	Configurable	Fast
`FileStorage`	Simple file-based persistence	Permanent	Moderate
`SimpleEloquentStorage`	Database (JSON blob)	Permanent	Moderate
`EloquentStorage`	Database (normalized rows)	Permanent	Best for querying

Driver Chain (Fallback Pattern)

LarAgent Storage classes support configuring multiple drivers in a chain. The first driver is the primary, and subsequent drivers serve as fallbacks:

protected $history = [
    CacheStorage::class,  // Primary: read first, write first
    FileStorage::class,   // Fallback: used if primary fails on read
];

How it works:

Reading: Tries the primary driver first. If it returns no data, falls back to the next driver.
Writing: Writes to all drivers in the chain to keep them synchronized.
Removing: Removes from all drivers.

Use the fallback pattern for high availability. For example, cache for speed with file storage as a durable backup.

InMemoryStorage

Stores data in PHP memory. Data is lost after the request ends. Ideal for testing or single-request agents.

protected $history = 'in_memory';

There is no point in using InMemoryStorage with other storage drivers in a fallback chain.

SessionStorage

Uses Laravel’s session to store data. Perfect for web applications where context should persist across user requests.

protected $history = 'session';

Requires an active Laravel session. Not suitable for CLI or queue workers.

CacheStorage

Uses Laravel’s cache system. Supports different cache stores like Redis, Memcached, or file.

protected $history = 'cache';

Custom configuration

MyAgent

use LarAgent\Context\Drivers\CacheStorage;

protected function defaultStorageDrivers(): array
{
    return [
        // Use default cache store
        new CacheStorage(),
        
        // Or use a specific cache store
        new CacheStorage('redis'),
    ];
}

Constructor arguments:

Parameter	Type	Default	Description
`$store`	`?string`	`null`	Cache store name (e.g., `'redis'`, `'memcached'`). Uses default cache store if `null`.

FileStorage

Stores data as JSON files on disk using Laravel’s filesystem.

protected $history = 'file';

Custom configuration

MyAgent

use LarAgent\Context\Drivers\FileStorage;

protected function defaultStorageDrivers(): array
{
    return [
        // Use default disk and folder
        new FileStorage(),
        
        // Use specific disk
        new FileStorage('local'),
        
        // Use specific disk and custom folder
        new FileStorage('s3', 'agent_storage'),
    ];
}

Constructor arguments:

Parameter	Type	Default	Description
`$disk`	`?string`	`null`	Storage disk name. Uses `config('filesystems.default')` if `null`.
`$folder`	`string`	`'laragent_storage'`	Folder path within the disk where files are stored.

EloquentStorage

Stores each item as a separate database row. Best for applications that need to query individual messages or require advanced database features.

# Publish and run migration
php artisan la:publish eloquent-storage
php artisan migrate

protected $history = 'database';

Example here uses historyStorageDrivers instead of defaultStorageDrivers to show chat history specific laravel model override.

Custom configuration

MyAgent

use LarAgent\Context\Drivers\EloquentStorage;

protected function historyStorageDrivers(): string|array
{
    // Use default model
    $storage = new EloquentStorage();
    
    // Or use custom model
    $storage = new EloquentStorage(\App\Models\ChatMessage::class);
    
    // With custom column names
    $storage = (new EloquentStorage(\App\Models\ChatMessage::class))
        ->setKeyColumn('chat_session_id')
        ->setPositionColumn('order');
    
    return [$storage];
}

Constructor arguments:

Parameter	Type	Default	Description
`$model`	`?string`	`null`	Eloquent model class name. Defaults to `LaragentMessage::class`.

Additional methods:

Method	Description
`setKeyColumn(string $column)`	Column for session identifier
`setPositionColumn(string $column)`	Column for item ordering

Custom model example

<?php

namespace App\Models;

use LarAgent\Context\Models\LaragentMessage;

class ChatMessage extends LaragentMessage
{
    protected $table = 'chat_messages';
    
    protected $fillable = [
        'session_key',
        'position',
        'role',
        'content',
        'message_uuid',
        'message_created',
        'tool_calls',
        'tool_call_id',
        'usage',
        'metadata',
        'extras',
        // Custom fields
        'user_id',
        'agent_name',
    ];
    
    // Add relationships
    public function user()
    {
        return $this->belongsTo(User::class);
    }
    
    // Add scopes
    public function scopeByAgent($query, string $agentName)
    {
        return $query->where('agent_name', $agentName);
    }
}

SimpleEloquentStorage

Stores all data as a JSON blob in a single database row. Simple setup, good for basic use cases.

# Publish and run migration
php artisan la:publish simple-eloquent-storage
php artisan migrate

protected $history = 'database-simple';

Custom configuration

MyAgent

use LarAgent\Context\Drivers\SimpleEloquentStorage;

protected function defaultStorageDrivers(): array
{
    return [
        // Use default model
        new SimpleEloquentStorage(),
        
        // Or use custom model
        new SimpleEloquentStorage(\App\Models\CustomStorage::class),
    ];
}

Constructor arguments:

Parameter	Type	Default	Description
`$model`	`?string`	`null`	Eloquent model class name. Defaults to `LaragentStorage::class`.

Custom model example

<?php

namespace App\Models;

use LarAgent\Context\Models\LaragentStorage;

class CustomStorage extends LaragentStorage
{
    protected $table = 'my_custom_storage';
    
    protected $fillable = [
        'key',
        'data',
        'user_id', // Additional field
    ];
    
    protected $casts = [
        'data' => 'array',
    ];
    
    public function user()
    {
        return $this->belongsTo(User::class);
    }
}

Selection Guide

Use Case	Recommended Driver(s)
Development/Testing	`in_memory`
Simple web app	`session` or `cache`
Production with Redis	`cache` (redis)
Need to query data	`database` (EloquentStorage)
Simple DB persistence	`database-simple`
High availability	`cache` + `file` (fallback chain)
Serverless/Lambda	`database` or `database-simple`
Long-running processes	`cache` + `database`

Available Drivers

Driver Chain (Fallback Pattern)

InMemoryStorage

SessionStorage

CacheStorage

FileStorage

EloquentStorage

SimpleEloquentStorage

Selection Guide

Next Steps

Chat History

Usage Tracking

​Available Drivers

​Driver Chain (Fallback Pattern)

​InMemoryStorage

​SessionStorage

​CacheStorage

​FileStorage

​EloquentStorage

​SimpleEloquentStorage

​Selection Guide

​Next Steps

Chat History

Usage Tracking

Available Drivers

Driver Chain (Fallback Pattern)

InMemoryStorage

SessionStorage

CacheStorage

FileStorage

EloquentStorage

SimpleEloquentStorage

Selection Guide

Next Steps