Introduction

Here introduces a DeepSeek Harness (DSH) plugin: flowctx-dsh.

It addresses common context management challenges in agent programming: as sessions grow longer, tool outputs continuously accumulate, historical details gradually blur, and the model may repeat searches, forget constraints, or lose early failure paths and key identifiers. Existing approaches typically rely on basic compression or summarization, but summaries may lose failure paths, and compressed tool results might be difficult to retrieve in their original form.

flowctx-dsh provides additive extensions on top of dsh-compaction-basic: the summary style is closer to engineering handover notes, compressed tool results can be retrieved by hash, history can be collapsed into hierarchical summary nodes, and an optional working_memory editing tool is provided. All extensions can be toggled individually; when all are disabled, the behavior is equivalent to dsh-compaction-basic with only the summary style adjusted.

Plugin Overview

flowctx-dsh is a local-first context engine for DSH, maintained by Ayou-Claw.

  • Name: flowctx-dsh
  • Version: 0.1.0
  • License: MIT
  • GitHub: https://github.com/Ayou-Claw/flowctx-dsh

It does not replace DSH’s basic compression capability, but extends it:

  • Summary output targets engineering handover notes;
  • History can be collapsed into hierarchical summary nodes in the background;
  • Threshold-exceeded tool results undergo reversible projection;
  • Provides optional working memory tools;
  • Provides flowctx_retrieve for retrieving compressed materials.

Core Capabilities

Engineering Handover Note Summaries

This capability is hooked into agent/pre-step, replacing the original summary prompt.

It requires the summary to output a 6-segment handover note, and specifically preserves two types of key information:

  • Failure paths;
  • Verbatim identifiers.

Compared to generic narrative summaries, it is more suitable for software debugging, code fixing, and long-term task progress, because “which path was tried” and “which function, path, commit, or session ID appeared” is often more important than a general summary.

This capability is enabled by default.

Hierarchical DAG Summaries

This capability is also hooked into agent/pre-step, but follows a background fire-and-forget path.

It collapses history into hierarchical summary nodes, rather than maintaining just one rolling summary. For long sessions, early different topics can be preserved as summary nodes at different levels, avoiding them all being compressed into a generalized description.

This capability is enabled by default.

Reversible Tool Result Projection

This capability is hooked into tools/post-execute.

When the tool result exceeds a threshold, it performs structured compression on the tool result. During compression, instead of directly discarding the original text, it:

  • Stores the original text into CompressionStore by hash;
  • Retains a retrievable reference in the context;
  • Supports byte-exact retrieval.

In other words, large log blocks and long tool outputs can first enter compressed references and be restored in full when needed later.

This capability is enabled by default.

Editable Working Memory

This capability is provided via flowctx_scratch_* tools, used to maintain the <working_memory> block.

It is disabled by default. When enabled, the model can maintain working memory via the following tools:

  • flowctx_scratch_append
  • flowctx_scratch_replace
  • flowctx_scratch_rethink

Suitable for tasks where the agent needs to actively record current goals, to-do items, or non-forgotten results.

Retrieval Tool: flowctx_retrieve

flowctx_retrieve is the accompanying retrieval tool.

It supports two types of retrieval:

  • Retrieve the projected compressed original text by hash;
  • Retrieve handover notes of a specified level by node id.

This makes compression not a one-way loss, but a “reference first, restore later” approach.

Installation and Enablement

The following takes the web profile as an example.

1. Install Plugin

Execute:

dsh plugin --profile web add flowctx-dsh

2. Add to Profile Patch Layer

Edit:

~/.dsh/profiles/web/cordis.patch.yml

Add:

- insert:
    - id: flowctx-dsh

3. Restart DSH Web

dsh web

4. Verify Loading

dsh --profile web --dump-config | grep flowctx

If the configuration is loaded, flowctx related configurations should be visible in the command output.

Typical Usage

Retrieve Projected Compressed Original Text

When tool results have been projected and compressed, you can use:

flowctx_retrieve(hash="…")

to retrieve the original text by hash.

Retrieve Handover Notes of a Specified Level

flowctx_retrieve can also retrieve handover notes of a specified level by node id.

This is suitable for reviewing early-stage task goals, attempted solutions, failure paths, or key identifiers in long sessions.

Maintain Working Memory Using Scratchpad

After enabling the scratchpad, you can use:

  • flowctx_scratch_append
  • flowctx_scratch_replace
  • flowctx_scratch_rethink

to maintain <working_memory>.

This capability is disabled by default, suitable for scenarios where the agent is explicitly expected to actively maintain short-term working memory.

Configuration and State

All configuration items are optional. When unconfigured, flowctx-dsh behaves like dsh-compaction-basic, with the main difference being the summary style.

Default states:

  • Engineering Handover Note Summary: Enabled by default;
  • Hierarchical DAG Summary: Enabled by default;
  • Reversible Tool Result Projection: Enabled by default;
  • Editable Working Memory: Disabled by default.

There are two tiers of state storage:

  • When stateDir is not set, it degrades to pure memory + TTL, recoverable within the session;
  • After setting stateDir, compressed references, summary nodes, and scratchpad share a database handle and are persisted to:
<stateDir>/flowctx.sqlite

Regarding dependencies, peerDependencies specifies:

@deepseek-ai/cordis ^4.0.1

and several:

@deepseek-ai/* ^0.1.0-rc.6

dependencies.

Use Cases and Notes

Suitable for the following usage patterns:

  • Using DSH for long-session agent programming;
  • Need to preserve failure paths and key identifiers;
  • Need to compress long tool results into references and restore them on demand later;
  • Want history summaries to be preserved hierarchically rather than just maintaining one rolling summary;
  • Want to enable working memory editing on demand.

Notes to be aware of:

  • The plugin runs with the permissions of the current dsh process;
  • Check source code, license, and dependencies before installation;
  • Current version is 0.1.0, license is MIT;
  • DSH version SWE-bench evaluation is ongoing, results are not yet provided;
  • The complete list of configuration items inherited from dsh-compaction-basic is truncated in verified sources; this article does not elaborate.

Conclusion

The value of flowctx-dsh lies in: it advances DSH’s context compression from “summarizing away history” to an engineering memory model of “compress, layer, preserve, and retrieve.” For long-session agent programming, this recoverable context organization is more critical than simply shortening the prompt.

GitHub: https://github.com/Ayou-Claw/flowctx-dsh

The directory page address was not provided in the verified sources.