Dsh Session Vacuum

Introduction¶

DSH session logs keep growing as the number of conversation turns increases, eventually causing slow loading or even OOM. The root cause is that streaming fragments (such as assistant/chunk, text-chunks, etc.) are written but never read. This write-only, unread data accumulates continuously, causing a single session file to grow rapidly to the GB level and consume a large amount of memory during loading.

The dsh-session-vacuum plugin runs when DSH starts and deletes these dead fragments directly on disk, ensuring a smaller file size the next time the session is loaded.

What It Is¶

This is a DSH plugin for cleaning up dead streaming fragments in DSH session logs at startup. It is maintained by mili1360 and belongs to the memory-optimization category. Its core purpose is to prevent session files from swelling to the GB level when long sessions are loaded, thereby resolving slow loading and out-of-memory issues caused by oversized logs.

Core Capabilities¶

1. Deletes fragment lines on disk: It directly removes useless streaming fragment data from log files, rather than merely hiding it.
2. Atomic replacement and backup: It uses .orig as the only backup file and replaces the original log file through an atomic rename operation, ensuring write safety.
3. Pre-write self-check: Before writing the cleaned log, it validates whether the data structure satisfies DSH’s loading contract (such as contiguous seq values and no dangling references); if validation fails, the original file is retained.
4. Live mode by default: After a fresh installation, it is enabled by default and automatically prunes idle logs without requiring configuration.
5. Time window protection: By default, it respects the liveWindowMs setting (default is 2 minutes) and does not touch session logs that are currently being written to, avoiding interference with real-time interaction.

Installation and Configuration¶

The plugin is integrated through the dsh block. Before installing, make sure your Node.js version is at least 22.15.0.

Enable the plugin in dsh.config.yml or the corresponding plugin configuration:

dsh:
  bundle:
    patch: ./cordis.patch.yml

Configuration options:
- enabled: false: Disables the plugin.
- dryRun: true: Preview mode. It records the operations that would be performed but does not actually write to files, used to observe the cleanup effect.

Typical Usage¶

1. Observe the cleanup effect: First set dryRun: true, review the number of lines to be deleted and file size changes, and disable preview mode after confirming there are no issues.
2. Disable the plugin: If you need to completely turn it off, set enabled: false.
3. Recover from OOM: For sessions that have already caused OOM due to large logs, clean them up with this plugin and reload; this can significantly reduce memory usage.

Notes¶

1. Destructive by design: The plugin permanently deletes fragment lines on disk. .orig is the only backup file and is not automatically deleted.
2. Does not touch active sessions: The plugin does not modify session logs that have been written to within the last 2 minutes.
3. Does not shrink already loaded sessions: This plugin only processes files on disk. If a session has already been loaded into memory by the DSH process, it will not reduce the current process’s memory usage; it can only reduce the cost of the “next” load.

Conclusion¶

dsh-session-vacuum is an effective tool for addressing DSH long-session bloat. By cleaning up dead data on disk at startup, it can reduce session files from the GB level to the MB level, restore loading speed, and avoid OOM. Be sure to be aware of its destructive design when using it, and fully leverage the dryRun mode for validation.

• GitHub Repository