@vectorize-io/hindsight-coding-agents 0.8.5 → 0.8.7
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 +36 -30
- package/dist/antigravity-hook.js +130 -135
- package/dist/antigravity-statusline.js +1 -1
- package/dist/antigravity-stop-hook.js +113 -114
- package/dist/claude-hook.js +130 -135
- package/dist/claude-sessionstart-hook.js +205 -215
- package/dist/claude-stop-hook.js +113 -114
- package/dist/cline.js +206 -211
- package/dist/codebuddy-hook.js +130 -135
- package/dist/codebuddy-sessionstart-hook.js +205 -215
- package/dist/codebuddy-stop-hook.js +113 -114
- package/dist/codex-hook.js +130 -135
- package/dist/codex-sessionstart-hook.js +205 -215
- package/dist/codex-stop-hook.js +113 -114
- package/dist/copilot-hook.js +130 -135
- package/dist/copilot-sessionstart-hook.js +205 -215
- package/dist/copilot-stop-hook.js +113 -114
- package/dist/cursor-hook.js +130 -135
- package/dist/cursor-sessionstart-hook.js +205 -215
- package/dist/cursor-stop-hook.js +113 -114
- package/dist/daemon-start.js +1 -1
- package/dist/dcode-hook.js +130 -135
- package/dist/dcode-sessionstart-hook.js +205 -215
- package/dist/dcode-stop-hook.js +113 -114
- package/dist/deepen.js +80 -79
- package/dist/devin-hook.js +130 -135
- package/dist/devin-sessionstart-hook.js +205 -215
- package/dist/devin-stop-hook.js +113 -114
- package/dist/droid-hook.js +130 -135
- package/dist/droid-sessionstart-hook.js +205 -215
- package/dist/droid-stop-hook.js +113 -114
- package/dist/dsh.js +235 -248
- package/dist/grok-hook.js +130 -135
- package/dist/grok-sessionstart-hook.js +205 -215
- package/dist/grok-stop-hook.js +113 -114
- package/dist/hindsight-seed.js +1 -1
- package/dist/index.js +236 -249
- package/dist/installer.js +30 -28
- package/dist/kilo.js +236 -249
- package/dist/kimi-hook.js +130 -135
- package/dist/kimi-sessionstart-hook.js +205 -215
- package/dist/kimi-stop-hook.js +113 -114
- package/dist/mcp-server.js +94 -93
- package/dist/opencode2.js +236 -249
- package/dist/pi.js +235 -248
- package/dist/prime-agent.js +235 -248
- package/dist/qwen-hook.js +130 -135
- package/dist/qwen-sessionstart-hook.js +205 -215
- package/dist/qwen-stop-hook.js +113 -114
- package/dist/status.js +80 -79
- package/dist/traecode-hook.js +130 -135
- package/dist/traecode-sessionstart-hook.js +205 -215
- package/dist/traecode-stop-hook.js +113 -114
- package/dist/workbuddy-hook.js +130 -135
- package/dist/workbuddy-sessionstart-hook.js +205 -215
- package/dist/workbuddy-stop-hook.js +113 -114
- package/dist/zcode-hook.js +130 -135
- package/dist/zcode-sessionstart-hook.js +205 -215
- package/dist/zcode-stop-hook.js +113 -114
- package/package.json +2 -1
- package/plugin.json +1 -1
- package/skill/SKILL.md +26 -26
package/README.md
CHANGED
|
@@ -9,9 +9,14 @@ bank in the background as you work.
|
|
|
9
9
|
The premise: most of a real fix is derivable from the code, but the _last mile_ often hinges on a
|
|
10
10
|
project-specific decision that isn't in the code at all — a rounding rule, a retry allowlist, a
|
|
11
11
|
tie-break policy. Those decisions live in git history and past conversations. This package puts them
|
|
12
|
-
in front of the agent at the moment it starts working, and keeps a curated set of **
|
|
12
|
+
in front of the agent at the moment it starts working, and keeps a curated set of **pages**
|
|
13
13
|
(architecture, conventions, in-flight initiatives) that future sessions start from.
|
|
14
14
|
|
|
15
|
+
The agent reads those pages through the `hindsight_search_pages`, `hindsight_list_pages` and
|
|
16
|
+
`hindsight_read_page` tools. Before the rename they were `hindsight_search_knowledge_pages`,
|
|
17
|
+
`hindsight_list_knowledge_pages` and `hindsight_read_knowledge_page`: a permission rule in your
|
|
18
|
+
agent's own settings that names an old tool needs the new name.
|
|
19
|
+
|
|
15
20
|
<!-- figure: coding-agents -->
|
|
16
21
|
|
|
17
22
|
[View Changelog →](https://hindsight.vectorize.io/changelog/integrations/coding-agents)
|
|
@@ -109,9 +114,9 @@ Dcode namespaces a plugin's MCP tools, so they appear as
|
|
|
109
114
|
them from the tool guide either way. In headless runs (`dcode -n`) Dcode allows the read-only
|
|
110
115
|
Hindsight tools and gates the two that write (`hindsight_ingest_document`,
|
|
111
116
|
`hindsight_capture_initiative`) behind an approval it has no UI for; use the interactive TUI to
|
|
112
|
-
capture an initiative or ingest a document. For the same reason
|
|
113
|
-
under
|
|
114
|
-
|
|
117
|
+
capture an initiative or ingest a document. For the same reason Dcode gets no one-time codebase
|
|
118
|
+
survey: the survey runs only under the current agent's own CLI, and only Claude Code, Codex,
|
|
119
|
+
Antigravity and opencode v1 have a headless, read-only recipe for it.
|
|
115
120
|
|
|
116
121
|
#### <img src="https://hindsight.vectorize.io/img/harness/opencode.png" alt="" width="20" height="20" /> opencode
|
|
117
122
|
|
|
@@ -133,12 +138,13 @@ rewrote the plugin API, so it is a harness of its own. It writes the same plugin
|
|
|
133
138
|
if it sees v2's `plugins` key — and each CLI then loads its own entry point from the one registered
|
|
134
139
|
path. So installing either harness wires both, and uninstalling either removes the shared entry.
|
|
135
140
|
|
|
136
|
-
Two differences from v1, both because of the host:
|
|
137
|
-
|
|
138
|
-
banner is written to the plugin log instead of a TUI toast (v2 plugins cannot
|
|
139
|
-
injection, the native `hindsight_*` tools and session write-back are identical.
|
|
140
|
-
is identical too, but it is registered in memory through v2's skill API rather
|
|
141
|
-
skills directory — opencode2 has none of its own, and the two it reads belong to
|
|
141
|
+
Two differences from v1, both because of the host: there is no one-time codebase survey (v2 plugins
|
|
142
|
+
cannot define the read-only agent the survey needs, and the survey never borrows another agent's
|
|
143
|
+
CLI), and the seed banner is written to the plugin log instead of a TUI toast (v2 plugins cannot
|
|
144
|
+
raise one). Recall, injection, the native `hindsight_*` tools and session write-back are identical.
|
|
145
|
+
The companion skill is identical too, but it is registered in memory through v2's skill API rather
|
|
146
|
+
than copied into a skills directory — opencode2 has none of its own, and the two it reads belong to
|
|
147
|
+
other agents.
|
|
142
148
|
|
|
143
149
|
#### <img src="https://hindsight.vectorize.io/img/harness/kilo.svg" alt="" width="20" height="20" /> Kilo CLI
|
|
144
150
|
|
|
@@ -359,7 +365,7 @@ resolved per session workspace rather than once per process; and dsh has no plug
|
|
|
359
365
|
channel, so the seed line goes to the plugin log rather than the UI. A **forked** session saves only
|
|
360
366
|
the turns it adds after the fork — the part it inherited is already in the parent's conversation.
|
|
361
367
|
Everything model-facing —
|
|
362
|
-
recalled memory, the
|
|
368
|
+
recalled memory, the pages preamble, the `hindsight_*` tools — is unaffected. If you prefer the
|
|
363
369
|
published-package route, `dsh plugin --profile web add @vectorize-io/hindsight-coding-agents` works
|
|
364
370
|
too: the package ships the profile patch layer, so nothing else needs editing. Either route gets the
|
|
365
371
|
companion skill — a plugin wired by the host's own plugin manager installs it itself on the first
|
|
@@ -594,7 +600,7 @@ what reads it:
|
|
|
594
600
|
authentication or rotating the key is picked up on the next call with nothing to restart —
|
|
595
601
|
otherwise a rotation would leave a long-running agent failing every memory call until it was
|
|
596
602
|
restarted. Everything else follows the table: `apiUrl`, `disabled`, bank routing, `gitIngest`, and
|
|
597
|
-
the survey and
|
|
603
|
+
the survey and page settings.
|
|
598
604
|
|
|
599
605
|
`hindsight_diagnose` reports both sides of that gap — what the file says now, and what the running
|
|
600
606
|
client is actually using.
|
|
@@ -662,23 +668,23 @@ hook by Codex...), so one shared config serves several agents side by side:
|
|
|
662
668
|
| `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 |
|
|
663
669
|
| `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 |
|
|
664
670
|
| `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
|
|
665
|
-
| `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
|
|
671
|
+
| `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 page search, then to a raw recall of observations (recorded) |
|
|
666
672
|
| `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 |
|
|
667
673
|
| `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 |
|
|
668
674
|
| `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 |
|
|
669
|
-
| `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
|
|
675
|
+
| `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 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 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 |
|
|
670
676
|
| `autoReflect` | `true` | **deprecated** — use `autoInject`. Still honoured (`false` = `autoInject: "none"`), ignored when `autoInject` is set, and logs a deprecation warning |
|
|
671
|
-
| `pageSearchLimit` | `3` |
|
|
677
|
+
| `pageSearchLimit` | `3` | 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_pages` tool — because the limit lives on the client they all share |
|
|
672
678
|
| `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 |
|
|
673
|
-
| `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 `
|
|
674
|
-
| `pageRefreshEveryTurns` | `1` | refetch the
|
|
675
|
-
| `pageTriggerType` | `"cron"` | when NEW
|
|
679
|
+
| `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_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."` |
|
|
680
|
+
| `pageRefreshEveryTurns` | `1` | refetch the pages and re-inject the page roster + tool guide every N user turns (`0` also means 1) |
|
|
681
|
+
| `pageTriggerType` | `"cron"` | when NEW 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) |
|
|
676
682
|
| `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 |
|
|
677
|
-
| `pages` | every page | per-page configuration for the seeded
|
|
678
|
-
| `customPages` | — |
|
|
683
|
+
| `pages` | every page | per-page configuration for the seeded 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 |
|
|
684
|
+
| `customPages` | — | 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 |
|
|
679
685
|
| `autoSeed` | `true` | SessionStart: auto-seed a cold repo's bank from git history |
|
|
680
686
|
| `seedLimit` | `300` | git-log document size: a full write keeps the newest commits, between half of this and this many (the window moves in steps of half), and logs how many older ones it drops |
|
|
681
|
-
| `codebaseSurvey` | `true` | SessionStart: headless survey of a cold repo's structure, run under the current harness's own CLI (
|
|
687
|
+
| `codebaseSurvey` | `true` | SessionStart: headless survey of a cold repo's structure, run only under the current harness's own CLI (Claude Code, Codex, Antigravity, opencode v1); other agents get no survey |
|
|
682
688
|
| `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
|
|
683
689
|
| `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
|
|
684
690
|
| `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) |
|
|
@@ -697,7 +703,7 @@ LLM synthesis per page per consolidation, on a repo that consolidates all day. S
|
|
|
697
703
|
`pageTriggerType: "auto-refresh"` to go back to refreshing on every consolidation.
|
|
698
704
|
|
|
699
705
|
`pageTriggerType`/`pageTriggerCron` decide only **when** a page refreshes. **How** it refreshes
|
|
700
|
-
belongs to the server: Hindsight creates a
|
|
706
|
+
belongs to the server: Hindsight creates a page with a delta refresh (each pass edits the
|
|
701
707
|
page instead of rebuilding it) that doesn't reflect over sibling pages, and these settings merge
|
|
702
708
|
over those defaults rather than replacing them.
|
|
703
709
|
|
|
@@ -735,7 +741,7 @@ file is the source of truth for these pages: to give one a different schedule, c
|
|
|
735
741
|
page. Only the fields this plugin states are touched — a page's `mode`, its excluded siblings and
|
|
736
742
|
its minimum refresh interval are left exactly as they are.
|
|
737
743
|
|
|
738
|
-
### Customize
|
|
744
|
+
### Customize Pages — `pages`
|
|
739
745
|
|
|
740
746
|
Every repo gets the same five pages. They are a **taxonomy**, not a summary of your source: each one
|
|
741
747
|
is synthesized from what the bank ingested — commit history and past conversations — and each is
|
|
@@ -856,7 +862,7 @@ it: the seed pass only visits the pages it is configured to own.
|
|
|
856
862
|
|
|
857
863
|
Pointed at a bank, this plugin gives it the shape its ingestion needs: retain strategies for the
|
|
858
864
|
kinds of document it writes (`git`, `gitlog`, `conversation`, `document`, `survey`), a `knowledge`
|
|
859
|
-
entity-label group that routes facts to the
|
|
865
|
+
entity-label group that routes facts to the pages, and — on a bank that has no missions of
|
|
860
866
|
its own — the coding missions.
|
|
861
867
|
|
|
862
868
|
**It only ever adds what is missing.** A strategy you defined, an edit you made to one of the
|
|
@@ -905,7 +911,7 @@ you configure yourself. That bank should then define the five strategies above i
|
|
|
905
911
|
miss is **silent**: the server does not reject a retain naming a strategy the bank lacks, it logs a
|
|
906
912
|
warning and extracts with the bank's own configuration — so a commit diff, a session transcript and
|
|
907
913
|
a survey marker would all get the same generic treatment instead of the extraction each needs.
|
|
908
|
-
|
|
914
|
+
Pages are seeded either way; `pageTriggerType` governs what they cost.
|
|
909
915
|
|
|
910
916
|
Like every field here it can be set per bank, which is usually where it belongs:
|
|
911
917
|
|
|
@@ -1096,7 +1102,7 @@ scope fills with beliefs built from chat transcripts. Only a per-document decisi
|
|
|
1096
1102
|
|
|
1097
1103
|
It costs one extra consolidation pass per document, and it reads only `source:`, so a volatile
|
|
1098
1104
|
provenance tag never becomes a scope. The global scope is still written first and unchanged, so the
|
|
1099
|
-
untagged observations
|
|
1105
|
+
untagged observations pages read are unaffected.
|
|
1100
1106
|
|
|
1101
1107
|
`"per_tag"` and `"all_combinations"` split further still, and an explicit `[["project:demo"], …]`
|
|
1102
1108
|
declares the scopes literally. `HINDSIGHT_OBSERVATION_SCOPES` sets the scalar modes; a scope list is
|
|
@@ -1110,7 +1116,7 @@ they stay where they were built, and new work accrues under the new setting.
|
|
|
1110
1116
|
There is no user-facing ingest command — the deepen engine (`dist/deepen.js`) is spawned by every
|
|
1111
1117
|
session start and does only the missing work: bank configuration, conversation import (dedup by
|
|
1112
1118
|
document id), the one-time gitlog seed, the next per-commit diff batch (newest first, bounded per
|
|
1113
|
-
run), then
|
|
1119
|
+
run), then pages once extraction has drained. Harnesses that need deterministic ingestion
|
|
1114
1120
|
(benchmarks, e2e suites) run the same engine directly and poll `dist/status.js` until
|
|
1115
1121
|
`"synced": true` — the exact readiness contract the `hindsight_sync_status` agent tool reports.
|
|
1116
1122
|
|
|
@@ -1176,7 +1182,7 @@ as a JSON line to `~/.hindsight/coding-agents-logs/diag.jsonl` (override with
|
|
|
1176
1182
|
|
|
1177
1183
|
`reflect_failed` / `pages_failed` record the error; if you're comparing memory-on vs memory-off,
|
|
1178
1184
|
check this file — a run whose reflects failed is a no-memory run. When the failure was a timeout or
|
|
1179
|
-
a 5xx, the hook falls back to
|
|
1185
|
+
a 5xx, the hook falls back to page search and, if no page matches, to a raw recall of the
|
|
1180
1186
|
bank's memories: `reflect_fallback_pages` / `reflect_fallback_observations` record what each
|
|
1181
1187
|
step returned (`*_failed` when it errored). Seed starts are logged as
|
|
1182
1188
|
`seed_started`.
|
|
@@ -1204,8 +1210,8 @@ that: `"synced": true` means the seeded memory is queryable. It also reports git
|
|
|
1204
1210
|
far per-commit deepening has got, the codebase survey's state (`surveyBaseline` is the HEAD the last
|
|
1205
1211
|
survey started from, `surveyDocs` counts the findings documents that have landed, 0–4 — a baseline
|
|
1206
1212
|
with no findings retries automatically, at most three times per commit), and the extraction
|
|
1207
|
-
operations still in flight.
|
|
1208
|
-
with an error leaves one `[survey]` line in the plugin log.
|
|
1213
|
+
operations still in flight. A survey that was skipped (no survey for this agent, or its CLI not
|
|
1214
|
+
found), failed to launch or exited with an error leaves one `[survey]` line in the plugin log.
|
|
1209
1215
|
|
|
1210
1216
|
### Resetting a repo's memory
|
|
1211
1217
|
|