@vectorize-io/hindsight-coding-agents 0.4.3 → 0.5.1

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.
Files changed (46) hide show
  1. package/README.md +202 -52
  2. package/dist/antigravity-hook.js +637 -199
  3. package/dist/antigravity-statusline.js +219 -84
  4. package/dist/antigravity-stop-hook.js +654 -205
  5. package/dist/claude-hook.js +637 -199
  6. package/dist/claude-sessionstart-hook.js +862 -236
  7. package/dist/claude-stop-hook.js +654 -205
  8. package/dist/cline.js +588 -234
  9. package/dist/codex-hook.js +637 -199
  10. package/dist/codex-sessionstart-hook.js +862 -236
  11. package/dist/codex-stop-hook.js +654 -205
  12. package/dist/copilot-hook.js +637 -199
  13. package/dist/copilot-sessionstart-hook.js +862 -236
  14. package/dist/copilot-stop-hook.js +654 -205
  15. package/dist/cursor-hook.js +637 -199
  16. package/dist/cursor-sessionstart-hook.js +862 -236
  17. package/dist/cursor-stop-hook.js +654 -205
  18. package/dist/daemon-start.js +62 -43
  19. package/dist/dcode-hook.js +2577 -0
  20. package/dist/dcode-sessionstart-hook.js +3193 -0
  21. package/dist/dcode-stop-hook.js +2807 -0
  22. package/dist/deepen.js +361 -204
  23. package/dist/devin-hook.js +637 -199
  24. package/dist/devin-sessionstart-hook.js +862 -236
  25. package/dist/devin-stop-hook.js +654 -205
  26. package/dist/dsh.js +591 -235
  27. package/dist/grok-hook.js +637 -199
  28. package/dist/grok-sessionstart-hook.js +862 -236
  29. package/dist/grok-stop-hook.js +654 -205
  30. package/dist/hindsight-seed.js +222 -83
  31. package/dist/index.js +588 -234
  32. package/dist/installer.js +2331 -299
  33. package/dist/kilo.js +588 -234
  34. package/dist/mcp-server.js +363 -169
  35. package/dist/opencode2.js +30091 -0
  36. package/dist/pi.js +17649 -0
  37. package/dist/prime-agent.js +624 -260
  38. package/dist/qwen-hook.js +2577 -0
  39. package/dist/qwen-sessionstart-hook.js +3193 -0
  40. package/dist/qwen-stop-hook.js +2807 -0
  41. package/dist/status.js +300 -136
  42. package/hooks/hooks.json +37 -0
  43. package/index.js +10 -0
  44. package/package.json +15 -8
  45. package/plugin.json +16 -0
  46. package/skill/SKILL.md +114 -43
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**, **DeepSeek Harness**, **Claude Code**, **Codex CLI**, **Antigravity CLI**, **Cursor CLI**, **GitHub Copilot CLI**, **Devin CLI**, **Grok Build**). Ingestion is fully
5
+ (**opencode**, **opencode 2**, **Kilo CLI**, **Cline CLI**, **pi**, **Prime Agent**, **DeepSeek Harness**, **Claude Code**, **Codex CLI**, **DeepAgents Dcode**, **Antigravity CLI**, **Cursor CLI**, **GitHub Copilot CLI**, **Devin 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
 
@@ -20,6 +20,7 @@ in front of the agent at the moment it starts working, and keeps a curated set o
20
20
  npx @vectorize-io/hindsight-coding-agents install all # every detected agent, wired natively
21
21
  npx @vectorize-io/hindsight-coding-agents install claude-code # or just one
22
22
  npx @vectorize-io/hindsight-coding-agents uninstall all # removes exactly what install added
23
+ npx @vectorize-io/hindsight-coding-agents update # refresh the runtime only, no rewiring
23
24
  ```
24
25
 
25
26
  `install` takes an explicit target — `all`, or one or more harness names. A bare
@@ -27,6 +28,12 @@ npx @vectorize-io/hindsight-coding-agents uninstall all # removes exactly
27
28
  the machine is never something that happens by accident. **Updating is the same `install`
28
29
  command again** — it re-copies the runtime in place.
29
30
 
31
+ Day to day you should not have to: once a day, a session start checks npm and re-stages a newer
32
+ runtime in the background (`autoUpdate`, on by default — set it to `false` to pin the version you
33
+ have). That is the `update` command above, which refreshes the copy every wired agent already
34
+ points at and deliberately touches no host config; re-run `install` yourself after a release that
35
+ adds a new hook, or to wire another agent.
36
+
30
37
  <!-- skill:end -->
31
38
 
32
39
  On a terminal it also asks **where memory should live** — Hindsight Cloud, a server you run, or a
@@ -53,6 +60,27 @@ npx @vectorize-io/hindsight-coding-agents install codex
53
60
 
54
61
  3 hooks in `~/.codex/hooks.json` plus `[mcp_servers]` in `config.toml` (needs `codex_hooks = true`).
55
62
 
63
+ #### <img src="https://hindsight.vectorize.io/img/harness/dcode.svg" alt="" width="20" height="20" /> DeepAgents Dcode
64
+
65
+ ```bash
66
+ npx @vectorize-io/hindsight-coding-agents install dcode
67
+ ```
68
+
69
+ The installer registers this package as a local marketplace with Dcode, then invokes Dcode's own
70
+ `plugin install` command. The package is a native Agent Plugin: its root `plugin.json` contributes the shared skill, the
71
+ Hooks V2 `SessionStart`, `UserPromptSubmit`, and `Stop` lifecycle, and the namespaced
72
+ `hindsight_*` MCP server. Enable the plugin through Dcode's normal plugin manager; no Dcode config
73
+ patcher or compatibility bridge is required.
74
+
75
+ Dcode namespaces a plugin's MCP tools, so they appear as
76
+ `plugin__hindsight-coding-…__hindsight_…` rather than under their bare names — the agent resolves
77
+ them from the tool guide either way. In headless runs (`dcode -n`) Dcode allows the read-only
78
+ Hindsight tools and gates the two that write (`hindsight_ingest_document`,
79
+ `hindsight_capture_initiative`) behind an approval it has no UI for; use the interactive TUI to
80
+ capture an initiative or ingest a document. For the same reason the one-time codebase survey runs
81
+ under another installed agent's CLI when there is one, exactly as it does for Cursor, Copilot,
82
+ Devin, Grok Build, Cline, Kilo and Prime Agent.
83
+
56
84
  #### <img src="https://hindsight.vectorize.io/img/harness/opencode.png" alt="" width="20" height="20" /> opencode
57
85
 
58
86
  ```bash
@@ -61,6 +89,23 @@ npx @vectorize-io/hindsight-coding-agents install opencode
61
89
 
62
90
  A plugin entry in `~/.config/opencode/opencode.json` — native tools, no MCP needed.
63
91
 
92
+ #### <img src="https://hindsight.vectorize.io/img/harness/opencode.png" alt="" width="20" height="20" /> opencode 2
93
+
94
+ ```bash
95
+ npx @vectorize-io/hindsight-coding-agents install opencode2
96
+ ```
97
+
98
+ opencode v2 (`npm @opencode-ai/cli@beta`) installs its `opencode2` binary **alongside** v1 and
99
+ rewrote the plugin API, so it is a harness of its own. It writes the same plugin entry to the same
100
+ `~/.config/opencode/opencode.json` — the two CLIs share that file, and v1 rejects the whole config
101
+ if it sees v2's `plugins` key — and each CLI then loads its own entry point from the one registered
102
+ path. So installing either harness wires both, and uninstalling either removes the shared entry.
103
+
104
+ Two differences from v1, both because of the host: the one-time codebase survey runs under another
105
+ installed agent's CLI (v2 plugins cannot define the read-only agent the survey needs), and the seed
106
+ banner is written to the plugin log instead of a TUI toast (v2 plugins cannot raise one). Recall,
107
+ injection, the native `hindsight_*` tools and session write-back are identical.
108
+
64
109
  #### <img src="https://hindsight.vectorize.io/img/harness/kilo.svg" alt="" width="20" height="20" /> Kilo CLI
65
110
 
66
111
  ```bash
@@ -93,6 +138,20 @@ npx @vectorize-io/hindsight-coding-agents install grok-build
93
138
 
94
139
  Native hooks and MCP in `~/.grok/config.toml`, plus the companion skill.
95
140
 
141
+ #### <img src="https://hindsight.vectorize.io/img/harness/qwen-code.svg" alt="" width="20" height="20" /> Qwen Code
142
+
143
+ ```bash
144
+ npx @vectorize-io/hindsight-coding-agents install qwen-code
145
+ ```
146
+
147
+ Native hooks in `~/.qwen/settings.json`, plus MCP and the companion skill.
148
+
149
+ > Qwen's hook `timeout` is in **milliseconds** (its own docs: "Timeout in milliseconds, default
150
+ > 60000"), unlike every other supported agent, so the installed values are `30000/30000/60000`.
151
+ > Recall fires on genuine submissions only — `UserPromptSubmit` also fires on tool-result
152
+ > continuations, so interactive sessions recall once per prompt while headless (`qwen -p`),
153
+ > `serve`, SDK and ACP sessions seed and retain but do not recall.
154
+
96
155
  #### <img src="https://hindsight.vectorize.io/img/harness/antigravity-cli.png" alt="" width="20" height="20" /> Antigravity CLI
97
156
 
98
157
  ```bash
@@ -117,14 +176,35 @@ npx @vectorize-io/hindsight-coding-agents install cline-cli
117
176
 
118
177
  A native plugin via `cline plugin install`, plus MCP and the companion skill.
119
178
 
179
+ #### <img src="https://hindsight.vectorize.io/img/harness/pi.svg" alt="" width="20" height="20" /> pi
180
+
181
+ ```bash
182
+ npx @vectorize-io/hindsight-coding-agents install pi
183
+ ```
184
+
185
+ An extension entry in `~/.pi/agent/settings.json`, plus the companion skill in
186
+ `~/.pi/agent/skills` — native tools, no MCP needed.
187
+
188
+ This command is the only supported route, for pi and for Prime Agent below. Installing us as a pi
189
+ package (`pi install npm:@vectorize-io/hindsight-coding-agents`) is deliberately not wired: both
190
+ hosts read the same `pi` key of a package's `package.json`, and that key can only name one entry —
191
+ whichever host it did not name would load the other's bundle and report itself as the wrong agent,
192
+ taking that harness's config section and stamping every document it retains with it. So the package
193
+ carries no `pi` key at all, and each host is pointed at its own bundle by the install command above.
194
+
120
195
  #### <img src="https://hindsight.vectorize.io/img/harness/prime-agent.svg" alt="" width="20" height="20" /> Prime Agent
121
196
 
122
197
  ```bash
123
198
  npx @vectorize-io/hindsight-coding-agents install prime-agent
124
199
  ```
125
200
 
126
- An extension entry in `~/.prime/agent/settings.json` — native tools, no MCP needed — plus the
127
- companion skill in `~/.prime/agent/skills`.
201
+ Prime Agent is a fork of pi, so it is wired the same way: an extension entry, here in
202
+ `~/.prime/agent/settings.json`, plus the companion skill in `~/.prime/agent/skills` — native tools,
203
+ no MCP needed. Installing both is fine and expected:
204
+ each host loads its own entry from its own settings file, and like every other pair of agents they
205
+ **share one bank per repo** (the default `coding-agent::{gitProject}`), so what you tell pi is there
206
+ when you open Prime Agent. Separate entries are what keeps each side attributable — its own
207
+ `harnesses.<name>` config section, and its own agent stamped on every document it retains.
128
208
 
129
209
  #### <img src="https://hindsight.vectorize.io/img/harness/dsh.svg" alt="" width="20" height="20" /> DeepSeek Harness
130
210
 
@@ -160,12 +240,15 @@ removes only our entries. On Claude Code the install also ships a **companion sk
160
240
  "store this in hindsight" should do, the tool surface, per-repo configuration, debugging — so users
161
241
  can ask the agent itself. Manual wiring per harness, if you prefer:
162
242
 
163
- **opencode** installs directly — point `opencode.json` at the package dir:
243
+ **opencode** and **opencode 2** install directly — point `opencode.json` at the package dir:
164
244
 
165
245
  ```json
166
246
  { "plugin": ["/path/to/hindsight-coding-agents"] }
167
247
  ```
168
248
 
249
+ One entry, both CLIs: v1 resolves that directory through `package.json` `main`, v2 through its
250
+ `index.js`, so each loads its own plugin.
251
+
169
252
  **Claude Code** and **Codex** get their full three-hook + MCP wiring from this package's own
170
253
  installer — `npx @vectorize-io/hindsight-coding-agents install claude-code` / `install codex`. This package's `bin`
171
254
  entries (`hindsight-claude-hook`, `hindsight-codex-hook`,
@@ -209,14 +292,18 @@ transcripts are needed either way; going through them directly is simply the sho
209
292
  **How sessions are matched.** A conversation is imported only when the session itself records the
210
293
  directory it ran in — never inferred from a file or folder name. Claude Code writes that directory
211
294
  on its entries, Codex in its `session_meta` header and DeepSeek Harness in its session-log header,
212
- so all three can be attributed exactly, including sessions started in a subdirectory of the repo. Guessing was tempting (Claude names its history
295
+ and pi and Prime Agent in their session header, so all five can be attributed exactly, including
296
+ sessions started in a subdirectory of the repo. Guessing was tempting (Claude names its history
213
297
  folders after the project path) but unsafe: `/` and `.` both encode to `-`, so `repo-sub` is either
214
298
  the subdirectory `repo/sub` or an unrelated sibling repo — and a wrong guess files someone else's
215
299
  conversation into your bank. Sessions that record nothing are skipped and the count is reported.
216
300
  DeepSeek Harness logs are Zstandard-framed JSONL under `$DSH_HOME/sessions`, which needs Node 22.15+
217
- to read; an older Node skips the import with that reason rather than silently importing nothing. The
218
- other harnesses (opencode, Kilo, Cursor, Cline, Copilot, Devin) keep history in internal SQLite
219
- databases with unversioned schemas and are skipped with a reason.
301
+ to read; an older Node skips the import with that reason rather than silently importing nothing.
302
+ Dcode's transcripts record no directory at all — the working directory lives only in its LangGraph
303
+ checkpoint database — so the repo comes from `dcode threads list --json`, a declared, versioned
304
+ command contract rather than that internal schema; with the `dcode` CLI unavailable the import is
305
+ skipped with that reason. The other harnesses (opencode, opencode 2, Kilo, Cursor, Cline, Copilot, Devin) keep
306
+ history in internal SQLite databases with unversioned schemas and are skipped with a reason.
220
307
 
221
308
  **Nothing else is translated.** The old plugin's behavioural settings — 12 `recall*`, 7 `retain*`,
222
309
  `bankMission`/`retainMission`, `dynamicBankGranularity` — describe a pipeline this package replaced,
@@ -259,7 +346,6 @@ Nothing to sign up for and nothing to host — memory runs on your machine. The
259
346
  same error handling and the same diagnostics. Nothing downstream of the URL knows which mode it is.
260
347
  - **It keeps running** until you stop it. There is deliberately no stop-on-exit: one daemon is
261
348
  shared, so ending one session must not cut memory out from under another agent still working.
262
- Set `daemonIdleTimeout` to have it exit after that many seconds of inactivity.
263
349
  - **macOS additionally needs a current Rust toolchain.** `litellm` (a transitive dependency of the
264
350
  API) publishes wheels only for Linux and Windows, so a Mac compiles it from source through
265
351
  maturin and its crates pin a recent `rustc`. Install from [rustup.rs](https://rustup.rs) and keep
@@ -274,14 +360,14 @@ Nothing to sign up for and nothing to host — memory runs on your machine. The
274
360
  Daemon settings keep the names the old per-agent Claude Code plugin used, so an existing
275
361
  environment carries over unchanged:
276
362
 
277
- | field | env | default | meaning |
278
- | ------------------- | ------------------------------- | -------------- | ------------------------------------------ |
279
- | `serverMode` | `HINDSIGHT_SERVER_MODE` | `cloud` | `cloud` \| `self-hosted` \| `daemon` |
280
- | `apiPort` | `HINDSIGHT_API_PORT` | `9077` | port the local daemon listens on |
281
- | `daemonIdleTimeout` | `HINDSIGHT_DAEMON_IDLE_TIMEOUT` | — | seconds of inactivity before it exits |
282
- | `daemonProfile` | `HINDSIGHT_DAEMON_PROFILE` | `coding-agent` | which local database it uses |
283
- | `embedVersion` | `HINDSIGHT_EMBED_VERSION` | `latest` | which `hindsight-embed` release to run |
284
- | `embedPackagePath` | `HINDSIGHT_EMBED_PACKAGE_PATH` | — | run a local checkout instead (development) |
363
+ | field | env | default | meaning |
364
+ | ------------------- | ------------------------------- | -------------- | ---------------------------------------------------------- |
365
+ | `serverMode` | `HINDSIGHT_SERVER_MODE` | `cloud` | `cloud` \| `self-hosted` \| `daemon` |
366
+ | `apiPort` | `HINDSIGHT_API_PORT` | `9077` | port the local daemon listens on |
367
+ | `daemonIdleTimeout` | `HINDSIGHT_DAEMON_IDLE_TIMEOUT` | — | deprecated, ignored: the daemon no longer exits on its own |
368
+ | `daemonProfile` | `HINDSIGHT_DAEMON_PROFILE` | `coding-agent` | which local database it uses |
369
+ | `embedVersion` | `HINDSIGHT_EMBED_VERSION` | `latest` | which `hindsight-embed` release to run |
370
+ | `embedPackagePath` | `HINDSIGHT_EMBED_PACKAGE_PATH` | — | run a local checkout instead (development) |
285
371
 
286
372
  Any `HINDSIGHT_API_*` variable you export is forwarded to the daemon, so server-side settings need
287
373
  no equivalent here.
@@ -323,7 +409,7 @@ what reads it:
323
409
  | host | reads the file | an edit applies |
324
410
  | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------- |
325
411
  | 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 |
326
- | persistent plugins (opencode, Kilo CLI, Cline CLI, Prime Agent, DeepSeek Harness) | once per workspace, when the host loads the plugin | after restarting the agent |
412
+ | persistent plugins (opencode, opencode 2, Kilo CLI, Cline CLI, pi, Prime Agent, DeepSeek Harness) | once per workspace, when the host loads the plugin | after restarting the agent |
327
413
  | the MCP server behind the `hindsight_*` tools | once at startup | in your next session |
328
414
 
329
415
  `apiToken` is the exception. Every host re-reads it when the server rejects a request, so enabling
@@ -379,40 +465,42 @@ hook by Codex...), so one shared config serves several agents side by side:
379
465
 
380
466
  ### Reference
381
467
 
382
- | field | default | meaning |
383
- | ----------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
384
- | `apiUrl` | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server) |
385
- | `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 |
386
- | `bankId` | — | **explicit static bank**; unset ⇒ per-repo dynamic resolution (below) |
387
- | `dynamicBankId` | dynamic iff no `bankId` | force dynamic (`true`) or static (`false`) resolution |
388
- | `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo |
389
- | `mapPathToBank` | — | absolute path → bank; **longest prefix wins**; linked worktrees inherit their main checkout's mapping; overrides everything |
390
- | `optInOnly` | `false` | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see [Opt-in only](#opt-in-only) |
391
- | `optInPaths` | — | directories opted in, matched as prefixes with `~` expanded; each repo beneath and its linked worktrees are approved while keeping their own dynamic bank |
392
- | `resolveWorktrees` | `true` | linked worktrees inherit the main checkout's bank identity, path approval, and mapping |
393
- | `retainTags` | — | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
394
- | `retainMetadata` | — | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}` |
395
- | `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"]]` |
396
- | `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
397
- | `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) |
398
- | `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 |
399
- | `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 |
400
- | `autoReflect` | `true` | inject a one-time reflect synthesis on the session's **first prompt**. `false` = tool-only reflect: nothing is injected; the agent searches knowledge pages first and reflects only when they are too shallow |
401
- | `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
402
- | `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) |
403
- | `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 |
404
- | `autoSeed` | `true` | SessionStart: auto-seed a cold repo's bank from git history |
405
- | `seedLimit` | `300` | auto-seed: most-recent-N-commits cap |
406
- | `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 |
407
- | `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
408
- | `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
409
- | `surveyRefreshCommits` | `20` | re-run the survey at SessionStart once this many commits have accrued since the last one, so the structural pages track an architecture that keeps moving (`0` = survey a cold repo only, never again) |
410
- | `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 |
411
- | `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 |
412
- | `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
413
- | `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 |
414
- | `harnesses.<name>` | — | per-harness override of any field above |
415
- | `harness` | `opencode` | **deepen engine only**: which session format `--conversations` is read as |
468
+ | field | default | meaning |
469
+ | ----------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
470
+ | `apiUrl` | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server) |
471
+ | `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 |
472
+ | `bankId` | — | **explicit static bank**; unset ⇒ per-repo dynamic resolution (below) |
473
+ | `dynamicBankId` | dynamic iff no `bankId` | force dynamic (`true`) or static (`false`) resolution |
474
+ | `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo |
475
+ | `mapPathToBank` | — | absolute path → bank; **longest prefix wins**; linked worktrees inherit their main checkout's mapping; overrides everything |
476
+ | `optInOnly` | `false` | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see [Opt-in only](#opt-in-only) |
477
+ | `optInPaths` | — | directories opted in, matched as prefixes with `~` expanded; each repo beneath and its linked worktrees are approved while keeping their own dynamic bank |
478
+ | `resolveWorktrees` | `true` | linked worktrees inherit the main checkout's bank identity, path approval, and mapping |
479
+ | `retainTags` | — | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
480
+ | `retainMetadata` | — | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}` |
481
+ | `manageBankConfig` | `true` | let the plugin shape the bank's own configuration — the retain strategies it writes under, the `knowledge` entity-label group, and, on a bank that has none, the missions. Writing is strictly **additive**: it adds what the bank does not define and never overwrites what is there, so your control-plane edits survive. Set `false` to keep it out of the bank config entirely — see **A bank you shape yourself** below |
482
+ | `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"]]`; `"per_source"` adds a scope per `source:` kind alongside the global one, so commit knowledge and conversation knowledge consolidate apart |
483
+ | `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
484
+ | `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) |
485
+ | `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 |
486
+ | `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 |
487
+ | `autoReflect` | `true` | inject a one-time reflect synthesis on the session's **first prompt**. `false` = tool-only reflect: nothing is injected; the agent searches knowledge pages first and reflects only when they are too shallow |
488
+ | `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
489
+ | `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) |
490
+ | `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 |
491
+ | `autoSeed` | `true` | SessionStart: auto-seed a cold repo's bank from git history |
492
+ | `seedLimit` | `300` | auto-seed: most-recent-N-commits cap |
493
+ | `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 |
494
+ | `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
495
+ | `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
496
+ | `surveyRefreshCommits` | `20` | re-run the survey at SessionStart once this many commits have accrued since the last one, so the structural pages track an architecture that keeps moving (`0` = survey a cold repo only, never again) |
497
+ | `retainSessions` | `true` | session write-back, honored by every harness: hook harnesses write the transcript on Stop, plugin harnesses (opencode, opencode 2, 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 |
498
+ | `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 |
499
+ | `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
500
+ | `autoUpdate` | `true` | keep the installed runtime current by itself: once a day a session start asks npm for the published version and, when it is newer, re-stages `~/.hindsight/coding-agents` in the background. It rewires no host config, so a release adding a **new** hook entry point still needs a manual `install`. Set `false` to pin the installed version; `disabled` stops it too, since an inert plugin should stay inert. Only ever replaces a runtime installed the documented way, via `npx` — a copy installed with `npm i -g`, vendored as a project dependency, or built from a checkout is left to whoever manages it (update those the way you installed them), and it needs `npx` on `PATH` |
501
+ | `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 |
502
+ | `harnesses.<name>` | — | per-harness override of any field above |
503
+ | `harness` | `opencode` | **deepen engine only**: which session format `--conversations` is read as |
416
504
 
417
505
  `pageTriggerType`/`pageTriggerCron` decide only **when** a page refreshes. **How** it refreshes
418
506
  belongs to the server: Hindsight creates a knowledge page with a delta refresh (each pass edits the
@@ -425,6 +513,38 @@ repo already has: a page keeps the trigger it was created with, so a bank seeded
425
513
  through the API (`PATCH /knowledge-base/nodes/{id}`), an SDK, or the control plane — or delete it
426
514
  and let the next session seed it again.
427
515
 
516
+ ### A bank you shape yourself — `manageBankConfig`
517
+
518
+ Pointed at a bank, this plugin gives it the shape its ingestion needs: retain strategies for the
519
+ kinds of document it writes (`git`, `gitlog`, `conversation`, `document`, `survey`), a `knowledge`
520
+ entity-label group that routes facts to the knowledge pages, and — on a bank that has no missions of
521
+ its own — the coding missions.
522
+
523
+ **It only ever adds what is missing.** A strategy you defined, an edit you made to one of the
524
+ plugin's, a reworded label group, a mission you rewrote in the control plane: each is left exactly
525
+ as it is, on every session, forever. What the bank already says wins. The cost of that promise is
526
+ that a plugin release which _rewords_ an existing strategy or label does not reach a bank that
527
+ already has it. To take the current default back, clear that override on the bank (delete the
528
+ strategy, or the whole `retain_strategies` entry, in the control plane): the next session finds the
529
+ bank silent there and seeds it again.
530
+
531
+ Set `manageBankConfig: false` to keep the plugin out of the bank's configuration altogether — the
532
+ right setting for a bank you share with non-coding work, or one you configure yourself. That bank
533
+ should then define the five strategies above itself. Note that the miss is **silent**: the server
534
+ does not reject a retain naming a strategy the bank lacks, it logs a warning and extracts with the
535
+ bank's own configuration — so a commit diff, a session transcript and a survey marker would all get
536
+ the same generic treatment instead of the extraction each needs. Knowledge pages are seeded either
537
+ way; `pageTriggerType` governs what they cost.
538
+
539
+ Like every field here it can be set per bank, which is usually where it belongs:
540
+
541
+ ```json
542
+ {
543
+ "bankId": "my-global-bank",
544
+ "banks": { "my-global-bank": { "manageBankConfig": false } }
545
+ }
546
+ ```
547
+
428
548
  ### Per-repo opt-in/out — `banks.<bankId>`
429
549
 
430
550
  Per-repo control lives in the SAME file, keyed by the **resolved bank id** (shown in the session
@@ -545,6 +665,36 @@ scope per bank, which is what a bank already is — one project's memory. Set th
545
665
  }
546
666
  ```
547
667
 
668
+ ### Splitting code from conversation — `per_source`
669
+
670
+ `shared` puts every document a repo produces into one belief set. `"per_source"` keeps that set and
671
+ adds one per origin, so "what the commits say" and "what was decided in conversation" can be asked
672
+ apart:
673
+
674
+ ```jsonc
675
+ { "observationScopes": "per_source" }
676
+ ```
677
+
678
+ Each document consolidates into the global scope **plus** one named for each `source:` tag it
679
+ carries — `[[], ["source:chat"]]` for a session transcript, `[[], ["source:git"]]` for a commit
680
+ diff. Read an axis back with `tags: ["source:git"], tags_match: "exact"`, and the merged view with
681
+ `tags: [], tags_match: "exact"`.
682
+
683
+ A document carrying two `source:` tags gets a scope for each, and that is deliberate rather than
684
+ duplication. The commit-message seed is tagged `source:git` and `source:git-log`, so
685
+ `source:git-log` is fed only by the seed — what the commit _messages_ say — while `source:git` also
686
+ collects every per-commit diff under `gitIngest: "full"`. Two questions, two answers, each
687
+ deduplicated within itself by consolidation. A fact belonging to more than one axis is the point.
688
+
689
+ This cannot be expressed as a scope list. The server treats an explicit `list[list[str]]` as
690
+ unconditional — it is not filtered against the memory's own tags — so a configured
691
+ `[[], ["source:git"], ["source:chat"]]` writes every document into all three, and the `source:git`
692
+ scope fills with beliefs built from chat transcripts. Only a per-document decision separates them.
693
+
694
+ It costs one extra consolidation pass per document, and it reads only `source:`, so a volatile
695
+ provenance tag never becomes a scope. The global scope is still written first and unchanged, so the
696
+ untagged observations knowledge pages read are unaffected.
697
+
548
698
  `"per_tag"` and `"all_combinations"` split further still, and an explicit `[["project:demo"], …]`
549
699
  declares the scopes literally. `HINDSIGHT_OBSERVATION_SCOPES` sets the scalar modes; a scope list is
550
700
  file-only. Changing this does not rewrite observations already consolidated under the old scoping —