ModelScribe Audit Log Retention Policy Configuration

Audit logs grow without bound unless you have a deliberate strategy for pruning them. ModelScribe’s database driver ships with three retention modes that cover the most common operational needs: keep everything forever, discard records older than a configurable number of days, or maintain a fixed-size rolling window of the most recent records per table. Retention is declared in config/model-scribe.php and enforced on-demand when you run model-scribe:prune.

Retention modes

Permanent
Days
Rotating

The default mode. ModelScribe never deletes records automatically — every audit entry is kept indefinitely. Use this when your compliance or legal requirements mandate a full immutable history, or when you manage archival and deletion outside of ModelScribe.

// config/model-scribe.php

'drivers' => [
    'database' => [
        'driver' => 'database',
        'table'  => 'model_scribe_logs',

        'retention' => [
            'type' => 'permanent',
        ],
    ],
],

Running model-scribe:prune while type is 'permanent' is a safe no-op — it returns 0 deleted records and touches no rows.

Deletes all records whose created_at timestamp is older than days days when model-scribe:prune runs. This is the most common choice for applications that need a rolling compliance window (e.g. 90-day GDPR retention, 1-year SOC 2 retention).

// config/model-scribe.php

'drivers' => [
    'database' => [
        'driver' => 'database',
        'table'  => 'model_scribe_logs',

        'retention' => [
            'type' => env('MODEL_SCRIBE_RETENTION', 'days'),
            'days' => (int) env('MODEL_SCRIBE_RETENTION_DAYS', 90),
        ],
    ],
],

Environment variables:

Variable	Purpose	Default
`MODEL_SCRIBE_RETENTION`	Sets the `type`	`'permanent'`
`MODEL_SCRIBE_RETENTION_DAYS`	Number of days to retain	`90`

Set MODEL_SCRIBE_RETENTION=days and MODEL_SCRIBE_RETENTION_DAYS=365 in your .env to keep one year of history, for example.

Keeps only the latest keep records per table, deleting everything older. This is ideal for high-frequency models — such as a heartbeat or sync-status model — where you care about the recent trail but not the full history.

// config/model-scribe.php

'drivers' => [
    'database' => [
        'driver' => 'database',
        'table'  => 'model_scribe_logs',

        'retention' => [
            'type' => env('MODEL_SCRIBE_RETENTION', 'rotating'),
            'keep' => (int) env('MODEL_SCRIBE_RETENTION_KEEP', 500),
        ],
    ],
],

Environment variables:

Variable	Purpose	Default
`MODEL_SCRIBE_RETENTION`	Sets the `type`	`'permanent'`
`MODEL_SCRIBE_RETENTION_KEEP`	Number of records to retain	`500`

How it works: When pruning, ModelScribe queries the table ordered by id DESC, skips the first keep rows, and reads the id of the next row. Every record with an id less than or equal to that cutoff is then deleted in a single DELETE statement. If the table contains fewer than keep records, nothing is deleted.

Retention is enforced at prune-time

ModelScribe does not delete records on insert. Entries accumulate in the database as they are written, and the configured policy is only enforced when you explicitly trigger a prune. This means your tables may grow beyond the retention threshold between prune runs — plan your schedule accordingly. Run the prune command manually at any time:

php artisan model-scribe:prune

# Prune a specific driver only
php artisan model-scribe:prune --driver=database

Schedule the prune command in routes/console.php so it runs automatically. Daily is a sensible default for most applications:

use Illuminate\Support\Facades\Schedule;

Schedule::command('model-scribe:prune')->daily();

For very high-write tables with rotating retention you may want to prune more frequently — for example ->hourly() — to keep table size tightly bounded.

The file driver’s prune() method is intentionally a no-op and always returns 0. Log file rotation for the file driver is handled entirely by Laravel’s built-in logging system. Configure it in config/logging.php using the daily channel’s days option or whichever channel you have pointed MODEL_SCRIBE_LOG_CHANNEL at.

The rotating retention mode counts records per table, not per subject model. If a table is shared by multiple model types — for instance, several models all using the default model_scribe_logs table — the keep limit applies to the combined total across all of them. A single high-frequency model can therefore push older entries for other models out of the window ahead of schedule. Use named stores to give each model type its own table before applying rotating retention.

Getting Started

Core Concepts

Usage

Configuration

Maintenance

ModelScribe Audit Log Retention Policy Configuration

Retention modes

Retention is enforced at prune-time

​Retention modes

​Retention is enforced at prune-time

Retention modes

Retention is enforced at prune-time