# Convex Retention

> Manage Convex table retention policies, TTL fields, cleanup crons, and schema classification for ClawHub.

- Skill: `openclaw/convex-retention` (Agent Skill)
- Install (CLI): `npx skillmds@latest add openclaw/convex-retention`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openclaw/convex-retention/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics, Coding & Dev Tools, SQL & Databases
- Tags: Cleanup, Convex, Cron, Retention Policy, Schema, Testing, Ttl, Vitest
- Author: OpenClaw (https://skillmd.com/u/openclaw)
- Updated: 2026-07-06
- Page: https://skillmd.com/skills/openclaw/convex-retention

---


# Convex Retention

## Overview

ClawHub retention is code-owned. Every current Convex table must be classified in
`convex/lib/retentionPolicy.ts`, and ephemeral tables need an indexed, bounded cleanup path unless
their lifecycle is handled by usage-time validation or a documented component.

## Checklist

- Read `convex/_generated/ai/guidelines.md` and the Convex ops rules in `AGENTS.md` first.
- Add every new schema table to `RETENTION_POLICIES`; the `Record<TableNames, RetentionPolicy>` type
  is the enforcement gate.
- For ephemeral tables, prefer an explicit expiration field plus index, then prune with `.withIndex()`
  and `.take(...)`.
- For new generic TTL tables, prefer `expirationTime` to match Convex Auth. Keep existing `expiresAt`,
  `dayStart`, and `processedAt` fields unless that table already needs a real migration.
- Use `RETENTION_STANDARD_BATCH_SIZE` for ordinary retention jobs. Keep incident-tested special cases,
  such as `skillStatEvents`, on their documented caps.
- Cron jobs should schedule bounded cleanup entrypoints only. Large one-off production migrations or
  destructive backfills still start with `convex-migration-helper`.
- Do not bulk-clear active auth state. Expired `authSessions` and `authRefreshTokens` are pruned by
  `convex/retention.ts`.

## Verification

- Add or update focused tests for policy classification and cleanup behavior.
- Run the focused Vitest slice for touched cleanup modules.
- Run `bunx convex codegen` after schema/API changes.
- Run a real Convex runtime check such as `bunx convex dev --once --typecheck=disable`.