In long sessions, an agent repeatedly rereads unchanged files. In scenarios such as context compaction recovery, parallel subagents, and before/after edit comparison, every repeated read performs file I/O and line-number rendering, even though the retrieved byte content is identical. dsh-readcache provides an in-process result cache with version-token validation for the DSH read tool. It intercepts the tools/execute event waterfall so that repeated reads hit the cache directly, reducing I/O and rendering overhead.

Core Features

  • Result caching: Provides result caching for the DSH read tool; repeated reads of unchanged files skip file I/O.
  • Version token validation: On every cache hit, an additional stat is performed on the file and the version token must match exactly (for the local backend, dev:ino:size:mtimeNs:ctimeNs). Any write path (such as the edit/write tools, bash, or an external editor) changes the token and immediately invalidates the corresponding entry.
  • Agent isolation: The cache key includes the agent ID. The filesystem observation gate requires each agent to have read the file itself before editing it; per-agent key isolation ensures every cache hit is grounded in that agent’s own prior observation.
  • Memory management: Uses an LRU strategy with limits of 300 entries / 16 MiB total / 4 MiB per entry.
  • Safety protections:
  • No write races: On a cache miss, the result is cached only if a second stat still reports the pre-execution token (double-stat protection).
  • Only cache valid results: Only successful, non-aborted, losslessly JSON-serializable read tool results are cached; failed results are passed through unchanged.

Installation and Enabling

Install using the official command:

dsh plugin --profile web add dsh-readcache

Or install from a local checkout:

cd dsh-readcache && npm pack
dsh plugin --profile web add ../dsh-readcache/dsh-readcache-1.0.1.tgz

After installation, restart DeepSeek Harness to activate the plugin.

Typical Usage

The plugin registers a model-visible tool readcache, where action can be "stats" or "clear".

View Statistics

Enter the following to view cache hit information:

{
  "action": "stats"
}

The stats output includes statistics such as hits, misses, savedChars, and entries. Example:

{
  "hits": 2,
  "misses": 4,
  "hitRatio": 33.3,
  "stale": 1,
  "stores": 4,
  "evictions": 0,
  "savedChars": 1210,
  "clearedEntries": 0,
  "entries": 3,
  "cachedChars": 1662,
  "maxEntries": 300
}

Clear Cache

Enter the following to clear all cached entries:

{
  "action": "clear"
}

Applicable Scenarios and Notes

  • Applicable scenarios: Long sessions, context compaction, parallel subagents, before/after edit comparison, and other scenarios where the same file is read repeatedly and frequently.
  • Notes:
  • Only results that can be losslessly serialized to JSON are cached.
  • The cache runs entirely within the host process.
  • The client dashboard feature is on the v1.1 roadmap.
  • The plugin runs with the permissions of the current DSH process; review the source code and license before installing.
  • GitHub: https://github.com/yongshuai0314/dsh-readcache
  • Directory: https://www.skillhub.cn/plugins/yongshuai0314/dsh-readcache