@vectorize-io/hindsight-coding-agents 0.3.3 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Long-term project memory for **coding agents**, backed by [Hindsight](https://vectorize.io/hindsight).
4
4
  One package, several agents: a shared reflect-and-inject core with a thin entry point per agent
5
- (**opencode**, **Kilo CLI**, **Cline CLI**, **Prime Agent**, **Claude Code**, **Codex CLI**, **Antigravity CLI**, **Cursor CLI**, **GitHub Copilot CLI**, **Grok Build**). Ingestion is fully
5
+ (**opencode**, **Kilo CLI**, **Cline CLI**, **Prime Agent**, **DeepSeek Harness**, **Claude Code**, **Codex CLI**, **Antigravity CLI**, **Cursor CLI**, **GitHub Copilot CLI**, **Grok Build**). Ingestion is fully
6
6
  automatic — there is no setup command: a repo's git history and conversations flow into its memory
7
7
  bank in the background as you work.
8
8
 
@@ -120,6 +120,21 @@ npx @vectorize-io/hindsight-coding-agents install prime-agent
120
120
 
121
121
  An extension entry in `~/.prime/agent/settings.json` — native tools, no MCP needed.
122
122
 
123
+ #### <img src="https://hindsight.vectorize.io/img/harness/dsh.svg" alt="" width="20" height="20" /> DeepSeek Harness
124
+
125
+ ```bash
126
+ npx @vectorize-io/hindsight-coding-agents install dsh
127
+ ```
128
+
129
+ A Cordis plugin row in `$DSH_HOME/cordis.patch.yml` (`~/.dsh` by default), which every dsh profile
130
+ composes — native tools, no MCP needed. Two dsh-specific notes: one dsh process serves **several
131
+ repositories** (its Web UI opens each session in whatever directory you pick), so the bank is
132
+ resolved per session workspace rather than once per process; and dsh has no plugin-facing notice
133
+ channel, so the seed line goes to the plugin log rather than the UI. Everything model-facing —
134
+ recalled memory, the knowledge preamble, the `hindsight_*` tools — is unaffected. If you prefer the
135
+ published-package route, `dsh plugin --profile web add @vectorize-io/hindsight-coding-agents` works
136
+ too: the package ships the profile patch layer, so nothing else needs editing.
137
+
123
138
  Uninstall the same way: `npx @vectorize-io/hindsight-coding-agents uninstall claude-code` (or `uninstall all`).
124
139
 
125
140
  **Devin CLI needs Node 22.5 or newer.** Its hooks pass only a session id — the conversation itself
@@ -153,7 +168,8 @@ minimal, hand-wired setup.
153
168
 
154
169
  Adding an agent: hook-based → write a `HookSpec` entry point (see `src/cursor-hook.ts`) and register
155
170
  a `hookAdapter` in `src/harness/registry.ts`; persistent-plugin → implement `HarnessAdapter`
156
- (`src/core/types.ts`) fully (see `src/harness/opencode.ts`).
171
+ (`src/core/types.ts`) fully (see `src/harness/opencode.ts`), or bind the host's own plugin API to
172
+ `RuntimeCore` directly when it is not an opencode fork (see `src/cline.ts`, `src/dsh.ts`).
157
173
 
158
174
  ## Migrating from the per-agent plugins
159
175
 
@@ -186,12 +202,14 @@ transcripts are needed either way; going through them directly is simply the sho
186
202
 
187
203
  **How sessions are matched.** A conversation is imported only when the session itself records the
188
204
  directory it ran in — never inferred from a file or folder name. Claude Code writes that directory
189
- on its entries and Codex in its `session_meta` header, so both can be attributed exactly, including
190
- sessions started in a subdirectory of the repo. Guessing was tempting (Claude names its history
205
+ on its entries, Codex in its `session_meta` header and DeepSeek Harness in its session-log header,
206
+ so all three can be attributed exactly, including sessions started in a subdirectory of the repo. Guessing was tempting (Claude names its history
191
207
  folders after the project path) but unsafe: `/` and `.` both encode to `-`, so `repo-sub` is either
192
208
  the subdirectory `repo/sub` or an unrelated sibling repo — and a wrong guess files someone else's
193
209
  conversation into your bank. Sessions that record nothing are skipped and the count is reported.
194
- The other harnesses (opencode, Kilo, Cursor, Cline, Copilot, Devin) keep history in internal SQLite
210
+ DeepSeek Harness logs are Zstandard-framed JSONL under `$DSH_HOME/sessions`, which needs Node 22.15+
211
+ to read; an older Node skips the import with that reason rather than silently importing nothing. The
212
+ other harnesses (opencode, Kilo, Cursor, Cline, Copilot, Devin) keep history in internal SQLite
195
213
  databases with unversioned schemas and are skipped with a reason.
196
214
 
197
215
  **Nothing else is translated.** The old plugin's behavioural settings — 12 `recall*`, 7 `retain*`,
@@ -233,9 +251,9 @@ Nothing to sign up for and nothing to host — memory runs on your machine. The
233
251
  A session that begins before it is ready simply has no memory for a turn or two — a daemon that
234
252
  isn't up is treated as an unreachable server, exactly like a Cloud or self-hosted outage, with the
235
253
  same error handling and the same diagnostics. Nothing downstream of the URL knows which mode it is.
236
- - **It shuts down on idle**, after `daemonIdleTimeout` seconds. There is deliberately no
237
- stop-on-exit: one daemon is shared, so ending one session must not cut memory out from under
238
- another agent still working.
254
+ - **It keeps running** until you stop it. There is deliberately no stop-on-exit: one daemon is
255
+ shared, so ending one session must not cut memory out from under another agent still working.
256
+ Set `daemonIdleTimeout` to have it exit after that many seconds of inactivity.
239
257
  - **macOS additionally needs a current Rust toolchain.** `litellm` (a transitive dependency of the
240
258
  API) publishes wheels only for Linux and Windows, so a Mac compiles it from source through
241
259
  maturin and its crates pin a recent `rustc`. Install from [rustup.rs](https://rustup.rs) and keep
@@ -252,7 +270,7 @@ environment carries over unchanged:
252
270
  | ------------------- | ------------------------------- | -------------- | ------------------------------------------ |
253
271
  | `serverMode` | `HINDSIGHT_SERVER_MODE` | `cloud` | `cloud` \| `self-hosted` \| `daemon` |
254
272
  | `apiPort` | `HINDSIGHT_API_PORT` | `9077` | port the local daemon listens on |
255
- | `daemonIdleTimeout` | `HINDSIGHT_DAEMON_IDLE_TIMEOUT` | `300` | seconds of inactivity before it exits |
273
+ | `daemonIdleTimeout` | `HINDSIGHT_DAEMON_IDLE_TIMEOUT` | — | seconds of inactivity before it exits |
256
274
  | `daemonProfile` | `HINDSIGHT_DAEMON_PROFILE` | `coding-agent` | which local database it uses |
257
275
  | `embedVersion` | `HINDSIGHT_EMBED_VERSION` | `latest` | which `hindsight-embed` release to run |
258
276
  | `embedPackagePath` | `HINDSIGHT_EMBED_PACKAGE_PATH` | — | run a local checkout instead (development) |
@@ -277,6 +295,26 @@ The map-valued settings (`mapPathToBank`, `harnesses`, `banks`, `retainMetadata`
277
295
  per-key branching doesn't survive flattening into one variable. `maxParallelRetains` is available
278
296
  as `HINDSIGHT_MAX_PARALLEL_RETAINS` for containers and CI.
279
297
 
298
+ ### When a change takes effect
299
+
300
+ Config is read when a process starts — the file is not watched — so when an edit applies depends on
301
+ what reads it:
302
+
303
+ | host | reads the file | an edit applies |
304
+ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------- |
305
+ | hook harnesses (Claude Code, Codex CLI, Cursor CLI, GitHub Copilot CLI, Grok Build, Antigravity CLI, Devin) | once per hook invocation — each hook is its own short-lived process | on your next prompt |
306
+ | persistent plugins (opencode, Kilo CLI, Cline CLI, Prime Agent, DeepSeek Harness) | once per workspace, when the host loads the plugin | after restarting the agent |
307
+ | the MCP server behind the `hindsight_*` tools | once at startup | in your next session |
308
+
309
+ `apiToken` is the exception. Every host re-reads it when the server rejects a request, so enabling
310
+ authentication or rotating the key is picked up on the next call with nothing to restart —
311
+ otherwise a rotation would leave a long-running agent failing every memory call until it was
312
+ restarted. Everything else follows the table: `apiUrl`, `disabled`, bank routing, `gitIngest`, and
313
+ the survey and knowledge-page settings.
314
+
315
+ `hindsight_diagnose` reports both sides of that gap — what the file says now, and what the running
316
+ client is actually using.
317
+
280
318
  ### Opt-in only
281
319
 
282
320
  By default every project gets memory — that is what makes the plugin zero-setup. If you would
@@ -321,33 +359,49 @@ hook by Codex...), so one shared config serves several agents side by side:
321
359
 
322
360
  ### Reference
323
361
 
324
- | field | default | meaning |
325
- | ----------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
326
- | `apiUrl` | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server) |
327
- | `apiToken` | — | bearer token (Hindsight Cloud) |
328
- | `bankId` | — | **explicit static bank**; unset ⇒ per-repo dynamic resolution (below) |
329
- | `dynamicBankId` | dynamic iff no `bankId` | force dynamic (`true`) or static (`false`) resolution |
330
- | `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo |
331
- | `mapPathToBank` | — | absolute path → bank; **longest prefix wins**; overrides everything |
332
- | `optInOnly` | `false` | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see [Opt-in only](#opt-in-only) |
333
- | `optInPaths` | — | directories opted in, matched as prefixes with `~` expanded; each repo beneath keeps its own dynamic bank |
334
- | `resolveWorktrees` | `true` | `{gitProject}`: linked worktrees share the main repo's bank |
335
- | `retainTags` | — | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
336
- | `retainMetadata` | — | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}` |
337
- | `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
338
- | `reflectTimeoutMs` | `120000` | session-reflect timeout (hook harnesses additionally cap it at 25s to fit the host's hook window); on timeout the session runs without reflect (recorded) |
339
- | `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
340
- | `autoSeed` | `true` | SessionStart: auto-seed a cold repo's bank from git history |
341
- | `seedLimit` | `300` | auto-seed: most-recent-N-commits cap |
342
- | `codebaseSurvey` | `true` | SessionStart: headless survey of a cold repo's structure, run under the current harness's own CLI (claude/codex/antigravity/opencode), falling back to any available agent |
343
- | `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
344
- | `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
345
- | `retainSessions` | `true` | plugin-harness write-back (opencode, Kilo): async upsert of the session transcript every turn, plus an idle flush that captures the reply the per-turn pass can't see (set `false` to opt out; hook harnesses always write on Stop) |
346
- | `maxParallelRetains` | `10` | cap on concurrent retain-related requests: drain()'s per-op polls plus deepen's chat/git retain pools. The API rate-limits bursts, not single requests — if you see 429s, lower this rather than raising it |
347
- | `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
348
- | `gitIngest` | `"message"` | git depth for seeding AND staying current (same engine): `"message"` = commit messages only (one doc, re-upserted when HEAD moves); `"full"` = messages + per-commit full diffs (progressive, newest first); `"none"` = git off |
349
- | `harnesses.<name>` | — | per-harness override of any field above |
350
- | `harness` | `opencode` | **deepen engine only**: which session format `--conversations` is read as |
362
+ | field | default | meaning |
363
+ | ----------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
364
+ | `apiUrl` | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server) |
365
+ | `apiToken` | — | bearer token (Hindsight Cloud). Picked up without restarting the agent: a long-lived host re-reads it after a rejected request, so enabling auth or rotating the key mid-session recovers on the next call |
366
+ | `bankId` | — | **explicit static bank**; unset ⇒ per-repo dynamic resolution (below) |
367
+ | `dynamicBankId` | dynamic iff no `bankId` | force dynamic (`true`) or static (`false`) resolution |
368
+ | `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo |
369
+ | `mapPathToBank` | — | absolute path → bank; **longest prefix wins**; linked worktrees inherit their main checkout's mapping; overrides everything |
370
+ | `optInOnly` | `false` | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see [Opt-in only](#opt-in-only) |
371
+ | `optInPaths` | — | directories opted in, matched as prefixes with `~` expanded; each repo beneath and its linked worktrees are approved while keeping their own dynamic bank |
372
+ | `resolveWorktrees` | `true` | linked worktrees inherit the main checkout's bank identity, path approval, and mapping |
373
+ | `retainTags` | — | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
374
+ | `retainMetadata` | — | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}` |
375
+ | `observationScopes` | `"shared"` | how consolidation groups observations: `"shared"` (default) = ONE global scope per bank, so every agent on a repo builds one set of beliefs; also `"combined"` (the server default), `"per_tag"`, `"all_combinations"`, `[["t"]]` |
376
+ | `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
377
+ | `reflectTimeoutMs` | `120000` | **automatic** session-reflect timeout (hook harnesses additionally cap it at 25s to fit the host's hook window); on timeout the session runs without reflect (recorded) |
378
+ | `reflectToolTimeoutMs` | `330000` | timeout for the agent-invoked `hindsight_reflect` tool — a call the agent waits on, whose high-budget synthesis on a populated bank runs for minutes. Defaults above the server's own reflect wall timeout (`HINDSIGHT_API_REFLECT_WALL_TIMEOUT`, 300s) so the server decides when to give up. Unset, it inherits an explicitly raised `reflectTimeoutMs`, but a short one never lowers it |
379
+ | `reflectBudget` | `"high"` | reflect budget for the `hindsight_reflect` tool: `"low"`, `"mid"` or `"high"`. Drop it on a large bank where high-budget synthesis exceeds the server's wall timeout. The automatic session-start reflect always uses `"low"` to fit its hook window and is unaffected |
380
+ | `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
381
+ | `pageTriggerType` | `"auto-refresh"` | when NEW knowledge pages refresh, i.e. what keeping them current costs — `"auto-refresh"` after every consolidation that produced new material, `"cron"` on `pageTriggerCron` only, `"manual"` never on their own. Auto-refresh is the most current and the most expensive: one synthesis per page per consolidation. Maps to the page's `trigger.refresh_after_consolidation` in the Hindsight API (`true` for auto-refresh, `false` for manual) |
382
+ | `pageTriggerCron` | — | schedule for `pageTriggerType: "cron"` — UTC, standard 5-field cron, e.g. `"0 3 * * *"`. Sets the page's `trigger.refresh_cron`, which the API treats as mutually exclusive with `refresh_after_consolidation`; a scheduled refresh is skipped when nothing changed |
383
+ | `autoSeed` | `true` | SessionStart: auto-seed a cold repo's bank from git history |
384
+ | `seedLimit` | `300` | auto-seed: most-recent-N-commits cap |
385
+ | `codebaseSurvey` | `true` | SessionStart: headless survey of a cold repo's structure, run under the current harness's own CLI (claude/codex/antigravity/opencode), falling back to any available agent |
386
+ | `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
387
+ | `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
388
+ | `retainSessions` | `true` | session write-back, honored by every harness: hook harnesses write the transcript on Stop, plugin harnesses (opencode, Kilo) upsert it every turn plus an idle flush that captures the reply the per-turn pass can't see. Set `false` — globally, per harness, or per bank — to stop writing transcripts (the background history import stops with it) while recall, git ingest and the memory tools keep working |
389
+ | `maxParallelRetains` | `10` | cap on concurrent retain-related requests: drain()'s per-op polls plus deepen's chat/git retain pools. The API rate-limits bursts, not single requests — if you see 429s, lower this rather than raising it |
390
+ | `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
391
+ | `gitIngest` | `"message"` | git depth for seeding AND staying current (same engine): `"message"` = commit messages only (one doc, re-upserted when HEAD moves); `"full"` = messages + per-commit full diffs (progressive, newest first); `"none"` = git off |
392
+ | `harnesses.<name>` | — | per-harness override of any field above |
393
+ | `harness` | `opencode` | **deepen engine only**: which session format `--conversations` is read as |
394
+
395
+ `pageTriggerType`/`pageTriggerCron` decide only **when** a page refreshes. **How** it refreshes
396
+ belongs to the server: Hindsight creates a knowledge page with a delta refresh (each pass edits the
397
+ page instead of rebuilding it) that doesn't reflect over sibling pages, and these settings merge
398
+ over those defaults rather than replacing them.
399
+
400
+ **These settings apply to pages created from here on.** Changing them does not migrate the pages a
401
+ repo already has: a page keeps the trigger it was created with, so a bank seeded before you set
402
+ `"manual"` keeps refreshing on every consolidation. To move an existing page, change its trigger
403
+ through the API (`PATCH /knowledge-base/nodes/{id}`), an SDK, or the control plane — or delete it
404
+ and let the next session seed it again.
351
405
 
352
406
  ### Per-repo opt-in/out — `banks.<bankId>`
353
407
 
@@ -408,7 +462,10 @@ Coding memory is **per repository**. Resolution order for the working directory:
408
462
  3. Dynamic — `bankIdTemplate` with placeholders:
409
463
  - `{gitProject}` — worktree-aware repo name: `git rev-parse --git-common-dir` resolves every
410
464
  linked worktree to the **main** worktree's basename, so all worktrees of a repo share one bank
411
- (bare repos use the bare dir name; non-git directories fall back to the dir basename)
465
+ (bare repos use the bare dir name). **Outside a repo** there is nothing for git to resolve, so
466
+ it falls back to the basename of the directory the **session started in** — an agent that
467
+ `cd`s into a subdirectory keeps writing to one bank, and a subdirectory gets its own bank only
468
+ when you deliberately start a session there
412
469
  - `{project}` — plain working-directory basename
413
470
  - `{harness}` — the entry point asking (`opencode`, `claude-code`, `codex`, `antigravity-cli`, `cursor-cli`, `copilot-cli`)
414
471
  - `{channel}` / `{user}` — `$HINDSIGHT_CHANNEL_ID` / `$HINDSIGHT_USER_ID`
@@ -441,6 +498,36 @@ of. Both accept the same placeholders as `bankIdTemplate` — `{gitProject}`, `{
441
498
  The plugin's own `source:` and `harness:` tags are reserved: entries in those namespaces are ignored
442
499
  with a warning, so a document's agent attribution always reflects the agent that actually wrote it.
443
500
 
501
+ ### One set of beliefs per repo
502
+
503
+ Every document this integration writes carries provenance tags — `source:chat`, `harness:<id>`,
504
+ `knowledge:<kind>`, plus anything from `retainTags`. Those tags say **who wrote** a memory; they are
505
+ what filters recall and draws each document's agent logo, and they stay on the facts.
506
+
507
+ They are not, however, a good boundary for
508
+ [observations](https://hindsight.vectorize.io/developer/observations). Consolidation's own
509
+ default (`combined`) builds one observation set per distinct tag set, so the same repository
510
+ worked on by two agents would grow two parallel sets of beliefs — one per harness — that never
511
+ merge, each blind to the other, at double the consolidation cost. Which agent happened to be typing
512
+ does not change whether a convention or a decision is true.
513
+
514
+ So the integration retains with `observationScopes: "shared"`: one global, untagged observation
515
+ scope per bank, which is what a bank already is — one project's memory. Set the field to change it:
516
+
517
+ ```jsonc
518
+ {
519
+ "observationScopes": "combined", // one observation set per distinct tag set (server default)
520
+ "banks": {
521
+ "coding-agent::mono": { "observationScopes": "per_tag" }, // per-repo, like any behavioral field
522
+ },
523
+ }
524
+ ```
525
+
526
+ `"per_tag"` and `"all_combinations"` split further still, and an explicit `[["project:demo"], …]`
527
+ declares the scopes literally. `HINDSIGHT_OBSERVATION_SCOPES` sets the scalar modes; a scope list is
528
+ file-only. Changing this does not rewrite observations already consolidated under the old scoping —
529
+ they stay where they were built, and new work accrues under the new setting.
530
+
444
531
  ## Ingestion internals (no CLI)
445
532
 
446
533
  There is no user-facing ingest command — the deepen engine (`dist/deepen.js`) is spawned by every
@@ -0,0 +1,18 @@
1
+ # DeepSeek Harness profile layer for Hindsight memory.
2
+ #
3
+ # `dsh plugin --profile <name> add @vectorize-io/hindsight-coding-agents` installs this package into
4
+ # the profile and — because package.json declares `dsh.bundle.patch` — appends this file to the
5
+ # profile's ordered bundle list. Nothing else needs editing: the row below mounts on the host plane,
6
+ # where the pre-step/session-start/turn-stopping events and the layered tools registry all reach
7
+ # every session, including the Web surface's per-session agent presets.
8
+ #
9
+ # Memory itself is configured OUTSIDE dsh, in ~/.hindsight/coding-agent.json (server URL, token,
10
+ # bank naming, opt-outs) — the same file every other Hindsight coding-agent harness reads. To turn
11
+ # it off for one profile without uninstalling, patch this row in the profile's own
12
+ # cordis.patch.yml:
13
+ #
14
+ # - id: hindsight
15
+ # disabled: true
16
+ - insert:
17
+ - id: hindsight
18
+ name: "@vectorize-io/hindsight-coding-agents/dsh"