Media store#

The media store is a file-based data store for media assets (images and video) used by media-understanding and related features.

Characteristics#

Kind: file
Assets: image/video assets
Cleanup: TTL-based (max 7 days / 168 hours)

The store holds assets referenced during media understanding, generation, and related runtime flows. Assets are persisted on disk and cleaned up automatically to bound storage growth.

TTL and cleanup#

The hard maximum TTL is 7 days, defined as MAX_MEDIA_TTL_HOURS = 24 * 7.

Any raw TTL hours value passed to resolveMediaCleanupTtlMs(ttlHoursRaw) is clamped to the closed interval [1, 168]. Values outside this range are adjusted to the nearest bound before use.

Periodic cleanup is driven by gateway maintenance timers. These timers start with a default interval of 1 hour once the gateway reaches the ready state. Each run invokes cleanOldMedia(ttlMs, { recursive: true, pruneEmptyDirs: true }) to walk the store, remove assets whose age exceeds the current TTL, and delete any directories that become empty as a result.

Cleanup is best-effort and runs in the background; it does not block request or agent paths.

Configuration#

Cleanup behavior is controlled by the mediaCleanupTtlMs value supplied to gateway server maintenance. When this value is present, the maintenance subsystem starts the periodic timer using the resolved TTL in milliseconds. The effective TTL is always clamped as described above.

Integration#

The media store is consumed internally by:

media-understanding
media-runtime
media-mime
generation runtimes

These components write assets into the store and later read them for processing or delivery.

SDK exposure#

Plugins access the media store and its companion runtimes through the documented SDK barrels:

openclaw/plugin-sdk/media-store
openclaw/plugin-sdk/media-runtime
openclaw/plugin-sdk/media-understanding
openclaw/plugin-sdk/media-understanding-runtime
openclaw/plugin-sdk/media-generation-runtime

Import from these paths to obtain the runtime handles, media utilities, and understanding/generation contracts needed to participate in media flows. See the Plugin SDK for registration patterns and the full set of narrow contracts.

Session transcripts that reference media assets stored here are described in Sessions and transcripts.