Session storage OOM: auto-retention, archiving, and external DB support

[gigimento]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Session storage OOM: auto-retention, archiving, and external DB support

Problem

The OpenCode CLI uses SQLite as its session storage backend. Over time, the database file at ~/.local/share/opencode/opencode.db grows unboundedly. On my system it reached 1.25 GB, causing:

1. OOM crash in OpenCode Desktop (Electron) — the utility process loads the entire DB into memory on startup and V8 heap exhausts. Same crash pattern affects any Electron app using the same SQLite DB (Discord, Antigravity, etc.).
2. Slow queries — SELECT on the part table (52k+ rows, 152 MB of base64-encoded attachments) times out.
3. No built-in cleanup — there is no retention policy, no size cap, no archiving mechanism.

Root Cause

• The part table stores base64-encoded file attachments (PDFs, images) inline with session data.
• A single oversized session (263 MB of PDFs) caused V8 heap exhaustion in the Electron utility process (previous occurrence, May 31 2026).
• Repeated occurrence: 1.25 GB DB, ~90 MB concentrated in just 10 sessions.
• Global NODE_OPTIONS=--max-old-space-size=4096 does NOT help — Electron sidecar/utility processes ignore it.

Suggested Features

1. Automatic Retention Policy

Add configurable retention settings in opencode.json:

{
  "session": {
    "maxSizeMB": 200,
    "maxAgeDays": 30,
    "maxSessions": 100
  }
}

On session write (or on startup), if any threshold is exceeded, the oldest sessions (by time_created) should be evicted, with a warning logged.

2. Session Archiving Before Eviction

Before deleting old sessions, export them to a file:

opencode session archive --output ~/opencode-archive-2026.json

Format: JSON array of session objects with messages and metadata. This gives users a safety net before automatic cleanup runs.

3. External Database Backend

Allow configuring an external database (PostgreSQL, MySQL, SQL Server) as the primary storage backend instead of SQLite:

{
  "session": {
    "storage": "sqlserver",
    "connectionString": "Server=localhost;Database=opencode;Trusted_Connection=yes"
  }
}

This would solve the problem at the root — SQLite is convenient but not appropriate for long-running heavy usage with large attachments.

4. Size Warning Notifications

Emit a warning when the database crosses thresholds:

Warning: OpenCode database is 512 MB. Consider archiving or enabling auto-retention.

Thresholds: 100 MB, 500 MB, 1 GB.

5. Session Delete Should VACUUM

opencode session delete deletes rows but does not reclaim disk space. It should either:

• Run VACUUM automatically after bulk deletes, OR
• Enable SQLite auto_vacuum=INCREMENTAL, OR
• At minimum document that users should run opencode db "VACUUM" after cleanup.

Workaround (for now)

For anyone hitting this before the fix ships, here's what I did:

1. Export sessions to an external DB (I used SQL Server via a Python script)
2. Delete old/large sessions: opencode session delete <session_id>
3. Reclaim space: opencode db "VACUUM"
4. Unset NODE_OPTIONS if set globally (causes Electron issues)
5. Set up a cron/scheduled task to auto-export and clean sessions older than 14 days

But this should really be built-in.

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• [FEATURE]: Session Lifecycle Management — unified storage reclamation, auto-archival, and child session cleanup #16101: [FEATURE]: Session Lifecycle Management — covers the same unbounded SQLite growth problem, auto-archival, VACUUM after deletes, retention policy, and session management tooling
• [FEATURE]: Retention Config #32630: [FEATURE]: Retention Config — directly requests auto-deletion of older sessions to address the same growing opencode.db problem
• [FEATURE]: Support more DBMS' for OpenCode state storage #14212: [FEATURE]: Support more DBMS' for OpenCode state storage — covers the external database backend request (PostgreSQL/etc. as primary storage)

Before proceeding, please check whether your request is already covered by these issues. If it is, consider adding a comment there with your specific data points (the 1.25 GB DB, OOM crash details) rather than opening a new issue.

[gigimento]

This issue might be a duplicate of existing issues. Please check:

• [FEATURE]: Session Lifecycle Management — unified storage reclamation, auto-archival, and child session cleanup #16101: [FEATURE]: Session Lifecycle Management — covers the same unbounded SQLite growth problem, auto-archival, VACUUM after deletes, retention policy, and session management tooling
• [FEATURE]: Retention Config #32630: [FEATURE]: Retention Config — directly requests auto-deletion of older sessions to address the same growing opencode.db problem
• [FEATURE]: Support more DBMS' for OpenCode state storage #14212: [FEATURE]: Support more DBMS' for OpenCode state storage — covers the external database backend request (PostgreSQL/etc. as primary storage)

Before proceeding, please check whether your request is already covered by these issues. If it is, consider adding a comment there with your specific data points (the 1.25 GB DB, OOM crash details) rather than opening a new issue.

Thank you for pointing out, I obviously searched with the wrong keywords...