@vectorize-io/hindsight-coding-agents 0.6.0 → 0.7.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.
- package/README.md +179 -40
- package/dist/antigravity-hook.js +344 -169
- package/dist/antigravity-statusline.js +117 -4
- package/dist/antigravity-stop-hook.js +262 -113
- package/dist/claude-hook.js +344 -169
- package/dist/claude-sessionstart-hook.js +348 -136
- package/dist/claude-stop-hook.js +262 -113
- package/dist/cline.js +494 -184
- package/dist/codex-hook.js +344 -169
- package/dist/codex-sessionstart-hook.js +348 -136
- package/dist/codex-stop-hook.js +262 -113
- package/dist/copilot-hook.js +344 -169
- package/dist/copilot-sessionstart-hook.js +348 -136
- package/dist/copilot-stop-hook.js +262 -113
- package/dist/cursor-hook.js +344 -169
- package/dist/cursor-sessionstart-hook.js +348 -136
- package/dist/cursor-stop-hook.js +262 -113
- package/dist/daemon-start.js +116 -4
- package/dist/dcode-hook.js +344 -169
- package/dist/dcode-sessionstart-hook.js +348 -136
- package/dist/dcode-stop-hook.js +262 -113
- package/dist/deepen.js +204 -47
- package/dist/devin-hook.js +344 -169
- package/dist/devin-sessionstart-hook.js +348 -136
- package/dist/devin-stop-hook.js +262 -113
- package/dist/droid-hook.js +344 -169
- package/dist/droid-sessionstart-hook.js +348 -136
- package/dist/droid-stop-hook.js +262 -113
- package/dist/dsh.js +494 -184
- package/dist/grok-hook.js +344 -169
- package/dist/grok-sessionstart-hook.js +348 -136
- package/dist/grok-stop-hook.js +262 -113
- package/dist/hindsight-seed.js +116 -4
- package/dist/index.js +494 -184
- package/dist/installer.js +92 -70
- package/dist/kilo.js +494 -184
- package/dist/mcp-server.js +230 -57
- package/dist/opencode2.js +521 -184
- package/dist/pi.js +495 -186
- package/dist/prime-agent.js +495 -186
- package/dist/qwen-hook.js +344 -169
- package/dist/qwen-sessionstart-hook.js +348 -136
- package/dist/qwen-stop-hook.js +262 -113
- package/dist/status.js +203 -47
- package/dist/zcode-hook.js +344 -169
- package/dist/zcode-sessionstart-hook.js +348 -136
- package/dist/zcode-stop-hook.js +262 -113
- package/package.json +2 -2
- package/plugin.json +1 -1
- package/skill/SKILL.md +173 -39
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vectorize-io/hindsight-coding-agents",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"repository": {
|
|
5
5
|
"type": "git",
|
|
6
6
|
"url": "https://github.com/vectorize-io/hindsight.git",
|
|
@@ -92,7 +92,7 @@
|
|
|
92
92
|
},
|
|
93
93
|
"devDependencies": {
|
|
94
94
|
"@opencode-ai/plugin": "^1.18.9",
|
|
95
|
-
"@opencode
|
|
95
|
+
"@opencode/plugin": "^2.0.3",
|
|
96
96
|
"@opencode-ai/sdk": "^1.18.9",
|
|
97
97
|
"@types/node": "^26.1.0",
|
|
98
98
|
"tsup": "^8.3.0",
|
package/plugin.json
CHANGED
package/skill/SKILL.md
CHANGED
|
@@ -20,8 +20,9 @@ explains what happens automatically, which tools you have, and how to configure
|
|
|
20
20
|
read-only codebase survey; every session start, a background engine tops it up (new commits, new
|
|
21
21
|
conversations) and keeps 5 knowledge pages current. There is NO ingest command to run.
|
|
22
22
|
- **Session synthesis**: by default, the first prompt of a session triggers one deep memory
|
|
23
|
-
synthesis (`reflect`) injected into context.
|
|
24
|
-
|
|
23
|
+
synthesis (`reflect`) injected into context. `autoInject` switches the source: `pages` (knowledge
|
|
24
|
+
page search hits), `recall` (recalled observations), or `none` (nothing injected; the agent
|
|
25
|
+
searches the knowledge pages first and reflects only when they are too shallow).
|
|
25
26
|
- **Write-back**: the session transcript is retained into the bank automatically at session end
|
|
26
27
|
(per-turn on opencode). The user never needs to "save" a conversation.
|
|
27
28
|
|
|
@@ -189,42 +190,48 @@ hook by Codex...), so one shared config serves several agents side by side:
|
|
|
189
190
|
|
|
190
191
|
### Reference
|
|
191
192
|
|
|
192
|
-
| field | default | meaning
|
|
193
|
-
| ----------------------- | ------------------------------------ |
|
|
194
|
-
| `apiUrl` | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server)
|
|
195
|
-
| `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
|
|
196
|
-
| `bankId` | — | **explicit static bank**; unset ⇒ per-repo dynamic resolution (below)
|
|
197
|
-
| `dynamicBankId` | dynamic iff no `bankId` | force dynamic (`true`) or static (`false`) resolution
|
|
198
|
-
| `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo
|
|
199
|
-
| `mapPathToBank` | — | absolute path → bank; **longest prefix wins**; linked worktrees inherit their main checkout's mapping; overrides everything
|
|
200
|
-
| `optInOnly` | `false` | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see [Opt-in only](#opt-in-only)
|
|
201
|
-
| `optInPaths` | — | directories opted in, matched as prefixes with `~` expanded; each repo beneath and its linked worktrees are approved while keeping their own dynamic bank
|
|
202
|
-
| `resolveWorktrees` | `true` | linked worktrees inherit the main checkout's bank identity, path approval, and mapping
|
|
203
|
-
| `retainTags` | — | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below
|
|
204
|
-
| `retainMetadata` | — | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}`
|
|
205
|
-
| `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
|
|
206
|
-
| `
|
|
207
|
-
| `
|
|
208
|
-
| `
|
|
209
|
-
| `
|
|
210
|
-
| `
|
|
211
|
-
| `
|
|
212
|
-
| `
|
|
213
|
-
| `
|
|
214
|
-
| `
|
|
215
|
-
| `
|
|
216
|
-
| `
|
|
217
|
-
| `
|
|
218
|
-
| `
|
|
219
|
-
| `
|
|
220
|
-
| `
|
|
221
|
-
| `
|
|
222
|
-
| `
|
|
223
|
-
| `
|
|
224
|
-
| `
|
|
225
|
-
| `
|
|
226
|
-
| `
|
|
227
|
-
| `
|
|
193
|
+
| field | default | meaning |
|
|
194
|
+
| ----------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
195
|
+
| `apiUrl` | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server) |
|
|
196
|
+
| `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 |
|
|
197
|
+
| `bankId` | — | **explicit static bank**; unset ⇒ per-repo dynamic resolution (below) |
|
|
198
|
+
| `dynamicBankId` | dynamic iff no `bankId` | force dynamic (`true`) or static (`false`) resolution |
|
|
199
|
+
| `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo |
|
|
200
|
+
| `mapPathToBank` | — | absolute path → bank; **longest prefix wins**; linked worktrees inherit their main checkout's mapping; overrides everything |
|
|
201
|
+
| `optInOnly` | `false` | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see [Opt-in only](#opt-in-only) |
|
|
202
|
+
| `optInPaths` | — | directories opted in, matched as prefixes with `~` expanded; each repo beneath and its linked worktrees are approved while keeping their own dynamic bank |
|
|
203
|
+
| `resolveWorktrees` | `true` | linked worktrees inherit the main checkout's bank identity, path approval, and mapping |
|
|
204
|
+
| `retainTags` | — | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
|
|
205
|
+
| `retainMetadata` | — | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}` |
|
|
206
|
+
| `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 |
|
|
207
|
+
| `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`) |
|
|
208
|
+
| `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 |
|
|
209
|
+
| `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
|
|
210
|
+
| `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) |
|
|
211
|
+
| `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 |
|
|
212
|
+
| `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 |
|
|
213
|
+
| `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), so they stay well inside the hook window |
|
|
214
|
+
| `autoReflect` | `true` | **deprecated** — use `autoInject`. Still honoured (`false` = `autoInject: "none"`), ignored when `autoInject` is set, and logs a deprecation warning |
|
|
215
|
+
| `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 |
|
|
216
|
+
| `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 |
|
|
217
|
+
| `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
|
|
218
|
+
| `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) |
|
|
219
|
+
| `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 |
|
|
220
|
+
| `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 |
|
|
221
|
+
| `customPages` | — | knowledge pages of your own, seeded alongside the five above and keyed by the name they get: `{"Security posture": {"source_query": "...", "tags": ["knowledge:decision"]}}`. `source_query` is required; `tags` picks which facts feed the page and is optional — omitted, the page draws on everything the bank holds. A separate setting from `pages` on purpose, so that an unknown name there stays a typo warning rather than quietly creating a page. File-only, and replaced (not merged) by a `banks.<id>` section |
|
|
222
|
+
| `autoSeed` | `true` | SessionStart: auto-seed a cold repo's bank from git history |
|
|
223
|
+
| `seedLimit` | `300` | auto-seed: most-recent-N-commits cap |
|
|
224
|
+
| `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 |
|
|
225
|
+
| `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
|
|
226
|
+
| `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
|
|
227
|
+
| `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) |
|
|
228
|
+
| `retainSessions` | `true` | session write-back, honored by every harness: hook harnesses write the transcript on Stop, Factory Droid also writes on its cancellation notification, and plugin harnesses (opencode, opencode 2, Kilo) upsert it every turn plus an idle flush that captures the reply the per-turn pass can't see. Set `false` - globally, per harness, or per bank - to stop writing transcripts (the background history import stops with it) while recall, git ingest and the memory tools keep working |
|
|
229
|
+
| `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 |
|
|
230
|
+
| `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
|
|
231
|
+
| `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` |
|
|
232
|
+
| `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 |
|
|
233
|
+
| `harnesses.<name>` | — | per-harness override of any field above |
|
|
234
|
+
| `harness` | `opencode` | **deepen engine only**: which session format `--conversations` is read as |
|
|
228
235
|
|
|
229
236
|
By default a page refreshes **hourly, staggered**: `pageTriggerCron` is `"H * * * *"`, so every
|
|
230
237
|
page gets its own minute of the hour (see below) and a tick with nothing new to fold in is skipped
|
|
@@ -271,6 +278,123 @@ file is the source of truth for these pages: to give one a different schedule, c
|
|
|
271
278
|
page. Only the fields this plugin states are touched — a page's `mode`, its excluded siblings and
|
|
272
279
|
its minimum refresh interval are left exactly as they are.
|
|
273
280
|
|
|
281
|
+
### Customize Knowledge Pages — `pages`
|
|
282
|
+
|
|
283
|
+
Every repo gets the same five pages. They are a **taxonomy**, not a summary of your source: each one
|
|
284
|
+
is synthesized from what the bank ingested — commit history and past conversations — and each is
|
|
285
|
+
pinned to one knowledge tier, so a page draws only on the facts the extractor routed to it.
|
|
286
|
+
|
|
287
|
+
| Page | What it answers | Tier tag |
|
|
288
|
+
| ------------------------------ | ------------------------------------------------------------------------------------------------------- | ------------------------ |
|
|
289
|
+
| `Component map` | the main components/modules/subsystems, what each is responsible for, and how they depend on each other | `knowledge:component` |
|
|
290
|
+
| `Core concepts` | the domain abstractions and key entities — the vocabulary a developer has to know | `knowledge:concept` |
|
|
291
|
+
| `Conventions and patterns` | how THIS project does things: testing, error handling, naming, structure, how changes are made | `knowledge:convention` |
|
|
292
|
+
| `Key decisions and rationale` | the significant technical decisions and the durable "why we do it this way" behind them | `knowledge:decision` |
|
|
293
|
+
| `Initiatives and enhancements` | the major initiatives and features over time, linking out to each captured initiative's own page | `knowledge:feature-work` |
|
|
294
|
+
|
|
295
|
+
`pages` says which of them to seed and what each one asks. Keys are the page names above, matched
|
|
296
|
+
ignoring case and surrounding spaces:
|
|
297
|
+
|
|
298
|
+
```jsonc
|
|
299
|
+
{
|
|
300
|
+
"pages": {
|
|
301
|
+
// don't seed this page at all
|
|
302
|
+
"Component map": false,
|
|
303
|
+
// seed it, but ask your question instead of the built-in one
|
|
304
|
+
"Key decisions and rationale": {
|
|
305
|
+
"source_query": "What did we decide about data retention, encryption and PII handling, and why? Prefer decisions that constrain what new code may do.",
|
|
306
|
+
},
|
|
307
|
+
},
|
|
308
|
+
}
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
Omit `pages` entirely — the default — and all five are seeded with their built-in queries.
|
|
312
|
+
|
|
313
|
+
**Fewer pages.** Each page costs one LLM synthesis per refresh, so a repo that only wants the
|
|
314
|
+
architecture ones turns the rest off:
|
|
315
|
+
|
|
316
|
+
```jsonc
|
|
317
|
+
{
|
|
318
|
+
"pages": {
|
|
319
|
+
"Initiatives and enhancements": false,
|
|
320
|
+
"Conventions and patterns": false,
|
|
321
|
+
"Key decisions and rationale": false,
|
|
322
|
+
},
|
|
323
|
+
}
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
**Per repo**, like every other field — usually where this belongs, since what a page should ask is a
|
|
327
|
+
property of the project, not of your machine:
|
|
328
|
+
|
|
329
|
+
```jsonc
|
|
330
|
+
{
|
|
331
|
+
"banks": {
|
|
332
|
+
"coding-agent::payments-api": {
|
|
333
|
+
"pages": {
|
|
334
|
+
"Core concepts": {
|
|
335
|
+
"source_query": "What are the payment domain's entities — orders, ledgers, settlement states — and what does each mean in OUR model?",
|
|
336
|
+
},
|
|
337
|
+
},
|
|
338
|
+
},
|
|
339
|
+
},
|
|
340
|
+
}
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
Four things worth knowing before you reach for it:
|
|
344
|
+
|
|
345
|
+
- **This is the only durable way to reword a page.** Every session compares each seeded page against
|
|
346
|
+
the query it is configured to have and re-syncs the ones that differ, so a `source_query` edited
|
|
347
|
+
through the API or the control plane is replaced the next time an agent runs. Setting it here makes
|
|
348
|
+
your wording the configured one. When a re-sync does replace a query, the plugin now says which
|
|
349
|
+
page in the plugin log rather than doing it silently.
|
|
350
|
+
- **Your query still gets the scoping clause.** The sentence that keeps a dependency's decisions off
|
|
351
|
+
your project's page is appended to a custom query too — a bank holds facts about the libraries and
|
|
352
|
+
services a repo merely uses, and without that clause a page will present them as yours.
|
|
353
|
+
- **The tier tag stays the taxonomy's.** It selects which facts the synthesis reads; rewording the
|
|
354
|
+
question changes what is asked of those facts, not which ones are in scope.
|
|
355
|
+
- **`false` does not delete anything.** A page already seeded keeps its content and simply stops
|
|
356
|
+
being re-synced — remove it in the control plane if you want it gone.
|
|
357
|
+
|
|
358
|
+
A name that matches no page above is ignored with a warning in the plugin log, so a typo fails
|
|
359
|
+
loudly instead of looking like it disabled something. Adding pages of your own is not what this
|
|
360
|
+
setting is for: the agent's `hindsight_capture_initiative` tool already creates pages, one per
|
|
361
|
+
initiative, each with its own query.
|
|
362
|
+
|
|
363
|
+
#### Pages of your own — `customPages`
|
|
364
|
+
|
|
365
|
+
`pages` only reworks the five above. To add a page, name it under `customPages`:
|
|
366
|
+
|
|
367
|
+
```jsonc
|
|
368
|
+
{
|
|
369
|
+
"customPages": {
|
|
370
|
+
"Security posture": {
|
|
371
|
+
"source_query": "What are this project's security decisions — authn, secrets handling, PII, dependency policy — and what do they constrain in new code?",
|
|
372
|
+
"tags": ["knowledge:decision"],
|
|
373
|
+
},
|
|
374
|
+
"Operational runbook": {
|
|
375
|
+
"source_query": "How does this project get deployed, monitored and rolled back? What has broken in production, and what fixed it?",
|
|
376
|
+
},
|
|
377
|
+
},
|
|
378
|
+
}
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
`source_query` is required. `tags` is optional and picks which facts feed the page — one of the tier
|
|
382
|
+
tags above, or any tag you stamp on your own writes with `retainTags`. Omit it and the page draws on
|
|
383
|
+
everything the bank holds: a refresh matches tags with `all`, so no tags means no tag constraint,
|
|
384
|
+
**not** an empty page.
|
|
385
|
+
|
|
386
|
+
Your pages are seeded at the same root as the taxonomy, on the same refresh schedule, and re-synced
|
|
387
|
+
from the config the same way — reword one here and the live page follows on the next session. They
|
|
388
|
+
compose with `pages`, so trading two built-ins for one of your own is just both settings at once.
|
|
389
|
+
|
|
390
|
+
**Why it is a separate setting.** `pages` refuses a name that matches no seeded page, and that is
|
|
391
|
+
what makes a typo loud: if an unknown key there meant "create this page", `"Componnet map"` would
|
|
392
|
+
quietly create an empty second page instead of rewording the one you meant. For the same reason,
|
|
393
|
+
naming a seeded page under `customPages` is refused — reword it under `pages`.
|
|
394
|
+
|
|
395
|
+
A page you create yourself in the control plane is a third thing again, and the plugin never touches
|
|
396
|
+
it: the seed pass only visits the pages it is configured to own.
|
|
397
|
+
|
|
274
398
|
### A bank you shape yourself — `manageBankConfig`
|
|
275
399
|
|
|
276
400
|
Pointed at a bank, this plugin gives it the shape its ingestion needs: retain strategies for the
|
|
@@ -286,6 +410,11 @@ already has it. To take the current default back, clear that override on the ban
|
|
|
286
410
|
strategy, or the whole `retain_strategies` entry, in the control plane): the next session finds the
|
|
287
411
|
bank silent there and seeds it again.
|
|
288
412
|
|
|
413
|
+
One field is the exception: the extraction mode of the plugin's own four strategies (`git`,
|
|
414
|
+
`gitlog`, `conversation`, `document`) follows `retainExtractionMode` and is put back on every session
|
|
415
|
+
if it drifts — the same way a seeded page's query is. Change it in `coding-agent.json`, not in the
|
|
416
|
+
control plane. The strategies' other fields, and your own strategies, are still left alone.
|
|
417
|
+
|
|
289
418
|
Set `manageBankConfig: false` to keep the plugin out of the bank's configuration altogether — the
|
|
290
419
|
right setting for a bank you share with non-coding work, or one you configure yourself. That bank
|
|
291
420
|
should then define the five strategies above itself. Note that the miss is **silent**: the server
|
|
@@ -487,10 +616,15 @@ as a JSON line to `~/.hindsight/coding-agents-logs/diag.jsonl` (override with
|
|
|
487
616
|
`reflect_failed` / `pages_failed` record the error; if you're comparing memory-on vs memory-off,
|
|
488
617
|
check this file — a run whose reflects failed is a no-memory run. When the failure was a timeout or
|
|
489
618
|
a 5xx, the hook falls back to knowledge-page search and, if no page matches, to a raw recall of the
|
|
490
|
-
bank's
|
|
619
|
+
bank's memories: `reflect_fallback_pages` / `reflect_fallback_observations` record what each
|
|
491
620
|
step returned (`*_failed` when it errored). Seed starts are logged as
|
|
492
621
|
`seed_started`.
|
|
493
622
|
|
|
623
|
+
When `autoInject` names a retrieval source instead of reflect, that source records its own
|
|
624
|
+
outcome with the number of items it returned: `inject_pages` for `"pages"`, `inject_recall` for
|
|
625
|
+
`"recall"` (`inject_pages_failed` / `inject_recall_failed` when the call errored). No reflect
|
|
626
|
+
event is written on those turns — nothing reflected.
|
|
627
|
+
|
|
494
628
|
**Tool usage** (is the agent using Hindsight?): one JSON line per finished user turn in
|
|
495
629
|
`~/.hindsight/coding-agents-logs/usage.jsonl` (override `HINDSIGHT_USAGE_FILE`) — the `hindsight_*`
|
|
496
630
|
tools the agent called during that turn, and whether its reply credited Hindsight memory ("From
|