@vectorize-io/hindsight-coding-agents 0.8.0 → 0.8.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/README.md +73 -8
  2. package/dist/antigravity-hook.js +444 -80
  3. package/dist/antigravity-statusline.js +9 -4
  4. package/dist/antigravity-stop-hook.js +444 -95
  5. package/dist/claude-hook.js +444 -80
  6. package/dist/claude-sessionstart-hook.js +476 -93
  7. package/dist/claude-stop-hook.js +444 -95
  8. package/dist/cline.js +322 -122
  9. package/dist/codebuddy-hook.js +4273 -0
  10. package/dist/codebuddy-sessionstart-hook.js +5033 -0
  11. package/dist/codebuddy-stop-hook.js +4567 -0
  12. package/dist/codex-hook.js +444 -80
  13. package/dist/codex-sessionstart-hook.js +476 -93
  14. package/dist/codex-stop-hook.js +444 -95
  15. package/dist/copilot-hook.js +444 -80
  16. package/dist/copilot-sessionstart-hook.js +476 -93
  17. package/dist/copilot-stop-hook.js +444 -95
  18. package/dist/cursor-hook.js +444 -80
  19. package/dist/cursor-sessionstart-hook.js +476 -93
  20. package/dist/cursor-stop-hook.js +444 -95
  21. package/dist/daemon-start.js +16 -8
  22. package/dist/dcode-hook.js +444 -80
  23. package/dist/dcode-sessionstart-hook.js +476 -93
  24. package/dist/dcode-stop-hook.js +444 -95
  25. package/dist/deepen.js +252 -79
  26. package/dist/devin-hook.js +444 -80
  27. package/dist/devin-sessionstart-hook.js +476 -93
  28. package/dist/devin-stop-hook.js +444 -95
  29. package/dist/droid-hook.js +444 -80
  30. package/dist/droid-sessionstart-hook.js +476 -93
  31. package/dist/droid-stop-hook.js +444 -95
  32. package/dist/dsh.js +329 -122
  33. package/dist/grok-hook.js +444 -80
  34. package/dist/grok-sessionstart-hook.js +476 -93
  35. package/dist/grok-stop-hook.js +444 -95
  36. package/dist/hindsight-seed.js +9 -4
  37. package/dist/index.js +331 -131
  38. package/dist/installer.js +1046 -647
  39. package/dist/kilo.js +331 -131
  40. package/dist/kimi-hook.js +444 -80
  41. package/dist/kimi-sessionstart-hook.js +476 -93
  42. package/dist/kimi-stop-hook.js +444 -95
  43. package/dist/mcp-server.js +272 -89
  44. package/dist/opencode2.js +328 -128
  45. package/dist/pi.js +384 -134
  46. package/dist/prime-agent.js +384 -134
  47. package/dist/qwen-hook.js +444 -80
  48. package/dist/qwen-sessionstart-hook.js +476 -93
  49. package/dist/qwen-stop-hook.js +444 -95
  50. package/dist/status.js +124 -43
  51. package/dist/traecode-hook.js +444 -80
  52. package/dist/traecode-sessionstart-hook.js +476 -93
  53. package/dist/traecode-stop-hook.js +444 -95
  54. package/dist/workbuddy-hook.js +4273 -0
  55. package/dist/workbuddy-sessionstart-hook.js +5033 -0
  56. package/dist/workbuddy-stop-hook.js +4567 -0
  57. package/dist/zcode-hook.js +444 -80
  58. package/dist/zcode-sessionstart-hook.js +476 -93
  59. package/dist/zcode-stop-hook.js +444 -95
  60. package/package.json +9 -3
  61. package/plugin.json +1 -1
  62. package/skill/SKILL.md +10 -6
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**, **Kimi Code**, **Factory Droid**, **ZCode**, **TraeCode**, **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" -->
@@ -145,7 +172,9 @@ npx @vectorize-io/hindsight-coding-agents install grok-build
145
172
 
146
173
  Native hooks in `~/.grok/hooks/hindsight.json`, MCP in `~/.grok/config.toml`, plus the companion
147
174
  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.
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).
149
178
 
150
179
  #### <img src="https://hindsight.vectorize.io/img/harness/qwen-code.svg" alt="" width="20" height="20" /> Qwen Code
151
180
 
@@ -334,6 +363,38 @@ too: the package ships the profile patch layer, so nothing else needs editing. E
334
363
  companion skill — a plugin wired by the host's own plugin manager installs it itself on the first
335
364
  session, since that route never runs our installer.
336
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
+
337
398
  Uninstall the same way: `npx @vectorize-io/hindsight-coding-agents uninstall claude-code` (or `uninstall all`).
338
399
 
339
400
  **Devin CLI needs Node 22.5 or newer.** Its hooks pass only a session id — the conversation itself
@@ -603,12 +664,12 @@ hook by Codex...), so one shared config serves several agents side by side:
603
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 |
604
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 |
605
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 |
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` |
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 |
607
668
  | `autoReflect` | `true` | **deprecated** — use `autoInject`. Still honoured (`false` = `autoInject: "none"`), ignored when `autoInject` is set, and logs a deprecation warning |
608
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 |
609
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 |
610
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."` |
611
- | `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
672
+ | `pageRefreshEveryTurns` | `1` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns (`0` also means 1) |
612
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) |
613
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 |
614
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 |
@@ -1121,8 +1182,8 @@ event is written on those turns — nothing reflected.
1121
1182
  `~/.hindsight/coding-agents-logs/usage.jsonl` (override `HINDSIGHT_USAGE_FILE`) — the `hindsight_*`
1122
1183
  tools the agent called during that turn, and whether its reply credited Hindsight memory ("From
1123
1184
  Hindsight memory"). The credit rate counts only turns that called a retrieval tool (search, list,
1124
- read, reflect); saving a document is not expected to be credited. Recorded when the session is written back, so a scope with
1125
- `retainSessions: false` records none. It never leaves your machine. Summarize it per agent with:
1185
+ read, reflect); saving a document is not expected to be credited. Recorded at the end of each turn,
1186
+ whether or not `retainSessions` writes the session back. It never leaves your machine. Summarize it per agent with:
1126
1187
 
1127
1188
  ```bash
1128
1189
  npx @vectorize-io/hindsight-coding-agents stats
@@ -1151,8 +1212,12 @@ delete:
1151
1212
  "✅ completed" once its findings land. It is retained under the `survey` strategy, whose marker
1152
1213
  rule extracts **nothing** from a status marker, and it drives the re-survey cadence
1153
1214
  (`surveyRefreshCommits`) and `surveyBaseline` in sync status.
1154
- - `gitlog:<repo>` — the aggregated commit-message seed document, re-upserted rather than duplicated
1155
- when the seed runs again.
1215
+ - `gitlog:<repo>` — the aggregated commit-message seed document, oldest commit first. Once seeded it
1216
+ is kept current by **appending** only the commits since the one its `gitlog-head:<sha>` tag
1217
+ names, so a new commit costs the extraction of its own message, not of the whole log. It is
1218
+ written in full again (bounded by `seedLimit`) only when an append cannot describe HEAD: the
1219
+ recorded commit is no longer an ancestor of HEAD (a rebase, a force-push), more than `seedLimit`
1220
+ commits are new, or the server cannot append safely.
1156
1221
 
1157
1222
  ### When memory seems to be missing
1158
1223