dsh-plugin-hindsight-advanced

Long-term memory for your DeepSeek Harness (dsh) agent. An agent's conversation ends when the session does — this plugin gives the agent memory that doesn't: it stores what is worth remembering, and brings the right things back at the right time.

What your agent gets:

• a hindsight tool — it stores what is worth remembering (retain), finds it again when it is needed (recall), and can ask the memory a question and get an answer grounded in it (reflect);
• automatic recall — at the start of every turn, the memories that matter to the current conversation are placed in front of the agent, so nothing relevant is ever asked for twice;
• standing rules — "always do this" and "never do that" rules that are applied on every turn until you change them, even when nothing else in the memory matches;
• visibility you choose per memory — every memory is visible to everything in the bank (global), to one agent preset (preset), or to a single session (session); a memory never appears outside its scope.

The memories live in your own Hindsight server, not in the plugin. Uninstalling the plugin never touches them.

Installation

You need a running Hindsight server (hindsight-api — any local port works; the config below points at it) and a DeepSeek Harness checkout.

1. Install the plugin. One command does both halves — it links the plugin into your profile and registers the mounting row for it:

dsh plugin --profile web add /path/to/dsh-hindsight-advanced

(Use a plain path, not a file: URL — a plain path links the source, so edits are picked up without reinstalling. Without the dsh binary on your PATH, run node --import tsx/esm apps/cli/src/bin.ts plugin … from inside the DSH checkout.)

If you checked this repo out fresh, recreate the one machine-local link the source needs first: ln -s /path/to/deepseek-harness/apps/cli/node_modules node_modules inside this repo.

2. Restart dsh web once.

3. Tell it which bank and server to use — one small block in your own config, below. Then restart dsh web again, and the agent remembers.

The install ships switched off on purpose: until you add that block, the agent gets nothing. What you enable, and where, is your call.

To uninstall later: dsh plugin --profile web remove dsh-plugin-hindsight-advanced, remove your config block, restart dsh web. Your memories stay on the Hindsight server.

Configuration

The configuration is one hindsight row in your own DSH config — never an edit to the plugin's files. You place it in one of two spots (pick one, never both):

Every session. In your profile's patch layer (~/.dsh/profiles/web/cordis.patch.yml, append to your existing file):

- id: hindsight
  disabled: false
  config:
    bank: my-bank
    baseUrl: http://127.0.0.1:9177
    apiKeyRef: HINDSIGHT_API_KEY

One preset only. In that preset's own file (~/.dsh/.agent-presets/<preset>/agent.cordis.yml, append):

- id: hindsight
  name: dsh-plugin-hindsight-advanced
  config:
    bank: my-bank
    baseUrl: http://127.0.0.1:9177
    apiKeyRef: HINDSIGHT_API_KEY

Presets that point at the same bank don't need separate banks — the preset scope already keeps each preset's memories apart.

Two things to know about the row:

• the config block replaces the plugin's defaults wholesale — list every key you want; only bank is strictly required, the rest fall back to the defaults in the table below (but baseUrl and apiKeyRef are worth repeating, since their defaults point at port 8888 and carry no key);
• to switch the plugin off again, set disabled: true on the row (or remove the preset row) and restart.

The configuration keys

key	default	what it does
bank	—	Required. The name of the Hindsight bank to use (the server creates it on first use).
baseUrl	http://127.0.0.1:8888	Your Hindsight server's address.
apiKeyRef	—	The way to give the plugin its key — a name for the secret, not the secret itself. The value is looked up on every call (environment → ~/.dsh/.credentials.yaml → .env files), so rotating the key needs no restart and the key never sits in a config file. See below.
apiKey	—	A plain key in the config, instead of a reference. Prefer apiKeyRef.
autoContext	true	Set false to turn off the automatic per-turn recall (the hindsight tool stays).
retainScope	preset	Where a stored memory lands when the agent doesn't say: global (everything in the bank), preset (this agent preset), or session (this session only).
maxRecallTokens	1024	How much memory to bring back per recall.
autoContextTimeoutMs	2500	How long a turn may wait on the memory server before moving on without it. A slow or stopped server never blocks the agent.
retainAsync	false	false (the default): storing waits until the bank has processed the memory, so the next turn already sees it. true: store acknowledges fast and the bank processes it in the background.
bankConfig	—	Optional instructions for the server's own memory extraction — for example retain_mission: "Focus on decisions and durable project facts." tells the Hindsight server what to pull out of what the agent stores.

Giving the plugin its key

apiKeyRef: HINDSIGHT_API_KEY is only a name — the plugin looks up the value by that name on every call, in this order: the environment, then ~/.dsh/.credentials.yaml, then .env files. The usual way is one line in ~/.dsh/.credentials.yaml, added alongside your existing entries (like the LLM key — don't replace them):

version: 1
refs:
  HINDSIGHT_API_KEY: <the Hindsight server's token>

(Or export HINDSIGHT_API_KEY in the environment that starts dsh web.) Because the lookup happens on every call, editing the file — or rotating the token in place — takes effect immediately, with no restart.