@vectorize-io/hindsight-coding-agents 0.7.0 → 0.8.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 (62) hide show
  1. package/README.md +201 -16
  2. package/dist/antigravity-hook.js +1132 -115
  3. package/dist/antigravity-statusline.js +77 -11
  4. package/dist/antigravity-stop-hook.js +1193 -133
  5. package/dist/claude-hook.js +1132 -115
  6. package/dist/claude-sessionstart-hook.js +1241 -140
  7. package/dist/claude-stop-hook.js +1193 -133
  8. package/dist/cline.js +578 -163
  9. package/dist/codebuddy-hook.js +4270 -0
  10. package/dist/codebuddy-sessionstart-hook.js +5030 -0
  11. package/dist/codebuddy-stop-hook.js +4564 -0
  12. package/dist/codex-hook.js +1132 -115
  13. package/dist/codex-sessionstart-hook.js +1241 -140
  14. package/dist/codex-stop-hook.js +1193 -133
  15. package/dist/copilot-hook.js +1132 -115
  16. package/dist/copilot-sessionstart-hook.js +1241 -140
  17. package/dist/copilot-stop-hook.js +1193 -133
  18. package/dist/cursor-hook.js +1132 -115
  19. package/dist/cursor-sessionstart-hook.js +1241 -140
  20. package/dist/cursor-stop-hook.js +1193 -133
  21. package/dist/daemon-start.js +54 -9
  22. package/dist/dcode-hook.js +1132 -115
  23. package/dist/dcode-sessionstart-hook.js +1241 -140
  24. package/dist/dcode-stop-hook.js +1193 -133
  25. package/dist/deepen.js +370 -104
  26. package/dist/devin-hook.js +1132 -115
  27. package/dist/devin-sessionstart-hook.js +1241 -140
  28. package/dist/devin-stop-hook.js +1193 -133
  29. package/dist/droid-hook.js +1132 -115
  30. package/dist/droid-sessionstart-hook.js +1241 -140
  31. package/dist/droid-stop-hook.js +1193 -133
  32. package/dist/dsh.js +586 -164
  33. package/dist/grok-hook.js +1132 -115
  34. package/dist/grok-sessionstart-hook.js +1241 -140
  35. package/dist/grok-stop-hook.js +1193 -133
  36. package/dist/hindsight-seed.js +50 -8
  37. package/dist/index.js +587 -172
  38. package/dist/installer.js +2010 -769
  39. package/dist/kilo.js +587 -172
  40. package/dist/kimi-hook.js +4270 -0
  41. package/dist/kimi-sessionstart-hook.js +5030 -0
  42. package/dist/kimi-stop-hook.js +4564 -0
  43. package/dist/mcp-server.js +419 -115
  44. package/dist/opencode2.js +586 -169
  45. package/dist/pi.js +644 -175
  46. package/dist/prime-agent.js +644 -175
  47. package/dist/qwen-hook.js +1132 -115
  48. package/dist/qwen-sessionstart-hook.js +1241 -140
  49. package/dist/qwen-stop-hook.js +1193 -133
  50. package/dist/status.js +243 -52
  51. package/dist/traecode-hook.js +4270 -0
  52. package/dist/traecode-sessionstart-hook.js +5030 -0
  53. package/dist/traecode-stop-hook.js +4564 -0
  54. package/dist/workbuddy-hook.js +4270 -0
  55. package/dist/workbuddy-sessionstart-hook.js +5030 -0
  56. package/dist/workbuddy-stop-hook.js +4564 -0
  57. package/dist/zcode-hook.js +1132 -115
  58. package/dist/zcode-sessionstart-hook.js +1241 -140
  59. package/dist/zcode-stop-hook.js +1193 -133
  60. package/package.json +22 -12
  61. package/plugin.json +1 -1
  62. package/skill/SKILL.md +73 -14
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
- (**Claude Code**, **Codex CLI**, **DeepAgents Dcode**, **opencode**, **opencode 2**, **Kilo CLI**, **Cursor CLI**, **GitHub Copilot CLI**, **Grok Build**, **Qwen Code**, **Factory Droid**, **ZCode**, **Antigravity CLI**, **Devin CLI**, **Cline CLI**, **pi**, **Prime Agent**, **DeepSeek Harness**). Ingestion is fully
5
+ (**Claude Code**, **Codex CLI**, **DeepAgents Dcode**, **opencode**, **opencode 2**, **Kilo CLI**, **Cursor CLI**, **GitHub Copilot CLI**, **Grok Build**, **Qwen Code**, **Kimi Code**, **Factory Droid**, **ZCode**, **TraeCode**, **Antigravity CLI**, **Devin CLI**, **Cline CLI**, **pi**, **Prime Agent**, **DeepSeek Harness**, **WorkBuddy**, **CodeBuddy**). 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
 
@@ -16,6 +16,33 @@ in front of the agent at the moment it starts working, and keeps a curated set o
16
16
 
17
17
  [View Changelog →](https://hindsight.vectorize.io/changelog/integrations/coding-agents)
18
18
 
19
+ ## Does it work?
20
+
21
+ [AMB's sdebench](https://agentmemorybenchmark.ai/dataset/sdebench) is the measurement: a coding
22
+ agent over 61 real repository tasks, three runs each, with and without memory.
23
+
24
+ Accuracy is not what moves — every run solves 60–61 of the 61 either way. These are tasks a good
25
+ agent can already do. What memory changes is how much it costs you to get there: how often you have
26
+ to stop and correct the agent, and what the tokens cost.
27
+
28
+ <!-- figure: coding-agents-benchmark -->
29
+
30
+ | Agent | Corrections / task | Cost / task |
31
+ | ----------- | ------------------ | ------------------- |
32
+ | Claude Code | 0.85 → **0.36** | $0.445 → **$0.338** |
33
+ | Codex CLI | 1.34 → **0.47** | $0.577 → **$0.276** |
34
+ | opencode | 1.20 → **0.80** | $0.634 → **$0.553** |
35
+
36
+ No memory → with Hindsight, mean of 3 runs. Corrections reproduce the labels AMB prints on its own
37
+ chart; cost is derived from the same per-run table.
38
+
39
+ Both numbers move together, and that is the mechanism rather than a coincidence. A correction is a
40
+ round trip: the agent guesses a project-specific decision wrong, you stop it, you explain, it redoes
41
+ the work. Every one of those costs a turn of tokens and a turn of your attention. Handing the agent
42
+ the decision _before_ it starts — the rounding rule, the retry allowlist, the tie-break policy that
43
+ was settled in a commit message or a conversation months ago — removes the guess, and the round trip
44
+ with it.
45
+
19
46
  ## Install
20
47
 
21
48
  <!-- skill:begin title="Install / update" -->
@@ -143,7 +170,11 @@ npx @vectorize-io/hindsight-coding-agents install copilot-cli
143
170
  npx @vectorize-io/hindsight-coding-agents install grok-build
144
171
  ```
145
172
 
146
- Native hooks and MCP in `~/.grok/config.toml`, plus the companion skill.
173
+ Native hooks in `~/.grok/hooks/hindsight.json`, MCP in `~/.grok/config.toml`, plus the companion
174
+ skill. Grok also runs Claude Code's hooks from `~/.claude/settings.json`; those stay silent inside
175
+ Grok, so a machine wired for both hosts records each Grok session once. Grok passes hook context to
176
+ the model only from tool hooks, so the session and prompt context arrive with the result of the
177
+ agent's first tool call after each prompt (a `PostToolUse` hook).
147
178
 
148
179
  #### <img src="https://hindsight.vectorize.io/img/harness/qwen-code.svg" alt="" width="20" height="20" /> Qwen Code
149
180
 
@@ -159,6 +190,19 @@ Native hooks in `~/.qwen/settings.json`, plus MCP and the companion skill.
159
190
  > continuations, so interactive sessions recall once per prompt while headless (`qwen -p`),
160
191
  > `serve`, SDK and ACP sessions seed and retain but do not recall.
161
192
 
193
+ #### <img src="https://hindsight.vectorize.io/img/harness/kimi-code.svg" alt="" width="20" height="20" /> Kimi Code
194
+
195
+ ```bash
196
+ npx @vectorize-io/hindsight-coding-agents install kimi-code
197
+ ```
198
+
199
+ Native hooks in `~/.kimi-code/config.toml`, plus MCP in `~/.kimi-code/mcp.json` and the companion skill.
200
+ (Hooks and MCP go under `$KIMI_CODE_HOME` instead when it is set.)
201
+
202
+ > Kimi's SessionStart hook cannot reach the model, so the session briefing is silent there;
203
+ > recalled memory arrives on the first prompt instead, as a `<hook_result>` block. Sessions are
204
+ > retained from every agent's `wire.jsonl` under the session directory, subagents included.
205
+
162
206
  #### <img src="https://hindsight.vectorize.io/img/harness/factory-droid.svg" alt="" width="20" height="20" /> Factory Droid
163
207
 
164
208
  ```bash
@@ -198,6 +242,56 @@ refuses to touch an MCP server named `hindsight` that it did not write.
198
242
  > appending each new turn to the same session document. `--import-conversations` is therefore not
199
243
  > available for ZCode: there is no past history on disk to backfill from.
200
244
 
245
+ #### <img src="https://hindsight.vectorize.io/img/harness/traecode.png" alt="" width="20" height="20" /> TraeCode
246
+
247
+ ```bash
248
+ npx @vectorize-io/hindsight-coding-agents install traecode
249
+ ```
250
+
251
+ Three hook registrations in TraeCode's user-level `hooks.json`, the companion skill under the
252
+ same dot-dir's `skills/`, and two `filesystem.readWrite` rules in `sandbox.json` — one for
253
+ `~/.hindsight`, without which the hooks fail silently (exit 0, no effect) because the sandbox
254
+ blocks those writes, and one for Trae's per-window storage DBs
255
+ (`<userData>/User/workspaceStorage`), which the SessionStart hook seeds with the workspace's
256
+ MCP enable switch. Network is allowed by default. TRAE ships two editions with different brand
257
+ roots — the CN build uses `~/.trae-cn` and "Trae CN", the international build `~/.trae` and
258
+ "Trae" — so every path resolves by probing for the edition dir that exists and defaulting to the
259
+ CN names. Plain JSON files, no CLI round-trip. TraeCode speaks Claude Code's hook protocol, so
260
+ recall and injection work exactly as they do there; the event map lives under the top-level
261
+ `hooks` key and the `version` field the host writes is preserved.
262
+
263
+ MCP is registered per repo, never at the user level: Trae launches user-level servers with the
264
+ Electron process's cwd (your home directory), where a hindsight entry either self-disables under
265
+ `optInOnly` (zero tools) or resolves the home bank instead of the repo's. So the installer
266
+ pre-seeds the per-repo registration for every repo opted in via `mapPathToBank` — a
267
+ `mcpServers.hindsight` stdio server in `<repo>/.trae/mcp.json`, pinned to that repo via
268
+ `HINDSIGHT_MCP_PROJECT_CWD` — migrates any stale user-level entry back out of
269
+ `<userData>/User/mcp.json`, and seeds the per-workspace enable switch directly. The SessionStart
270
+ hook re-checks both on every session and writes them only when missing or stale (idempotent
271
+ fallback) — Trae's hook sandbox cannot be relied on to perform those writes itself. The per-repo
272
+ file is merged not clobbered, and gitignored when the repo has a `.gitignore` (the path is
273
+ machine-specific). A foreign `hindsight` entry — in either file — is the user's own server and
274
+ is never touched.
275
+
276
+ Trae only reads that per-repo file once the global `trae.mcp.enableWorkspaceMcp` setting is on
277
+ (default off), so the installer handles the gate: an interactive run asks, a non-interactive run
278
+ takes `--enable-workspace-mcp`, and either way the setting is written and Trae windows must be
279
+ restarted to pick it up (declining, or a settings file with comments, prints the manual step).
280
+ Registrations and enable switches take effect on the NEXT window, so the MCP tools appear when
281
+ you reload after the first session; repos opted into `mapPathToBank` after install need one more
282
+ `install traecode` run, and if a repo's server still shows disabled in the MCP panel, flip it on
283
+ once there.
284
+
285
+ > One manual step remains after install (UI state the installer cannot write): enable the hooks
286
+ > under TraeCode Settings > Hooks. If you declined the workspace-MCP prompt, enable it later in
287
+ > Trae settings (search "enableWorkspaceMcp").
288
+
289
+ > TraeCode keeps no readable session transcript - sessions live in an encrypted local DB or the
290
+ > cloud. Like ZCode, its conversation is journaled by the plugin itself: the prompt hook records
291
+ > what you asked, and the `Stop` hook closes the turn with the reply it carries in
292
+ > `last_assistant_message`. `--import-conversations` is therefore not available for TraeCode:
293
+ > there is no past history on disk to backfill from.
294
+
201
295
  #### <img src="https://hindsight.vectorize.io/img/harness/antigravity-cli.png" alt="" width="20" height="20" /> Antigravity CLI
202
296
 
203
297
  ```bash
@@ -269,6 +363,38 @@ too: the package ships the profile patch layer, so nothing else needs editing. E
269
363
  companion skill — a plugin wired by the host's own plugin manager installs it itself on the first
270
364
  session, since that route never runs our installer.
271
365
 
366
+ #### <img src="https://hindsight.vectorize.io/img/harness/workbuddy.png" alt="" width="20" height="20" /> WorkBuddy
367
+
368
+ ```bash
369
+ npx @vectorize-io/hindsight-coding-agents install workbuddy
370
+ ```
371
+
372
+ 3 hooks in `~/.workbuddy/settings.json`, the stdio MCP server in `~/.workbuddy/mcp.json`, and the
373
+ companion skill in `~/.workbuddy/skills`. WorkBuddy (Tencent's AI workbench) is built on the shared
374
+ `@genie/agent-cli` engine, so its hooks follow Claude Code's protocol — the main difference is the
375
+ transcript schema (`type:"message"` records carrying top-level `role`/`content`), which the
376
+ package's own reader normalizes.
377
+
378
+ #### <img src="https://hindsight.vectorize.io/img/harness/codebuddy.png" alt="" width="20" height="20" /> CodeBuddy
379
+
380
+ ```bash
381
+ npx @vectorize-io/hindsight-coding-agents install codebuddy
382
+ ```
383
+
384
+ 3 hooks in `~/.codebuddy/settings.json`, the stdio MCP server in `~/.codebuddy/.mcp.json` — the
385
+ recommended file: the installer follows CodeBuddy's documented fallback chain, merging into an
386
+ existing deprecated `~/.codebuddy/mcp.json` or legacy `~/.codebuddy.json` rather than shadowing it —
387
+ and the companion skill in `~/.codebuddy/skills`. CodeBuddy Code runs the same `@genie/agent-cli`
388
+ engine as WorkBuddy — WorkBuddy merely ships it with a different home folder — so it reuses
389
+ WorkBuddy's hook runtime, and differs only in the root it writes to.
390
+
391
+ **Both CodeBuddy hosts are covered, and they do not store sessions alike.** CodeBuddy Code (the CLI)
392
+ writes the WorkBuddy JSONL that the shared reader parses. The IDE hands the Stop hook its own
393
+ per-conversation directory instead — `CodeBuddyIDE/<uid>/history/<md5(workspace)>/<conversationId>/`,
394
+ whose `index.json` _is_ the `transcript_path` and whose prose sits one level down, in
395
+ `messages/<messageId>.json` — so the reader dispatches on the shape it was handed
396
+ (core/transcript-codebuddy-ide.ts).
397
+
272
398
  Uninstall the same way: `npx @vectorize-io/hindsight-coding-agents uninstall claude-code` (or `uninstall all`).
273
399
 
274
400
  **Devin CLI needs Node 22.5 or newer.** Its hooks pass only a session id — the conversation itself
@@ -433,14 +559,16 @@ Configuration is **one JSON file**: `~/.hindsight/coding-agent.json`. Layering,
433
559
  (`HINDSIGHT_<FIELD_IN_CAPS>`), for containers and CI that inject config rather than write a file
434
560
  3. the file's top level
435
561
  4. its `harnesses.<name>` section — per-agent override
436
- 5. its `banks.<resolvedBankId>` section — per-repo override, applied after the bank is resolved
562
+ 5. its `paths.<prefix>` section — per-directory override, applied after the bank is resolved
563
+ (see [Per-directory overrides](#per-directory-overrides--pathsprefix))
564
+ 6. its `banks.<resolvedBankId>` section — per-repo override, applied after the bank is resolved
437
565
  (see [Per-repo opt-in/out](#per-repo-opt-inout--banksbankid))
438
566
 
439
567
  Environment variables are a **fallback**: the file wins wherever it sets a value, so adding env to
440
568
  an existing setup changes nothing. The two list-valued settings, `retainTags` and `optInPaths`, take
441
569
  a comma-separated value (`HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work"`); entries are
442
570
  trimmed and blanks dropped.
443
- The map-valued settings (`mapPathToBank`, `harnesses`, `banks`, `retainMetadata`) are file-only —
571
+ The map-valued settings (`mapPathToBank`, `harnesses`, `paths`, `banks`, `retainMetadata`) are file-only —
444
572
  per-key branching doesn't survive flattening into one variable. `maxParallelRetains` is available
445
573
  as `HINDSIGHT_MAX_PARALLEL_RETAINS` for containers and CI.
446
574
 
@@ -526,18 +654,22 @@ hook by Codex...), so one shared config serves several agents side by side:
526
654
  | `resolveWorktrees` | `true` | linked worktrees inherit the main checkout's bank identity, path approval, and mapping |
527
655
  | `retainTags` | — | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
528
656
  | `retainMetadata` | — | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}` |
657
+ | `retainContext` | see description | the `context` sent with every session write-back. Extraction reads it to decide whose claim a sentence is, so the default names both speakers, and asks for an agent's own "fixed" or "passes" to be stored as its claim rather than as fact. Accepts the same `{placeholder}` templates as `retainTags` |
529
658
  | `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 **additive**: it adds what the bank does not define and never overwrites what is there, so your control-plane edits survive — the one exception is the extraction mode of its own strategies, which follows `retainExtractionMode`. Set `false` to keep it out of the bank config entirely — see **A bank you shape yourself** below |
530
659
  | `retainExtractionMode` | `"concise"` | how the server extracts memories from sessions, commits and documents: `"concise"`, `"verbose"`, `"verbatim"` or `"chunks"` (store the text, no extraction). Every Stop writes the session back, so this is what each turn costs — `"verbose"` pulls more detail for several times the tokens. Kept in sync on the plugin's own retain strategies every session, so a change reaches existing banks too (not with `manageBankConfig: false`) |
660
+ | `defaultBankConfig` | — | bank-config fields of your own for the banks the plugin shapes, e.g. `{"enable_observations": false, "enable_auto_consolidation": false, "mental_model_min_refresh_interval_seconds": 21600}`. Keys are the bank-config API's own field names. Written under the same additive rule as the rest: only where the bank does not define the field, so a bank the plugin creates is born with these instead of the server's defaults and a value you set in the control plane is never overwritten. Wins over the template on a key both name (`enable_observations`); `retain_strategies`, `entity_labels` and `retain_extraction_mode` are refused, since the plugin governs them itself. Ignored with `manageBankConfig: false` — see **A bank you shape yourself** below. File-only, like `recallOptions`; in a `banks.<id>` section it replaces the global map rather than merging into it |
531
661
  | `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 |
532
662
  | `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
533
663
  | `reflectTimeoutMs` | `20000` | **automatic** session-reflect timeout; on hook harnesses the installer registers a 30s prompt-hook timeout, so going above ~20s also means raising that hook's `timeout` in the host's config, or the host kills the hook mid-reflect; on timeout or a 5xx the hook falls back to knowledge-page search, then to a raw recall of observations (recorded) |
534
664
  | `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 |
665
+ | `injectTimeoutMs` | `7000` | retrieval timeout in milliseconds for `autoInject: "pages"` and `autoInject: "recall"`; also the **shared** budget for page search then recall after a reflect timeout/5xx (recall gets only the time left after page search). Set e.g. `2000` to limit turn latency or `15000` for a slower self-hosted bank. Environment fallback: `HINDSIGHT_INJECT_TIMEOUT_MS`. On hook harnesses, injection must fit the host's prompt-hook timeout (30s by default); for reflect with fallback, allow for **`reflectTimeoutMs` + `injectTimeoutMs`**, and raise the host hook's `timeout` when needed |
535
666
  | `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 |
536
- | `autoInject` | `"reflect"` | what to inject once, on the session's **first prompt**: `"reflect"` = a low-budget reflect synthesis (on timeout/5xx it falls back to page search, then recall); `"pages"` = the knowledge pages matching the prompt by search; `"recall"` = the bank's memories recalled for the prompt (what it asks for is `recallOptions`, observations by default); `"none"` = nothing — the agent searches knowledge pages first and reflects only when they are too shallow. `"pages"` and `"recall"` are retrieval only (no LLM), so they stay well inside the hook window |
667
+ | `autoInject` | `"reflect"` | what to inject once, on the session's **first prompt**: `"reflect"` = a low-budget reflect synthesis (on timeout/5xx it falls back to page search, then recall); `"pages"` = the knowledge pages matching the prompt by search; `"recall"` = the bank's memories recalled for the prompt (what it asks for is `recallOptions`, observations by default); `"none"` = nothing — the agent searches knowledge pages first and reflects only when they are too shallow. `"pages"` and `"recall"` are retrieval only (no LLM), their time budget is `injectTimeoutMs`, and when one finds nothing for the prompt it tries again on the next one, up to 5 prompts |
537
668
  | `autoReflect` | `true` | **deprecated** — use `autoInject`. Still honoured (`false` = `autoInject: "none"`), ignored when `autoInject` is set, and logs a deprecation warning |
538
669
  | `pageSearchLimit` | `3` | knowledge pages ONE search returns. Applies to every search of the bank — the `autoInject: "pages"` injection, the reflect fallback, and the agent's own `hindsight_search_knowledge_pages` tool — because the limit lives on the client they all share |
539
670
  | `recallOptions` | see description | overrides merged key-by-key into the body of every recall — the `autoInject: "recall"` source and the reflect fallback. Keys are the API's own recall parameters, passed straight through, so anything recall accepts is settable without a new option here; `query` is the one field it cannot replace. The default body is `{"types": ["observation"], "budget": "low", "max_tokens": 2000, "include": {"entities": null}}`, and what you set is merged over it one key at a time — `{"max_tokens": 4000}` changes the budget and leaves the rest alone. Observations are the consolidated layer, so they answer best per token, but a bank with **consolidation disabled never grows any** and the default recall comes back empty on it: set `{"types": ["world", "experience"]}` there, or `{"types": null}` for every type. File-only, like `retainMetadata` — an object does not flatten into an env var |
540
- | `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
671
+ | `toolGuideExtra` | — | your own guidance on how the agent should treat memory, added **after** the built-in tool guide (at session start and on every refresh) and after the crediting note returned with `hindsight_search_knowledge_pages` results. It adds to the built-in text, never replaces it. Set it per harness or per bank like any other key, e.g. `"Memory is a past record, not current state: verify any claim against the code before acting on it."` |
672
+ | `pageRefreshEveryTurns` | `1` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns (`0` also means 1) |
541
673
  | `pageTriggerType` | `"cron"` | when NEW knowledge pages refresh, i.e. what keeping them current costs — `"cron"` (default) on `pageTriggerCron` only and only when actually stale, `"auto-refresh"` after every consolidation that produced new material, `"manual"` never on their own. Auto-refresh is the most current and by far the most expensive: one synthesis per page per consolidation. Maps to the page's `trigger.refresh_cron`, or `trigger.refresh_after_consolidation` in the Hindsight API (`true` for auto-refresh, `false` for manual) |
542
674
  | `pageTriggerCron` | `"H * * * *"` | schedule for `pageTriggerType: "cron"` — UTC, standard 5-field cron, e.g. `"0 3 * * *"`. The default is hourly, each page on its own hashed minute. 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. Write a field as `H` to give each page its own value there — see **Spreading refreshes with `H`** below |
543
675
  | `pages` | every page | per-page configuration for the seeded knowledge pages, keyed by page name (case-insensitive): `false` skips a page entirely, `{"source_query": "..."}` seeds it with your question instead of the built-in one. Omitted, all five pages are seeded with their built-in queries. This is the supported way to own a page's wording — the plugin re-syncs a page whose live query differs from the one it is configured to have, so a query edited through the API or the control plane is replaced on the next session. A skipped page is **not deleted**: one already seeded keeps its content and stops being re-synced. The scoping clause is appended to your query too, so a reworded page cannot start reporting a dependency's decisions as this project's. File-only, like `recallOptions`; in a `banks.<id>` section it replaces the global map rather than merging into it |
@@ -552,7 +684,7 @@ hook by Codex...), so one shared config serves several agents side by side:
552
684
  | `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 |
553
685
  | `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
554
686
  | `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` and `npm` on `PATH` |
555
- | `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 |
687
+ | `gitIngest` | `"message"` | git depth for seeding AND staying current (same engine): `"message"` = commit messages only (one doc, re-upserted when HEAD has a commit it lacks); `"full"` = messages + per-commit full diffs (progressive, newest first); `"none"` = git off |
556
688
  | `harnesses.<name>` | — | per-harness override of any field above |
557
689
  | `harness` | `opencode` | **deepen engine only**: which session format `--conversations` is read as |
558
690
 
@@ -738,13 +870,40 @@ One field is the exception: the extraction mode of the plugin's own four strateg
738
870
  if it drifts — the same way a seeded page's query is. Change it in `coding-agent.json`, not in the
739
871
  control plane. The strategies' other fields, and your own strategies, are still left alone.
740
872
 
741
- Set `manageBankConfig: false` to keep the plugin out of the bank's configuration altogether — the
742
- right setting for a bank you share with non-coding work, or one you configure yourself. That bank
743
- should then define the five strategies above itself. Note that the miss is **silent**: the server
744
- does not reject a retain naming a strategy the bank lacks, it logs a warning and extracts with the
745
- bank's own configuration — so a commit diff, a session transcript and a survey marker would all get
746
- the same generic treatment instead of the extraction each needs. Knowledge pages are seeded either
747
- way; `pageTriggerType` governs what they cost.
873
+ **Your own defaults for new banks — `defaultBankConfig`.** Everything the template does not name, a
874
+ bank the plugin creates gets from the server: auto-consolidation on, observations on, a 60s floor
875
+ between mental-model refreshes. With one bank per repo those are the settings that cost money, and
876
+ a new repo an agent touches spawns a new bank with all of them switched on — while every bank you had
877
+ hand-tuned in the control plane sits at a cheaper baseline. `defaultBankConfig` names the baseline
878
+ once, in the plugin's config, and it travels in the same import that creates the bank:
879
+
880
+ ```json
881
+ {
882
+ "defaultBankConfig": {
883
+ "enable_observations": false,
884
+ "enable_auto_consolidation": false,
885
+ "mental_model_min_refresh_interval_seconds": 21600
886
+ }
887
+ }
888
+ ```
889
+
890
+ The keys are the bank-config API's own field names, passed straight through, so anything the
891
+ bank-config accepts can go here. They follow the same additive rule as the template: written only
892
+ where the bank is silent, so an existing bank picks them up on its next session **except** for the
893
+ fields it already sets — a value you chose in the control plane stays, even one equal to the server
894
+ default, and so does a value an earlier plugin release seeded (the template writes
895
+ `enable_observations: true` alongside the missions; clear that override on the bank to let your
896
+ default in). On a key the template also names, your default wins. The three fields the plugin
897
+ governs itself — `retain_strategies`, `entity_labels` and `retain_extraction_mode` — are refused
898
+ with a warning: the first two are merged entry by entry, the last is `retainExtractionMode`'s.
899
+
900
+ Set `manageBankConfig: false` to keep the plugin out of the bank's configuration altogether,
901
+ `defaultBankConfig` included — the right setting for a bank you share with non-coding work, or one
902
+ you configure yourself. That bank should then define the five strategies above itself. Note that the
903
+ miss is **silent**: the server does not reject a retain naming a strategy the bank lacks, it logs a
904
+ warning and extracts with the bank's own configuration — so a commit diff, a session transcript and
905
+ a survey marker would all get the same generic treatment instead of the extraction each needs.
906
+ Knowledge pages are seeded either way; `pageTriggerType` governs what they cost.
748
907
 
749
908
  Like every field here it can be set per bank, which is usually where it belongs:
750
909
 
@@ -804,6 +963,32 @@ every repo (present and future) beneath it:
804
963
  Rule of thumb: converge by **id** for a hand-picked set of repos; map by **path** when a folder is
805
964
  the boundary ("everything I clone under `work/client-x` shares memory").
806
965
 
966
+ ### Per-directory overrides — `paths.<prefix>`
967
+
968
+ When a folder is the boundary for something other than the bank — typically a different server
969
+ or tenant for client work — key the override by directory instead of by bank id:
970
+
971
+ ```jsonc
972
+ {
973
+ "apiToken": "personal-key",
974
+ "paths": {
975
+ "~/work/client-x": { "apiToken": "client-x-key" },
976
+ "~/work/acme": { "apiUrl": "https://hindsight.acme.internal", "apiToken": "acme-key" },
977
+ "~/oss": { "serverMode": "daemon" },
978
+ },
979
+ }
980
+ ```
981
+
982
+ Every repo under the prefix, present and future, keeps its own bank but uses the entry's
983
+ settings. The longest matching prefix wins, and a linked worktree outside the tree uses its main
984
+ checkout's entry, as with `mapPathToBank`. The section applies after bank resolution and before
985
+ `banks.<bankId>`, so a bank section still wins for its one repo. Bank-resolution and approval
986
+ fields (`bankId`, `mapPathToBank`, `bank`, `optInOnly`, `optInPaths`, ...) are ignored inside a
987
+ path section. Any connection setting can be overridden — `serverMode`, `apiUrl`, `apiPort`,
988
+ `apiToken` — so one directory can use a local daemon while another uses Cloud or a self-hosted
989
+ server. The token is re-read on a rejected request, like the top-level `apiToken`, but only while
990
+ the directory still points at the same server.
991
+
807
992
  ### Bank resolution
808
993
 
809
994
  Coding memory is **per repository**. Resolution order for the working directory:
@@ -997,8 +1182,8 @@ event is written on those turns — nothing reflected.
997
1182
  `~/.hindsight/coding-agents-logs/usage.jsonl` (override `HINDSIGHT_USAGE_FILE`) — the `hindsight_*`
998
1183
  tools the agent called during that turn, and whether its reply credited Hindsight memory ("From
999
1184
  Hindsight memory"). The credit rate counts only turns that called a retrieval tool (search, list,
1000
- read, reflect); saving a document is not expected to be credited. Recorded when the session is written back, so a scope with
1001
- `retainSessions: false` records none. It never leaves your machine. Summarize it per agent with:
1185
+ read, reflect); saving a document is not expected to be credited. Recorded at the end of each turn,
1186
+ whether or not `retainSessions` writes the session back. It never leaves your machine. Summarize it per agent with:
1002
1187
 
1003
1188
  ```bash
1004
1189
  npx @vectorize-io/hindsight-coding-agents stats