@vectorize-io/hindsight-coding-agents 0.3.4 → 0.4.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 CHANGED
@@ -251,9 +251,9 @@ Nothing to sign up for and nothing to host — memory runs on your machine. The
251
251
  A session that begins before it is ready simply has no memory for a turn or two — a daemon that
252
252
  isn't up is treated as an unreachable server, exactly like a Cloud or self-hosted outage, with the
253
253
  same error handling and the same diagnostics. Nothing downstream of the URL knows which mode it is.
254
- - **It shuts down on idle**, after `daemonIdleTimeout` seconds. There is deliberately no
255
- stop-on-exit: one daemon is shared, so ending one session must not cut memory out from under
256
- another agent still working.
254
+ - **It keeps running** until you stop it. There is deliberately no stop-on-exit: one daemon is
255
+ shared, so ending one session must not cut memory out from under another agent still working.
256
+ Set `daemonIdleTimeout` to have it exit after that many seconds of inactivity.
257
257
  - **macOS additionally needs a current Rust toolchain.** `litellm` (a transitive dependency of the
258
258
  API) publishes wheels only for Linux and Windows, so a Mac compiles it from source through
259
259
  maturin and its crates pin a recent `rustc`. Install from [rustup.rs](https://rustup.rs) and keep
@@ -270,7 +270,7 @@ environment carries over unchanged:
270
270
  | ------------------- | ------------------------------- | -------------- | ------------------------------------------ |
271
271
  | `serverMode` | `HINDSIGHT_SERVER_MODE` | `cloud` | `cloud` \| `self-hosted` \| `daemon` |
272
272
  | `apiPort` | `HINDSIGHT_API_PORT` | `9077` | port the local daemon listens on |
273
- | `daemonIdleTimeout` | `HINDSIGHT_DAEMON_IDLE_TIMEOUT` | `300` | seconds of inactivity before it exits |
273
+ | `daemonIdleTimeout` | `HINDSIGHT_DAEMON_IDLE_TIMEOUT` | — | seconds of inactivity before it exits |
274
274
  | `daemonProfile` | `HINDSIGHT_DAEMON_PROFILE` | `coding-agent` | which local database it uses |
275
275
  | `embedVersion` | `HINDSIGHT_EMBED_VERSION` | `latest` | which `hindsight-embed` release to run |
276
276
  | `embedPackagePath` | `HINDSIGHT_EMBED_PACKAGE_PATH` | — | run a local checkout instead (development) |
@@ -295,6 +295,26 @@ The map-valued settings (`mapPathToBank`, `harnesses`, `banks`, `retainMetadata`
295
295
  per-key branching doesn't survive flattening into one variable. `maxParallelRetains` is available
296
296
  as `HINDSIGHT_MAX_PARALLEL_RETAINS` for containers and CI.
297
297
 
298
+ ### When a change takes effect
299
+
300
+ Config is read when a process starts — the file is not watched — so when an edit applies depends on
301
+ what reads it:
302
+
303
+ | host | reads the file | an edit applies |
304
+ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------- |
305
+ | 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 |
306
+ | persistent plugins (opencode, Kilo CLI, Cline CLI, Prime Agent, DeepSeek Harness) | once per workspace, when the host loads the plugin | after restarting the agent |
307
+ | the MCP server behind the `hindsight_*` tools | once at startup | in your next session |
308
+
309
+ `apiToken` is the exception. Every host re-reads it when the server rejects a request, so enabling
310
+ authentication or rotating the key is picked up on the next call with nothing to restart —
311
+ otherwise a rotation would leave a long-running agent failing every memory call until it was
312
+ restarted. Everything else follows the table: `apiUrl`, `disabled`, bank routing, `gitIngest`, and
313
+ the survey and knowledge-page settings.
314
+
315
+ `hindsight_diagnose` reports both sides of that gap — what the file says now, and what the running
316
+ client is actually using.
317
+
298
318
  ### Opt-in only
299
319
 
300
320
  By default every project gets memory — that is what makes the plugin zero-setup. If you would
@@ -339,33 +359,49 @@ hook by Codex...), so one shared config serves several agents side by side:
339
359
 
340
360
  ### Reference
341
361
 
342
- | field | default | meaning |
343
- | ----------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
344
- | `apiUrl` | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server) |
345
- | `apiToken` | — | bearer token (Hindsight Cloud) |
346
- | `bankId` | — | **explicit static bank**; unset ⇒ per-repo dynamic resolution (below) |
347
- | `dynamicBankId` | dynamic iff no `bankId` | force dynamic (`true`) or static (`false`) resolution |
348
- | `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo |
349
- | `mapPathToBank` | — | absolute path → bank; **longest prefix wins**; overrides everything |
350
- | `optInOnly` | `false` | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see [Opt-in only](#opt-in-only) |
351
- | `optInPaths` | — | directories opted in, matched as prefixes with `~` expanded; each repo beneath keeps its own dynamic bank |
352
- | `resolveWorktrees` | `true` | `{gitProject}`: linked worktrees share the main repo's bank |
353
- | `retainTags` | — | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
354
- | `retainMetadata` | — | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}` |
355
- | `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
356
- | `reflectTimeoutMs` | `120000` | 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) |
357
- | `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
358
- | `autoSeed` | `true` | SessionStart: auto-seed a cold repo's bank from git history |
359
- | `seedLimit` | `300` | auto-seed: most-recent-N-commits cap |
360
- | `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 |
361
- | `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
362
- | `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
363
- | `retainSessions` | `true` | plugin-harness write-back (opencode, Kilo): async upsert of the session transcript every turn, plus an idle flush that captures the reply the per-turn pass can't see (set `false` to opt out; hook harnesses always write on Stop) |
364
- | `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 |
365
- | `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
366
- | `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 |
367
- | `harnesses.<name>` | — | per-harness override of any field above |
368
- | `harness` | `opencode` | **deepen engine only**: which session format `--conversations` is read as |
362
+ | field | default | meaning |
363
+ | ----------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
364
+ | `apiUrl` | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server) |
365
+ | `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 |
366
+ | `bankId` | — | **explicit static bank**; unset ⇒ per-repo dynamic resolution (below) |
367
+ | `dynamicBankId` | dynamic iff no `bankId` | force dynamic (`true`) or static (`false`) resolution |
368
+ | `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo |
369
+ | `mapPathToBank` | — | absolute path → bank; **longest prefix wins**; linked worktrees inherit their main checkout's mapping; overrides everything |
370
+ | `optInOnly` | `false` | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see [Opt-in only](#opt-in-only) |
371
+ | `optInPaths` | — | directories opted in, matched as prefixes with `~` expanded; each repo beneath and its linked worktrees are approved while keeping their own dynamic bank |
372
+ | `resolveWorktrees` | `true` | linked worktrees inherit the main checkout's bank identity, path approval, and mapping |
373
+ | `retainTags` | — | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
374
+ | `retainMetadata` | — | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}` |
375
+ | `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"]]` |
376
+ | `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
377
+ | `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) |
378
+ | `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 |
379
+ | `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 |
380
+ | `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
381
+ | `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) |
382
+ | `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 |
383
+ | `autoSeed` | `true` | SessionStart: auto-seed a cold repo's bank from git history |
384
+ | `seedLimit` | `300` | auto-seed: most-recent-N-commits cap |
385
+ | `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 |
386
+ | `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
387
+ | `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
388
+ | `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 |
389
+ | `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 |
390
+ | `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
391
+ | `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 |
392
+ | `harnesses.<name>` | — | per-harness override of any field above |
393
+ | `harness` | `opencode` | **deepen engine only**: which session format `--conversations` is read as |
394
+
395
+ `pageTriggerType`/`pageTriggerCron` decide only **when** a page refreshes. **How** it refreshes
396
+ belongs to the server: Hindsight creates a knowledge page with a delta refresh (each pass edits the
397
+ page instead of rebuilding it) that doesn't reflect over sibling pages, and these settings merge
398
+ over those defaults rather than replacing them.
399
+
400
+ **These settings apply to pages created from here on.** Changing them does not migrate the pages a
401
+ repo already has: a page keeps the trigger it was created with, so a bank seeded before you set
402
+ `"manual"` keeps refreshing on every consolidation. To move an existing page, change its trigger
403
+ through the API (`PATCH /knowledge-base/nodes/{id}`), an SDK, or the control plane — or delete it
404
+ and let the next session seed it again.
369
405
 
370
406
  ### Per-repo opt-in/out — `banks.<bankId>`
371
407
 
@@ -426,7 +462,10 @@ Coding memory is **per repository**. Resolution order for the working directory:
426
462
  3. Dynamic — `bankIdTemplate` with placeholders:
427
463
  - `{gitProject}` — worktree-aware repo name: `git rev-parse --git-common-dir` resolves every
428
464
  linked worktree to the **main** worktree's basename, so all worktrees of a repo share one bank
429
- (bare repos use the bare dir name; non-git directories fall back to the dir basename)
465
+ (bare repos use the bare dir name). **Outside a repo** there is nothing for git to resolve, so
466
+ it falls back to the basename of the directory the **session started in** — an agent that
467
+ `cd`s into a subdirectory keeps writing to one bank, and a subdirectory gets its own bank only
468
+ when you deliberately start a session there
430
469
  - `{project}` — plain working-directory basename
431
470
  - `{harness}` — the entry point asking (`opencode`, `claude-code`, `codex`, `antigravity-cli`, `cursor-cli`, `copilot-cli`)
432
471
  - `{channel}` / `{user}` — `$HINDSIGHT_CHANNEL_ID` / `$HINDSIGHT_USER_ID`
@@ -459,6 +498,36 @@ of. Both accept the same placeholders as `bankIdTemplate` — `{gitProject}`, `{
459
498
  The plugin's own `source:` and `harness:` tags are reserved: entries in those namespaces are ignored
460
499
  with a warning, so a document's agent attribution always reflects the agent that actually wrote it.
461
500
 
501
+ ### One set of beliefs per repo
502
+
503
+ Every document this integration writes carries provenance tags — `source:chat`, `harness:<id>`,
504
+ `knowledge:<kind>`, plus anything from `retainTags`. Those tags say **who wrote** a memory; they are
505
+ what filters recall and draws each document's agent logo, and they stay on the facts.
506
+
507
+ They are not, however, a good boundary for
508
+ [observations](https://hindsight.vectorize.io/developer/observations). Consolidation's own
509
+ default (`combined`) builds one observation set per distinct tag set, so the same repository
510
+ worked on by two agents would grow two parallel sets of beliefs — one per harness — that never
511
+ merge, each blind to the other, at double the consolidation cost. Which agent happened to be typing
512
+ does not change whether a convention or a decision is true.
513
+
514
+ So the integration retains with `observationScopes: "shared"`: one global, untagged observation
515
+ scope per bank, which is what a bank already is — one project's memory. Set the field to change it:
516
+
517
+ ```jsonc
518
+ {
519
+ "observationScopes": "combined", // one observation set per distinct tag set (server default)
520
+ "banks": {
521
+ "coding-agent::mono": { "observationScopes": "per_tag" }, // per-repo, like any behavioral field
522
+ },
523
+ }
524
+ ```
525
+
526
+ `"per_tag"` and `"all_combinations"` split further still, and an explicit `[["project:demo"], …]`
527
+ declares the scopes literally. `HINDSIGHT_OBSERVATION_SCOPES` sets the scalar modes; a scope list is
528
+ file-only. Changing this does not rewrite observations already consolidated under the old scoping —
529
+ they stay where they were built, and new work accrues under the new setting.
530
+
462
531
  ## Ingestion internals (no CLI)
463
532
 
464
533
  There is no user-facing ingest command — the deepen engine (`dist/deepen.js`) is spawned by every