Preface¶

When developing DeepSeek Harness agents, long conversation histories and large tool outputs can easily cause context overflow. The host’s existing compaction process sometimes lacks a clear benefit assessment, or makes it difficult to precisely control the retention of critical memory and diagnostic information. The following introduces dsh-ctxopt-compaction, a tool output pruning plugin that adds benefit assessment, bounded summary caching, explicit memory control, and retention of diagnostic information on top of the host’s existing compaction process.

Plugin Overview¶

dsh-ctxopt-compaction is a context compaction plugin for DeepSeek Harness, developed by maintainer chunsi-w. The current version is 0.0.1. It does not run as a standalone chat service; instead, it relies on the host to provide the necessary dependencies (including the compaction engine, tool pruning, LLM, session, and Schemastery). The plugin provides its functionality through JavaScript source code and requires no transpilation.

Installation and Activation¶

To enable this plugin in the host environment, you must first obtain and package the source code, then load it through the host’s installation mechanism.

Obtain and Package¶

git clone https://github.com/chunsi-w/dsh-ctxopt-compaction.git
cd dsh-ctxopt-compaction
npm pack

The generated package name is dsh-ctxopt-compaction-0.0.1.tgz.

Headless Loading¶

In a DeepSeek Harness directory where dependencies are installed and the build is complete, run the following commands and replace the plugin’s absolute path:

pnpm dsh plugin --profile headless add file:/absolute/path/to/dsh-ctxopt-compaction
pnpm dsh --profile headless --dump-config

After running, check whether the generated configuration includes ctxopt-compaction and ctxopt-tool-result-pruner, and confirm that the sibling default components at the same level have been disabled.

Web Loading¶

In a Web environment, installing only the top-level bundle or passing cordis.patch.yml directly is not sufficient to replace the default components in the standard preset. Create an override configuration based on the host’s packages/bundle/web-app/presets/standard.patch.yml. Within the compaction group, change the name of compaction-basic to the absolute path of src/engine.js in this repository, and change the name of tool-result-pruner to the absolute path of src/pruner.js.

- id: compaction-basic
  name: /absolute/path/to/dsh-ctxopt-compaction/src/engine.js
  config:
    thresholdRatio: 0.4
    headroomTokens: 512
    retainTokens: 1400
    maxTokens: 1536
    compactionRetries: 1
- id: tool-result-pruner
  name: /absolute/path/to/dsh-ctxopt-compaction/src/pruner.js
  config:
    thresholdChars: 8192
    headChars: 4096
    digestChars: 1536
    tailChars: 1024

Core Features¶

The plugin mainly includes the following five components and capabilities:

1. Compaction benefit assessment: Estimate the benefit based on the actual history to be replaced, excluding un-replaced system messages; by default, skip the summary call for fragments with fewer than 512 estimated tokens.
2. Summary quality and budget: Reject replacement when the summary is too short, exceeds the budget, or saves insufficiently, and retain the original history; by default, do not additionally retry degenerate summaries.
3. Summary caching: Cache separately by session, input, tool history, routing, and configuration, with limits on entry count, byte size, and expiration.
4. Controllable memory: Use explicit instructions to save, update, and delete key-value facts and todos, and write the current state into a compaction checkpoint.
5. Diagnostic retention: When pruning long tool outputs, retain intermediate diagnostic information such as errors, files, and tickets that the budget allows between the head and tail.

Configuration Description¶

The plugin controls benefit assessment, cache size, memory entries, and tool pruning parameters through configuration files. The host patch replaces the entire config of the target entry and does not merge recursively.

Engine Configuration¶

The following are example parameters for a 32K window; other values are this plugin’s defaults:

thresholdRatio: 0.4
headroomTokens: 512
retainTokens: 1400
maxTokens: 1536
compactionRetries: 1

budgets:
  minRegionTokens: 512
  minSavingsTokens: 96
  checkpointReserveTokens: 128
  maxCheckpointTokens: 2048
  maxExtrasTokens: 384

cache:
  enabled: true
  maxEntries: 16
  maxBytes: 262144
  ttlMs: 300000
  failureTtlMs: 30000

memoryBlock: true
reminders: true
memory:
  maxItems: 8
  maxTodos: 4
  maxItemChars: 160
  allowedKeys: []

anchorValidation: true
degenerateGate: true
degenerateRetries: 0
economics:
  enabled: false

Key Parameter Description¶

• thresholdRatio / headroomTokens: Control the position at which the host triggers compaction and the window headroom; they are not a hard truncation limit on input.
• maxCheckpointTokens: Used to calculate the summary budget, after deducting checkpointReserveTokens; the final checkpoint is metered by the host.
• cache.maxEntries / maxBytes: The cache entry count and the byte limit for keys/serialized payloads for each engine instance, not process RSS.
• memory.allowedKeys: Whitelist of key names allowed to be saved; an empty array means no restriction on key names.

Tool Output Pruning Configuration¶

The pruner’s independent default configuration is as follows:

thresholdChars: 8192
headChars: 2048
digestChars: 1536
tailChars: 2048
smartDiagnostic: true

headChars, digestChars, and tailChars respectively control the head, diagnostic digest, and tail budgets, counted by Unicode code points. Setting tailChars: 0 disables tail retention on the smart pruning path.

Memory and Todo Control¶

Write instruction lines separately in user messages to control memory and todo state. Do not place them inside code blocks or quoted text when sending.

Instruction Example¶

MEMORY project=ATLAS
MEMORY schema=v3
TODO release=完成回归测试后发布
MEMORY schema=v4
FORGET project
DONE release
MEMORY RESET

Instruction Rules¶

• Reassigning the same key again indicates an update.
• The syntax for deletion, completion, and clearing is shown above.
• Key names are case-sensitive and must be 1–64 characters long, using ASCII letters, digits, underscores, periods, or hyphens.
• When the entry limit is exceeded, the earlier updated entries are evicted; if a single value exceeds maxItemChars, the entire entry is skipped.
• Todos represent only unfinished states in summaries, are not scheduled reminders, and are not shared across sessions.
• FORGET and MEMORY RESET only clear the current state managed by the plugin and do not erase historical narratives in the original chat logs or model summaries.

Notes¶

1. Information retention: Compaction is still performed by model-generated summaries, so it cannot guarantee that all historical information is retained.
2. Dependency requirements: The host must provide the peer dependencies declared in package.json.
3. Operation mode: It cannot run as a standalone chat service.
4. Configuration merging: The host patch replaces the entire config of the target entry and does not merge recursively.
5. Log viewing: Loading via source paths does not automatically generate the management card for installed plugins. You can determine whether the plugin is effective by checking host logs for keywords such as ctxopt decision, skip-small-region, and summary-ready.
6. Performance dependency: Latency and token savings depend on actual inputs and the model service; this README does not promise a fixed improvement ratio.