OpenClaw Bounds Trajectory Runtime Events After a 1.7 GiB Production Database Case
A merged main-branch fix adds bounded retention for trajectory runtime events after live rows consumed 85% of one long-lived agent database.
OpenClaw merged bounded retention for trajectory_runtime_events into main on 27 July after a production deployment showed how badly the table could grow on a long-lived host.
The upstream case measured 1,714 MiB of runtime events inside a 2,022 MiB agent database: 58,613 live rows averaging roughly 30 KiB each. Because the space belonged to live records, SQLite reported no reclaimable free pages. Running VACUUM alone could not solve it.
This is an operational data-lifecycle fix, not a cosmetic database optimization. Operators using trajectory capture should check growth now and adopt a containing build through a controlled upgrade. The merge is on main; the pull request does not establish that a particular published package already includes it.
Operator decision
| Condition | What to do |
|---|---|
| Agent databases grow steadily on a long-lived host | Measure the database family and available disk, then determine whether trajectory runtime events are the driver |
| Disk headroom is already tight | Stop nonessential growth, take a consistent backup and plan the containing update before the filesystem becomes the outage |
| You build from source | Use commit c682bbcf903b46d7f77d2d30bf214288cd1d3dc4 or later, then verify retention under representative workloads |
| You rely on trajectories for audit or incident review | Confirm the new retention behaviour meets evidence requirements before rollout; export required records through supported tooling |
| You see a large file after old rows are removed | Treat logical retention and physical compaction as separate tasks; use supported maintenance only after backup and with writer coordination |
Do not delete SQLite rows or sidecar files by hand. The state database may be live, and a large WAL or database file is not proof that arbitrary file removal is safe.
Why VACUUM was not the answer
SQLite can reclaim unused pages, but it cannot discard rows the application still considers live. In the reported case, runtime-event data occupied 85% of the agent database and free-page accounting showed nothing reclaimable. The retention contract had to change first.
That distinction matters during incident response:
- logical growth is data still retained by OpenClaw;
- free pages are deleted data SQLite may be able to reuse or compact; and
- WAL growth is a separate journal-maintenance concern.
A generic “vacuum the database” runbook conflates all three and can waste downtime without reducing the live dataset.
Safe rollout sequence
- Identify the containing build. Match PR #114250 or commit
c682bbcto the release or source revision you intend to deploy. - Measure before changing anything. Record database and sidecar sizes, disk headroom, host uptime and whether trajectory-heavy workloads correlate with growth.
- Take a consistent backup. Preserve the complete SQLite family through OpenClaw’s supported backup or snapshot path; copying only the main file while writers are active is not a coherent backup.
- Protect required evidence. Export trajectories that must survive the retention change using supported tooling, and store them under your normal access and retention controls.
- Upgrade in staging first. Exercise long and tool-heavy runs, then verify that event counts and disk use become bounded without breaking trajectory export or incident review.
- Deploy with monitoring. Alert on absolute database size, growth rate and remaining filesystem capacity rather than waiting for a full disk.
- Compact only if justified. After retention has removed old live data, follow supported SQLite maintenance with writers coordinated. Do not assume logical deletion immediately shrinks the file on disk.
Evidence and limits
PR #114250 is labelled as a session-state compatibility risk and describes two independent causes of unbounded retention. The compact official record available to this editorial run confirms the production measurements and the landed retention fix, but it truncates the detailed retention algorithm and defaults.
OpenClaw Academy therefore does not prescribe an invented row cap, age window or configuration key. We also did not open the affected production database or independently load-test the patch. Web retrieval of the full PR was unavailable during verification; the measurements and fix behaviour above are attributed to the official merged PR record and commit.
Interpretation: deployments with compliance retention requirements should not assume the new application default is automatically their policy. Validate what remains exportable, document any external archive, and avoid extending live operational storage indefinitely merely because evidence might someday be useful.
Bottom line
A trajectory table consuming 1.7 GiB and 85% of a production agent database is enough evidence that unbounded runtime-event retention can become an outage precursor. The fix is now merged on main.
Measure long-lived hosts, preserve required evidence, upgrade to a confirmed containing build, and verify both logical retention and physical disk behaviour. VACUUM is maintenance; it is not a retention policy.
THE RECEIPTS
Claims should survive the click.
Primary links used for this article are listed openly. If the evidence changes, the verification date changes with it.THE OPERATOR BRIEF