# How to Configure Recording Retention Based on Detected Objects in Frigate

> Configure Frigate recording retention for detected objects. Set mode to active_objects and specify days to save only relevant footage, optimizing storage.

- Repository: [Blake Blackshear/frigate](https://github.com/blakeblackshear/frigate)
- Tags: how-to-guide
- Published: 2026-05-25

---

**Set `retain.mode` to `active_objects` in your camera's `record` configuration under `detections` or `alerts` to keep only recordings containing detected objects, then specify your retention period with the `days` parameter.**

Frigate is an open-source network video recorder (NVR) with real-time AI object detection that allows you to configure recording retention based on detected objects to optimize storage usage. By leveraging the `active_objects` retain mode defined in [`frigate/config/camera/record.py`](https://github.com/blakeblackshear/frigate/blob/main/frigate/config/camera/record.py), you ensure the system preserves only video segments containing verified detections rather than continuous footage. This article explains how to implement this retention policy using the configuration schema and processing logic from the Frigate source code.

## Understanding Retention Modes

The retention behavior is controlled by the `RetainModeEnum` defined in [`frigate/config/camera/record.py`](https://github.com/blakeblackshear/frigate/blob/main/frigate/config/camera/record.py) (lines 32-36), which supports three distinct modes:

- **all**: Retains every recorded segment regardless of content
- **motion**: Retains only segments containing motion activity
- **active_objects**: Retains only segments containing detected objects (alerts or detections)

When `active_objects` is selected, Frigate evaluates each segment using `ObjectProcessing.should_retain_recording()` (lines 64-82 in [`frigate/track/object_processing.py`](https://github.com/blakeblackshear/frigate/blob/main/frigate/track/object_processing.py)). This method returns `True` only when the object is not a false positive and has an assigned severity level, ensuring you retain only meaningful detection events.

## Configuration Steps

To configure recording retention based on detected objects:

1. **Enable recording** by setting `record.enabled: true` for your camera.
2. **Select event types** to configure under `detections` or `alerts` (or both).
3. **Set the retain mode** to `active_objects` within the `retain` block.
4. **Define the retention period** using the `days` parameter to specify how long to keep matching segments.
5. **Disable unnecessary recording types** (like continuous) by setting their `days` value to `0`.

## YAML Configuration Example

Here is a complete example showing how to retain recordings only when objects are detected:

```yaml
cameras:
  front_yard:
    record:
      enabled: true
      continuous:
        days: 0
      motion:
        days: 2
      detections:
        retain:
          days: 7
          mode: active_objects
      alerts:
        retain:
          days: 30
          mode: active_objects

```

In this configuration, `detections.retain.mode: active_objects` ensures that only segments containing detected objects are preserved for seven days, while the `alerts` retention extends critical events to 30 days. The `continuous` recording is disabled by setting `days: 0`, ensuring no footage is retained without object activity.

## How the Retention Logic Works Internally

The retention system operates through several key components in the Frigate codebase.

**Configuration Schema**

The `ReviewRetainConfig` class (lines 45-49 in [`frigate/config/camera/record.py`](https://github.com/blakeblackshear/frigate/blob/main/frigate/config/camera/record.py)) defines the `mode` parameter, while `RecordRetainConfig` (lines 23-50) structures the overall retention settings. These classes validate the `RetainModeEnum` values during startup.

**Processing Pipeline**

When objects are tracked, `ObjectProcessing.should_retain_recording()` evaluates whether to mark a segment for retention. According to the source code (lines 64-82 in [`frigate/track/object_processing.py`](https://github.com/blakeblackshear/frigate/blob/main/frigate/track/object_processing.py)), this method returns `True` when:
- The camera has recording enabled
- The object is not a false positive
- The object has moved
- The object has a maximum severity assigned (alert or detection)

**Cleanup Execution**

The `record/maintainer` service applies retention policies through `should_discard_segment()` (lines 61-71 in [`frigate/record/maintainer.py`](https://github.com/blakeblackshear/frigate/blob/main/frigate/record/maintainer.py)), while the `record/cleanup` module (lines 68-72 in [`frigate/record/cleanup.py`](https://github.com/blakeblackshear/frigate/blob/main/frigate/record/cleanup.py)) executes the actual deletion of expired recordings based on the configured mode and day limits.

## Summary

- **Set `retain.mode` to `active_objects`** in your camera configuration to keep only recordings with detected objects
- **Configure `days`** under `detections` or `alerts` to control how long object-triggered segments are stored
- **Reference `RetainModeEnum`** in [`frigate/config/camera/record.py`](https://github.com/blakeblackshear/frigate/blob/main/frigate/config/camera/record.py) for valid retention mode values
- **Understand the processing logic** in `ObjectProcessing.should_retain_recording()` to know when segments are marked for retention
- **Disable continuous recording** by setting `continuous.days: 0` to conserve storage space

## Frequently Asked Questions

### What is the difference between active_objects and motion retention modes?

The `motion` mode retains any recording segment containing detected motion regardless of whether an object was identified, while `active_objects` specifically filters for segments containing verified object detections or alerts. According to the implementation in [`frigate/track/object_processing.py`](https://github.com/blakeblackshear/frigate/blob/main/frigate/track/object_processing.py), `active_objects` requires a valid object with severity that passes the `should_retain_recording()` check, ensuring you only keep footage with meaningful AI-detected activity.

### How do I completely disable continuous recording while keeping detection-based retention?

Set `record.continuous.days: 0` in your camera configuration. This disables retention for continuous footage while allowing you to maintain separate retention policies for `detections` and `alerts` with `mode: active_objects`. The `days: 0` value signals the cleanup workers in [`frigate/record/cleanup.py`](https://github.com/blakeblackshear/frigate/blob/main/frigate/record/cleanup.py) to immediately purge continuous segments while preserving object-triggered recordings.

### Where does Frigate store the retention configuration schema?

The configuration schema is defined in [`frigate/config/camera/record.py`](https://github.com/blakeblackshear/frigate/blob/main/frigate/config/camera/record.py), which contains the `RecordRetainConfig` and `ReviewRetainConfig` classes (lines 23-50). This file defines the `RetainModeEnum` with values `all`, `motion`, and `active_objects` (lines 32-36), and validates the `days` and `mode` parameters during the configuration loading phase.

### Can I set different retention periods for different object types?

No, retention periods in Frigate are configured per event type (`detections`, `alerts`, `motion`, `continuous`) rather than per object class. However, you can achieve similar filtering by configuring zones and required zones for specific objects, as only objects entering defined camera zones trigger retention events when using `active_objects` mode. The retention decision occurs at the segment level based on whether any qualifying object was present.