Introduction

DeepSeek Harness (DSH) stores session logs and memory data. If session.jsonl.zstd is accidentally deleted, overwritten, or corrupted, standard file recovery often yields only fragmented content, making it difficult to directly restore a session. The approach of dsh-session-recovery is to read directly from the raw disk, locate identifiable zstd frames and SQLite data, and then organize the recoverable content into DSH-verifiable, usable session files.

What is it

dsh-session-recovery is a DSH recovery tool, hosted at https://github.com/Coprexist/dsh-session-recovery, under the MIT license.

It primarily performs two tasks:

  1. Recover DSH session file session.jsonl.zstd from a raw disk.
  2. Recover memory database memory.db from a raw disk.

The repository consists of a set of recovery scripts and manual recovery instructions, but can also be installed as a dsh plugin into the web UI, providing the /session-repair command.

Core Features

Recovering memory.db

The script locates memory.db on the raw disk based on the SQLite ‘SQLite format 3’ header, exports the corresponding data window, and uses SQLite’s .recover mechanism to salvage readable rows. It skips corrupted pages, attempting to preserve as much readable data as possible.

Recovering Session Logs

The script scans the raw disk for the zstd frame magic 0xFD2FB528, clusters frames by disk offset, splits different sessions at turn resets, and finally rebuilds the official session.jsonl.zstd format.

Repairing Rebuilt Sessions

The rebuilt logs may not pass DSH verification directly. The tool automatically fixes the following issues:

  • Reorganize seq to make it continuous.
  • Deeply repair sourceEventSeqs and messageSeqs.
  • Normalize surfaceOp.

If the session still cannot resume, repair-session.js or the web UI’s /session-repair command replays DSH’s inbox, surface, and wire rules to perform further repair on the file.

Read-only Reading of Raw Disk

The script reads block devices in read-only mode and writes the recovery results to a specified directory. The original disk contents are not modified.

Installation and Usage

If installing as a dsh plugin, add it from the local repository path:

dsh plugin --profile web add file:/path/to/dsh-session-recovery
systemctl restart dsh-web

Note: file:/path/to/dsh-session-recovery is a local path placeholder that needs to be replaced with the actual path.

After installation or replacement of recovery files, dsh-web needs to be restarted.

Typical Usage

The following is the sequential recovery process.

1. Stop Services That Write to the Disk First

Stop services that might continue writing DSH data to avoid state changes during recovery:

systemctl stop dsh-web

2. Recover SQLite Memory

Recover memory.db from the block device:

node scripts/recover-memory.js /dev/<dev> /tmp/recovered/

This step recovers readable SQLite data to the /tmp/recovered/ directory.

3. Scan zstd Session Frames in Raw Disk

Scan the raw disk and write the found zstd session frames to an event stream:

node scripts/scan-zstd.js /dev/<dev> > /tmp/session-events.jsonl

4. Split into Different Sessions

Scan results typically mix multiple sessions. The script splits them by session:

node scripts/split-sessions.js /tmp/session-events.jsonl 2026-08-16T07:05:06Z

5. Rebuild Official Format Session Files

Use scripts/rebuild-session.js to rebuild the official session.jsonl.zstd format. You need to provide information such as input, session ID, creation time, working directory, and output directory:

node scripts/rebuild-session.js \
  --input <input-jsonl> \
  --id <session-id> \
  --created-at <created-at> \
  --cwd <workspace-dir> \
  --out-dir <out-dir>

6. Verify or Repair Rebuilt Sessions

First perform a dry-run to check the repair content:

node scripts/repair-session.js <session.jsonl.zstd> --dry-run

After confirming there are no issues, execute the repair:

node scripts/repair-session.js <session.jsonl.zstd>

After repair, session.jsonl.zstd.repaired files and backup files will be generated. After checking the content of .repaired and the backups, decide whether to replace the original file:

cp <session.jsonl.zstd>.repaired <session.jsonl.zstd>

7. Use /session-repair in Web UI

After installing the plugin, you can execute it in any session:

/session-repair --dry-run

Analyze the current session without writing files.

/session-repair <session-id-or-path>

Execute the repair, defaulting to writing to .repaired files and backups.

/session-repair --apply <id>

Replace the original file after repair. Note: --apply is rejected for a live session running the command itself; it needs to be executed from another session.

Use Cases and Notes

Suitable for the following scenarios:

  1. session.jsonl.zstd is deleted or corrupted, and you need to recover as much readable content as possible.
  2. memory.db is corrupted, and you need to salvage the SQLite data within it.
  3. The rebuilt session cannot resume, and you need to repair it according to DSH rules.

Notes before use:

  1. Requires Node 24+, and depends on node:sqlite and node:zlib.
  2. The script reads block devices in read-only mode and writes recovery files to a user-specified directory; it does not modify the original disk.
  3. The plugin runs with the privileges of the current dsh process; check the source code and license before installing.
  4. Using --apply will overwrite the original session file; check the .repaired file and backups before executing.
  5. After plugin changes or replacement of recovery files, dsh-web should be restarted.

Conclusion

dsh-session-recovery provides a path to read from raw disks, rebuild, and repair DSH sessions and memory. It is suitable for use when standard file recovery is unavailable, but zstd frames or SQLite data can still be found on the block device.

Repository address:

https://github.com/Coprexist/dsh-session-recovery