@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.
- package/README.md +201 -16
- package/dist/antigravity-hook.js +1132 -115
- package/dist/antigravity-statusline.js +77 -11
- package/dist/antigravity-stop-hook.js +1193 -133
- package/dist/claude-hook.js +1132 -115
- package/dist/claude-sessionstart-hook.js +1241 -140
- package/dist/claude-stop-hook.js +1193 -133
- package/dist/cline.js +578 -163
- package/dist/codebuddy-hook.js +4270 -0
- package/dist/codebuddy-sessionstart-hook.js +5030 -0
- package/dist/codebuddy-stop-hook.js +4564 -0
- package/dist/codex-hook.js +1132 -115
- package/dist/codex-sessionstart-hook.js +1241 -140
- package/dist/codex-stop-hook.js +1193 -133
- package/dist/copilot-hook.js +1132 -115
- package/dist/copilot-sessionstart-hook.js +1241 -140
- package/dist/copilot-stop-hook.js +1193 -133
- package/dist/cursor-hook.js +1132 -115
- package/dist/cursor-sessionstart-hook.js +1241 -140
- package/dist/cursor-stop-hook.js +1193 -133
- package/dist/daemon-start.js +54 -9
- package/dist/dcode-hook.js +1132 -115
- package/dist/dcode-sessionstart-hook.js +1241 -140
- package/dist/dcode-stop-hook.js +1193 -133
- package/dist/deepen.js +370 -104
- package/dist/devin-hook.js +1132 -115
- package/dist/devin-sessionstart-hook.js +1241 -140
- package/dist/devin-stop-hook.js +1193 -133
- package/dist/droid-hook.js +1132 -115
- package/dist/droid-sessionstart-hook.js +1241 -140
- package/dist/droid-stop-hook.js +1193 -133
- package/dist/dsh.js +586 -164
- package/dist/grok-hook.js +1132 -115
- package/dist/grok-sessionstart-hook.js +1241 -140
- package/dist/grok-stop-hook.js +1193 -133
- package/dist/hindsight-seed.js +50 -8
- package/dist/index.js +587 -172
- package/dist/installer.js +2010 -769
- package/dist/kilo.js +587 -172
- package/dist/kimi-hook.js +4270 -0
- package/dist/kimi-sessionstart-hook.js +5030 -0
- package/dist/kimi-stop-hook.js +4564 -0
- package/dist/mcp-server.js +419 -115
- package/dist/opencode2.js +586 -169
- package/dist/pi.js +644 -175
- package/dist/prime-agent.js +644 -175
- package/dist/qwen-hook.js +1132 -115
- package/dist/qwen-sessionstart-hook.js +1241 -140
- package/dist/qwen-stop-hook.js +1193 -133
- package/dist/status.js +243 -52
- package/dist/traecode-hook.js +4270 -0
- package/dist/traecode-sessionstart-hook.js +5030 -0
- package/dist/traecode-stop-hook.js +4564 -0
- package/dist/workbuddy-hook.js +4270 -0
- package/dist/workbuddy-sessionstart-hook.js +5030 -0
- package/dist/workbuddy-stop-hook.js +4564 -0
- package/dist/zcode-hook.js +1132 -115
- package/dist/zcode-sessionstart-hook.js +1241 -140
- package/dist/zcode-stop-hook.js +1193 -133
- package/package.json +22 -12
- package/plugin.json +1 -1
- 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
|
|
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 `
|
|
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),
|
|
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
|
-
| `
|
|
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
|
|
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
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
the
|
|
747
|
-
|
|
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
|
|
1001
|
-
`retainSessions
|
|
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
|