@vectorize-io/hindsight-coding-agents 0.4.0 β†’ 0.4.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.
package/skill/SKILL.md CHANGED
@@ -3,6 +3,9 @@ name: hindsight-coding-agent
3
3
  description: How this machine's Hindsight coding-agent memory works β€” the plugin behind the 🧠 banner. Use when the user says "store/remember this in hindsight", asks what the memory/knowledge pages are, wants to configure per-repo memory (disable, rename banks, git depth), or something memory-related looks broken.
4
4
  ---
5
5
 
6
+ <!-- GENERATED from README.md (its skill:begin regions) + skill-src/preamble.md.
7
+ Edit those, then run: npm run skill:build -->
8
+
6
9
  # Hindsight Coding-Agent Memory
7
10
 
8
11
  This machine runs the `hindsight-coding-agents` plugin: long-term project memory for coding
@@ -16,8 +19,9 @@ explains what happens automatically, which tools you have, and how to configure
16
19
  - **Ingestion builds itself**: on first open, the bank is seeded from recent commit messages and a
17
20
  read-only codebase survey; every session start, a background engine tops it up (new commits, new
18
21
  conversations) and keeps 5 knowledge pages current. There is NO ingest command to run.
19
- - **Session synthesis**: the first prompt of a session triggers one deep memory synthesis
20
- (`reflect`) injected into context. Later turns inject nothing automatically.
22
+ - **Session synthesis**: by default, the first prompt of a session triggers one deep memory
23
+ synthesis (`reflect`) injected into context. With `autoReflect=false`, the agent searches the
24
+ knowledge pages first and reflects only when they are too shallow.
21
25
  - **Write-back**: the session transcript is retained into the bank automatically at session end
22
26
  (per-turn on opencode). The user never needs to "save" a conversation.
23
27
 
@@ -58,81 +62,354 @@ Newer facts supersede older ones in retrieval, so one clear correction permanent
58
62
  stale memory. Do this whenever you catch a wrong injected memory, a stale knowledge-page claim, or
59
63
  an outdated decision β€” silent disregard leaves the trap armed for the next session.
60
64
 
61
- ## Configuration β€” ONE file: `~/.hindsight/coding-agent.json`
65
+ ## Install / update
66
+
67
+ ```bash
68
+ npx @vectorize-io/hindsight-coding-agents install all # every detected agent, wired natively
69
+ npx @vectorize-io/hindsight-coding-agents install claude-code # or just one
70
+ npx @vectorize-io/hindsight-coding-agents uninstall all # removes exactly what install added
71
+ ```
72
+
73
+ `install` takes an explicit target β€” `all`, or one or more harness names. A bare
74
+ `npx @vectorize-io/hindsight-coding-agents install` changes nothing and prints the choice, so wiring every agent on
75
+ the machine is never something that happens by accident. **Updating is the same `install`
76
+ command again** β€” it re-copies the runtime in place.
77
+
78
+ ## Local daemon settings (daemon mode)
79
+
80
+ Daemon settings keep the names the old per-agent Claude Code plugin used, so an existing
81
+ environment carries over unchanged:
82
+
83
+ | field | env | default | meaning |
84
+ | ------------------- | ------------------------------- | -------------- | ------------------------------------------ |
85
+ | `serverMode` | `HINDSIGHT_SERVER_MODE` | `cloud` | `cloud` \| `self-hosted` \| `daemon` |
86
+ | `apiPort` | `HINDSIGHT_API_PORT` | `9077` | port the local daemon listens on |
87
+ | `daemonIdleTimeout` | `HINDSIGHT_DAEMON_IDLE_TIMEOUT` | β€” | seconds of inactivity before it exits |
88
+ | `daemonProfile` | `HINDSIGHT_DAEMON_PROFILE` | `coding-agent` | which local database it uses |
89
+ | `embedVersion` | `HINDSIGHT_EMBED_VERSION` | `latest` | which `hindsight-embed` release to run |
90
+ | `embedPackagePath` | `HINDSIGHT_EMBED_PACKAGE_PATH` | β€” | run a local checkout instead (development) |
91
+
92
+ Any `HINDSIGHT_API_*` variable you export is forwarded to the daemon, so server-side settings need
93
+ no equivalent here.
94
+
95
+ ## Configuration
96
+
97
+ Configuration is **one JSON file**: `~/.hindsight/coding-agent.json`. Layering, later wins per field:
98
+
99
+ 1. built-in defaults
100
+ 2. environment variables β€” `HINDSIGHT_API_URL`, `HINDSIGHT_API_TOKEN`, and one per scalar setting
101
+ (`HINDSIGHT_<FIELD_IN_CAPS>`), for containers and CI that inject config rather than write a file
102
+ 3. the file's top level
103
+ 4. its `harnesses.<name>` section β€” per-agent override
104
+ 5. its `banks.<resolvedBankId>` section β€” per-repo override, applied after the bank is resolved
105
+ (see [Per-repo opt-in/out](#per-repo-opt-inout--banksbankid))
106
+
107
+ Environment variables are a **fallback**: the file wins wherever it sets a value, so adding env to
108
+ an existing setup changes nothing. The two list-valued settings, `retainTags` and `optInPaths`, take
109
+ a comma-separated value (`HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work"`); entries are
110
+ trimmed and blanks dropped.
111
+ The map-valued settings (`mapPathToBank`, `harnesses`, `banks`, `retainMetadata`) are file-only β€”
112
+ per-key branching doesn't survive flattening into one variable. `maxParallelRetains` is available
113
+ as `HINDSIGHT_MAX_PARALLEL_RETAINS` for containers and CI.
114
+
115
+ `HINDSIGHT_CONFIG` moves the file itself β€” point it at another path for a container or a test
116
+ harness where `$HOME` is not the right anchor. It is still exactly one file; only its location
117
+ changes. (The other variables that are not settings are `HINDSIGHT_LOG_FILE`, `HINDSIGHT_DIAG_FILE`
118
+ and `HINDSIGHT_LOG_LEVEL` β€” see [Diagnostics & logging](#diagnostics--logging).)
119
+
120
+ ### When a change takes effect
121
+
122
+ Config is read when a process starts β€” the file is not watched β€” so when an edit applies depends on
123
+ what reads it:
124
+
125
+ | host | reads the file | an edit applies |
126
+ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------- |
127
+ | hook harnesses (Claude Code, Codex CLI, Cursor CLI, GitHub Copilot CLI, Grok Build, Antigravity CLI, Devin) | once per hook invocation β€” each hook is its own short-lived process | on your next prompt |
128
+ | persistent plugins (opencode, Kilo CLI, Cline CLI, Prime Agent, DeepSeek Harness) | once per workspace, when the host loads the plugin | after restarting the agent |
129
+ | the MCP server behind the `hindsight_*` tools | once at startup | in your next session |
130
+
131
+ `apiToken` is the exception. Every host re-reads it when the server rejects a request, so enabling
132
+ authentication or rotating the key is picked up on the next call with nothing to restart β€”
133
+ otherwise a rotation would leave a long-running agent failing every memory call until it was
134
+ restarted. Everything else follows the table: `apiUrl`, `disabled`, bank routing, `gitIngest`, and
135
+ the survey and knowledge-page settings.
136
+
137
+ `hindsight_diagnose` reports both sides of that gap β€” what the file says now, and what the running
138
+ client is actually using.
139
+
140
+ ### Opt-in only
141
+
142
+ By default every project gets memory β€” that is what makes the plugin zero-setup. If you would
143
+ rather nothing be remembered until you say so, turn memory off everywhere and name the projects
144
+ that may use it:
145
+
146
+ ```jsonc
147
+ {
148
+ "optInOnly": true,
149
+ "optInPaths": ["~/work/client-x", "~/oss"],
150
+ }
151
+ ```
152
+
153
+ Anything outside those paths is **inert**: no bank is created, nothing is retained, no seed runs,
154
+ and the agent behaves exactly as it would without the plugin. Approving costs nothing else β€”
155
+ `optInPaths` says _which projects_, not _which bank_, so an approved repo keeps its usual
156
+ `coding-agent::{gitProject}` name. Paths are prefixes, so approving `~/work` approves every repo
157
+ under it while each still gets its own bank.
158
+
159
+ A `mapPathToBank` entry counts as opted in too, since routing a path to a named bank already
160
+ declares that project. A bare `bankId` does not: it names a bank rather than a project, so it
161
+ cannot say which work may be remembered, and a privacy switch has to fail closed.
162
+
163
+ There is no per-repo opt-in file, for the same reason there is no repo-carried config at all: a
164
+ cloned repository must not be able to turn memory on.
62
165
 
63
- No environment variables (exceptions: `HINDSIGHT_CONFIG` relocates this file;
64
- `HINDSIGHT_DIAG_FILE`/`HINDSIGHT_LOG_FILE`/`HINDSIGHT_LOG_LEVEL` for diagnostics).
65
- Layering, later wins: defaults β†’ file β†’ `harnesses.<name>` β†’ `banks.<resolvedBankId>`.
166
+ There is deliberately no repo-carried config file β€” per-repo bank routing is `mapPathToBank`,
167
+ per-agent differences are `harnesses.<name>`.
168
+
169
+ Each entry point knows which harness it _is_ (the opencode plugin is loaded by opencode, the codex
170
+ hook by Codex...), so one shared config serves several agents side by side:
171
+
172
+ ```jsonc
173
+ {
174
+ "apiUrl": "https://api.hindsight.vectorize.io",
175
+ "harnesses": {
176
+ "opencode": { "reflectTimeoutMs": 60000 },
177
+ "claude-code": { "disabled": true }, // e.g. memory off for Claude only
178
+ },
179
+ }
180
+ ```
181
+
182
+ ### Reference
183
+
184
+ | field | default | meaning |
185
+ | ----------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
186
+ | `apiUrl` | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server) |
187
+ | `apiToken` | β€” | bearer token (Hindsight Cloud). Picked up without restarting the agent: a long-lived host re-reads it after a rejected request, so enabling auth or rotating the key mid-session recovers on the next call |
188
+ | `bankId` | β€” | **explicit static bank**; unset β‡’ per-repo dynamic resolution (below) |
189
+ | `dynamicBankId` | dynamic iff no `bankId` | force dynamic (`true`) or static (`false`) resolution |
190
+ | `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo |
191
+ | `mapPathToBank` | β€” | absolute path β†’ bank; **longest prefix wins**; linked worktrees inherit their main checkout's mapping; overrides everything |
192
+ | `optInOnly` | `false` | run memory ONLY in opted-in projects β€” everything else is inert, with no bank created; see [Opt-in only](#opt-in-only) |
193
+ | `optInPaths` | β€” | directories opted in, matched as prefixes with `~` expanded; each repo beneath and its linked worktrees are approved while keeping their own dynamic bank |
194
+ | `resolveWorktrees` | `true` | linked worktrees inherit the main checkout's bank identity, path approval, and mapping |
195
+ | `retainTags` | β€” | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` β€” see **Recording where a memory came from** below |
196
+ | `retainMetadata` | β€” | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}` |
197
+ | `observationScopes` | `"shared"` | how consolidation groups observations: `"shared"` (default) = ONE global scope per bank, so every agent on a repo builds one set of beliefs; also `"combined"` (the server default), `"per_tag"`, `"all_combinations"`, `[["t"]]` |
198
+ | `disabled` | `false` | hard off-switch (inert plugin/hook β€” a no-memory baseline) |
199
+ | `reflectTimeoutMs` | `120000` | **automatic** session-reflect timeout (hook harnesses additionally cap it at 25s to fit the host's hook window); on timeout the session runs without reflect (recorded) |
200
+ | `reflectToolTimeoutMs` | `330000` | timeout for the agent-invoked `hindsight_reflect` tool β€” a call the agent waits on, whose high-budget synthesis on a populated bank runs for minutes. Defaults above the server's own reflect wall timeout (`HINDSIGHT_API_REFLECT_WALL_TIMEOUT`, 300s) so the server decides when to give up. Unset, it inherits an explicitly raised `reflectTimeoutMs`, but a short one never lowers it |
201
+ | `reflectBudget` | `"high"` | reflect budget for the `hindsight_reflect` tool: `"low"`, `"mid"` or `"high"`. Drop it on a large bank where high-budget synthesis exceeds the server's wall timeout. The automatic session-start reflect always uses `"low"` to fit its hook window and is unaffected |
202
+ | `autoReflect` | `true` | inject a one-time reflect synthesis on the session's **first prompt**. `false` = tool-only reflect: nothing is injected; the agent searches knowledge pages first and reflects only when they are too shallow |
203
+ | `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
204
+ | `pageTriggerType` | `"auto-refresh"` | when NEW knowledge pages refresh, i.e. what keeping them current costs β€” `"auto-refresh"` after every consolidation that produced new material, `"cron"` on `pageTriggerCron` only, `"manual"` never on their own. Auto-refresh is the most current and the most expensive: one synthesis per page per consolidation. Maps to the page's `trigger.refresh_after_consolidation` in the Hindsight API (`true` for auto-refresh, `false` for manual) |
205
+ | `pageTriggerCron` | β€” | schedule for `pageTriggerType: "cron"` β€” UTC, standard 5-field cron, e.g. `"0 3 * * *"`. Sets the page's `trigger.refresh_cron`, which the API treats as mutually exclusive with `refresh_after_consolidation`; a scheduled refresh is skipped when nothing changed |
206
+ | `autoSeed` | `true` | SessionStart: auto-seed a cold repo's bank from git history |
207
+ | `seedLimit` | `300` | auto-seed: most-recent-N-commits cap |
208
+ | `codebaseSurvey` | `true` | SessionStart: headless survey of a cold repo's structure, run under the current harness's own CLI (claude/codex/antigravity/opencode), falling back to any available agent |
209
+ | `surveyModel` | `haiku` | model for the survey β€” Claude recipe only (`claude -p --model`); other agents use their configured default |
210
+ | `surveyBudgetUsd` | `2` | survey spend cap β€” Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
211
+ | `surveyRefreshCommits` | `20` | re-run the survey at SessionStart once this many commits have accrued since the last one, so the structural pages track an architecture that keeps moving (`0` = survey a cold repo only, never again) |
212
+ | `retainSessions` | `true` | session write-back, honored by every harness: hook harnesses write the transcript on Stop, plugin harnesses (opencode, Kilo) upsert it every turn plus an idle flush that captures the reply the per-turn pass can't see. Set `false` β€” globally, per harness, or per bank β€” to stop writing transcripts (the background history import stops with it) while recall, git ingest and the memory tools keep working |
213
+ | `maxParallelRetains` | `10` | cap on concurrent retain-related requests: drain()'s per-op polls plus deepen's chat/git retain pools. The API rate-limits bursts, not single requests β€” if you see 429s, lower this rather than raising it |
214
+ | `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
215
+ | `gitIngest` | `"message"` | git depth for seeding AND staying current (same engine): `"message"` = commit messages only (one doc, re-upserted when HEAD moves); `"full"` = messages + per-commit full diffs (progressive, newest first); `"none"` = git off |
216
+ | `harnesses.<name>` | β€” | per-harness override of any field above |
217
+ | `harness` | `opencode` | **deepen engine only**: which session format `--conversations` is read as |
218
+
219
+ `pageTriggerType`/`pageTriggerCron` decide only **when** a page refreshes. **How** it refreshes
220
+ belongs to the server: Hindsight creates a knowledge page with a delta refresh (each pass edits the
221
+ page instead of rebuilding it) that doesn't reflect over sibling pages, and these settings merge
222
+ over those defaults rather than replacing them.
223
+
224
+ **These settings apply to pages created from here on.** Changing them does not migrate the pages a
225
+ repo already has: a page keeps the trigger it was created with, so a bank seeded before you set
226
+ `"manual"` keeps refreshing on every consolidation. To move an existing page, change its trigger
227
+ through the API (`PATCH /knowledge-base/nodes/{id}`), an SDK, or the control plane β€” or delete it
228
+ and let the next session seed it again.
229
+
230
+ ### Per-repo opt-in/out β€” `banks.<bankId>`
231
+
232
+ Per-repo control lives in the SAME file, keyed by the **resolved bank id** (shown in the session
233
+ banner) and applied AFTER bank resolution β€” so it works regardless of where the repo lives, and
234
+ survives directory moves:
66
235
 
67
236
  ```jsonc
68
237
  {
69
- "apiUrl": "http://localhost:8888", // your Hindsight server
70
- "apiToken": "…", // Hindsight Cloud only
71
- "gitIngest": "message", // "message" | "full" (per-commit diffs) | "none"
72
- "harnesses": { "claude-code": { "disabled": true } }, // per-agent override of anything
73
- "mapPathToBank": { "/Users/me/work/client-x": "client-x-memory" }, // path-prefix β†’ bank
74
238
  "banks": {
75
- // per-repo control, keyed by RESOLVED bank id
76
- "coding-agent::secret": { "disabled": true }, // blacklist a repo
77
- "coding-agent::old": { "bank": "team::shared" }, // rename / converge banks (single hop)
78
- "coding-agent::mono": { "gitIngest": "full", "retainSessions": false },
239
+ "coding-agent::secret-client": { "disabled": true }, // blacklist: no memory at all
240
+ "coding-agent::old-name": { "bank": "team::shared" }, // rename / converge banks
241
+ "coding-agent::big-mono": { "gitIngest": "full", "retainSessions": false },
79
242
  },
80
243
  }
81
244
  ```
82
245
 
83
- Key behavioral fields (any of them valid per-harness or per-bank): `disabled`,
84
- `retainSessions` (transcript write-back opt-out, history import included β€” recall and git ingest keep working), `gitIngest`,
85
- `reflectTimeoutMs` (AUTOMATIC session reflect, default 120000; hooks cap at 25s),
86
- `reflectToolTimeoutMs`/`reflectBudget` (the agent-invoked `hindsight_reflect` tool: default 330000 β€”
87
- above the server's 300s reflect wall timeout β€” and "high"), `autoReflect` (true; false = no injected
88
- first-prompt synthesis β€” the agent is instead told to call `hindsight_reflect` on new goals),
89
- `pageRefreshEveryTurns` (10),
90
- `pageTriggerType`/`pageTriggerCron` (when NEW knowledge pages refresh: `auto-refresh` (default) after
91
- each consolidation, `cron` on a schedule, `manual` never β€” existing pages keep the trigger they were
92
- created with), `autoSeed`/`seedLimit` (true/300),
93
- `codebaseSurvey`/`surveyModel`/`surveyBudgetUsd` (true/haiku/2), `surveyRefreshCommits` (0=off),
94
- `logLevel` ("info").
95
-
96
- Config is read at process start, not watched: a hook harness picks an edit up on the next prompt, a
97
- persistent plugin (opencode, Kilo, Cline, Prime Agent, dsh) only after the agent restarts, and the
98
- MCP server in the next session. `apiToken` is the exception β€” re-read whenever the server rejects a
99
- request, so rotating it needs no restart. `hindsight_diagnose` reports the file's token and the
100
- running client's separately, which is how you tell a stale credential from a wrong one.
101
-
102
- Blacklist a whole directory tree: map it to one bank and disable that bank β€”
103
- `"mapPathToBank": {"~/scratch": "scratch"}` + `"banks": {"scratch": {"disabled": true}}`.
104
-
105
- Bank resolution order: `mapPathToBank` longest prefix β†’ static `bankId` β†’ template
106
- (default `coding-agent::{gitProject}`) β†’ the matching `banks.<id>` section (its `bank` field
107
- renames the destination). Two repos share memory by converging their `banks.<id>.bank` on one
108
- name, or by one `mapPathToBank` prefix over their parent directory.
109
-
110
- ## Install / update (for setting up another machine or harness)
246
+ Any behavioral field can be overridden per bank, and `bank` **renames the destination** (single
247
+ hop: the section is selected by the resolved id, the target is literal β€” several ids may converge
248
+ on one shared bank, and the target's own section is not consulted). Other bank-resolution fields
249
+ are ignored inside a bank section.
111
250
 
112
- ```bash
113
- npx @vectorize-io/hindsight-coding-agents install all # every detected agent
114
- npx @vectorize-io/hindsight-coding-agents install codex # or specific: opencode|claude-code|codex|antigravity-cli|cursor-cli
115
- npx @vectorize-io/hindsight-coding-agents uninstall # removes exactly what install added
116
- # updating is the same install command again β€” it re-copies the runtime in place
251
+ #### Recipe: two repos, one shared bank
252
+
253
+ Two ways, by what the natural key is:
254
+
255
+ **By resolved id** β€” you know the repo names; works wherever the repos live (and keeps working if
256
+ they move). Both ids converge on one literal target:
257
+
258
+ ```jsonc
259
+ {
260
+ "banks": {
261
+ "coding-agent::backend": { "bank": "team::product" },
262
+ "coding-agent::frontend": { "bank": "team::product" },
263
+ },
264
+ }
265
+ ```
266
+
267
+ **By path prefix** β€” the repos live under one directory; a single `mapPathToBank` entry covers
268
+ every repo (present and future) beneath it:
269
+
270
+ ```jsonc
271
+ {
272
+ "mapPathToBank": { "/Users/me/work/client-x": "client-x-memory" },
273
+ }
274
+ ```
275
+
276
+ Rule of thumb: converge by **id** for a hand-picked set of repos; map by **path** when a folder is
277
+ the boundary ("everything I clone under `work/client-x` shares memory").
278
+
279
+ ### Bank resolution
280
+
281
+ Coding memory is **per repository**. Resolution order for the working directory:
282
+
283
+ 1. `mapPathToBank` β€” longest matching absolute-path prefix (mapping a repo root covers every
284
+ subdirectory; deeper mappings win; overrides even an explicit `bankId`).
285
+ 2. Static β€” `bankId` set (or `dynamicBankId: false`).
286
+ 3. Dynamic β€” `bankIdTemplate` with placeholders:
287
+ - `{gitProject}` β€” worktree-aware repo name: `git rev-parse --git-common-dir` resolves every
288
+ linked worktree to the **main** worktree's basename, so all worktrees of a repo share one bank
289
+ (bare repos use the bare dir name). **Outside a repo** there is nothing for git to resolve, so
290
+ it falls back to the basename of the directory the **session started in** β€” an agent that
291
+ `cd`s into a subdirectory keeps writing to one bank, and a subdirectory gets its own bank only
292
+ when you deliberately start a session there
293
+ - `{project}` β€” plain working-directory basename
294
+ - `{harness}` β€” the entry point asking (`opencode`, `claude-code`, `codex`, `antigravity-cli`, `cursor-cli`, `copilot-cli`)
295
+ - `{channel}` / `{user}` β€” `$HINDSIGHT_CHANNEL_ID` / `$HINDSIGHT_USER_ID`
296
+
297
+ The default `"coding-agent::{gitProject}"` is **harness-neutral**, so opencode, Claude Code, and Codex
298
+ all share one memory per repo β€” use `"{harness}-{gitProject}"` to split per agent instead.
299
+
300
+ ### Recording where a memory came from
301
+
302
+ With a bank per repo, the bank _is_ the answer to "where did this come from". On a deliberately
303
+ **shared** bank β€” one bank holding cross-project knowledge so facts recall everywhere β€” it isn't:
304
+ every memory looks alike. `retainTags` and `retainMetadata` stamp that provenance onto conversations,
305
+ git history and diffs, survey lifecycle documents, initiative markers, and documents saved through
306
+ `hindsight_ingest_document`:
307
+
308
+ ```jsonc
309
+ {
310
+ "bankId": "shared", // one bank for everything
311
+ "retainTags": ["project:{gitProject}", "env:work"],
312
+ "retainMetadata": { "repo": "{gitProject}" },
313
+ }
314
+ ```
315
+
316
+ Recalls can then filter by `project:<repo>`, and every document shows which repository it came out
317
+ of. Both accept the same placeholders as `bankIdTemplate` β€” `{gitProject}`, `{project}`,
318
+ `{harness}`, `{channel}`, `{user}` β€” plus `{bankId}`, `{sessionId}` and `{timestamp}`.
319
+ `{gitProject}` is worktree-aware here too, so every linked worktree of a repo stamps one name.
320
+ `{sessionId}` resolves to `unknown` for documents that do not originate from an agent session.
321
+
322
+ The plugin's own `source:` and `harness:` tags are reserved: entries in those namespaces are ignored
323
+ with a warning, so a document's agent attribution always reflects the agent that actually wrote it.
324
+
325
+ ### One set of beliefs per repo
326
+
327
+ Every document this integration writes carries provenance tags β€” `source:chat`, `harness:<id>`,
328
+ `knowledge:<kind>`, plus anything from `retainTags`. Those tags say **who wrote** a memory; they are
329
+ what filters recall and draws each document's agent logo, and they stay on the facts.
330
+
331
+ They are not, however, a good boundary for
332
+ [observations](https://hindsight.vectorize.io/developer/observations). Consolidation's own
333
+ default (`combined`) builds one observation set per distinct tag set, so the same repository
334
+ worked on by two agents would grow two parallel sets of beliefs β€” one per harness β€” that never
335
+ merge, each blind to the other, at double the consolidation cost. Which agent happened to be typing
336
+ does not change whether a convention or a decision is true.
337
+
338
+ So the integration retains with `observationScopes: "shared"`: one global, untagged observation
339
+ scope per bank, which is what a bank already is β€” one project's memory. Set the field to change it:
340
+
341
+ ```jsonc
342
+ {
343
+ "observationScopes": "combined", // one observation set per distinct tag set (server default)
344
+ "banks": {
345
+ "coding-agent::mono": { "observationScopes": "per_tag" }, // per-repo, like any behavioral field
346
+ },
347
+ }
117
348
  ```
118
349
 
119
- ## Debugging
120
-
121
- - **Readiness**: `hindsight_sync_status` β€” `synced: true` = seeded memory queryable; also shows
122
- gitlog freshness, per-commit deepening progress, survey state (`surveyDocs` 0–4 = findings
123
- present; baseline without findings retries automatically), and active extraction ops.
124
- - **Logs**: `$TMPDIR/hindsight-coding-agent/plugin.log` (leveled; set `"logLevel": "debug"` or
125
- `HINDSIGHT_LOG_LEVEL=debug` to mirror every event) and `/tmp/hindsight-plugin.log` (structured
126
- JSONL diag events with timings: `session_start`, `reflect_ok`, `deepen_done`, `retain_ok`, …).
127
- - **Reset a repo's memory**: delete its bank on the server β€” the bank is the ONLY state; the next
128
- session is a true first-open. No client files to clean.
129
- - **Rule of thumb**: memory silently missing β†’ check the diag log for whether `session_start`/
130
- `deepen_started` ever fired for that bank; a session started before the plugin was installed has
131
- no SessionStart behind it (its first prompt after install self-heals).
132
- - **Internal marker docs you may notice** (safe to ignore, safe to delete): `survey-baseline:<sha>`
133
- β€” "πŸ›°οΈ researching…" while a codebase survey runs, flipped to "βœ… completed" once its findings
134
- land. Retained under the `survey` strategy, whose marker rule extracts NOTHING from status markers;
135
- powers the re-survey cadence and `surveyBaseline` in sync status. `gitlog:<repo>` is the
136
- aggregated commit-message seed document.
137
- - Failures never break the agent: reflect/pages/retain failures degrade to a normal memoryless
138
- turn and are recorded in the logs.
350
+ `"per_tag"` and `"all_combinations"` split further still, and an explicit `[["project:demo"], …]`
351
+ declares the scopes literally. `HINDSIGHT_OBSERVATION_SCOPES` sets the scalar modes; a scope list is
352
+ file-only. Changing this does not rewrite observations already consolidated under the old scoping β€”
353
+ they stay where they were built, and new work accrues under the new setting.
354
+
355
+ ## Diagnostics & logging
356
+
357
+ Two files, two audiences:
358
+
359
+ **Leveled plugin log** (humans debugging): `$TMPDIR/hindsight-coding-agent/plugin.log` (override
360
+ `HINDSIGHT_LOG_FILE`) β€” timestamped `LEVEL [scope] message` lines from every component, including
361
+ the ingestion engine. Level defaults to `info`; set `"logLevel": "debug"` in config or
362
+ `HINDSIGHT_LOG_LEVEL=debug` for ad-hoc debugging (at `debug`, every diag event below is mirrored
363
+ here too, so one file tells the whole story).
364
+
365
+ **Structured diag events** (machines/harnesses): every reflect and page-fetch outcome is appended
366
+ as a JSON line to `/tmp/hindsight-plugin.log` (override with `HINDSIGHT_DIAG_FILE`):
367
+
368
+ ```json
369
+ {
370
+ "ts": "2026-07-27T07:05:52Z",
371
+ "harness": "claude-code",
372
+ "event": "reflect_ok",
373
+ "ms": 14210,
374
+ "chars": 792,
375
+ "query": "..."
376
+ }
377
+ ```
378
+
379
+ `reflect_failed` / `pages_failed` record the error; if you're comparing memory-on vs memory-off,
380
+ check this file β€” a run whose reflects failed is a no-memory run. Seed starts are logged as
381
+ `seed_started`.
382
+
383
+ ### Is the memory ready yet?
384
+
385
+ `hindsight_sync_status` β€” the agent-facing tool, `dist/status.js` for scripts β€” answers exactly
386
+ that: `"synced": true` means the seeded memory is queryable. It also reports gitlog freshness, how
387
+ far per-commit deepening has got, the codebase survey's state (`surveyBaseline` is the HEAD the last
388
+ survey started from, `surveyDocs` counts the findings documents that have landed, 0–4 β€” a baseline
389
+ with no findings retries automatically), and the extraction operations still in flight.
390
+
391
+ ### Resetting a repo's memory
392
+
393
+ Delete its bank on the server. The bank is the **only** state this integration keeps, so the next
394
+ session in that repo is a true first open β€” seed and survey run again from scratch. There are no
395
+ client-side files to clean up.
396
+
397
+ ### Marker documents you may notice
398
+
399
+ Two document ids exist for the machinery's own bookkeeping. Both are safe to ignore and safe to
400
+ delete:
401
+
402
+ - `survey-baseline:<sha>` β€” reads "πŸ›°οΈ researching…" while a codebase survey runs and flips to
403
+ "βœ… completed" once its findings land. It is retained under the `survey` strategy, whose marker
404
+ rule extracts **nothing** from a status marker, and it drives the re-survey cadence
405
+ (`surveyRefreshCommits`) and `surveyBaseline` in sync status.
406
+ - `gitlog:<repo>` β€” the aggregated commit-message seed document, re-upserted rather than duplicated
407
+ when the seed runs again.
408
+
409
+ ### When memory seems to be missing
410
+
411
+ Failures never break the agent: a reflect, page fetch or retain that fails degrades to an ordinary
412
+ memoryless turn and is recorded in the logs. "No memory" is therefore a log question β€” check the
413
+ diag file for whether `session_start` and `deepen_started` ever fired for that bank. A session that
414
+ was already running when the plugin was installed has no SessionStart behind it; its first prompt
415
+ after the install self-heals.