dsh-dream

DSH "Dream" plugin — scheduled background memory consolidation for DeepSeek Harness, inspired by OpenClaw's Dreaming.

While a root agent is idle, the plugin periodically runs a dream pass in a background subagent (not in the main conversation): it reviews recent session work and distills it into long-term memory files under <workspace>/memory (MEMORY.md + dreams.md). No manual triggering needed, nothing pollutes the chat.

Features

• Background execution — dreams run in a fresh background subagent (mode: subagent, default). The dream conversation is separate, so nothing appears in the main session; the child gets a compact digest of recent messages + the memory files, keeping token use low.
• Low frequency — intervalSeconds defaults to 21600 (6 h); the event watermark counts real user messages only (the plugin's own activity is excluded), so dreams never self-trigger in a loop.
• Non-intrusive — never preempts a busy session; skips when nothing new happened.
• Memory file management — auto-creates memory/ with seed files; archives MEMORY.md to memory/archive/ and rebuilds it when it exceeds maxMemoryBytes.
• State persistence — per-session dream progress (count, last time, user-message watermark) is saved in memory/.dream-<sessionId>.json and survives restarts.
• Two agent tools:
  • dream_status — view dream state (mode, interval, last/next dream time, user-event watermark, memory directory).
  • dream_run — request a dream pass immediately (runs when idle, queues while busy).

Installation (web profile)

Option A: npm registry (recommended)

In the DSH web profile directory (Windows default: C:\Users\<you>\.dsh\profiles\web):

npm i dsh-dream

Option B: local link (development / self-hosted)

Place the package at <DSH_HOME>\plugins\dsh-dream, then add to the profile's package.json dependencies:

"dsh-dream": "link:<DSH_HOME>/plugins/dsh-dream"

Enable the plugin

Add an insert entry in the profile's cordis.patch.yml:

- insert:
    - id: dream
      name: dsh-dream
      config:
        intervalSeconds: 21600   # check every 6 hours (min 300)
        minNewEvents: 3           # dream only when >= 3 new user messages
        maxMemoryBytes: 20000     # archive MEMORY.md when it exceeds 20 KB
        memoryDir: "F:/your-workspace/memory"  # recommended: set explicitly
        mode: "subagent"          # subagent (default, background) | followup (legacy, visible)
        subagentProvider: "spawn" # "spawn" = fresh context; "fork" = inherits parent history
        # diagFile: "F:/your-workspace/dream-diag.log"  # optional diagnostic log

Then restart the web service (e.g. dsh-web-restart.cmd or restart the profile).

Note: the subagent mode requires the subagents service (part of the standard DSH web profile, which ships @deepseek-ai/dsh-subagent-spawn-in-process). If it is unavailable, the dream is skipped and a warning is logged.

Configuration

Field	Default	Description
intervalSeconds	21600	Check interval in seconds (min 300)
minNewEvents	3	Minimum number of real user messages since the last dream before a dream is worth doing (plugin activity is excluded)
maxMemoryBytes	20000	Archive & rebuild MEMORY.md when it exceeds this size (0 = disabled)
memoryDir	see below	Memory directory. Recommended to set explicitly to <workspace>/memory. When unset, resolution falls back to session meta.cwd → process.cwd(); when the web is launched by the logon scheduled task, process.cwd() defaults to C:\Windows\System32, which would write memory files into the system directory
diagFile	off	Optional absolute path for a plugin diagnostic log (event stream); enable for troubleshooting
mode	subagent	subagent = background subagent (nothing in the main chat); followup = legacy visible [DREAM] user message
subagentProvider	spawn	Subagent provider: spawn (fresh context, low tokens) or fork (inherits the parent's full history — more context, more tokens)
digestEvents	40	How many recent user/assistant messages to include in the dream child's digest
digestChars	8000	Max digest length (older content is truncated)

How it works

• When the plugin loads, each root agent created afterwards gets a per-agent runtime with a timer.
• On tick: if the agent is alive and enough new user messages have accumulated, the runtime claims maintenance, flushes session persistence, and starts a background subagent (startContinuable with the configured provider).
• The dream child runs in its own conversation: the framing prompt + a compact digest of recent messages + the memory files. It reviews and updates MEMORY.md / dreams.md (the same pattern as the dream-consolidate skill) and replies with a short summary that stays in the child's session.

Known limitations

• Only applies to root agents created after the plugin loads (same boundary as dsh-schedule); sessions created after a restart get the capability automatically.
• The timer lives with the web process; no dreams are produced while the process is down.
• Each dream pass is executed by a subagent and consumes tokens (a small context: prompt + digest + memory files); tune frequency with intervalSeconds / minNewEvents.
• Multiple sessions sharing the same memory files can race on writes; acceptable in practice (model-side writes dominate).

License

MIT