@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/README.md +84 -4
- package/dist/antigravity-hook.js +56 -25
- package/dist/antigravity-statusline.js +24 -2
- package/dist/antigravity-stop-hook.js +69 -26
- package/dist/claude-hook.js +56 -25
- package/dist/claude-sessionstart-hook.js +83 -31
- package/dist/claude-stop-hook.js +69 -26
- package/dist/cline.js +85 -32
- package/dist/codex-hook.js +56 -25
- package/dist/codex-sessionstart-hook.js +83 -31
- package/dist/codex-stop-hook.js +69 -26
- package/dist/copilot-hook.js +56 -25
- package/dist/copilot-sessionstart-hook.js +83 -31
- package/dist/copilot-stop-hook.js +69 -26
- package/dist/cursor-hook.js +56 -25
- package/dist/cursor-sessionstart-hook.js +83 -31
- package/dist/cursor-stop-hook.js +69 -26
- package/dist/daemon-start.js +15 -3
- package/dist/deepen.js +58 -24
- package/dist/devin-hook.js +56 -25
- package/dist/devin-sessionstart-hook.js +83 -31
- package/dist/devin-stop-hook.js +69 -26
- package/dist/dsh.js +85 -32
- package/dist/grok-hook.js +56 -25
- package/dist/grok-sessionstart-hook.js +83 -31
- package/dist/grok-stop-hook.js +69 -26
- package/dist/hindsight-seed.js +26 -3
- package/dist/index.js +85 -32
- package/dist/installer.js +16 -4
- package/dist/kilo.js +85 -32
- package/dist/mcp-server.js +59 -24
- package/dist/prime-agent.js +85 -32
- package/dist/status.js +59 -24
- package/package.json +3 -2
- package/skill/SKILL.md +345 -68
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Long-term project memory for **coding agents**, backed by [Hindsight](https://vectorize.io/hindsight).
|
|
4
4
|
One package, several agents: a shared reflect-and-inject core with a thin entry point per agent
|
|
5
|
-
(**opencode**, **Kilo CLI**, **Cline CLI**, **Prime Agent**, **DeepSeek Harness**, **Claude Code**, **Codex CLI**, **Antigravity CLI**, **Cursor CLI**, **GitHub Copilot CLI**, **Grok Build**). Ingestion is fully
|
|
5
|
+
(**opencode**, **Kilo CLI**, **Cline CLI**, **Prime Agent**, **DeepSeek Harness**, **Claude Code**, **Codex CLI**, **Antigravity CLI**, **Cursor CLI**, **GitHub Copilot CLI**, **Devin CLI**, **Grok Build**). Ingestion is fully
|
|
6
6
|
automatic — there is no setup command: a repo's git history and conversations flow into its memory
|
|
7
7
|
bank in the background as you work.
|
|
8
8
|
|
|
@@ -14,6 +14,8 @@ in front of the agent at the moment it starts working, and keeps a curated set o
|
|
|
14
14
|
|
|
15
15
|
## Install
|
|
16
16
|
|
|
17
|
+
<!-- skill:begin title="Install / update" -->
|
|
18
|
+
|
|
17
19
|
```bash
|
|
18
20
|
npx @vectorize-io/hindsight-coding-agents install all # every detected agent, wired natively
|
|
19
21
|
npx @vectorize-io/hindsight-coding-agents install claude-code # or just one
|
|
@@ -22,7 +24,10 @@ npx @vectorize-io/hindsight-coding-agents uninstall all # removes exactly
|
|
|
22
24
|
|
|
23
25
|
`install` takes an explicit target — `all`, or one or more harness names. A bare
|
|
24
26
|
`npx @vectorize-io/hindsight-coding-agents install` changes nothing and prints the choice, so wiring every agent on
|
|
25
|
-
the machine is never something that happens by accident.
|
|
27
|
+
the machine is never something that happens by accident. **Updating is the same `install`
|
|
28
|
+
command again** — it re-copies the runtime in place.
|
|
29
|
+
|
|
30
|
+
<!-- skill:end -->
|
|
26
31
|
|
|
27
32
|
On a terminal it also asks **where memory should live** — Hindsight Cloud, a server you run, or a
|
|
28
33
|
local daemon on this machine (see [Where memory lives](#where-memory-lives)). Scripted installs pass
|
|
@@ -263,6 +268,8 @@ Nothing to sign up for and nothing to host — memory runs on your machine. The
|
|
|
263
268
|
otherwise the first of `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`;
|
|
264
269
|
otherwise the Claude Code CLI, which needs no key. `install` tells you which it found.
|
|
265
270
|
|
|
271
|
+
<!-- skill:begin title="Local daemon settings (daemon mode)" -->
|
|
272
|
+
|
|
266
273
|
Daemon settings keep the names the old per-agent Claude Code plugin used, so an existing
|
|
267
274
|
environment carries over unchanged:
|
|
268
275
|
|
|
@@ -278,6 +285,10 @@ environment carries over unchanged:
|
|
|
278
285
|
Any `HINDSIGHT_API_*` variable you export is forwarded to the daemon, so server-side settings need
|
|
279
286
|
no equivalent here.
|
|
280
287
|
|
|
288
|
+
<!-- skill:end -->
|
|
289
|
+
|
|
290
|
+
<!-- skill:begin -->
|
|
291
|
+
|
|
281
292
|
## Configuration
|
|
282
293
|
|
|
283
294
|
Configuration is **one JSON file**: `~/.hindsight/coding-agent.json`. Layering, later wins per field:
|
|
@@ -287,14 +298,22 @@ Configuration is **one JSON file**: `~/.hindsight/coding-agent.json`. Layering,
|
|
|
287
298
|
(`HINDSIGHT_<FIELD_IN_CAPS>`), for containers and CI that inject config rather than write a file
|
|
288
299
|
3. the file's top level
|
|
289
300
|
4. its `harnesses.<name>` section — per-agent override
|
|
301
|
+
5. its `banks.<resolvedBankId>` section — per-repo override, applied after the bank is resolved
|
|
302
|
+
(see [Per-repo opt-in/out](#per-repo-opt-inout--banksbankid))
|
|
290
303
|
|
|
291
304
|
Environment variables are a **fallback**: the file wins wherever it sets a value, so adding env to
|
|
292
|
-
an existing setup changes nothing. `retainTags`
|
|
293
|
-
(`HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work"`); entries are
|
|
305
|
+
an existing setup changes nothing. The two list-valued settings, `retainTags` and `optInPaths`, take
|
|
306
|
+
a comma-separated value (`HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work"`); entries are
|
|
307
|
+
trimmed and blanks dropped.
|
|
294
308
|
The map-valued settings (`mapPathToBank`, `harnesses`, `banks`, `retainMetadata`) are file-only —
|
|
295
309
|
per-key branching doesn't survive flattening into one variable. `maxParallelRetains` is available
|
|
296
310
|
as `HINDSIGHT_MAX_PARALLEL_RETAINS` for containers and CI.
|
|
297
311
|
|
|
312
|
+
`HINDSIGHT_CONFIG` moves the file itself — point it at another path for a container or a test
|
|
313
|
+
harness where `$HOME` is not the right anchor. It is still exactly one file; only its location
|
|
314
|
+
changes. (The other variables that are not settings are `HINDSIGHT_LOG_FILE`, `HINDSIGHT_DIAG_FILE`
|
|
315
|
+
and `HINDSIGHT_LOG_LEVEL` — see [Diagnostics & logging](#diagnostics--logging).)
|
|
316
|
+
|
|
298
317
|
### When a change takes effect
|
|
299
318
|
|
|
300
319
|
Config is read when a process starts — the file is not watched — so when an edit applies depends on
|
|
@@ -377,6 +396,7 @@ hook by Codex...), so one shared config serves several agents side by side:
|
|
|
377
396
|
| `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
397
|
| `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
398
|
| `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 |
|
|
399
|
+
| `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 |
|
|
380
400
|
| `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
|
|
381
401
|
| `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
402
|
| `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 |
|
|
@@ -385,6 +405,7 @@ hook by Codex...), so one shared config serves several agents side by side:
|
|
|
385
405
|
| `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
406
|
| `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
|
|
387
407
|
| `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
|
|
408
|
+
| `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) |
|
|
388
409
|
| `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
410
|
| `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
411
|
| `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
|
|
@@ -528,6 +549,8 @@ declares the scopes literally. `HINDSIGHT_OBSERVATION_SCOPES` sets the scalar mo
|
|
|
528
549
|
file-only. Changing this does not rewrite observations already consolidated under the old scoping —
|
|
529
550
|
they stay where they were built, and new work accrues under the new setting.
|
|
530
551
|
|
|
552
|
+
<!-- skill:end -->
|
|
553
|
+
|
|
531
554
|
## Ingestion internals (no CLI)
|
|
532
555
|
|
|
533
556
|
There is no user-facing ingest command — the deepen engine (`dist/deepen.js`) is spawned by every
|
|
@@ -550,6 +573,27 @@ docker run -d -p 8888:8888 -p 9999:9999 -e HINDSIGHT_API_LLM_PROVIDER=gemini \
|
|
|
550
573
|
ghcr.io/vectorize-io/hindsight:latest
|
|
551
574
|
```
|
|
552
575
|
|
|
576
|
+
## Companion skill (generated)
|
|
577
|
+
|
|
578
|
+
Every skills-capable host gets `skill/SKILL.md`, which teaches the agent what this integration does
|
|
579
|
+
and how to configure it. **It is generated — do not edit it.** This file is the single source: the
|
|
580
|
+
regions between `<!-- skill:begin -->` and `<!-- skill:end -->` are copied into the skill (a region
|
|
581
|
+
that starts mid-section names itself with `title="…"`, and heading levels are normalised so a marked
|
|
582
|
+
`###` becomes the skill's `##`). Only the agent-facing half — which tools to call, crediting memory,
|
|
583
|
+
correcting a wrong memory — lives outside it, in `skill-src/preamble.md`.
|
|
584
|
+
|
|
585
|
+
```bash
|
|
586
|
+
npm run skill:build # after editing this README or the preamble
|
|
587
|
+
```
|
|
588
|
+
|
|
589
|
+
`src/docs-freshness.test.ts` fails when the skill is stale, and when a field of `RawConfig` is
|
|
590
|
+
readable from a config file but named nowhere in this README — the drift that produced #3735, where
|
|
591
|
+
the skill and the README each documented a different subset of the same settings. The docs site page
|
|
592
|
+
is generated from this file too (`node hindsight-docs/scripts/sync-coding-agents-doc.mjs`), which
|
|
593
|
+
drops the markers along with the contributor-only sections.
|
|
594
|
+
|
|
595
|
+
<!-- skill:begin -->
|
|
596
|
+
|
|
553
597
|
## Diagnostics & logging
|
|
554
598
|
|
|
555
599
|
Two files, two audiences:
|
|
@@ -577,3 +621,39 @@ as a JSON line to `/tmp/hindsight-plugin.log` (override with `HINDSIGHT_DIAG_FIL
|
|
|
577
621
|
`reflect_failed` / `pages_failed` record the error; if you're comparing memory-on vs memory-off,
|
|
578
622
|
check this file — a run whose reflects failed is a no-memory run. Seed starts are logged as
|
|
579
623
|
`seed_started`.
|
|
624
|
+
|
|
625
|
+
### Is the memory ready yet?
|
|
626
|
+
|
|
627
|
+
`hindsight_sync_status` — the agent-facing tool, `dist/status.js` for scripts — answers exactly
|
|
628
|
+
that: `"synced": true` means the seeded memory is queryable. It also reports gitlog freshness, how
|
|
629
|
+
far per-commit deepening has got, the codebase survey's state (`surveyBaseline` is the HEAD the last
|
|
630
|
+
survey started from, `surveyDocs` counts the findings documents that have landed, 0–4 — a baseline
|
|
631
|
+
with no findings retries automatically), and the extraction operations still in flight.
|
|
632
|
+
|
|
633
|
+
### Resetting a repo's memory
|
|
634
|
+
|
|
635
|
+
Delete its bank on the server. The bank is the **only** state this integration keeps, so the next
|
|
636
|
+
session in that repo is a true first open — seed and survey run again from scratch. There are no
|
|
637
|
+
client-side files to clean up.
|
|
638
|
+
|
|
639
|
+
### Marker documents you may notice
|
|
640
|
+
|
|
641
|
+
Two document ids exist for the machinery's own bookkeeping. Both are safe to ignore and safe to
|
|
642
|
+
delete:
|
|
643
|
+
|
|
644
|
+
- `survey-baseline:<sha>` — reads "🛰️ researching…" while a codebase survey runs and flips to
|
|
645
|
+
"✅ completed" once its findings land. It is retained under the `survey` strategy, whose marker
|
|
646
|
+
rule extracts **nothing** from a status marker, and it drives the re-survey cadence
|
|
647
|
+
(`surveyRefreshCommits`) and `surveyBaseline` in sync status.
|
|
648
|
+
- `gitlog:<repo>` — the aggregated commit-message seed document, re-upserted rather than duplicated
|
|
649
|
+
when the seed runs again.
|
|
650
|
+
|
|
651
|
+
### When memory seems to be missing
|
|
652
|
+
|
|
653
|
+
Failures never break the agent: a reflect, page fetch or retain that fails degrades to an ordinary
|
|
654
|
+
memoryless turn and is recorded in the logs. "No memory" is therefore a log question — check the
|
|
655
|
+
diag file for whether `session_start` and `deepen_started` ever fired for that bank. A session that
|
|
656
|
+
was already running when the plugin was installed has no SessionStart behind it; its first prompt
|
|
657
|
+
after the install self-heals.
|
|
658
|
+
|
|
659
|
+
<!-- skill:end -->
|
package/dist/antigravity-hook.js
CHANGED
|
@@ -33,14 +33,36 @@ function getProjectRootFromGit(directory) {
|
|
|
33
33
|
const commonDir = execFileSync(
|
|
34
34
|
"git",
|
|
35
35
|
["rev-parse", "--path-format=absolute", "--git-common-dir"],
|
|
36
|
-
{
|
|
36
|
+
{
|
|
37
|
+
cwd: directory,
|
|
38
|
+
encoding: "utf-8",
|
|
39
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
40
|
+
timeout: 1e3,
|
|
41
|
+
windowsHide: true
|
|
42
|
+
}
|
|
37
43
|
).trim();
|
|
38
44
|
if (!commonDir) return null;
|
|
39
|
-
|
|
45
|
+
if (basename(commonDir) === ".git") return dirname(commonDir);
|
|
46
|
+
if (basename(commonDir).startsWith(".") && isBareRepository(commonDir)) {
|
|
47
|
+
return dirname(commonDir);
|
|
48
|
+
}
|
|
49
|
+
return commonDir;
|
|
40
50
|
} catch {
|
|
41
51
|
return null;
|
|
42
52
|
}
|
|
43
53
|
}
|
|
54
|
+
function isBareRepository(commonDir) {
|
|
55
|
+
try {
|
|
56
|
+
return execFileSync("git", ["-C", commonDir, "rev-parse", "--is-bare-repository"], {
|
|
57
|
+
encoding: "utf-8",
|
|
58
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
59
|
+
timeout: 1e3,
|
|
60
|
+
env: { ...process.env, GIT_DIR: void 0, GIT_WORK_TREE: void 0 }
|
|
61
|
+
}).trim() === "true";
|
|
62
|
+
} catch {
|
|
63
|
+
return false;
|
|
64
|
+
}
|
|
65
|
+
}
|
|
44
66
|
var PROJECT_ROOT_ENV = ["CLAUDE_PROJECT_DIR"];
|
|
45
67
|
function nearestExistingDir(directory) {
|
|
46
68
|
let current2 = directory;
|
|
@@ -157,7 +179,8 @@ function startBackgroundSeed(repoDir, opts = {}) {
|
|
|
157
179
|
],
|
|
158
180
|
{
|
|
159
181
|
detached: true,
|
|
160
|
-
stdio: "ignore"
|
|
182
|
+
stdio: "ignore",
|
|
183
|
+
windowsHide: true
|
|
161
184
|
}
|
|
162
185
|
);
|
|
163
186
|
child.on("error", () => {
|
|
@@ -315,7 +338,7 @@ var PAGE_TAXONOMY = [
|
|
|
315
338
|
},
|
|
316
339
|
{
|
|
317
340
|
name: "Initiatives and enhancements",
|
|
318
|
-
source_query: "Based on this repository's commit history, what are the major initiatives, features, and enhancements the project has worked on? Summarize the themes and notable changes over time. When a source memory carries a
|
|
341
|
+
source_query: "Based on this repository's commit history, what are the major initiatives, features, and enhancements the project has worked on? Summarize the themes and notable changes over time. When a source memory's context carries a `[[page:<id>]]` link, repeat that link in the summary of what it describes, so each initiative links to its detailed page.",
|
|
319
342
|
tags: ["knowledge:feature-work"]
|
|
320
343
|
}
|
|
321
344
|
];
|
|
@@ -324,9 +347,10 @@ function pagesFor(project) {
|
|
|
324
347
|
return PAGE_TAXONOMY.map((page) => ({ ...page, source_query: page.source_query + scope }));
|
|
325
348
|
}
|
|
326
349
|
var PAGE_MAX_TOKENS = 4096;
|
|
350
|
+
var PAGE_TAGS_MATCH = "all";
|
|
327
351
|
var PAGE_FACT_TYPES = ["world", "experience", "observation"];
|
|
328
352
|
function buildPageTrigger(cfg = {}) {
|
|
329
|
-
const base = { fact_types: PAGE_FACT_TYPES };
|
|
353
|
+
const base = { fact_types: PAGE_FACT_TYPES, tags_match: PAGE_TAGS_MATCH };
|
|
330
354
|
switch (cfg.pageTriggerType) {
|
|
331
355
|
case "cron":
|
|
332
356
|
return { ...base, refresh_cron: cfg.pageTriggerCron };
|
|
@@ -836,11 +860,20 @@ var HindsightClient = class {
|
|
|
836
860
|
return;
|
|
837
861
|
}
|
|
838
862
|
if (r.status !== 409) created++;
|
|
839
|
-
} else
|
|
863
|
+
} else {
|
|
864
|
+
const sourceDrift = hit.description !== page.source_query;
|
|
865
|
+
const triggerDrift = hit.trigger != null && hit.trigger.tags_match !== pageTrigger.tags_match;
|
|
866
|
+
if (!sourceDrift && !triggerDrift) continue;
|
|
867
|
+
const patch = {};
|
|
868
|
+
if (sourceDrift) {
|
|
869
|
+
patch.source_query = page.source_query;
|
|
870
|
+
patch.tags = page.tags;
|
|
871
|
+
}
|
|
872
|
+
if (triggerDrift) patch.trigger = pageTrigger;
|
|
840
873
|
const r = await this.req(
|
|
841
874
|
"PATCH",
|
|
842
875
|
this.bankUrl(`/knowledge-base/nodes/${encodeURIComponent(hit.id)}`),
|
|
843
|
-
|
|
876
|
+
patch
|
|
844
877
|
);
|
|
845
878
|
if ([404, 405, 501].includes(r.status)) {
|
|
846
879
|
this.knowledgePagesSupported = false;
|
|
@@ -861,10 +894,17 @@ var HindsightClient = class {
|
|
|
861
894
|
return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "initiative";
|
|
862
895
|
}
|
|
863
896
|
/**
|
|
864
|
-
* Active-path capture: register a major feature as a per-initiative page + a
|
|
865
|
-
* New initiative → creates a page under the Initiatives folder
|
|
897
|
+
* Active-path capture: register a major feature as a per-initiative page + a marker memory.
|
|
898
|
+
* New initiative → creates a page under the Initiatives folder.
|
|
866
899
|
* Update (relatesToPageId) → no new page; only a marker accruing to the existing page, so an
|
|
867
900
|
* enhancement or a mid-work plan change lands on the initiative it belongs to.
|
|
901
|
+
*
|
|
902
|
+
* The marker carries its page id in two places, neither of them a tag (#3641):
|
|
903
|
+
* `metadata.relatedPageId` for provenance (visible on the document, and to a reflect loop that
|
|
904
|
+
* expands one), and a `[[page:<id>]]` link in the retain CONTEXT, which is the only one of the
|
|
905
|
+
* three channels a page synthesis actually reads — reflect's search results keep `context` and
|
|
906
|
+
* `tags` but strip `metadata` (`_UNREAD_RESULT_FIELDS`), and the id has no business in a tag
|
|
907
|
+
* vocabulary that exists to be matched with exact set-ops.
|
|
868
908
|
*/
|
|
869
909
|
async captureInitiative(args) {
|
|
870
910
|
let pageId = args.relatesToPageId;
|
|
@@ -887,20 +927,11 @@ var HindsightClient = class {
|
|
|
887
927
|
const verb = args.relatesToPageId ? "Update to an existing initiative" : "New initiative";
|
|
888
928
|
const content = `${verb}: ${args.title}. ${args.summary}`;
|
|
889
929
|
const markerId = `initiative-marker-${this.slugify(args.title)}-${Date.now()}`;
|
|
890
|
-
const tags = [
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
])
|
|
896
|
-
];
|
|
897
|
-
if (Object.keys(args.stamp?.metadata ?? {}).length) {
|
|
898
|
-
await this.retain(content, "initiative marker", markerId, tags, "document", {
|
|
899
|
-
metadata: args.stamp?.metadata
|
|
900
|
-
});
|
|
901
|
-
} else {
|
|
902
|
-
await this.retain(content, "initiative marker", markerId, tags, "document");
|
|
903
|
-
}
|
|
930
|
+
const tags = [.../* @__PURE__ */ new Set([...args.stamp?.tags ?? [], "knowledge:feature-work"])];
|
|
931
|
+
const context = `initiative marker for [[page:${pageId}]]`;
|
|
932
|
+
await this.retain(content, context, markerId, tags, "document", {
|
|
933
|
+
metadata: { ...args.stamp?.metadata ?? {}, relatedPageId: pageId }
|
|
934
|
+
});
|
|
904
935
|
return { page_id: pageId };
|
|
905
936
|
}
|
|
906
937
|
/** Find a root folder by name (case-insensitive) or create it; returns its id. Fail-open to undefined. */
|
|
@@ -1239,9 +1270,9 @@ var TOOL_GUIDE = `- hindsight_search_knowledge_pages(query) \u2014 FIRST STOP fo
|
|
|
1239
1270
|
- hindsight_reflect(query) \u2014 when pages are too shallow and you need the WHY: deep reasoning over the repo's full memory for the past decision and exact values that explain a behavior or bug (slower \u2014 use deliberately, and credit results with a blockquote header "> \u{1F9E0} **From Hindsight memory** \u2014 <summary>").
|
|
1240
1271
|
- hindsight_capture_initiative(title, summary) \u2014 right after the user approves a plan or finishes brainstorming a new feature/capability and you are about to start implementing (BEFORE you write any code), call this to record it as a tracked page; then call it AGAIN with relates_to_page_id set to that page whenever the goal, scope, or rationale materially changes mid-work, so the page tracks the current plan and not the opening one. Skip bug fixes, small tweaks, chores, and trivial course-corrections.
|
|
1241
1272
|
- hindsight_ingest_document(title, content) \u2014 save an external document or durable notes/findings you want remembered (not the current conversation \u2014 that is captured automatically at session end).`;
|
|
1242
|
-
var
|
|
1273
|
+
var PAGES_FIRST_ON_GOALS = "- The user just set a NEW task or goal \u2192 search the knowledge pages FIRST with hindsight_search_knowledge_pages. No synthesis is injected automatically in this configuration; call hindsight_reflect only when those pages are too shallow and deeper reasoning is needed.\n";
|
|
1243
1274
|
function toolGuide(opts) {
|
|
1244
|
-
return (opts?.reflectOnNewGoals ?
|
|
1275
|
+
return (opts?.reflectOnNewGoals ? PAGES_FIRST_ON_GOALS : "") + TOOL_GUIDE;
|
|
1245
1276
|
}
|
|
1246
1277
|
function buildRosterRefresh(pages, opts) {
|
|
1247
1278
|
const rosterBlock = pages.length ? `Current Hindsight knowledge pages (may have changed):
|
|
@@ -41,14 +41,36 @@ function getProjectRootFromGit(directory) {
|
|
|
41
41
|
const commonDir = execFileSync(
|
|
42
42
|
"git",
|
|
43
43
|
["rev-parse", "--path-format=absolute", "--git-common-dir"],
|
|
44
|
-
{
|
|
44
|
+
{
|
|
45
|
+
cwd: directory,
|
|
46
|
+
encoding: "utf-8",
|
|
47
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
48
|
+
timeout: 1e3,
|
|
49
|
+
windowsHide: true
|
|
50
|
+
}
|
|
45
51
|
).trim();
|
|
46
52
|
if (!commonDir) return null;
|
|
47
|
-
|
|
53
|
+
if (basename(commonDir) === ".git") return dirname2(commonDir);
|
|
54
|
+
if (basename(commonDir).startsWith(".") && isBareRepository(commonDir)) {
|
|
55
|
+
return dirname2(commonDir);
|
|
56
|
+
}
|
|
57
|
+
return commonDir;
|
|
48
58
|
} catch {
|
|
49
59
|
return null;
|
|
50
60
|
}
|
|
51
61
|
}
|
|
62
|
+
function isBareRepository(commonDir) {
|
|
63
|
+
try {
|
|
64
|
+
return execFileSync("git", ["-C", commonDir, "rev-parse", "--is-bare-repository"], {
|
|
65
|
+
encoding: "utf-8",
|
|
66
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
67
|
+
timeout: 1e3,
|
|
68
|
+
env: { ...process.env, GIT_DIR: void 0, GIT_WORK_TREE: void 0 }
|
|
69
|
+
}).trim() === "true";
|
|
70
|
+
} catch {
|
|
71
|
+
return false;
|
|
72
|
+
}
|
|
73
|
+
}
|
|
52
74
|
var PROJECT_ROOT_ENV = ["CLAUDE_PROJECT_DIR"];
|
|
53
75
|
function nearestExistingDir(directory) {
|
|
54
76
|
let current2 = directory;
|
|
@@ -33,14 +33,36 @@ function getProjectRootFromGit(directory) {
|
|
|
33
33
|
const commonDir = execFileSync(
|
|
34
34
|
"git",
|
|
35
35
|
["rev-parse", "--path-format=absolute", "--git-common-dir"],
|
|
36
|
-
{
|
|
36
|
+
{
|
|
37
|
+
cwd: directory,
|
|
38
|
+
encoding: "utf-8",
|
|
39
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
40
|
+
timeout: 1e3,
|
|
41
|
+
windowsHide: true
|
|
42
|
+
}
|
|
37
43
|
).trim();
|
|
38
44
|
if (!commonDir) return null;
|
|
39
|
-
|
|
45
|
+
if (basename(commonDir) === ".git") return dirname(commonDir);
|
|
46
|
+
if (basename(commonDir).startsWith(".") && isBareRepository(commonDir)) {
|
|
47
|
+
return dirname(commonDir);
|
|
48
|
+
}
|
|
49
|
+
return commonDir;
|
|
40
50
|
} catch {
|
|
41
51
|
return null;
|
|
42
52
|
}
|
|
43
53
|
}
|
|
54
|
+
function isBareRepository(commonDir) {
|
|
55
|
+
try {
|
|
56
|
+
return execFileSync("git", ["-C", commonDir, "rev-parse", "--is-bare-repository"], {
|
|
57
|
+
encoding: "utf-8",
|
|
58
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
59
|
+
timeout: 1e3,
|
|
60
|
+
env: { ...process.env, GIT_DIR: void 0, GIT_WORK_TREE: void 0 }
|
|
61
|
+
}).trim() === "true";
|
|
62
|
+
} catch {
|
|
63
|
+
return false;
|
|
64
|
+
}
|
|
65
|
+
}
|
|
44
66
|
function projectNameOf(directory, sessionRoot) {
|
|
45
67
|
return gitProjectName(directory, true, sessionRoot);
|
|
46
68
|
}
|
|
@@ -292,7 +314,7 @@ var PAGE_TAXONOMY = [
|
|
|
292
314
|
},
|
|
293
315
|
{
|
|
294
316
|
name: "Initiatives and enhancements",
|
|
295
|
-
source_query: "Based on this repository's commit history, what are the major initiatives, features, and enhancements the project has worked on? Summarize the themes and notable changes over time. When a source memory carries a
|
|
317
|
+
source_query: "Based on this repository's commit history, what are the major initiatives, features, and enhancements the project has worked on? Summarize the themes and notable changes over time. When a source memory's context carries a `[[page:<id>]]` link, repeat that link in the summary of what it describes, so each initiative links to its detailed page.",
|
|
296
318
|
tags: ["knowledge:feature-work"]
|
|
297
319
|
}
|
|
298
320
|
];
|
|
@@ -301,9 +323,10 @@ function pagesFor(project) {
|
|
|
301
323
|
return PAGE_TAXONOMY.map((page) => ({ ...page, source_query: page.source_query + scope }));
|
|
302
324
|
}
|
|
303
325
|
var PAGE_MAX_TOKENS = 4096;
|
|
326
|
+
var PAGE_TAGS_MATCH = "all";
|
|
304
327
|
var PAGE_FACT_TYPES = ["world", "experience", "observation"];
|
|
305
328
|
function buildPageTrigger(cfg = {}) {
|
|
306
|
-
const base = { fact_types: PAGE_FACT_TYPES };
|
|
329
|
+
const base = { fact_types: PAGE_FACT_TYPES, tags_match: PAGE_TAGS_MATCH };
|
|
307
330
|
switch (cfg.pageTriggerType) {
|
|
308
331
|
case "cron":
|
|
309
332
|
return { ...base, refresh_cron: cfg.pageTriggerCron };
|
|
@@ -813,11 +836,20 @@ var HindsightClient = class {
|
|
|
813
836
|
return;
|
|
814
837
|
}
|
|
815
838
|
if (r.status !== 409) created++;
|
|
816
|
-
} else
|
|
839
|
+
} else {
|
|
840
|
+
const sourceDrift = hit.description !== page.source_query;
|
|
841
|
+
const triggerDrift = hit.trigger != null && hit.trigger.tags_match !== pageTrigger.tags_match;
|
|
842
|
+
if (!sourceDrift && !triggerDrift) continue;
|
|
843
|
+
const patch = {};
|
|
844
|
+
if (sourceDrift) {
|
|
845
|
+
patch.source_query = page.source_query;
|
|
846
|
+
patch.tags = page.tags;
|
|
847
|
+
}
|
|
848
|
+
if (triggerDrift) patch.trigger = pageTrigger;
|
|
817
849
|
const r = await this.req(
|
|
818
850
|
"PATCH",
|
|
819
851
|
this.bankUrl(`/knowledge-base/nodes/${encodeURIComponent(hit.id)}`),
|
|
820
|
-
|
|
852
|
+
patch
|
|
821
853
|
);
|
|
822
854
|
if ([404, 405, 501].includes(r.status)) {
|
|
823
855
|
this.knowledgePagesSupported = false;
|
|
@@ -838,10 +870,17 @@ var HindsightClient = class {
|
|
|
838
870
|
return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "initiative";
|
|
839
871
|
}
|
|
840
872
|
/**
|
|
841
|
-
* Active-path capture: register a major feature as a per-initiative page + a
|
|
842
|
-
* New initiative → creates a page under the Initiatives folder
|
|
873
|
+
* Active-path capture: register a major feature as a per-initiative page + a marker memory.
|
|
874
|
+
* New initiative → creates a page under the Initiatives folder.
|
|
843
875
|
* Update (relatesToPageId) → no new page; only a marker accruing to the existing page, so an
|
|
844
876
|
* enhancement or a mid-work plan change lands on the initiative it belongs to.
|
|
877
|
+
*
|
|
878
|
+
* The marker carries its page id in two places, neither of them a tag (#3641):
|
|
879
|
+
* `metadata.relatedPageId` for provenance (visible on the document, and to a reflect loop that
|
|
880
|
+
* expands one), and a `[[page:<id>]]` link in the retain CONTEXT, which is the only one of the
|
|
881
|
+
* three channels a page synthesis actually reads — reflect's search results keep `context` and
|
|
882
|
+
* `tags` but strip `metadata` (`_UNREAD_RESULT_FIELDS`), and the id has no business in a tag
|
|
883
|
+
* vocabulary that exists to be matched with exact set-ops.
|
|
845
884
|
*/
|
|
846
885
|
async captureInitiative(args) {
|
|
847
886
|
let pageId = args.relatesToPageId;
|
|
@@ -864,20 +903,11 @@ var HindsightClient = class {
|
|
|
864
903
|
const verb = args.relatesToPageId ? "Update to an existing initiative" : "New initiative";
|
|
865
904
|
const content = `${verb}: ${args.title}. ${args.summary}`;
|
|
866
905
|
const markerId = `initiative-marker-${this.slugify(args.title)}-${Date.now()}`;
|
|
867
|
-
const tags = [
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
])
|
|
873
|
-
];
|
|
874
|
-
if (Object.keys(args.stamp?.metadata ?? {}).length) {
|
|
875
|
-
await this.retain(content, "initiative marker", markerId, tags, "document", {
|
|
876
|
-
metadata: args.stamp?.metadata
|
|
877
|
-
});
|
|
878
|
-
} else {
|
|
879
|
-
await this.retain(content, "initiative marker", markerId, tags, "document");
|
|
880
|
-
}
|
|
906
|
+
const tags = [.../* @__PURE__ */ new Set([...args.stamp?.tags ?? [], "knowledge:feature-work"])];
|
|
907
|
+
const context = `initiative marker for [[page:${pageId}]]`;
|
|
908
|
+
await this.retain(content, context, markerId, tags, "document", {
|
|
909
|
+
metadata: { ...args.stamp?.metadata ?? {}, relatedPageId: pageId }
|
|
910
|
+
});
|
|
881
911
|
return { page_id: pageId };
|
|
882
912
|
}
|
|
883
913
|
/** Find a root folder by name (case-insensitive) or create it; returns its id. Fail-open to undefined. */
|
|
@@ -1386,7 +1416,11 @@ async function isServerHealthy(baseUrl, timeoutMs = 2e3) {
|
|
|
1386
1416
|
function hasRustToolchain() {
|
|
1387
1417
|
if (process.platform !== "darwin") return true;
|
|
1388
1418
|
try {
|
|
1389
|
-
execFileSync2("cargo", ["--version"], {
|
|
1419
|
+
execFileSync2("cargo", ["--version"], {
|
|
1420
|
+
stdio: "pipe",
|
|
1421
|
+
timeout: 1e4,
|
|
1422
|
+
windowsHide: true
|
|
1423
|
+
});
|
|
1390
1424
|
return true;
|
|
1391
1425
|
} catch {
|
|
1392
1426
|
return false;
|
|
@@ -1394,7 +1428,11 @@ function hasRustToolchain() {
|
|
|
1394
1428
|
}
|
|
1395
1429
|
function hasUvx() {
|
|
1396
1430
|
try {
|
|
1397
|
-
execFileSync2("uvx", ["--version"], {
|
|
1431
|
+
execFileSync2("uvx", ["--version"], {
|
|
1432
|
+
stdio: "pipe",
|
|
1433
|
+
timeout: 1e4,
|
|
1434
|
+
windowsHide: true
|
|
1435
|
+
});
|
|
1398
1436
|
return true;
|
|
1399
1437
|
} catch {
|
|
1400
1438
|
return false;
|
|
@@ -1426,7 +1464,11 @@ function detectLlm(env = process.env) {
|
|
|
1426
1464
|
}
|
|
1427
1465
|
function onPath(bin) {
|
|
1428
1466
|
try {
|
|
1429
|
-
execFileSync2("which", [bin], {
|
|
1467
|
+
execFileSync2("which", [bin], {
|
|
1468
|
+
stdio: "pipe",
|
|
1469
|
+
timeout: 5e3,
|
|
1470
|
+
windowsHide: true
|
|
1471
|
+
});
|
|
1430
1472
|
return true;
|
|
1431
1473
|
} catch {
|
|
1432
1474
|
return false;
|
|
@@ -1437,7 +1479,8 @@ function startDaemonDetached(cfg, harness, spawnFn = realSpawn2) {
|
|
|
1437
1479
|
const starter = join6(dirname5(fileURLToPath2(import.meta.url)), "daemon-start.js");
|
|
1438
1480
|
const child = spawnFn("node", [starter, "--harness", harness], {
|
|
1439
1481
|
detached: true,
|
|
1440
|
-
stdio: "ignore"
|
|
1482
|
+
stdio: "ignore",
|
|
1483
|
+
windowsHide: true
|
|
1441
1484
|
});
|
|
1442
1485
|
child.on("error", () => {
|
|
1443
1486
|
});
|