@vectorize-io/hindsight-coding-agents 0.4.3 → 0.5.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 (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 +863 -236
  7. package/dist/claude-stop-hook.js +654 -205
  8. package/dist/cline.js +589 -234
  9. package/dist/codex-hook.js +637 -199
  10. package/dist/codex-sessionstart-hook.js +863 -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 +863 -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 +863 -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 +3194 -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 +863 -236
  25. package/dist/devin-stop-hook.js +654 -205
  26. package/dist/dsh.js +592 -235
  27. package/dist/grok-hook.js +637 -199
  28. package/dist/grok-sessionstart-hook.js +863 -236
  29. package/dist/grok-stop-hook.js +654 -205
  30. package/dist/hindsight-seed.js +222 -83
  31. package/dist/index.js +589 -234
  32. package/dist/installer.js +2331 -299
  33. package/dist/kilo.js +589 -234
  34. package/dist/mcp-server.js +363 -169
  35. package/dist/opencode2.js +30092 -0
  36. package/dist/pi.js +17650 -0
  37. package/dist/prime-agent.js +625 -260
  38. package/dist/qwen-hook.js +2577 -0
  39. package/dist/qwen-sessionstart-hook.js +3194 -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
@@ -0,0 +1,37 @@
1
+ {
2
+ "hooks": {
3
+ "SessionStart": [
4
+ {
5
+ "hooks": [
6
+ {
7
+ "type": "command",
8
+ "command": "node \"${PLUGIN_ROOT}/dist/dcode-sessionstart-hook.js\"",
9
+ "timeout": 30
10
+ }
11
+ ]
12
+ }
13
+ ],
14
+ "UserPromptSubmit": [
15
+ {
16
+ "hooks": [
17
+ {
18
+ "type": "command",
19
+ "command": "node \"${PLUGIN_ROOT}/dist/dcode-hook.js\"",
20
+ "timeout": 30
21
+ }
22
+ ]
23
+ }
24
+ ],
25
+ "Stop": [
26
+ {
27
+ "hooks": [
28
+ {
29
+ "type": "command",
30
+ "command": "node \"${PLUGIN_ROOT}/dist/dcode-stop-hook.js\"",
31
+ "timeout": 60
32
+ }
33
+ ]
34
+ }
35
+ ]
36
+ }
37
+ }
package/index.js ADDED
@@ -0,0 +1,10 @@
1
+ /**
2
+ * opencode v2 (`opencode2`) plugin entrypoint.
3
+ *
4
+ * opencode v1 and v2 share `~/.config/opencode/opencode.json` and v1 rejects the whole file when it
5
+ * sees v2's `plugins` key, so both hosts have to load from the ONE package path already registered
6
+ * in the user's `plugin` array. They resolve a plugin directory differently, which is what makes
7
+ * that work: v1 follows package.json `main` (→ dist/index.js, the v1 plugin), while v2 ignores
8
+ * `main` and loads `<dir>/index.js` — this file. See src/opencode2.ts.
9
+ */
10
+ export { default, HindsightOpencode2Plugin } from "./dist/opencode2.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vectorize-io/hindsight-coding-agents",
3
- "version": "0.4.3",
3
+ "version": "0.5.0",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "https://github.com/vectorize-io/hindsight.git",
@@ -23,9 +23,15 @@
23
23
  "hindsight-grok-sessionstart-hook": "dist/grok-sessionstart-hook.js",
24
24
  "hindsight-grok-stop-hook": "dist/grok-stop-hook.js",
25
25
  "hindsight-codex-hook": "dist/codex-hook.js",
26
+ "hindsight-dcode-hook": "dist/dcode-hook.js",
27
+ "hindsight-dcode-sessionstart-hook": "dist/dcode-sessionstart-hook.js",
28
+ "hindsight-dcode-stop-hook": "dist/dcode-stop-hook.js",
26
29
  "hindsight-antigravity-hook": "dist/antigravity-hook.js",
27
30
  "hindsight-antigravity-statusline": "dist/antigravity-statusline.js",
28
- "hindsight-devin-hook": "dist/devin-hook.js"
31
+ "hindsight-devin-hook": "dist/devin-hook.js",
32
+ "hindsight-qwen-hook": "dist/qwen-hook.js",
33
+ "hindsight-qwen-sessionstart-hook": "dist/qwen-sessionstart-hook.js",
34
+ "hindsight-qwen-stop-hook": "dist/qwen-stop-hook.js"
29
35
  },
30
36
  "exports": {
31
37
  ".": {
@@ -40,7 +46,10 @@
40
46
  "files": [
41
47
  "skill",
42
48
  "dist",
43
- "cordis.patch.yml"
49
+ "index.js",
50
+ "cordis.patch.yml",
51
+ "plugin.json",
52
+ "hooks"
44
53
  ],
45
54
  "dsh": {
46
55
  "bundle": {
@@ -59,26 +68,24 @@
59
68
  }
60
69
  ]
61
70
  },
62
- "pi": {
63
- "extensions": [
64
- "./dist/prime-agent.js"
65
- ]
66
- },
67
71
  "scripts": {
68
72
  "build": "tsup",
69
73
  "skill:build": "node scripts/build-skill.mjs",
70
74
  "clean": "rm -rf dist",
71
75
  "prepublishOnly": "npm run clean && npm run skill:build && npm run build",
72
76
  "test": "vitest run --exclude '**/*.e2e.test.ts'",
77
+ "test:dcode-e2e": "npm run build && HINDSIGHT_DCODE_E2E=1 vitest run src/dcode-plugin.e2e.test.ts",
73
78
  "test:harness-e2e": "npm run build && HINDSIGHT_HARNESS_E2E=1 vitest run src/harness.e2e.test.ts"
74
79
  },
75
80
  "dependencies": {
76
81
  "@modelcontextprotocol/sdk": "^1.29.0",
77
82
  "@vectorize-io/hindsight-all": "^0.8.6",
83
+ "jsonc-parser": "^3.3.1",
78
84
  "zod": "^4.4.3"
79
85
  },
80
86
  "devDependencies": {
81
87
  "@opencode-ai/plugin": "^1.18.9",
88
+ "@opencode-ai/plugin-v2": "npm:@opencode-ai/plugin@0.0.0-beta-18743",
82
89
  "@opencode-ai/sdk": "^1.18.9",
83
90
  "@types/node": "^26.1.0",
84
91
  "tsup": "^8.3.0",
package/plugin.json ADDED
@@ -0,0 +1,16 @@
1
+ {
2
+ "name": "hindsight-coding-agents",
3
+ "version": "0.5.0",
4
+ "description": "Long-term project memory for coding agents",
5
+ "skills": "./skill",
6
+ "hooks": "./hooks/hooks.json",
7
+ "mcpServers": {
8
+ "hindsight": {
9
+ "command": "node",
10
+ "args": ["${PLUGIN_ROOT}/dist/mcp-server.js"],
11
+ "env": {
12
+ "HINDSIGHT_MCP_HARNESS": "dcode"
13
+ }
14
+ }
15
+ }
16
+ }
package/skill/SKILL.md CHANGED
@@ -68,6 +68,7 @@ an outdated decision — silent disregard leaves the trap armed for the next ses
68
68
  npx @vectorize-io/hindsight-coding-agents install all # every detected agent, wired natively
69
69
  npx @vectorize-io/hindsight-coding-agents install claude-code # or just one
70
70
  npx @vectorize-io/hindsight-coding-agents uninstall all # removes exactly what install added
71
+ npx @vectorize-io/hindsight-coding-agents update # refresh the runtime only, no rewiring
71
72
  ```
72
73
 
73
74
  `install` takes an explicit target — `all`, or one or more harness names. A bare
@@ -75,19 +76,25 @@ npx @vectorize-io/hindsight-coding-agents uninstall all # removes exactly
75
76
  the machine is never something that happens by accident. **Updating is the same `install`
76
77
  command again** — it re-copies the runtime in place.
77
78
 
79
+ Day to day you should not have to: once a day, a session start checks npm and re-stages a newer
80
+ runtime in the background (`autoUpdate`, on by default — set it to `false` to pin the version you
81
+ have). That is the `update` command above, which refreshes the copy every wired agent already
82
+ points at and deliberately touches no host config; re-run `install` yourself after a release that
83
+ adds a new hook, or to wire another agent.
84
+
78
85
  ## Local daemon settings (daemon mode)
79
86
 
80
87
  Daemon settings keep the names the old per-agent Claude Code plugin used, so an existing
81
88
  environment carries over unchanged:
82
89
 
83
- | field | env | default | meaning |
84
- | ------------------- | ------------------------------- | -------------- | ------------------------------------------ |
85
- | `serverMode` | `HINDSIGHT_SERVER_MODE` | `cloud` | `cloud` \| `self-hosted` \| `daemon` |
86
- | `apiPort` | `HINDSIGHT_API_PORT` | `9077` | port the local daemon listens on |
87
- | `daemonIdleTimeout` | `HINDSIGHT_DAEMON_IDLE_TIMEOUT` | — | seconds of inactivity before it exits |
88
- | `daemonProfile` | `HINDSIGHT_DAEMON_PROFILE` | `coding-agent` | which local database it uses |
89
- | `embedVersion` | `HINDSIGHT_EMBED_VERSION` | `latest` | which `hindsight-embed` release to run |
90
- | `embedPackagePath` | `HINDSIGHT_EMBED_PACKAGE_PATH` | — | run a local checkout instead (development) |
90
+ | field | env | default | meaning |
91
+ | ------------------- | ------------------------------- | -------------- | ---------------------------------------------------------- |
92
+ | `serverMode` | `HINDSIGHT_SERVER_MODE` | `cloud` | `cloud` \| `self-hosted` \| `daemon` |
93
+ | `apiPort` | `HINDSIGHT_API_PORT` | `9077` | port the local daemon listens on |
94
+ | `daemonIdleTimeout` | `HINDSIGHT_DAEMON_IDLE_TIMEOUT` | — | deprecated, ignored: the daemon no longer exits on its own |
95
+ | `daemonProfile` | `HINDSIGHT_DAEMON_PROFILE` | `coding-agent` | which local database it uses |
96
+ | `embedVersion` | `HINDSIGHT_EMBED_VERSION` | `latest` | which `hindsight-embed` release to run |
97
+ | `embedPackagePath` | `HINDSIGHT_EMBED_PACKAGE_PATH` | — | run a local checkout instead (development) |
91
98
 
92
99
  Any `HINDSIGHT_API_*` variable you export is forwarded to the daemon, so server-side settings need
93
100
  no equivalent here.
@@ -125,7 +132,7 @@ what reads it:
125
132
  | host | reads the file | an edit applies |
126
133
  | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------- |
127
134
  | 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 |
128
- | persistent plugins (opencode, Kilo CLI, Cline CLI, Prime Agent, DeepSeek Harness) | once per workspace, when the host loads the plugin | after restarting the agent |
135
+ | 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 |
129
136
  | the MCP server behind the `hindsight_*` tools | once at startup | in your next session |
130
137
 
131
138
  `apiToken` is the exception. Every host re-reads it when the server rejects a request, so enabling
@@ -181,40 +188,42 @@ hook by Codex...), so one shared config serves several agents side by side:
181
188
 
182
189
  ### Reference
183
190
 
184
- | field | default | meaning |
185
- | ----------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
186
- | `apiUrl` | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server) |
187
- | `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 |
188
- | `bankId` | — | **explicit static bank**; unset ⇒ per-repo dynamic resolution (below) |
189
- | `dynamicBankId` | dynamic iff no `bankId` | force dynamic (`true`) or static (`false`) resolution |
190
- | `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo |
191
- | `mapPathToBank` | — | absolute path → bank; **longest prefix wins**; linked worktrees inherit their main checkout's mapping; overrides everything |
192
- | `optInOnly` | `false` | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see [Opt-in only](#opt-in-only) |
193
- | `optInPaths` | — | directories opted in, matched as prefixes with `~` expanded; each repo beneath and its linked worktrees are approved while keeping their own dynamic bank |
194
- | `resolveWorktrees` | `true` | linked worktrees inherit the main checkout's bank identity, path approval, and mapping |
195
- | `retainTags` | — | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
196
- | `retainMetadata` | — | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}` |
197
- | `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"]]` |
198
- | `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
199
- | `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) |
200
- | `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 |
201
- | `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 |
202
- | `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 |
203
- | `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
204
- | `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) |
205
- | `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 |
206
- | `autoSeed` | `true` | SessionStart: auto-seed a cold repo's bank from git history |
207
- | `seedLimit` | `300` | auto-seed: most-recent-N-commits cap |
208
- | `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 |
209
- | `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
210
- | `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
211
- | `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) |
212
- | `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 |
213
- | `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 |
214
- | `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
215
- | `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 |
216
- | `harnesses.<name>` | — | per-harness override of any field above |
217
- | `harness` | `opencode` | **deepen engine only**: which session format `--conversations` is read as |
191
+ | field | default | meaning |
192
+ | ----------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
193
+ | `apiUrl` | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server) |
194
+ | `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 |
195
+ | `bankId` | — | **explicit static bank**; unset ⇒ per-repo dynamic resolution (below) |
196
+ | `dynamicBankId` | dynamic iff no `bankId` | force dynamic (`true`) or static (`false`) resolution |
197
+ | `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo |
198
+ | `mapPathToBank` | — | absolute path → bank; **longest prefix wins**; linked worktrees inherit their main checkout's mapping; overrides everything |
199
+ | `optInOnly` | `false` | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see [Opt-in only](#opt-in-only) |
200
+ | `optInPaths` | — | directories opted in, matched as prefixes with `~` expanded; each repo beneath and its linked worktrees are approved while keeping their own dynamic bank |
201
+ | `resolveWorktrees` | `true` | linked worktrees inherit the main checkout's bank identity, path approval, and mapping |
202
+ | `retainTags` | — | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
203
+ | `retainMetadata` | — | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}` |
204
+ | `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 |
205
+ | `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 |
206
+ | `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
207
+ | `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) |
208
+ | `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 |
209
+ | `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 |
210
+ | `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 |
211
+ | `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
212
+ | `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) |
213
+ | `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 |
214
+ | `autoSeed` | `true` | SessionStart: auto-seed a cold repo's bank from git history |
215
+ | `seedLimit` | `300` | auto-seed: most-recent-N-commits cap |
216
+ | `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 |
217
+ | `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
218
+ | `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
219
+ | `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) |
220
+ | `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 |
221
+ | `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 |
222
+ | `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
223
+ | `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` |
224
+ | `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 |
225
+ | `harnesses.<name>` | — | per-harness override of any field above |
226
+ | `harness` | `opencode` | **deepen engine only**: which session format `--conversations` is read as |
218
227
 
219
228
  `pageTriggerType`/`pageTriggerCron` decide only **when** a page refreshes. **How** it refreshes
220
229
  belongs to the server: Hindsight creates a knowledge page with a delta refresh (each pass edits the
@@ -227,6 +236,38 @@ repo already has: a page keeps the trigger it was created with, so a bank seeded
227
236
  through the API (`PATCH /knowledge-base/nodes/{id}`), an SDK, or the control plane — or delete it
228
237
  and let the next session seed it again.
229
238
 
239
+ ### A bank you shape yourself — `manageBankConfig`
240
+
241
+ Pointed at a bank, this plugin gives it the shape its ingestion needs: retain strategies for the
242
+ kinds of document it writes (`git`, `gitlog`, `conversation`, `document`, `survey`), a `knowledge`
243
+ entity-label group that routes facts to the knowledge pages, and — on a bank that has no missions of
244
+ its own — the coding missions.
245
+
246
+ **It only ever adds what is missing.** A strategy you defined, an edit you made to one of the
247
+ plugin's, a reworded label group, a mission you rewrote in the control plane: each is left exactly
248
+ as it is, on every session, forever. What the bank already says wins. The cost of that promise is
249
+ that a plugin release which _rewords_ an existing strategy or label does not reach a bank that
250
+ already has it. To take the current default back, clear that override on the bank (delete the
251
+ strategy, or the whole `retain_strategies` entry, in the control plane): the next session finds the
252
+ bank silent there and seeds it again.
253
+
254
+ Set `manageBankConfig: false` to keep the plugin out of the bank's configuration altogether — the
255
+ right setting for a bank you share with non-coding work, or one you configure yourself. That bank
256
+ should then define the five strategies above itself. Note that the miss is **silent**: the server
257
+ does not reject a retain naming a strategy the bank lacks, it logs a warning and extracts with the
258
+ bank's own configuration — so a commit diff, a session transcript and a survey marker would all get
259
+ the same generic treatment instead of the extraction each needs. Knowledge pages are seeded either
260
+ way; `pageTriggerType` governs what they cost.
261
+
262
+ Like every field here it can be set per bank, which is usually where it belongs:
263
+
264
+ ```json
265
+ {
266
+ "bankId": "my-global-bank",
267
+ "banks": { "my-global-bank": { "manageBankConfig": false } }
268
+ }
269
+ ```
270
+
230
271
  ### Per-repo opt-in/out — `banks.<bankId>`
231
272
 
232
273
  Per-repo control lives in the SAME file, keyed by the **resolved bank id** (shown in the session
@@ -347,6 +388,36 @@ scope per bank, which is what a bank already is — one project's memory. Set th
347
388
  }
348
389
  ```
349
390
 
391
+ ### Splitting code from conversation — `per_source`
392
+
393
+ `shared` puts every document a repo produces into one belief set. `"per_source"` keeps that set and
394
+ adds one per origin, so "what the commits say" and "what was decided in conversation" can be asked
395
+ apart:
396
+
397
+ ```jsonc
398
+ { "observationScopes": "per_source" }
399
+ ```
400
+
401
+ Each document consolidates into the global scope **plus** one named for each `source:` tag it
402
+ carries — `[[], ["source:chat"]]` for a session transcript, `[[], ["source:git"]]` for a commit
403
+ diff. Read an axis back with `tags: ["source:git"], tags_match: "exact"`, and the merged view with
404
+ `tags: [], tags_match: "exact"`.
405
+
406
+ A document carrying two `source:` tags gets a scope for each, and that is deliberate rather than
407
+ duplication. The commit-message seed is tagged `source:git` and `source:git-log`, so
408
+ `source:git-log` is fed only by the seed — what the commit _messages_ say — while `source:git` also
409
+ collects every per-commit diff under `gitIngest: "full"`. Two questions, two answers, each
410
+ deduplicated within itself by consolidation. A fact belonging to more than one axis is the point.
411
+
412
+ This cannot be expressed as a scope list. The server treats an explicit `list[list[str]]` as
413
+ unconditional — it is not filtered against the memory's own tags — so a configured
414
+ `[[], ["source:git"], ["source:chat"]]` writes every document into all three, and the `source:git`
415
+ scope fills with beliefs built from chat transcripts. Only a per-document decision separates them.
416
+
417
+ It costs one extra consolidation pass per document, and it reads only `source:`, so a volatile
418
+ provenance tag never becomes a scope. The global scope is still written first and unchanged, so the
419
+ untagged observations knowledge pages read are unaffected.
420
+
350
421
  `"per_tag"` and `"all_combinations"` split further still, and an explicit `[["project:demo"], …]`
351
422
  declares the scopes literally. `HINDSIGHT_OBSERVATION_SCOPES` sets the scalar modes; a scope list is
352
423
  file-only. Changing this does not rewrite observations already consolidated under the old scoping —