Configure retention bounds

Retention controls how long Tale keeps each category of data. Operators set the allowed bounds; organization admins enable categories and choose a duration within those bounds. A shorter duration can delete existing history, so review its effect before applying it.

Understand bounds and policy

Two files under TALE_CONFIG_DIR/<orgSlug>/governance/ have different jobs:

The organization gets its own files when it is created. A change to one organization’s file does not change another organization’s policy. There is no fallback to a default organization when an organization’s bounds file is missing.

Each category has min, max, default and unit. Raising min requires data to be kept longer; lowering max limits how long it may be kept. Neither value enables cleanup by itself. The applied policy determines whether the category is enabled.

Edit the organization’s bounds

Start from the organization’s existing complete file. Preserve categories you are not changing. This fragment shows the shape of one category, rather than a replacement for the whole file:

chatHistory:
  min: 30
  max: 730
  default: 90
  unit: days

Most categories use days; userTempHours and agentTempHours use hours. The token-usage category is named usageLedger. Use the category identifiers already present in the file so validation can catch mistakes.

Environment overrides are declared explicitly by the file’s root _metadata.envNames, with an optional _metadata.envPrefix. The bundled file maps TALE_RETENTION_AUDIT_MIN to auditLog.min, for example. A minimum override can only raise the floor; a maximum override can only lower the ceiling. Restart the backend processes after changing their environment.

Review and apply a change

After editing bounds, ask the organization admin to review the proposed change in Policies and limits. Cleanup uses the applied bounds snapshot; an operator’s file edit alone does not silently apply new bounds.

Review enabled categories, the old and new durations, and any grace period before applying. A value such as auditLogRetentionDays: 730 is a chosen duration, while auditLog.min: 365 is a lower bound. Keep those meanings separate when reviewing a diff.

Understand the cleanup result

The backend worker runs scheduled cleanup per organization. Threads, documents, contacts and external conversations have lifecycle handling; row-level categories can be deleted directly after their applicable retention and grace period. Do not assume that every deleted record appears in Trash.

Each run deletes a limited number of records per category and organization: up to 50,000 chat filter events, and batches of up to 1,000 records for every other category. A larger backlog, such as a long history when a category is first enabled, takes several daily runs to clear.

Audit retention is also organization-scoped. It removes the oldest eligible prefix of that organization’s audit chain, stopping when a held row must remain. One tenant’s shorter window does not shorten another tenant’s history.

Each run is recorded in the organization’s audit log as system events in the data category. It begins with Retention run started, adds one event for each category that deleted records, carrying the number removed rather than one event per record, and ends with Retention run completed. A run that stops on an error, or keeps due records because their deletion failed, ends with Retention run failed instead; the next scheduled run retries those records. All events of one run name the same retention run as their target, and a run that finds nothing to delete still records its start and end.

TALE_RETENTION_DISABLED=true pauses scheduled retention cleanup for an operator-controlled maintenance window. It does not restore deleted data or disable other deletion paths. Record when you enable it and remove it when the maintenance is complete.

Preserve held data

Legal holds override retention for their supported scope. An organization-wide hold protects the organization; narrower holds protect the matching entities or custodians. Review the legal hold workflow before changing a policy that affects held data.

A hold is not a backup. Once deletion has completed outside a hold, increasing the retention duration cannot recover the data; recovery depends on a retained backup and its matching deployment state.