@vectorize-io/hindsight-coding-agents 0.6.1 → 0.8.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.
Files changed (56) hide show
  1. package/README.md +314 -51
  2. package/dist/antigravity-hook.js +1039 -198
  3. package/dist/antigravity-statusline.js +185 -11
  4. package/dist/antigravity-stop-hook.js +1026 -163
  5. package/dist/claude-hook.js +1039 -198
  6. package/dist/claude-sessionstart-hook.js +1123 -190
  7. package/dist/claude-stop-hook.js +1026 -163
  8. package/dist/cline.js +749 -209
  9. package/dist/codex-hook.js +1039 -198
  10. package/dist/codex-sessionstart-hook.js +1123 -190
  11. package/dist/codex-stop-hook.js +1026 -163
  12. package/dist/copilot-hook.js +1039 -198
  13. package/dist/copilot-sessionstart-hook.js +1123 -190
  14. package/dist/copilot-stop-hook.js +1026 -163
  15. package/dist/cursor-hook.js +1039 -198
  16. package/dist/cursor-sessionstart-hook.js +1123 -190
  17. package/dist/cursor-stop-hook.js +1026 -163
  18. package/dist/daemon-start.js +154 -5
  19. package/dist/dcode-hook.js +1039 -198
  20. package/dist/dcode-sessionstart-hook.js +1123 -190
  21. package/dist/dcode-stop-hook.js +1026 -163
  22. package/dist/deepen.js +437 -105
  23. package/dist/devin-hook.js +1039 -198
  24. package/dist/devin-sessionstart-hook.js +1123 -190
  25. package/dist/devin-stop-hook.js +1026 -163
  26. package/dist/droid-hook.js +1039 -198
  27. package/dist/droid-sessionstart-hook.js +1123 -190
  28. package/dist/droid-stop-hook.js +1026 -163
  29. package/dist/dsh.js +750 -210
  30. package/dist/grok-hook.js +1039 -198
  31. package/dist/grok-sessionstart-hook.js +1123 -190
  32. package/dist/grok-stop-hook.js +1026 -163
  33. package/dist/hindsight-seed.js +157 -8
  34. package/dist/index.js +749 -209
  35. package/dist/installer.js +1233 -366
  36. package/dist/kilo.js +749 -209
  37. package/dist/kimi-hook.js +3909 -0
  38. package/dist/kimi-sessionstart-hook.js +4650 -0
  39. package/dist/kimi-stop-hook.js +4218 -0
  40. package/dist/mcp-server.js +373 -71
  41. package/dist/opencode2.js +778 -209
  42. package/dist/pi.js +754 -211
  43. package/dist/prime-agent.js +754 -211
  44. package/dist/qwen-hook.js +1039 -198
  45. package/dist/qwen-sessionstart-hook.js +1123 -190
  46. package/dist/qwen-stop-hook.js +1026 -163
  47. package/dist/status.js +333 -59
  48. package/dist/traecode-hook.js +3909 -0
  49. package/dist/traecode-sessionstart-hook.js +4650 -0
  50. package/dist/traecode-stop-hook.js +4218 -0
  51. package/dist/zcode-hook.js +1039 -198
  52. package/dist/zcode-sessionstart-hook.js +1123 -190
  53. package/dist/zcode-stop-hook.js +1026 -163
  54. package/package.json +15 -11
  55. package/plugin.json +1 -1
  56. package/skill/SKILL.md +241 -48
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**). 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
 
@@ -12,6 +12,8 @@ tie-break policy. Those decisions live in git history and past conversations. Th
12
12
  in front of the agent at the moment it starts working, and keeps a curated set of **knowledge pages**
13
13
  (architecture, conventions, in-flight initiatives) that future sessions start from.
14
14
 
15
+ <!-- figure: coding-agents -->
16
+
15
17
  [View Changelog →](https://hindsight.vectorize.io/changelog/integrations/coding-agents)
16
18
 
17
19
  ## Install
@@ -98,7 +100,7 @@ A plugin entry in `~/.config/opencode/opencode.json` — native tools, no MCP ne
98
100
  npx @vectorize-io/hindsight-coding-agents install opencode2
99
101
  ```
100
102
 
101
- opencode v2 (`npm @opencode-ai/cli@beta`) installs its `opencode2` binary **alongside** v1 and
103
+ opencode v2 (`npm @opencode/cli`) exposes an `opencode2` binary alias **alongside** `opencode` and
102
104
  rewrote the plugin API, so it is a harness of its own. It writes the same plugin entry to the same
103
105
  `~/.config/opencode/opencode.json` — the two CLIs share that file, and v1 rejects the whole config
104
106
  if it sees v2's `plugins` key — and each CLI then loads its own entry point from the one registered
@@ -107,7 +109,9 @@ path. So installing either harness wires both, and uninstalling either removes t
107
109
  Two differences from v1, both because of the host: the one-time codebase survey runs under another
108
110
  installed agent's CLI (v2 plugins cannot define the read-only agent the survey needs), and the seed
109
111
  banner is written to the plugin log instead of a TUI toast (v2 plugins cannot raise one). Recall,
110
- injection, the native `hindsight_*` tools and session write-back are identical.
112
+ injection, the native `hindsight_*` tools and session write-back are identical. The companion skill
113
+ is identical too, but it is registered in memory through v2's skill API rather than copied into a
114
+ skills directory — opencode2 has none of its own, and the two it reads belong to other agents.
111
115
 
112
116
  #### <img src="https://hindsight.vectorize.io/img/harness/kilo.svg" alt="" width="20" height="20" /> Kilo CLI
113
117
 
@@ -139,7 +143,9 @@ npx @vectorize-io/hindsight-coding-agents install copilot-cli
139
143
  npx @vectorize-io/hindsight-coding-agents install grok-build
140
144
  ```
141
145
 
142
- Native hooks and MCP in `~/.grok/config.toml`, plus the companion skill.
146
+ Native hooks in `~/.grok/hooks/hindsight.json`, MCP in `~/.grok/config.toml`, plus the companion
147
+ skill. Grok also runs Claude Code's hooks from `~/.claude/settings.json`; those stay silent inside
148
+ Grok, so a machine wired for both hosts records each Grok session once.
143
149
 
144
150
  #### <img src="https://hindsight.vectorize.io/img/harness/qwen-code.svg" alt="" width="20" height="20" /> Qwen Code
145
151
 
@@ -155,6 +161,19 @@ Native hooks in `~/.qwen/settings.json`, plus MCP and the companion skill.
155
161
  > continuations, so interactive sessions recall once per prompt while headless (`qwen -p`),
156
162
  > `serve`, SDK and ACP sessions seed and retain but do not recall.
157
163
 
164
+ #### <img src="https://hindsight.vectorize.io/img/harness/kimi-code.svg" alt="" width="20" height="20" /> Kimi Code
165
+
166
+ ```bash
167
+ npx @vectorize-io/hindsight-coding-agents install kimi-code
168
+ ```
169
+
170
+ Native hooks in `~/.kimi-code/config.toml`, plus MCP in `~/.kimi-code/mcp.json` and the companion skill.
171
+ (Hooks and MCP go under `$KIMI_CODE_HOME` instead when it is set.)
172
+
173
+ > Kimi's SessionStart hook cannot reach the model, so the session briefing is silent there;
174
+ > recalled memory arrives on the first prompt instead, as a `<hook_result>` block. Sessions are
175
+ > retained from every agent's `wire.jsonl` under the session directory, subagents included.
176
+
158
177
  #### <img src="https://hindsight.vectorize.io/img/harness/factory-droid.svg" alt="" width="20" height="20" /> Factory Droid
159
178
 
160
179
  ```bash
@@ -194,6 +213,56 @@ refuses to touch an MCP server named `hindsight` that it did not write.
194
213
  > appending each new turn to the same session document. `--import-conversations` is therefore not
195
214
  > available for ZCode: there is no past history on disk to backfill from.
196
215
 
216
+ #### <img src="https://hindsight.vectorize.io/img/harness/traecode.png" alt="" width="20" height="20" /> TraeCode
217
+
218
+ ```bash
219
+ npx @vectorize-io/hindsight-coding-agents install traecode
220
+ ```
221
+
222
+ Three hook registrations in TraeCode's user-level `hooks.json`, the companion skill under the
223
+ same dot-dir's `skills/`, and two `filesystem.readWrite` rules in `sandbox.json` — one for
224
+ `~/.hindsight`, without which the hooks fail silently (exit 0, no effect) because the sandbox
225
+ blocks those writes, and one for Trae's per-window storage DBs
226
+ (`<userData>/User/workspaceStorage`), which the SessionStart hook seeds with the workspace's
227
+ MCP enable switch. Network is allowed by default. TRAE ships two editions with different brand
228
+ roots — the CN build uses `~/.trae-cn` and "Trae CN", the international build `~/.trae` and
229
+ "Trae" — so every path resolves by probing for the edition dir that exists and defaulting to the
230
+ CN names. Plain JSON files, no CLI round-trip. TraeCode speaks Claude Code's hook protocol, so
231
+ recall and injection work exactly as they do there; the event map lives under the top-level
232
+ `hooks` key and the `version` field the host writes is preserved.
233
+
234
+ MCP is registered per repo, never at the user level: Trae launches user-level servers with the
235
+ Electron process's cwd (your home directory), where a hindsight entry either self-disables under
236
+ `optInOnly` (zero tools) or resolves the home bank instead of the repo's. So the installer
237
+ pre-seeds the per-repo registration for every repo opted in via `mapPathToBank` — a
238
+ `mcpServers.hindsight` stdio server in `<repo>/.trae/mcp.json`, pinned to that repo via
239
+ `HINDSIGHT_MCP_PROJECT_CWD` — migrates any stale user-level entry back out of
240
+ `<userData>/User/mcp.json`, and seeds the per-workspace enable switch directly. The SessionStart
241
+ hook re-checks both on every session and writes them only when missing or stale (idempotent
242
+ fallback) — Trae's hook sandbox cannot be relied on to perform those writes itself. The per-repo
243
+ file is merged not clobbered, and gitignored when the repo has a `.gitignore` (the path is
244
+ machine-specific). A foreign `hindsight` entry — in either file — is the user's own server and
245
+ is never touched.
246
+
247
+ Trae only reads that per-repo file once the global `trae.mcp.enableWorkspaceMcp` setting is on
248
+ (default off), so the installer handles the gate: an interactive run asks, a non-interactive run
249
+ takes `--enable-workspace-mcp`, and either way the setting is written and Trae windows must be
250
+ restarted to pick it up (declining, or a settings file with comments, prints the manual step).
251
+ Registrations and enable switches take effect on the NEXT window, so the MCP tools appear when
252
+ you reload after the first session; repos opted into `mapPathToBank` after install need one more
253
+ `install traecode` run, and if a repo's server still shows disabled in the MCP panel, flip it on
254
+ once there.
255
+
256
+ > One manual step remains after install (UI state the installer cannot write): enable the hooks
257
+ > under TraeCode Settings > Hooks. If you declined the workspace-MCP prompt, enable it later in
258
+ > Trae settings (search "enableWorkspaceMcp").
259
+
260
+ > TraeCode keeps no readable session transcript - sessions live in an encrypted local DB or the
261
+ > cloud. Like ZCode, its conversation is journaled by the plugin itself: the prompt hook records
262
+ > what you asked, and the `Stop` hook closes the turn with the reply it carries in
263
+ > `last_assistant_message`. `--import-conversations` is therefore not available for TraeCode:
264
+ > there is no past history on disk to backfill from.
265
+
197
266
  #### <img src="https://hindsight.vectorize.io/img/harness/antigravity-cli.png" alt="" width="20" height="20" /> Antigravity CLI
198
267
 
199
268
  ```bash
@@ -261,7 +330,9 @@ resolved per session workspace rather than once per process; and dsh has no plug
261
330
  channel, so the seed line goes to the plugin log rather than the UI. Everything model-facing —
262
331
  recalled memory, the knowledge preamble, the `hindsight_*` tools — is unaffected. If you prefer the
263
332
  published-package route, `dsh plugin --profile web add @vectorize-io/hindsight-coding-agents` works
264
- too: the package ships the profile patch layer, so nothing else needs editing.
333
+ too: the package ships the profile patch layer, so nothing else needs editing. Either route gets the
334
+ companion skill — a plugin wired by the host's own plugin manager installs it itself on the first
335
+ session, since that route never runs our installer.
265
336
 
266
337
  Uninstall the same way: `npx @vectorize-io/hindsight-coding-agents uninstall claude-code` (or `uninstall all`).
267
338
 
@@ -427,14 +498,16 @@ Configuration is **one JSON file**: `~/.hindsight/coding-agent.json`. Layering,
427
498
  (`HINDSIGHT_<FIELD_IN_CAPS>`), for containers and CI that inject config rather than write a file
428
499
  3. the file's top level
429
500
  4. its `harnesses.<name>` section — per-agent override
430
- 5. its `banks.<resolvedBankId>` section — per-repo override, applied after the bank is resolved
501
+ 5. its `paths.<prefix>` section — per-directory override, applied after the bank is resolved
502
+ (see [Per-directory overrides](#per-directory-overrides--pathsprefix))
503
+ 6. its `banks.<resolvedBankId>` section — per-repo override, applied after the bank is resolved
431
504
  (see [Per-repo opt-in/out](#per-repo-opt-inout--banksbankid))
432
505
 
433
506
  Environment variables are a **fallback**: the file wins wherever it sets a value, so adding env to
434
507
  an existing setup changes nothing. The two list-valued settings, `retainTags` and `optInPaths`, take
435
508
  a comma-separated value (`HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work"`); entries are
436
509
  trimmed and blanks dropped.
437
- The map-valued settings (`mapPathToBank`, `harnesses`, `banks`, `retainMetadata`) are file-only —
510
+ The map-valued settings (`mapPathToBank`, `harnesses`, `paths`, `banks`, `retainMetadata`) are file-only —
438
511
  per-key branching doesn't survive flattening into one variable. `maxParallelRetains` is available
439
512
  as `HINDSIGHT_MAX_PARALLEL_RETAINS` for containers and CI.
440
513
 
@@ -507,42 +580,52 @@ hook by Codex...), so one shared config serves several agents side by side:
507
580
 
508
581
  ### Reference
509
582
 
510
- | field | default | meaning |
511
- | ----------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
512
- | `apiUrl` | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server) |
513
- | `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 |
514
- | `bankId` | — | **explicit static bank**; unset ⇒ per-repo dynamic resolution (below) |
515
- | `dynamicBankId` | dynamic iff no `bankId` | force dynamic (`true`) or static (`false`) resolution |
516
- | `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo |
517
- | `mapPathToBank` | — | absolute path → bank; **longest prefix wins**; linked worktrees inherit their main checkout's mapping; overrides everything |
518
- | `optInOnly` | `false` | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see [Opt-in only](#opt-in-only) |
519
- | `optInPaths` | — | directories opted in, matched as prefixes with `~` expanded; each repo beneath and its linked worktrees are approved while keeping their own dynamic bank |
520
- | `resolveWorktrees` | `true` | linked worktrees inherit the main checkout's bank identity, path approval, and mapping |
521
- | `retainTags` | — | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
522
- | `retainMetadata` | — | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}` |
523
- | `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 |
524
- | `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 |
525
- | `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
526
- | `reflectTimeoutMs` | `120000` | **automatic** session-reflect timeout (hook harnesses additionally cap it at 20s to fit the host's hook window); on timeout or a 5xx the hook falls back to knowledge-page search, then to a raw recall of observations (recorded) |
527
- | `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 |
528
- | `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 |
529
- | `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 |
530
- | `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
531
- | `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) |
532
- | `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 |
533
- | `autoSeed` | `true` | SessionStart: auto-seed a cold repo's bank from git history |
534
- | `seedLimit` | `300` | auto-seed: most-recent-N-commits cap |
535
- | `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 |
536
- | `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
537
- | `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
538
- | `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) |
539
- | `retainSessions` | `true` | session write-back, honored by every harness: hook harnesses write the transcript on Stop, Factory Droid also writes on its cancellation notification, and 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 |
540
- | `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 |
541
- | `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
542
- | `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` |
543
- | `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 |
544
- | `harnesses.<name>` | — | per-harness override of any field above |
545
- | `harness` | `opencode` | **deepen engine only**: which session format `--conversations` is read as |
583
+ | field | default | meaning |
584
+ | ----------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
585
+ | `apiUrl` | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server) |
586
+ | `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 |
587
+ | `bankId` | — | **explicit static bank**; unset ⇒ per-repo dynamic resolution (below) |
588
+ | `dynamicBankId` | dynamic iff no `bankId` | force dynamic (`true`) or static (`false`) resolution |
589
+ | `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo |
590
+ | `mapPathToBank` | — | absolute path → bank; **longest prefix wins**; linked worktrees inherit their main checkout's mapping; overrides everything |
591
+ | `optInOnly` | `false` | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see [Opt-in only](#opt-in-only) |
592
+ | `optInPaths` | — | directories opted in, matched as prefixes with `~` expanded; each repo beneath and its linked worktrees are approved while keeping their own dynamic bank |
593
+ | `resolveWorktrees` | `true` | linked worktrees inherit the main checkout's bank identity, path approval, and mapping |
594
+ | `retainTags` | — | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
595
+ | `retainMetadata` | — | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}` |
596
+ | `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` |
597
+ | `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 |
598
+ | `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`) |
599
+ | `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 |
600
+ | `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 |
601
+ | `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
602
+ | `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) |
603
+ | `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 |
604
+ | `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 |
605
+ | `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 |
606
+ | `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` |
607
+ | `autoReflect` | `true` | **deprecated** — use `autoInject`. Still honoured (`false` = `autoInject: "none"`), ignored when `autoInject` is set, and logs a deprecation warning |
608
+ | `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 |
609
+ | `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 |
610
+ | `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."` |
611
+ | `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
612
+ | `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) |
613
+ | `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 |
614
+ | `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 |
615
+ | `customPages` | — | knowledge pages of your own, seeded alongside the five above and keyed by the name they get: `{"Security posture": {"source_query": "...", "tags": ["knowledge:decision"]}}`. `source_query` is required; `tags` picks which facts feed the page and is optional — omitted, the page draws on everything the bank holds. A separate setting from `pages` on purpose, so that an unknown name there stays a typo warning rather than quietly creating a page. File-only, and replaced (not merged) by a `banks.<id>` section |
616
+ | `autoSeed` | `true` | SessionStart: auto-seed a cold repo's bank from git history |
617
+ | `seedLimit` | `300` | auto-seed: most-recent-N-commits cap |
618
+ | `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 |
619
+ | `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
620
+ | `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
621
+ | `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) |
622
+ | `retainSessions` | `true` | session write-back, honored by every harness: hook harnesses write the transcript on Stop, Factory Droid also writes on its cancellation notification, and 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 |
623
+ | `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 |
624
+ | `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
625
+ | `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` |
626
+ | `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 |
627
+ | `harnesses.<name>` | — | per-harness override of any field above |
628
+ | `harness` | `opencode` | **deepen engine only**: which session format `--conversations` is read as |
546
629
 
547
630
  By default a page refreshes **hourly, staggered**: `pageTriggerCron` is `"H * * * *"`, so every
548
631
  page gets its own minute of the hour (see below) and a tick with nothing new to fold in is skipped
@@ -589,6 +672,123 @@ file is the source of truth for these pages: to give one a different schedule, c
589
672
  page. Only the fields this plugin states are touched — a page's `mode`, its excluded siblings and
590
673
  its minimum refresh interval are left exactly as they are.
591
674
 
675
+ ### Customize Knowledge Pages — `pages`
676
+
677
+ Every repo gets the same five pages. They are a **taxonomy**, not a summary of your source: each one
678
+ is synthesized from what the bank ingested — commit history and past conversations — and each is
679
+ pinned to one knowledge tier, so a page draws only on the facts the extractor routed to it.
680
+
681
+ | Page | What it answers | Tier tag |
682
+ | ------------------------------ | ------------------------------------------------------------------------------------------------------- | ------------------------ |
683
+ | `Component map` | the main components/modules/subsystems, what each is responsible for, and how they depend on each other | `knowledge:component` |
684
+ | `Core concepts` | the domain abstractions and key entities — the vocabulary a developer has to know | `knowledge:concept` |
685
+ | `Conventions and patterns` | how THIS project does things: testing, error handling, naming, structure, how changes are made | `knowledge:convention` |
686
+ | `Key decisions and rationale` | the significant technical decisions and the durable "why we do it this way" behind them | `knowledge:decision` |
687
+ | `Initiatives and enhancements` | the major initiatives and features over time, linking out to each captured initiative's own page | `knowledge:feature-work` |
688
+
689
+ `pages` says which of them to seed and what each one asks. Keys are the page names above, matched
690
+ ignoring case and surrounding spaces:
691
+
692
+ ```jsonc
693
+ {
694
+ "pages": {
695
+ // don't seed this page at all
696
+ "Component map": false,
697
+ // seed it, but ask your question instead of the built-in one
698
+ "Key decisions and rationale": {
699
+ "source_query": "What did we decide about data retention, encryption and PII handling, and why? Prefer decisions that constrain what new code may do.",
700
+ },
701
+ },
702
+ }
703
+ ```
704
+
705
+ Omit `pages` entirely — the default — and all five are seeded with their built-in queries.
706
+
707
+ **Fewer pages.** Each page costs one LLM synthesis per refresh, so a repo that only wants the
708
+ architecture ones turns the rest off:
709
+
710
+ ```jsonc
711
+ {
712
+ "pages": {
713
+ "Initiatives and enhancements": false,
714
+ "Conventions and patterns": false,
715
+ "Key decisions and rationale": false,
716
+ },
717
+ }
718
+ ```
719
+
720
+ **Per repo**, like every other field — usually where this belongs, since what a page should ask is a
721
+ property of the project, not of your machine:
722
+
723
+ ```jsonc
724
+ {
725
+ "banks": {
726
+ "coding-agent::payments-api": {
727
+ "pages": {
728
+ "Core concepts": {
729
+ "source_query": "What are the payment domain's entities — orders, ledgers, settlement states — and what does each mean in OUR model?",
730
+ },
731
+ },
732
+ },
733
+ },
734
+ }
735
+ ```
736
+
737
+ Four things worth knowing before you reach for it:
738
+
739
+ - **This is the only durable way to reword a page.** Every session compares each seeded page against
740
+ the query it is configured to have and re-syncs the ones that differ, so a `source_query` edited
741
+ through the API or the control plane is replaced the next time an agent runs. Setting it here makes
742
+ your wording the configured one. When a re-sync does replace a query, the plugin now says which
743
+ page in the plugin log rather than doing it silently.
744
+ - **Your query still gets the scoping clause.** The sentence that keeps a dependency's decisions off
745
+ your project's page is appended to a custom query too — a bank holds facts about the libraries and
746
+ services a repo merely uses, and without that clause a page will present them as yours.
747
+ - **The tier tag stays the taxonomy's.** It selects which facts the synthesis reads; rewording the
748
+ question changes what is asked of those facts, not which ones are in scope.
749
+ - **`false` does not delete anything.** A page already seeded keeps its content and simply stops
750
+ being re-synced — remove it in the control plane if you want it gone.
751
+
752
+ A name that matches no page above is ignored with a warning in the plugin log, so a typo fails
753
+ loudly instead of looking like it disabled something. Adding pages of your own is not what this
754
+ setting is for: the agent's `hindsight_capture_initiative` tool already creates pages, one per
755
+ initiative, each with its own query.
756
+
757
+ #### Pages of your own — `customPages`
758
+
759
+ `pages` only reworks the five above. To add a page, name it under `customPages`:
760
+
761
+ ```jsonc
762
+ {
763
+ "customPages": {
764
+ "Security posture": {
765
+ "source_query": "What are this project's security decisions — authn, secrets handling, PII, dependency policy — and what do they constrain in new code?",
766
+ "tags": ["knowledge:decision"],
767
+ },
768
+ "Operational runbook": {
769
+ "source_query": "How does this project get deployed, monitored and rolled back? What has broken in production, and what fixed it?",
770
+ },
771
+ },
772
+ }
773
+ ```
774
+
775
+ `source_query` is required. `tags` is optional and picks which facts feed the page — one of the tier
776
+ tags above, or any tag you stamp on your own writes with `retainTags`. Omit it and the page draws on
777
+ everything the bank holds: a refresh matches tags with `all`, so no tags means no tag constraint,
778
+ **not** an empty page.
779
+
780
+ Your pages are seeded at the same root as the taxonomy, on the same refresh schedule, and re-synced
781
+ from the config the same way — reword one here and the live page follows on the next session. They
782
+ compose with `pages`, so trading two built-ins for one of your own is just both settings at once.
783
+
784
+ **Why it is a separate setting.** `pages` refuses a name that matches no seeded page, and that is
785
+ what makes a typo loud: if an unknown key there meant "create this page", `"Componnet map"` would
786
+ quietly create an empty second page instead of rewording the one you meant. For the same reason,
787
+ naming a seeded page under `customPages` is refused — reword it under `pages`.
788
+
789
+ A page you create yourself in the control plane is a third thing again, and the plugin never touches
790
+ it: the seed pass only visits the pages it is configured to own.
791
+
592
792
  ### A bank you shape yourself — `manageBankConfig`
593
793
 
594
794
  Pointed at a bank, this plugin gives it the shape its ingestion needs: retain strategies for the
@@ -604,13 +804,45 @@ already has it. To take the current default back, clear that override on the ban
604
804
  strategy, or the whole `retain_strategies` entry, in the control plane): the next session finds the
605
805
  bank silent there and seeds it again.
606
806
 
607
- Set `manageBankConfig: false` to keep the plugin out of the bank's configuration altogether — the
608
- right setting for a bank you share with non-coding work, or one you configure yourself. That bank
609
- should then define the five strategies above itself. Note that the miss is **silent**: the server
610
- does not reject a retain naming a strategy the bank lacks, it logs a warning and extracts with the
611
- bank's own configuration — so a commit diff, a session transcript and a survey marker would all get
612
- the same generic treatment instead of the extraction each needs. Knowledge pages are seeded either
613
- way; `pageTriggerType` governs what they cost.
807
+ One field is the exception: the extraction mode of the plugin's own four strategies (`git`,
808
+ `gitlog`, `conversation`, `document`) follows `retainExtractionMode` and is put back on every session
809
+ if it drifts — the same way a seeded page's query is. Change it in `coding-agent.json`, not in the
810
+ control plane. The strategies' other fields, and your own strategies, are still left alone.
811
+
812
+ **Your own defaults for new banks — `defaultBankConfig`.** Everything the template does not name, a
813
+ bank the plugin creates gets from the server: auto-consolidation on, observations on, a 60s floor
814
+ between mental-model refreshes. With one bank per repo those are the settings that cost money, and
815
+ a new repo an agent touches spawns a new bank with all of them switched on — while every bank you had
816
+ hand-tuned in the control plane sits at a cheaper baseline. `defaultBankConfig` names the baseline
817
+ once, in the plugin's config, and it travels in the same import that creates the bank:
818
+
819
+ ```json
820
+ {
821
+ "defaultBankConfig": {
822
+ "enable_observations": false,
823
+ "enable_auto_consolidation": false,
824
+ "mental_model_min_refresh_interval_seconds": 21600
825
+ }
826
+ }
827
+ ```
828
+
829
+ The keys are the bank-config API's own field names, passed straight through, so anything the
830
+ bank-config accepts can go here. They follow the same additive rule as the template: written only
831
+ where the bank is silent, so an existing bank picks them up on its next session **except** for the
832
+ fields it already sets — a value you chose in the control plane stays, even one equal to the server
833
+ default, and so does a value an earlier plugin release seeded (the template writes
834
+ `enable_observations: true` alongside the missions; clear that override on the bank to let your
835
+ default in). On a key the template also names, your default wins. The three fields the plugin
836
+ governs itself — `retain_strategies`, `entity_labels` and `retain_extraction_mode` — are refused
837
+ with a warning: the first two are merged entry by entry, the last is `retainExtractionMode`'s.
838
+
839
+ Set `manageBankConfig: false` to keep the plugin out of the bank's configuration altogether,
840
+ `defaultBankConfig` included — the right setting for a bank you share with non-coding work, or one
841
+ you configure yourself. That bank should then define the five strategies above itself. Note that the
842
+ miss is **silent**: the server does not reject a retain naming a strategy the bank lacks, it logs a
843
+ warning and extracts with the bank's own configuration — so a commit diff, a session transcript and
844
+ a survey marker would all get the same generic treatment instead of the extraction each needs.
845
+ Knowledge pages are seeded either way; `pageTriggerType` governs what they cost.
614
846
 
615
847
  Like every field here it can be set per bank, which is usually where it belongs:
616
848
 
@@ -670,6 +902,32 @@ every repo (present and future) beneath it:
670
902
  Rule of thumb: converge by **id** for a hand-picked set of repos; map by **path** when a folder is
671
903
  the boundary ("everything I clone under `work/client-x` shares memory").
672
904
 
905
+ ### Per-directory overrides — `paths.<prefix>`
906
+
907
+ When a folder is the boundary for something other than the bank — typically a different server
908
+ or tenant for client work — key the override by directory instead of by bank id:
909
+
910
+ ```jsonc
911
+ {
912
+ "apiToken": "personal-key",
913
+ "paths": {
914
+ "~/work/client-x": { "apiToken": "client-x-key" },
915
+ "~/work/acme": { "apiUrl": "https://hindsight.acme.internal", "apiToken": "acme-key" },
916
+ "~/oss": { "serverMode": "daemon" },
917
+ },
918
+ }
919
+ ```
920
+
921
+ Every repo under the prefix, present and future, keeps its own bank but uses the entry's
922
+ settings. The longest matching prefix wins, and a linked worktree outside the tree uses its main
923
+ checkout's entry, as with `mapPathToBank`. The section applies after bank resolution and before
924
+ `banks.<bankId>`, so a bank section still wins for its one repo. Bank-resolution and approval
925
+ fields (`bankId`, `mapPathToBank`, `bank`, `optInOnly`, `optInPaths`, ...) are ignored inside a
926
+ path section. Any connection setting can be overridden — `serverMode`, `apiUrl`, `apiPort`,
927
+ `apiToken` — so one directory can use a local daemon while another uses Cloud or a self-hosted
928
+ server. The token is re-read on a rejected request, like the top-level `apiToken`, but only while
929
+ the directory still points at the same server.
930
+
673
931
  ### Bank resolution
674
932
 
675
933
  Coding memory is **per repository**. Resolution order for the working directory:
@@ -850,10 +1108,15 @@ as a JSON line to `~/.hindsight/coding-agents-logs/diag.jsonl` (override with
850
1108
  `reflect_failed` / `pages_failed` record the error; if you're comparing memory-on vs memory-off,
851
1109
  check this file — a run whose reflects failed is a no-memory run. When the failure was a timeout or
852
1110
  a 5xx, the hook falls back to knowledge-page search and, if no page matches, to a raw recall of the
853
- bank's observations: `reflect_fallback_pages` / `reflect_fallback_observations` record what each
1111
+ bank's memories: `reflect_fallback_pages` / `reflect_fallback_observations` record what each
854
1112
  step returned (`*_failed` when it errored). Seed starts are logged as
855
1113
  `seed_started`.
856
1114
 
1115
+ When `autoInject` names a retrieval source instead of reflect, that source records its own
1116
+ outcome with the number of items it returned: `inject_pages` for `"pages"`, `inject_recall` for
1117
+ `"recall"` (`inject_pages_failed` / `inject_recall_failed` when the call errored). No reflect
1118
+ event is written on those turns — nothing reflected.
1119
+
857
1120
  **Tool usage** (is the agent using Hindsight?): one JSON line per finished user turn in
858
1121
  `~/.hindsight/coding-agents-logs/usage.jsonl` (override `HINDSIGHT_USAGE_FILE`) — the `hindsight_*`
859
1122
  tools the agent called during that turn, and whether its reply credited Hindsight memory ("From