Rolling Retention

Rolling retention is for repeated cleanup:

• keep a recent slice of history
• remove older content
• run the same rule again later

Start with First Run if you have not yet checked that the tool sees the right account and targets.

Step 1: start with a time window

The simplest rolling-retention rule is:

• keep recent messages
• delete messages older than that

dmd clean --include-ids <id> --keep-within 2w --dry-run

Here, --keep-within 2w keeps messages from the last 2 weeks, measured from when the command runs.

If you omit --include-ids, the run uses the default scope: all eligible channels the tool can see.

Step 2: add --fetch-within for recurring runs

--keep-within decides what is kept. --fetch-within limits how far back the command reads, measured from when the command runs.

That read limit matters on recurring runs. After the first cleanup, you usually do not want every run to fetch the full scoped history again just to confirm old history is already clean.

There is one important constraint: the cleaner can only delete messages it fetched in the current run. So --fetch-within must still reach far enough back to include messages that may have crossed the keep boundary since the previous run.

For a daily job that keeps 2 weeks, the recurring command is:

dmd clean --include-ids <id> --keep-within 2w --fetch-within 2w1d

2w1d means:

• 2w to reach the keep boundary
• 1d to cover the daily interval since the previous run

For other schedules, use:

• keep window
• plus the expected interval between runs
• plus a small optional buffer

Step 3: run the keep-within setup in order

Preview:

dmd clean --include-ids <id> --keep-within 2w --dry-run

First real cleanup:

dmd clean --include-ids <id> --keep-within 2w

Daily recurring command:

dmd clean --include-ids <id> --keep-within 2w --fetch-within 2w1d

The first real cleanup intentionally has no --fetch-within. That lets the tool inspect the full scoped history once and delete old messages that already exist.

Only add the narrower recurring fetch window after that first cleanup has seen enough history.

Step 4: add --keep-last to keep some context

A pure time window can remove all of your messages from a quiet channel. For example, if none of your messages are inside the last 2 weeks, --keep-within 2w has nothing recent to keep.

Use --keep-last when you also want a minimum floor of your recent messages per channel:

dmd clean --include-ids <id> --keep-within 2w --keep-last 20 --dry-run

That means:

• keep messages from the last 2 weeks
• also keep at least the last 20 messages per channel

Step 5: add preserve-cache when --keep-last needs memory

The keep-within-only shape above is stateless. Each recurring run makes decisions only from the messages it fetched in that run.

--preserve-cache adds memory between runs. The cache stores IDs of kept messages so later runs can keep continuity even when the fetch window is short.

This matters most when you combine:

• --keep-last
• limited --fetch-within
• repeated runs

For a daily job that keeps 2 weeks and at least 20 messages, the recurring command can be:

dmd clean --include-ids <id> --keep-within 2w --keep-last 20 --fetch-within 1d --preserve-cache

That works only after the cache has been seeded by an earlier real run that saw enough history.

The setup order is the same: preview first, run once without a narrow fetch window, then add the shorter recurring fetch window.

Preview:

dmd clean --include-ids <id> --keep-within 2w --keep-last 20 --preserve-cache --dry-run

First real cleanup and cache seed:

dmd clean --include-ids <id> --keep-within 2w --keep-last 20 --preserve-cache

Daily recurring command:

dmd clean --include-ids <id> --keep-within 2w --keep-last 20 --fetch-within 1d --preserve-cache

Dry-runs use a separate dry-run cache path, so a preview does not seed the real cache.

See Preserve Cache for the detailed behavior.

When profiles become worth it

If you are reusing the same rolling-retention command repeatedly, that is the point where profiles become useful.

For example, instead of keeping a long command in shell history:

dmd clean --include-ids <id> --keep-within 2w --keep-last 20 --preserve-cache --dry-run

you can save it as a named profile and run:

dmd clean --profile nightly-dms --dry-run

If that is what you want, continue with Recurring Cleanup with Profiles.

Common mistakes

• Adding a narrow --fetch-within before the first real cleanup has inspected enough history.
• Using --keep-last with a limited fetch window but no preserve-cache.
• Expecting --fetch-within to decide what is kept.
• Forgetting that time deltas are measured backwards from when the command runs.
• Forgetting to scope the run with --include-ids when you do not want the default scope.

See also

• Preserve Cache
• Recurring Cleanup with Profiles
• Profiles
• Value Formats