> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laragent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Configure default storage drivers for agent context persistence

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

```php theme={null}
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:

```php theme={null}
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:

<Tabs>
  <Tab title="Property">
    ```php theme={null}
    class SupportAgent extends Agent
    {
        // Default for all storages
        protected $storage = [CacheStorage::class];
        
        // Override for chat history only
        protected $history = 'database';
    }
    ```
  </Tab>

  <Tab title="Method Override">
    ```php theme={null}
    class SupportAgent extends Agent
    {
        protected $storage = [CacheStorage::class];
        
        // Override for chat history with custom model
        protected function historyStorageDrivers(): string|array
        {
            return [
                new EloquentStorage(\App\Models\ChatMessage::class),
            ];
        }
    }
    ```
  </Tab>
</Tabs>

<Note>
  For chat history-specific configuration like truncation strategies, metadata storage, and force read/save flags, see the [Chat History](/v1/context/history) documentation.
</Note>

### Usage Storage

Use `$usageStorage` property or `usageStorageDrivers()` method:

<Tabs>
  <Tab title="Property">
    ```php theme={null}
    class SupportAgent extends Agent
    {
        protected $storage = [CacheStorage::class];

        protected $trackUsage = true;
        
        // Override for usage tracking only
        protected $usageStorage = [EloquentStorage::class];
    }
    ```
  </Tab>

  <Tab title="Method Override">
    ```php theme={null}
    class SupportAgent extends Agent
    {
        protected $storage = [CacheStorage::class];

        protected $trackUsage = true;
        
        protected function usageStorageDrivers(): array
        {
            return [
                new EloquentStorage(\App\Models\UsageRecord::class),
            ];
        }
    }
    ```
  </Tab>
</Tabs>

<Note>
  For detailed usage tracking configuration, cost calculation, and custom models, see the [Usage Tracking](/v1/context/usage-tracking) documentation.
</Note>

## String Aliases

Both `$usageStorage` and `$history` properties accept string aliases for convenience:

```php theme={null}
class SupportAgent extends Agent
{
    // Using alias for usage
    protected $usageStorage = 'cache';
    
    // Using alias for history
    protected $history = 'database';
}
```

| Alias                | Driver Class            |
| -------------------- | ----------------------- |
| `'in_memory'`        | `InMemoryStorage`       |
| `'session'`          | `SessionStorage`        |
| `'cache'`            | `CacheStorage`          |
| `'file'` or `'json'` | `FileStorage`           |
| `'database'`         | `EloquentStorage`       |
| `'database-simple'`  | `SimpleEloquentStorage` |

<Note>
  For detailed information about each driver's constructor arguments, custom model examples, and the fallback pattern, see the [Storage Drivers](/v1/context/storage-drivers) reference.
</Note>

## Configuration Examples

### Simple: Single Driver for Everything

```php theme={null}
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

```php theme={null}
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

```php theme={null}
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

```php theme={null}
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

<Tip>
  Use `$storage` for simple cases and `defaultStorageDrivers()` when you need dynamic logic like environment checks or custom driver instances.
</Tip>

## 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.)

<CardGroup cols={2}>
  <Card title="Custom Storage" icon="box" href="/v1/customization/context/storage">
    Create custom storages with DataModels for type-safe persistence.
  </Card>

  <Card title="Custom Storage Driver" icon="plug" href="/v1/customization/context/storage-driver">
    Build custom storage drivers for specialized backends.
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Storage Drivers" icon="hard-drive" href="/v1/context/storage-drivers">
    Learn about all available storage drivers and their configuration options.
  </Card>

  <Card title="Chat History" icon="comments" href="/v1/context/history">
    Configure chat history storage and truncation strategies.
  </Card>

  <Card title="Usage Tracking" icon="chart-line" href="/v1/context/usage-tracking">
    Track token usage and costs across agent interactions.
  </Card>

  <Card title="Context Overview" icon="layer-group" href="/v1/context/overview">
    Understand the Context and Identity system for storage isolation.
  </Card>
</CardGroup>