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.

A release can add a category after an organization’s file was created; automationVersions is one. Until the organization’s file lists it, Tale takes that category’s bounds, and its environment bindings, from the bundled file. The bundled file maps TALE_RETENTION_VERSIONS_MIN, TALE_RETENTION_VERSIONS_MAX and TALE_RETENTION_VERSIONS_DEFAULT to it. Add the category to the organization’s own file to give it its own bounds; once the file has the category, the file wins. As for any change of bounds, the organization’s admin sees the proposal in Policies & Limits and applies it before cleanup enforces the category.

Two floors are fixed: auditLog.min cannot be lower than 180 days, and loginAttempt.min cannot be lower than 90 days. Tale does not load a file that undercuts either. Until you correct it, the organization’s Retention policy shows no allowed ranges and cannot be saved, and the backend log names both floors. Scheduled cleanup keeps using the bounds applied last.

The bundled file lets an organization keep audit logs for 180 to 3650 days. Upgrading Tale does not rewrite an organization’s file, so an organization created by an earlier release can still have auditLog.min: 365. Lower that value to allow a shorter audit retention, or raise it when a regulation or contract requires a longer audit history.

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: 180 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.

automationVersions removes saved automation versions that are older than its period. It is off until an admin enables it, and the bundled bounds allow 90 to 3650 days. Whatever the period, the cleanup keeps what the product still reads: the live version, the versions of the last ten deployments, every version a run used, the newest twenty versions, the versions those were restored from or based on, and versions saved by a person under a legal hold. A version number is never reused. The cleanup writes one audit event for each automation that lost versions, naming them.

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.