dsh-prolong-memory

Readme

# dsh-prolong-memory

[中文文档](README.zh.md)

Programmatic memory for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/dsh): every durable session event is appended to a structured `log.txt` in the workspace, and the agent retrieves it programmatically with grep / Python. No subagents, no vector search.

**Built-in self-diagnostics**: a write probe, a `/prolong status` command, and a permission-deny counter — so when a permission/sandbox plugin restricts this plugin, you can immediately tell *host-side log writes being blocked* apart from *agent retrieval calls being denied*.

## Why

Long-horizon agent sessions lose detail to context compaction. DSH's built-in summarizer is faithful to information that was **explicitly marked as important**, but operational detail that nobody flagged in advance — exact command lines, exit codes, file paths, error text — gets framed away. This plugin keeps a verbatim, greppable record of everything durable, and teaches the agent (via a small system-prompt section) to consult it when context feels missing.

This was verified with a reproducible A/B experiment ([experiments/compaction-ab](experiments/compaction-ab/README.md)):

| scenario | plugin ON | plugin OFF |
|---|---|---|
| facts explicitly marked "remember this" | 6/6 | 6/6 (DSH summary suffices — plugin is redundant here) |
| facts buried in "unimportant" command detail | **6/6** | **0/6** (agent greps `log.txt` and recovers them) |

## Relationship to PRO-LONG

This is a reimplementation of the core idea of [PRO-LONG](https://github.com/alexisfox7/PRO-LONG) (*Programmatic Memory Enables Long-Horizon Reasoning*):

- **Kept**: the harness (not the model) appends an append-only, structured event log; the model reads it back with ordinary programmatic tools (grep / Python) on demand.
- **Deliberately not ported**: PRO-LONG's subagents and any vector/embedding retrieval. Retrieval reuses the bash / file tools already shipped with DSH's Standard/Minimal profiles.

## Relationship to DeepSeek Harness

This is a **DSH plugin**, not a fork or a patch. It composes three public extension points (verified against the rc.7 sources):

| capability | extension point | notes |
|---|---|---|
| events → `log.txt` | `session/event` observer | sync hot-path notification; writes are queued and flushed asynchronously, never blocking the agent loop |
| PRO-LONG prompt | `ctx.systemPrompt.section()` | order=150 (tool-guidance band 100–199), ~20 lines |
| `/prolong status` | `ctx.commands.register()` | human-facing command, no model turn; skipped automatically on profiles without `ctx.commands` (lazy `ctx.inject`) |
| programmatic retrieval | — none added — | reuses the profile's built-in bash / file tools |

> DSH is in **developer preview** and upstream reserves breaking changes. After upgrading DSH, run `npm run test:integration` to re-validate the extension-point contracts (the smoke test mounts the real cordis / dsh-session / dsh-system-prompt / dsh-commands and always tests the repo sources, not the installed copy).

## Install

```sh
dsh plugin --profile web add /path/to/dsh-prolong-memory
# or, once published on GitHub:
dsh plugin --profile web add github:ycr40/dsh-prolong-memory
```

The package declares `"dsh": { "bundle": "cordis.yml" }`, so it lands in that profile's bundle layer automatically. Verify the composed tree:

```sh
dsh --profile web --dump-config   # should contain an `id: prolong-memory` entry
```

## Usage

Once mounted, no interaction is needed — every session in the profile gets a `log.txt` in its workspace, starting with a write-probe section. Ask the agent anything about earlier work ("what exact command failed back then?") and the prompt section steers it to grep the log.

Check plugin health at any time:

```
/prolong status
```

```
prolong-memory status
log file: log.txt (per-session workspace)
window: full

session 9f3c…
  path: /work/demo/log.txt
  writable=yes sections=128 lastSeq=341

denied tool calls referencing the log: 0
```

## Configuration (cordis.yml / patch overlay)

| field | default | meaning |
|---|---|---|
| `logFile` | `log.txt` | log file name inside the workspace (path traversal rejected; misconfiguration fails loud) |
| `logWindow` | `0` | `0` = keep everything; `N>0` = keep last N sections; `-1` = disable entirely (no-log ablation) |
| `promptOrder` | `150` | system-prompt section ordering |
| `registerPrompt` / `registerCommand` | `true` | toggle the prompt section / the status command independently |
| `denyKeep` | `20` | denied-call records kept for the status report |

Temporary debugging without touching the profile: `dsh --profile web --patch ./overlay.yml`.

## Self-diagnostics: spotting permission / sandbox restrictions

The two failure modes have different symptoms:

1. **Agent retrieval is denied** (`tools/pre-execute` policy) — the denial is itself a durable `tool/result` error event. The deny counter pairs `tool/call` with `tool/result` by `callId` (falling back to `(turn, step)` FIFO) and counts denied calls referencing `log.txt`; `/prolong status` lists them and hints `suspect a tools/pre-execute policy plugin`.
2. **Host-side log writes fail** (`ctx.sandbox` / fs policy) — silent otherwise. The first event of each session triggers a **probe write**; failure flips status to `writable=NO` with a logger warning and hints `suspect a permission/sandbox plugin`.

Deny semantics calibrated against rc.7 sources: a policy denial is `message.isError === true` **without** `data.error` (events carrying `data.error` are aborts/tool exceptions and are not counted).

## Development & testing

Test-first: all logic (formatting / writer / counter / status / config / prompt) lives in pure Cordis-free modules under `src/core/`; `src/index.js` is wiring only.

```sh
npm test                 # node --test, 48 cases incl. mock-Context wiring tests
npm run test:integration # smoke against the real local DSH runtime
```

Integration module resolution: `DSH_MODULES` > `DSH_HOME/profiles/node_modules` > `~/.dsh/profiles/node_modules`.

## Known limitations

- `logWindow > 0` trimming rewrites the file from sections seen by *this* process; after a restart the window re-accumulates from empty. A rebuild-from-the-durable-session-log pass can be added later (the DSH session log is already complete).
- Non-narrative events (`assistant/chunk`, `request/header`, …) are not logged, keeping `log.txt`'s signal-to-noise ratio greppable.
- Experiment evidence is directional (1 run per variant per mode), not statistical.

## License

MIT — see [LICENSE](LICENSE).