@vectorize-io/hindsight-coding-agents 0.0.3 → 0.0.4
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 +125 -122
- package/dist/antigravity-hook.js +36 -15
- package/dist/antigravity-stop-hook.js +36 -15
- package/dist/claude-hook.js +36 -15
- package/dist/claude-sessionstart-hook.js +38 -17
- package/dist/claude-stop-hook.js +36 -15
- package/dist/codex-hook.js +36 -15
- package/dist/codex-sessionstart-hook.js +38 -17
- package/dist/codex-stop-hook.js +36 -15
- package/dist/copilot-hook.js +36 -15
- package/dist/copilot-sessionstart-hook.js +38 -17
- package/dist/copilot-stop-hook.js +36 -15
- package/dist/cursor-hook.js +36 -15
- package/dist/cursor-sessionstart-hook.js +38 -17
- package/dist/cursor-stop-hook.js +36 -15
- package/dist/devin-hook.js +36 -15
- package/dist/devin-sessionstart-hook.js +38 -17
- package/dist/devin-stop-hook.js +36 -15
- package/dist/grok-hook.js +36 -15
- package/dist/grok-sessionstart-hook.js +38 -17
- package/dist/grok-stop-hook.js +36 -15
- package/dist/installer.js +454 -132
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -12,103 +12,7 @@ tie-break policy. Those decisions live in git history and past conversations. Th
|
|
|
12
12
|
in front of the agent at the moment it starts working, and keeps a curated set of **knowledge pages**
|
|
13
13
|
(architecture, conventions, in-flight initiatives) that future sessions start from.
|
|
14
14
|
|
|
15
|
-
##
|
|
16
|
-
|
|
17
|
-
1. **Seed a cold repo (automatic, once).** The first time an agent opens a repo whose bank is empty,
|
|
18
|
-
the entry point deterministically kicks off a background **seed**: it aggregates the last N commit
|
|
19
|
-
**messages** into a single cheap document (`gitlog` strategy) and spawns a short headless
|
|
20
|
-
**codebase survey** — run under the current agent's own CLI (claude/codex/antigravity/opencode),
|
|
21
|
-
read-only sandboxed — to map the structure. Both feed the knowledge pages.
|
|
22
|
-
1. **Deepen progressively (automatic, every session).** Every session start also fires the
|
|
23
|
-
idempotent background **deepen engine**: it ingests any conversations not yet in the bank and the
|
|
24
|
-
next batch of recent commits **individually with their full diffs, newest first** — so full
|
|
25
|
-
decision-level precision arrives across sessions without a big-bang ingest. A per-bank lock and
|
|
26
|
-
document-id dedup make concurrent or repeated runs a no-op. Ask the agent
|
|
27
|
-
`hindsight_sync_status` to see where ingestion stands (`synced: true` = seeded memory fully
|
|
28
|
-
queryable).
|
|
29
|
-
1. **Reflect once per session.** On the session's first prompt, the entry point runs Hindsight
|
|
30
|
-
`reflect` — an agentic synthesis over the bank that returns the past decision explaining the task
|
|
31
|
-
at hand, with its exact rule and literal values. The answer is cached for the session and
|
|
32
|
-
re-injected on every turn, wrapped in a visible-attribution directive so the agent surfaces a
|
|
33
|
-
`🧠 Using Hindsight Memories` header when memory informs its answer.
|
|
34
|
-
1. **Knowledge-page sections every turn.** The repo's knowledge pages are fetched on a cadence and
|
|
35
|
-
matched **locally** against each prompt (a lexical section index — no server round-trip, no LLM
|
|
36
|
-
call, ~ms): the top-scoring page sections are injected with provenance and a pointer to the full
|
|
37
|
-
page. Fast like recall, organized like reflect; below a relevance floor nothing is injected.
|
|
38
|
-
1. **Knowledge pages + tools.** At session start the agent is given the repo's page roster plus a
|
|
39
|
-
guide to the `hindsight_*` tools; it lists/reads pages to ground itself, searches raw memory for
|
|
40
|
-
specifics (`hindsight_search_memory` is where recall lives now), and calls
|
|
41
|
-
`hindsight_capture_initiative` right after a plan is approved to record a new feature as a tracked
|
|
42
|
-
page. On opencode these tools are registered natively; the hook harnesses get them through the
|
|
43
|
-
bundled **MCP server**.
|
|
44
|
-
1. **Write back.** The live session is upserted into the bank as a JSON transcript — user/assistant
|
|
45
|
-
turns plus a compact `action` turn per tool call (tool name + primary target, e.g.
|
|
46
|
-
`Edit boltons/strutils.py`; no arguments or outputs) — so sessions compound into memory without
|
|
47
|
-
burying decisions in mechanical noise. On Stop for the hook harnesses; for the plugin harnesses
|
|
48
|
-
(opencode, Kilo) on the turn cadence **and** again when the session goes idle. The idle pass is
|
|
49
|
-
what captures the agent's reply: the per-turn hook fires while the host is building a request, so
|
|
50
|
-
the transcript it sees always stops short of the answer that request produces — without the idle
|
|
51
|
-
pass, write-back lagged a turn and a session's final exchange was never stored at all.
|
|
52
|
-
1. **Never break the agent — never fail silently.** A failed reflect or page fetch degrades to
|
|
53
|
-
no-memory, but every outcome (`reflect_ok` / `reflect_empty` / `reflect_failed`, `pages_ok` /
|
|
54
|
-
`pages_failed`, with duration and error) is appended to a diagnostics file, so a memory-less
|
|
55
|
-
session can't masquerade as a memory session.
|
|
56
|
-
|
|
57
|
-
If the configured Hindsight server predates knowledge pages, the client detects that capability at
|
|
58
|
-
session start, skips page seeding and page lookups, and records `knowledge_pages_unavailable`.
|
|
59
|
-
Legacy bank configuration, git/session ingestion, reflection, and retention continue normally.
|
|
60
|
-
|
|
61
|
-
When memories **conflict** on the same rule, reflect prefers the latest/superseding decision — a rule
|
|
62
|
-
amended in a later conversation wins over the original.
|
|
63
|
-
|
|
64
|
-
## Harnesses
|
|
65
|
-
|
|
66
|
-
Every harness runs the same surface (seed → session reflect → per-turn page sections → knowledge
|
|
67
|
-
tools → write-back); they differ only in how that surface is delivered.
|
|
68
|
-
|
|
69
|
-
| harness | kind | lifecycle wiring | install |
|
|
70
|
-
| ------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
|
|
71
|
-
| `opencode` | persistent plugin | one process: load-time seed, session reflect + page sections, native tools, write-back | add the package dir to `opencode.json` → `"plugin": [...]` |
|
|
72
|
-
| `kilo` | persistent plugin | identical to `opencode` — Kilo CLI is an opencode fork, so it loads the same runtime (no hooks system) | `hindsight-coding-agents install kilo` → `kilo.json[c]` `"plugin"` |
|
|
73
|
-
| `claude-code` | per-prompt hooks | `SessionStart` (seed) + `UserPromptSubmit` (reflect + pages) + `Stop` (write-back) + MCP | `hindsight-coding-agents install claude-code` |
|
|
74
|
-
| `codex` | per-prompt hooks | same three hooks in `~/.codex/hooks.json` (+ `codex_hooks = true`, CLI ≥ 0.116) | `hindsight-coding-agents install codex` |
|
|
75
|
-
| `antigravity-cli` (`agy`) | lifecycle hooks | Antigravity CLI lifecycle hooks (`PreInvocation` + `Stop`) + MCP, plus a native colored `Hindsight · <bank>` status-line indicator | `hindsight-coding-agents install agy` |
|
|
76
|
-
| `cursor-cli` | lifecycle hooks | `sessionStart` (seed + pages) + `beforeSubmitPrompt` (reflect) + `stop` (write-back) | hooks in Cursor `hooks.json` |
|
|
77
|
-
| `copilot-cli` | lifecycle hooks | `sessionStart` (seed + pages) + `userPromptTransformed` (reflect) + `agentStop` (write-back) + MCP | `~/.copilot/hooks/hindsight-coding-agents.json` + `mcp-config.json` |
|
|
78
|
-
| `grok-build` | lifecycle hooks | `SessionStart` (seed) + `Stop` (write-back) + MCP | native `~/.grok/config.toml` — no Claude Code dependency |
|
|
79
|
-
| `cline-cli` | persistent plugin | native `beforeModel` (seed/reflect/pages) + `afterRun` (write-back) + MCP | `cline plugin install` (run by the installer) |
|
|
80
|
-
|
|
81
|
-
The hook-based harnesses share one runtime (`src/core/hook.ts`) plus their SessionStart/Stop
|
|
82
|
-
entrypoints. Persistent-plugin hosts (opencode/Kilo/Cline) delegate to the same `RuntimeCore`,
|
|
83
|
-
which in turn calls those shared session-start, prompt, and retain operations; only their host API
|
|
84
|
-
adapters differ. Opencode and Kilo can register the knowledge tools natively; Cline uses the shared
|
|
85
|
-
MCP server. All support opt-in **incremental git-sync** (retain commits new since the seed on load).
|
|
86
|
-
|
|
87
|
-
Antigravity renders the Hindsight indicator with its documented custom status-line command. It is
|
|
88
|
-
local and never calls the Hindsight API while the TUI redraws. If you already configured an
|
|
89
|
-
Antigravity custom status line, the installer leaves it untouched rather than replacing it.
|
|
90
|
-
|
|
91
|
-
### Grok Build limitation
|
|
92
|
-
|
|
93
|
-
Grok Build executes `UserPromptSubmit` hooks but ignores their stdout. Hindsight can therefore not
|
|
94
|
-
inject a reflect result, memory block, or banner into Grok's model-visible conversation. Grok still
|
|
95
|
-
gets native bank setup and transcript retention plus Hindsight MCP tools and the companion skill;
|
|
96
|
-
ask it to call `hindsight_reflect` or `hindsight_search_knowledge_pages` when needed. Automatic
|
|
97
|
-
injection requires a future Grok prompt-transform API.
|
|
98
|
-
|
|
99
|
-
### Cline CLI scope
|
|
100
|
-
|
|
101
|
-
Cline's external file hooks cannot alter a model request, so Hindsight uses Cline's native plugin
|
|
102
|
-
API instead. Its `beforeModel` hook injects the shared reflect/page context and
|
|
103
|
-
its `afterRun` hook upserts Cline's runtime transcript. `hindsight-coding-agents install cline-cli`
|
|
104
|
-
runs `cline plugin install --force <package-path>` and configures MCP plus the companion skill.
|
|
105
|
-
Cline CLI sandboxes plugin hooks with a three-second limit, so a slow first reflect finishes in the
|
|
106
|
-
background and is injected on a subsequent model call or turn rather than aborting the session.
|
|
107
|
-
Its write-back retains only user-visible user/assistant text; tool arguments, tool results and
|
|
108
|
-
command output, tool-role messages, reasoning parts, and Hindsight's injected context are excluded.
|
|
109
|
-
Cline IDE extensions are not currently supported by this CLI integration.
|
|
110
|
-
|
|
111
|
-
### Install — one command, every agent
|
|
15
|
+
## Install
|
|
112
16
|
|
|
113
17
|
```bash
|
|
114
18
|
npm install -g @vectorize-io/hindsight-coding-agents
|
|
@@ -121,7 +25,7 @@ hindsight-coding-agents uninstall all # removes exactly what install adde
|
|
|
121
25
|
`hindsight-coding-agents install` changes nothing and prints the choice, so wiring every agent on
|
|
122
26
|
the machine is never something that happens by accident.
|
|
123
27
|
|
|
124
|
-
|
|
28
|
+
### Per agent
|
|
125
29
|
|
|
126
30
|
Same command, only the harness name changes. Run after installing the package globally.
|
|
127
31
|
|
|
@@ -135,11 +39,16 @@ Same command, only the harness name changes. Run after installing the package gl
|
|
|
135
39
|
| GitHub Copilot CLI | `hindsight-coding-agents install copilot-cli` | `~/.copilot/hooks/` + `mcp-config.json` + skill |
|
|
136
40
|
| Grok Build | `hindsight-coding-agents install grok-build` | native hooks + MCP in `~/.grok/config.toml` + skill |
|
|
137
41
|
| Antigravity CLI | `hindsight-coding-agents install agy` | lifecycle hooks + MCP + the `Hindsight · <bank>` status line |
|
|
138
|
-
| Devin CLI | `hindsight-coding-agents install devin-cli` | hooks in `~/.config/devin/config.json` + MCP
|
|
42
|
+
| Devin CLI | `hindsight-coding-agents install devin-cli` | hooks in `~/.config/devin/config.json` + MCP (needs Node 22.5+, see below) |
|
|
139
43
|
| Cline CLI | `hindsight-coding-agents install cline-cli` | native plugin via `cline plugin install` + MCP + skill |
|
|
140
44
|
|
|
141
45
|
Uninstall the same way: `hindsight-coding-agents uninstall claude-code` (or `uninstall all`).
|
|
142
46
|
|
|
47
|
+
**Devin CLI needs Node 22.5 or newer.** Its hooks pass only a session id — the conversation itself
|
|
48
|
+
lives in `~/.local/share/devin/cli/sessions.db` — so reading it depends on Node's built-in
|
|
49
|
+
`node:sqlite`. Installing `devin-cli` checks for this first and refuses (with the reason) rather
|
|
50
|
+
than wiring hooks that could never retain anything. Every other agent works on any supported Node.
|
|
51
|
+
|
|
143
52
|
Install globally (not `npx`): the wiring points at this package's files, so it must live at a
|
|
144
53
|
stable path — the installer refuses to run from an npx cache. **Updating** is just
|
|
145
54
|
`npm update -g @vectorize-io/hindsight-coding-agents`: the wired paths stay valid, every new session runs the
|
|
@@ -169,14 +78,127 @@ Adding an agent: hook-based → write a `HookSpec` entry point (see `src/cursor-
|
|
|
169
78
|
a `hookAdapter` in `src/harness/registry.ts`; persistent-plugin → implement `HarnessAdapter`
|
|
170
79
|
(`src/core/types.ts`) fully (see `src/harness/opencode.ts`).
|
|
171
80
|
|
|
81
|
+
## Migrating from the per-agent plugins
|
|
82
|
+
|
|
83
|
+
The older per-agent integrations (`hindsight-claude-code`, `hindsight-cursor-cli`, `hindsight-codex`, …) are superseded by this package. Their memory does **not** carry over automatically, and it cannot be merged:
|
|
84
|
+
|
|
85
|
+
- They scope a bank **per agent per project** (`claude-code::myrepo`); this package uses one **per repo** (`coding-agent::myrepo`) so every agent shares it. Two old banks map onto one new one.
|
|
86
|
+
- The server restores a whole bank rather than merging into an existing one, so the old bank can't be folded in.
|
|
87
|
+
|
|
88
|
+
Instead, re-import the conversations the agent already wrote to disk — they get re-extracted into the current bank:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
cd /path/to/your/repo
|
|
92
|
+
hindsight-coding-agents install claude-code --import-conversations
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
**How sessions are matched.** A conversation is imported only when the session itself records the
|
|
96
|
+
directory it ran in — never inferred from a file or folder name. Claude Code writes that directory
|
|
97
|
+
on its entries and Codex in its `session_meta` header, so both can be attributed exactly, including
|
|
98
|
+
sessions started in a subdirectory of the repo. Guessing was tempting (Claude names its history
|
|
99
|
+
folders after the project path) but unsafe: `/` and `.` both encode to `-`, so `repo-sub` is either
|
|
100
|
+
the subdirectory `repo/sub` or an unrelated sibling repo — and a wrong guess files someone else's
|
|
101
|
+
conversation into your bank. Sessions that record nothing are skipped and the count is reported.
|
|
102
|
+
The other harnesses (opencode, Kilo, Cursor, Cline, Copilot, Devin) keep history in internal SQLite
|
|
103
|
+
databases with unversioned schemas and are skipped with a reason.
|
|
104
|
+
|
|
105
|
+
The import is scoped to the **current repo**, safe to re-run (ingestion dedups by document id), and
|
|
106
|
+
runs extraction — so it costs tokens roughly in proportion to the history imported.
|
|
107
|
+
|
|
108
|
+
Prefer to keep the old bank instead? Point this package at it — no data moves:
|
|
109
|
+
|
|
110
|
+
```jsonc
|
|
111
|
+
{ "bankIdTemplate": "{harness}::{gitProject}" } // reproduces the old per-agent naming
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## How it works
|
|
115
|
+
|
|
116
|
+
**Ingestion — automatic, no command to run**
|
|
117
|
+
|
|
118
|
+
- On a **cold repo**, the first session kicks off a background seed: recent commit **messages** as one cheap document, plus a short headless **codebase survey** to map the structure.
|
|
119
|
+
- On **every** session, a background "deepen" pass ingests conversations not yet stored and the next batch of recent commits **with full diffs, newest first** — precision arrives across sessions instead of one big ingest.
|
|
120
|
+
- Repeated or concurrent runs are a no-op (per-bank lock + document-id dedup).
|
|
121
|
+
- Ask the agent `hindsight_sync_status` to see where ingestion stands — `synced: true` means everything is queryable.
|
|
122
|
+
|
|
123
|
+
**In the session — what the agent actually receives**
|
|
124
|
+
|
|
125
|
+
- On the first prompt, a **reflect** call returns the past decision behind the task, with its exact rule and values. It's cached and re-injected each turn.
|
|
126
|
+
- Every turn, the repo's **knowledge pages** are matched locally against the prompt (lexical index — no server call, no LLM, ~ms) and the best sections are injected with provenance. Below a relevance floor, nothing is injected.
|
|
127
|
+
- The agent also gets the page roster and the `hindsight_*` tools, so it can read a page, search raw memory, or record a new initiative itself.
|
|
128
|
+
- Injected memory carries a visible-attribution directive, so the agent shows a `🧠 Using Hindsight Memories` header when memory shaped its answer.
|
|
129
|
+
|
|
130
|
+
**Write-back — sessions become memory**
|
|
131
|
+
|
|
132
|
+
- The live session is stored as a transcript: user/assistant turns plus a compact `action` line per tool call (name + target, no arguments or output) — decisions without the mechanical noise.
|
|
133
|
+
- Hook harnesses write on `Stop`. Plugin harnesses (opencode, Kilo) write on a turn cadence **and** when the session goes idle — the idle pass is what captures the agent's own reply, which the per-turn pass runs too early to see.
|
|
134
|
+
|
|
135
|
+
**Guarantees**
|
|
136
|
+
|
|
137
|
+
- A failed reflect or page fetch degrades to a no-memory turn; it never breaks the agent.
|
|
138
|
+
- It never fails _silently_ either: every outcome is written to a diagnostics file, so a memory-less session can't pass for a memory session.
|
|
139
|
+
- When two memories conflict on the same rule, the later decision wins and the superseded one is reported as no longer in effect.
|
|
140
|
+
- Against a Hindsight server that predates knowledge pages, page features are skipped (recorded as `knowledge_pages_unavailable`) and everything else continues.
|
|
141
|
+
|
|
142
|
+
## Harnesses
|
|
143
|
+
|
|
144
|
+
Every harness runs the same surface (seed → session reflect → per-turn page sections → knowledge
|
|
145
|
+
tools → write-back); they differ only in how that surface is delivered.
|
|
146
|
+
|
|
147
|
+
| harness | kind | lifecycle wiring | install |
|
|
148
|
+
| ------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
|
|
149
|
+
| `opencode` | persistent plugin | one process: load-time seed, session reflect + page sections, native tools, write-back | add the package dir to `opencode.json` → `"plugin": [...]` |
|
|
150
|
+
| `kilo` | persistent plugin | identical to `opencode` — Kilo CLI is an opencode fork, so it loads the same runtime (no hooks system) | `hindsight-coding-agents install kilo` → `kilo.json[c]` `"plugin"` |
|
|
151
|
+
| `claude-code` | per-prompt hooks | `SessionStart` (seed) + `UserPromptSubmit` (reflect + pages) + `Stop` (write-back) + MCP | `hindsight-coding-agents install claude-code` |
|
|
152
|
+
| `codex` | per-prompt hooks | same three hooks in `~/.codex/hooks.json` (+ `codex_hooks = true`, CLI ≥ 0.116) | `hindsight-coding-agents install codex` |
|
|
153
|
+
| `antigravity-cli` (`agy`) | lifecycle hooks | Antigravity CLI lifecycle hooks (`PreInvocation` + `Stop`) + MCP, plus a native colored `Hindsight · <bank>` status-line indicator | `hindsight-coding-agents install agy` |
|
|
154
|
+
| `cursor-cli` | lifecycle hooks | `sessionStart` (seed + pages) + `beforeSubmitPrompt` (reflect) + `stop` (write-back) | hooks in Cursor `hooks.json` |
|
|
155
|
+
| `copilot-cli` | lifecycle hooks | `sessionStart` (seed + pages) + `userPromptTransformed` (reflect) + `agentStop` (write-back) + MCP | `~/.copilot/hooks/hindsight-coding-agents.json` + `mcp-config.json` |
|
|
156
|
+
| `grok-build` | lifecycle hooks | `SessionStart` (seed) + `Stop` (write-back) + MCP | native `~/.grok/config.toml` — no Claude Code dependency |
|
|
157
|
+
| `cline-cli` | persistent plugin | native `beforeModel` (seed/reflect/pages) + `afterRun` (write-back) + MCP | `cline plugin install` (run by the installer) |
|
|
158
|
+
|
|
159
|
+
The hook-based harnesses share one runtime (`src/core/hook.ts`) plus their SessionStart/Stop
|
|
160
|
+
entrypoints. Persistent-plugin hosts (opencode/Kilo/Cline) delegate to the same `RuntimeCore`,
|
|
161
|
+
which in turn calls those shared session-start, prompt, and retain operations; only their host API
|
|
162
|
+
adapters differ. Opencode and Kilo can register the knowledge tools natively; Cline uses the shared
|
|
163
|
+
MCP server. All support opt-in **incremental git-sync** (retain commits new since the seed on load).
|
|
164
|
+
|
|
165
|
+
Antigravity renders the Hindsight indicator with its documented custom status-line command. It is
|
|
166
|
+
local and never calls the Hindsight API while the TUI redraws. If you already configured an
|
|
167
|
+
Antigravity custom status line, the installer leaves it untouched rather than replacing it.
|
|
168
|
+
|
|
169
|
+
### Grok Build limitation
|
|
170
|
+
|
|
171
|
+
Grok Build executes `UserPromptSubmit` hooks but ignores their stdout. Hindsight can therefore not
|
|
172
|
+
inject a reflect result, memory block, or banner into Grok's model-visible conversation. Grok still
|
|
173
|
+
gets native bank setup and transcript retention plus Hindsight MCP tools and the companion skill;
|
|
174
|
+
ask it to call `hindsight_reflect` or `hindsight_search_knowledge_pages` when needed. Automatic
|
|
175
|
+
injection requires a future Grok prompt-transform API.
|
|
176
|
+
|
|
177
|
+
### Cline CLI scope
|
|
178
|
+
|
|
179
|
+
Cline's external file hooks cannot alter a model request, so Hindsight uses Cline's native plugin
|
|
180
|
+
API instead. Its `beforeModel` hook injects the shared reflect/page context and
|
|
181
|
+
its `afterRun` hook upserts Cline's runtime transcript. `hindsight-coding-agents install cline-cli`
|
|
182
|
+
runs `cline plugin install --force <package-path>` and configures MCP plus the companion skill.
|
|
183
|
+
Cline CLI sandboxes plugin hooks with a three-second limit, so a slow first reflect finishes in the
|
|
184
|
+
background and is injected on a subsequent model call or turn rather than aborting the session.
|
|
185
|
+
Its write-back retains only user-visible user/assistant text; tool arguments, tool results and
|
|
186
|
+
command output, tool-role messages, reasoning parts, and Hindsight's injected context are excluded.
|
|
187
|
+
Cline IDE extensions are not currently supported by this CLI integration.
|
|
188
|
+
|
|
172
189
|
## Configuration
|
|
173
190
|
|
|
174
|
-
|
|
175
|
-
for the diagnostics path): `~/.hindsight/coding-agent.json`. Layering, later wins per field:
|
|
191
|
+
Configuration is **one JSON file**: `~/.hindsight/coding-agent.json`. Layering, later wins per field:
|
|
176
192
|
|
|
177
193
|
1. built-in defaults
|
|
178
|
-
2.
|
|
179
|
-
|
|
194
|
+
2. environment variables — `HINDSIGHT_API_URL`, `HINDSIGHT_API_TOKEN`, and one per scalar setting
|
|
195
|
+
(`HINDSIGHT_<FIELD_IN_CAPS>`), for containers and CI that inject config rather than write a file
|
|
196
|
+
3. the file's top level
|
|
197
|
+
4. its `harnesses.<name>` section — per-agent override
|
|
198
|
+
|
|
199
|
+
Environment variables are a **fallback**: the file wins wherever it sets a value, so adding env to
|
|
200
|
+
an existing setup changes nothing. The map-valued settings (`mapPathToBank`, `harnesses`, `banks`)
|
|
201
|
+
are file-only — nested branching doesn't survive flattening into one variable.
|
|
180
202
|
|
|
181
203
|
There is deliberately no repo-carried config file — per-repo bank routing is `mapPathToBank`,
|
|
182
204
|
per-agent differences are `harnesses.<name>`.
|
|
@@ -336,22 +358,3 @@ as a JSON line to `/tmp/hindsight-plugin.log` (override with `HINDSIGHT_DIAG_FIL
|
|
|
336
358
|
`reflect_failed` / `pages_failed` record the error; if you're comparing memory-on vs memory-off,
|
|
337
359
|
check this file — a run whose reflects failed is a no-memory run. Seed starts are logged as
|
|
338
360
|
`seed_started`.
|
|
339
|
-
|
|
340
|
-
## Layout
|
|
341
|
-
|
|
342
|
-
```
|
|
343
|
-
src/
|
|
344
|
-
core/ # harness-agnostic: config (layered), bank resolution, hindsight client, missions,
|
|
345
|
-
# git + chat ingest, git-sync, seed + survey, pages-index (local section matching),
|
|
346
|
-
# knowledge-injection, knowledge-tools, session-start, transcript readers,
|
|
347
|
-
# hook runtime, RuntimeCore
|
|
348
|
-
harness/ # per-agent adapters + registry (opencode persistent; claude/codex/antigravity/cursor/copilot as hooks)
|
|
349
|
-
index.ts # opencode plugin entrypoint
|
|
350
|
-
claude-hook.ts / claude-sessionstart-hook.ts / claude-stop-hook.ts # Claude Code entrypoints
|
|
351
|
-
codex-hook.ts / codex-sessionstart-hook.ts / codex-stop-hook.ts # Codex CLI entrypoints
|
|
352
|
-
antigravity-hook.ts / antigravity-stop-hook.ts # Antigravity CLI entrypoints
|
|
353
|
-
cursor-hook.ts # Cursor CLI hook entrypoint (bin: hindsight-cursor-hook)
|
|
354
|
-
copilot-*.ts # GitHub Copilot CLI SessionStart/prompt/agentStop entrypoints
|
|
355
|
-
mcp-server.ts # hindsight_* knowledge/recall tools for the hook harnesses (MCP)
|
|
356
|
-
backfill.ts # backfill CLI (bin: hindsight-coding-backfill)
|
|
357
|
-
```
|
package/dist/antigravity-hook.js
CHANGED
|
@@ -1283,10 +1283,13 @@ function readGrokTranscript(path) {
|
|
|
1283
1283
|
}
|
|
1284
1284
|
|
|
1285
1285
|
// src/core/transcript-devin.ts
|
|
1286
|
-
import {
|
|
1286
|
+
import { existsSync as existsSync5 } from "fs";
|
|
1287
|
+
import { createRequire } from "module";
|
|
1287
1288
|
import { homedir as homedir6 } from "os";
|
|
1288
1289
|
import { join as join9 } from "path";
|
|
1289
|
-
|
|
1290
|
+
function devinSessionDb(home = homedir6()) {
|
|
1291
|
+
return join9(home, ".local", "share", "devin", "cli", "sessions.db");
|
|
1292
|
+
}
|
|
1290
1293
|
function parseDevinMessages(nodes) {
|
|
1291
1294
|
const messages = /* @__PURE__ */ new Map();
|
|
1292
1295
|
for (const node of nodes) {
|
|
@@ -1307,23 +1310,41 @@ function parseDevinMessages(nodes) {
|
|
|
1307
1310
|
}
|
|
1308
1311
|
return [...messages.values()].sort((a, b) => a.index - b.index).map(({ role, content }) => ({ role, content }));
|
|
1309
1312
|
}
|
|
1310
|
-
|
|
1311
|
-
|
|
1313
|
+
var requireBuiltin = createRequire(import.meta.url);
|
|
1314
|
+
function loadSqlite() {
|
|
1312
1315
|
try {
|
|
1313
|
-
|
|
1314
|
-
const raw = execFileSync4(
|
|
1315
|
-
"sqlite3",
|
|
1316
|
-
[
|
|
1317
|
-
"-json",
|
|
1318
|
-
sessionDb,
|
|
1319
|
-
`SELECT node_id, chat_message FROM message_nodes WHERE session_id = '${quotedId}' ORDER BY node_id`
|
|
1320
|
-
],
|
|
1321
|
-
{ encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 2e3 }
|
|
1322
|
-
);
|
|
1323
|
-
return parseDevinMessages(JSON.parse(raw));
|
|
1316
|
+
return requireBuiltin("node:sqlite").DatabaseSync;
|
|
1324
1317
|
} catch {
|
|
1318
|
+
return void 0;
|
|
1319
|
+
}
|
|
1320
|
+
}
|
|
1321
|
+
function readDevinTranscript(sessionId, dbPath = devinSessionDb()) {
|
|
1322
|
+
if (!sessionId) return [];
|
|
1323
|
+
const Database = loadSqlite();
|
|
1324
|
+
if (!Database) {
|
|
1325
|
+
diag("devin-cli", "sqlite_unavailable", { node: process.version, dbPath });
|
|
1325
1326
|
return [];
|
|
1326
1327
|
}
|
|
1328
|
+
if (!existsSync5(dbPath)) {
|
|
1329
|
+
diag("devin-cli", "session_db_missing", { dbPath });
|
|
1330
|
+
return [];
|
|
1331
|
+
}
|
|
1332
|
+
let db;
|
|
1333
|
+
try {
|
|
1334
|
+
db = new Database(dbPath, { readOnly: true });
|
|
1335
|
+
const rows = db.prepare(
|
|
1336
|
+
"SELECT node_id, chat_message FROM message_nodes WHERE session_id = ? ORDER BY node_id"
|
|
1337
|
+
).all(sessionId);
|
|
1338
|
+
return parseDevinMessages(rows);
|
|
1339
|
+
} catch (error) {
|
|
1340
|
+
diag("devin-cli", "session_db_read_failed", { dbPath, error: String(error) });
|
|
1341
|
+
return [];
|
|
1342
|
+
} finally {
|
|
1343
|
+
try {
|
|
1344
|
+
db?.close();
|
|
1345
|
+
} catch {
|
|
1346
|
+
}
|
|
1347
|
+
}
|
|
1327
1348
|
}
|
|
1328
1349
|
|
|
1329
1350
|
// src/harness/hook-lifecycle.ts
|
|
@@ -1180,10 +1180,13 @@ function readGrokTranscript(path) {
|
|
|
1180
1180
|
}
|
|
1181
1181
|
|
|
1182
1182
|
// src/core/transcript-devin.ts
|
|
1183
|
-
import {
|
|
1183
|
+
import { existsSync as existsSync5 } from "fs";
|
|
1184
|
+
import { createRequire } from "module";
|
|
1184
1185
|
import { homedir as homedir6 } from "os";
|
|
1185
1186
|
import { join as join9 } from "path";
|
|
1186
|
-
|
|
1187
|
+
function devinSessionDb(home = homedir6()) {
|
|
1188
|
+
return join9(home, ".local", "share", "devin", "cli", "sessions.db");
|
|
1189
|
+
}
|
|
1187
1190
|
function parseDevinMessages(nodes) {
|
|
1188
1191
|
const messages = /* @__PURE__ */ new Map();
|
|
1189
1192
|
for (const node of nodes) {
|
|
@@ -1204,22 +1207,40 @@ function parseDevinMessages(nodes) {
|
|
|
1204
1207
|
}
|
|
1205
1208
|
return [...messages.values()].sort((a, b) => a.index - b.index).map(({ role, content }) => ({ role, content }));
|
|
1206
1209
|
}
|
|
1207
|
-
|
|
1208
|
-
|
|
1210
|
+
var requireBuiltin = createRequire(import.meta.url);
|
|
1211
|
+
function loadSqlite() {
|
|
1209
1212
|
try {
|
|
1210
|
-
|
|
1211
|
-
const raw = execFileSync4(
|
|
1212
|
-
"sqlite3",
|
|
1213
|
-
[
|
|
1214
|
-
"-json",
|
|
1215
|
-
sessionDb,
|
|
1216
|
-
`SELECT node_id, chat_message FROM message_nodes WHERE session_id = '${quotedId}' ORDER BY node_id`
|
|
1217
|
-
],
|
|
1218
|
-
{ encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 2e3 }
|
|
1219
|
-
);
|
|
1220
|
-
return parseDevinMessages(JSON.parse(raw));
|
|
1213
|
+
return requireBuiltin("node:sqlite").DatabaseSync;
|
|
1221
1214
|
} catch {
|
|
1215
|
+
return void 0;
|
|
1216
|
+
}
|
|
1217
|
+
}
|
|
1218
|
+
function readDevinTranscript(sessionId, dbPath = devinSessionDb()) {
|
|
1219
|
+
if (!sessionId) return [];
|
|
1220
|
+
const Database = loadSqlite();
|
|
1221
|
+
if (!Database) {
|
|
1222
|
+
diag("devin-cli", "sqlite_unavailable", { node: process.version, dbPath });
|
|
1223
|
+
return [];
|
|
1224
|
+
}
|
|
1225
|
+
if (!existsSync5(dbPath)) {
|
|
1226
|
+
diag("devin-cli", "session_db_missing", { dbPath });
|
|
1227
|
+
return [];
|
|
1228
|
+
}
|
|
1229
|
+
let db;
|
|
1230
|
+
try {
|
|
1231
|
+
db = new Database(dbPath, { readOnly: true });
|
|
1232
|
+
const rows = db.prepare(
|
|
1233
|
+
"SELECT node_id, chat_message FROM message_nodes WHERE session_id = ? ORDER BY node_id"
|
|
1234
|
+
).all(sessionId);
|
|
1235
|
+
return parseDevinMessages(rows);
|
|
1236
|
+
} catch (error) {
|
|
1237
|
+
diag("devin-cli", "session_db_read_failed", { dbPath, error: String(error) });
|
|
1222
1238
|
return [];
|
|
1239
|
+
} finally {
|
|
1240
|
+
try {
|
|
1241
|
+
db?.close();
|
|
1242
|
+
} catch {
|
|
1243
|
+
}
|
|
1223
1244
|
}
|
|
1224
1245
|
}
|
|
1225
1246
|
|
package/dist/claude-hook.js
CHANGED
|
@@ -1283,10 +1283,13 @@ function readGrokTranscript(path) {
|
|
|
1283
1283
|
}
|
|
1284
1284
|
|
|
1285
1285
|
// src/core/transcript-devin.ts
|
|
1286
|
-
import {
|
|
1286
|
+
import { existsSync as existsSync5 } from "fs";
|
|
1287
|
+
import { createRequire } from "module";
|
|
1287
1288
|
import { homedir as homedir6 } from "os";
|
|
1288
1289
|
import { join as join9 } from "path";
|
|
1289
|
-
|
|
1290
|
+
function devinSessionDb(home = homedir6()) {
|
|
1291
|
+
return join9(home, ".local", "share", "devin", "cli", "sessions.db");
|
|
1292
|
+
}
|
|
1290
1293
|
function parseDevinMessages(nodes) {
|
|
1291
1294
|
const messages = /* @__PURE__ */ new Map();
|
|
1292
1295
|
for (const node of nodes) {
|
|
@@ -1307,23 +1310,41 @@ function parseDevinMessages(nodes) {
|
|
|
1307
1310
|
}
|
|
1308
1311
|
return [...messages.values()].sort((a, b) => a.index - b.index).map(({ role, content }) => ({ role, content }));
|
|
1309
1312
|
}
|
|
1310
|
-
|
|
1311
|
-
|
|
1313
|
+
var requireBuiltin = createRequire(import.meta.url);
|
|
1314
|
+
function loadSqlite() {
|
|
1312
1315
|
try {
|
|
1313
|
-
|
|
1314
|
-
const raw = execFileSync4(
|
|
1315
|
-
"sqlite3",
|
|
1316
|
-
[
|
|
1317
|
-
"-json",
|
|
1318
|
-
sessionDb,
|
|
1319
|
-
`SELECT node_id, chat_message FROM message_nodes WHERE session_id = '${quotedId}' ORDER BY node_id`
|
|
1320
|
-
],
|
|
1321
|
-
{ encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 2e3 }
|
|
1322
|
-
);
|
|
1323
|
-
return parseDevinMessages(JSON.parse(raw));
|
|
1316
|
+
return requireBuiltin("node:sqlite").DatabaseSync;
|
|
1324
1317
|
} catch {
|
|
1318
|
+
return void 0;
|
|
1319
|
+
}
|
|
1320
|
+
}
|
|
1321
|
+
function readDevinTranscript(sessionId, dbPath = devinSessionDb()) {
|
|
1322
|
+
if (!sessionId) return [];
|
|
1323
|
+
const Database = loadSqlite();
|
|
1324
|
+
if (!Database) {
|
|
1325
|
+
diag("devin-cli", "sqlite_unavailable", { node: process.version, dbPath });
|
|
1325
1326
|
return [];
|
|
1326
1327
|
}
|
|
1328
|
+
if (!existsSync5(dbPath)) {
|
|
1329
|
+
diag("devin-cli", "session_db_missing", { dbPath });
|
|
1330
|
+
return [];
|
|
1331
|
+
}
|
|
1332
|
+
let db;
|
|
1333
|
+
try {
|
|
1334
|
+
db = new Database(dbPath, { readOnly: true });
|
|
1335
|
+
const rows = db.prepare(
|
|
1336
|
+
"SELECT node_id, chat_message FROM message_nodes WHERE session_id = ? ORDER BY node_id"
|
|
1337
|
+
).all(sessionId);
|
|
1338
|
+
return parseDevinMessages(rows);
|
|
1339
|
+
} catch (error) {
|
|
1340
|
+
diag("devin-cli", "session_db_read_failed", { dbPath, error: String(error) });
|
|
1341
|
+
return [];
|
|
1342
|
+
} finally {
|
|
1343
|
+
try {
|
|
1344
|
+
db?.close();
|
|
1345
|
+
} catch {
|
|
1346
|
+
}
|
|
1347
|
+
}
|
|
1327
1348
|
}
|
|
1328
1349
|
|
|
1329
1350
|
// src/harness/hook-lifecycle.ts
|
|
@@ -1173,9 +1173,9 @@ async function gitSyncNote(args) {
|
|
|
1173
1173
|
const deepened = [...gitIds].filter((id) => id.startsWith("git:")).length;
|
|
1174
1174
|
let target = DEEPEN_DIFF_TARGET;
|
|
1175
1175
|
try {
|
|
1176
|
-
const { execFileSync:
|
|
1176
|
+
const { execFileSync: execFileSync4 } = await import("child_process");
|
|
1177
1177
|
const n = Number(
|
|
1178
|
-
|
|
1178
|
+
execFileSync4("git", ["-C", cwd, "rev-list", "--count", "HEAD"], { encoding: "utf8" }).trim()
|
|
1179
1179
|
);
|
|
1180
1180
|
if (n > 0) target = Math.min(DEEPEN_DIFF_TARGET, n);
|
|
1181
1181
|
} catch {
|
|
@@ -1541,10 +1541,13 @@ function readGrokTranscript(path) {
|
|
|
1541
1541
|
}
|
|
1542
1542
|
|
|
1543
1543
|
// src/core/transcript-devin.ts
|
|
1544
|
-
import {
|
|
1544
|
+
import { existsSync as existsSync5 } from "fs";
|
|
1545
|
+
import { createRequire } from "module";
|
|
1545
1546
|
import { homedir as homedir6 } from "os";
|
|
1546
1547
|
import { join as join9 } from "path";
|
|
1547
|
-
|
|
1548
|
+
function devinSessionDb(home = homedir6()) {
|
|
1549
|
+
return join9(home, ".local", "share", "devin", "cli", "sessions.db");
|
|
1550
|
+
}
|
|
1548
1551
|
function parseDevinMessages(nodes) {
|
|
1549
1552
|
const messages = /* @__PURE__ */ new Map();
|
|
1550
1553
|
for (const node of nodes) {
|
|
@@ -1565,23 +1568,41 @@ function parseDevinMessages(nodes) {
|
|
|
1565
1568
|
}
|
|
1566
1569
|
return [...messages.values()].sort((a, b) => a.index - b.index).map(({ role, content }) => ({ role, content }));
|
|
1567
1570
|
}
|
|
1568
|
-
|
|
1569
|
-
|
|
1571
|
+
var requireBuiltin = createRequire(import.meta.url);
|
|
1572
|
+
function loadSqlite() {
|
|
1570
1573
|
try {
|
|
1571
|
-
|
|
1572
|
-
const raw = execFileSync4(
|
|
1573
|
-
"sqlite3",
|
|
1574
|
-
[
|
|
1575
|
-
"-json",
|
|
1576
|
-
sessionDb,
|
|
1577
|
-
`SELECT node_id, chat_message FROM message_nodes WHERE session_id = '${quotedId}' ORDER BY node_id`
|
|
1578
|
-
],
|
|
1579
|
-
{ encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 2e3 }
|
|
1580
|
-
);
|
|
1581
|
-
return parseDevinMessages(JSON.parse(raw));
|
|
1574
|
+
return requireBuiltin("node:sqlite").DatabaseSync;
|
|
1582
1575
|
} catch {
|
|
1576
|
+
return void 0;
|
|
1577
|
+
}
|
|
1578
|
+
}
|
|
1579
|
+
function readDevinTranscript(sessionId, dbPath = devinSessionDb()) {
|
|
1580
|
+
if (!sessionId) return [];
|
|
1581
|
+
const Database = loadSqlite();
|
|
1582
|
+
if (!Database) {
|
|
1583
|
+
diag("devin-cli", "sqlite_unavailable", { node: process.version, dbPath });
|
|
1583
1584
|
return [];
|
|
1584
1585
|
}
|
|
1586
|
+
if (!existsSync5(dbPath)) {
|
|
1587
|
+
diag("devin-cli", "session_db_missing", { dbPath });
|
|
1588
|
+
return [];
|
|
1589
|
+
}
|
|
1590
|
+
let db;
|
|
1591
|
+
try {
|
|
1592
|
+
db = new Database(dbPath, { readOnly: true });
|
|
1593
|
+
const rows = db.prepare(
|
|
1594
|
+
"SELECT node_id, chat_message FROM message_nodes WHERE session_id = ? ORDER BY node_id"
|
|
1595
|
+
).all(sessionId);
|
|
1596
|
+
return parseDevinMessages(rows);
|
|
1597
|
+
} catch (error) {
|
|
1598
|
+
diag("devin-cli", "session_db_read_failed", { dbPath, error: String(error) });
|
|
1599
|
+
return [];
|
|
1600
|
+
} finally {
|
|
1601
|
+
try {
|
|
1602
|
+
db?.close();
|
|
1603
|
+
} catch {
|
|
1604
|
+
}
|
|
1605
|
+
}
|
|
1585
1606
|
}
|
|
1586
1607
|
|
|
1587
1608
|
// src/harness/hook-lifecycle.ts
|
package/dist/claude-stop-hook.js
CHANGED
|
@@ -1180,10 +1180,13 @@ function readGrokTranscript(path) {
|
|
|
1180
1180
|
}
|
|
1181
1181
|
|
|
1182
1182
|
// src/core/transcript-devin.ts
|
|
1183
|
-
import {
|
|
1183
|
+
import { existsSync as existsSync5 } from "fs";
|
|
1184
|
+
import { createRequire } from "module";
|
|
1184
1185
|
import { homedir as homedir6 } from "os";
|
|
1185
1186
|
import { join as join9 } from "path";
|
|
1186
|
-
|
|
1187
|
+
function devinSessionDb(home = homedir6()) {
|
|
1188
|
+
return join9(home, ".local", "share", "devin", "cli", "sessions.db");
|
|
1189
|
+
}
|
|
1187
1190
|
function parseDevinMessages(nodes) {
|
|
1188
1191
|
const messages = /* @__PURE__ */ new Map();
|
|
1189
1192
|
for (const node of nodes) {
|
|
@@ -1204,22 +1207,40 @@ function parseDevinMessages(nodes) {
|
|
|
1204
1207
|
}
|
|
1205
1208
|
return [...messages.values()].sort((a, b) => a.index - b.index).map(({ role, content }) => ({ role, content }));
|
|
1206
1209
|
}
|
|
1207
|
-
|
|
1208
|
-
|
|
1210
|
+
var requireBuiltin = createRequire(import.meta.url);
|
|
1211
|
+
function loadSqlite() {
|
|
1209
1212
|
try {
|
|
1210
|
-
|
|
1211
|
-
const raw = execFileSync4(
|
|
1212
|
-
"sqlite3",
|
|
1213
|
-
[
|
|
1214
|
-
"-json",
|
|
1215
|
-
sessionDb,
|
|
1216
|
-
`SELECT node_id, chat_message FROM message_nodes WHERE session_id = '${quotedId}' ORDER BY node_id`
|
|
1217
|
-
],
|
|
1218
|
-
{ encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 2e3 }
|
|
1219
|
-
);
|
|
1220
|
-
return parseDevinMessages(JSON.parse(raw));
|
|
1213
|
+
return requireBuiltin("node:sqlite").DatabaseSync;
|
|
1221
1214
|
} catch {
|
|
1215
|
+
return void 0;
|
|
1216
|
+
}
|
|
1217
|
+
}
|
|
1218
|
+
function readDevinTranscript(sessionId, dbPath = devinSessionDb()) {
|
|
1219
|
+
if (!sessionId) return [];
|
|
1220
|
+
const Database = loadSqlite();
|
|
1221
|
+
if (!Database) {
|
|
1222
|
+
diag("devin-cli", "sqlite_unavailable", { node: process.version, dbPath });
|
|
1223
|
+
return [];
|
|
1224
|
+
}
|
|
1225
|
+
if (!existsSync5(dbPath)) {
|
|
1226
|
+
diag("devin-cli", "session_db_missing", { dbPath });
|
|
1227
|
+
return [];
|
|
1228
|
+
}
|
|
1229
|
+
let db;
|
|
1230
|
+
try {
|
|
1231
|
+
db = new Database(dbPath, { readOnly: true });
|
|
1232
|
+
const rows = db.prepare(
|
|
1233
|
+
"SELECT node_id, chat_message FROM message_nodes WHERE session_id = ? ORDER BY node_id"
|
|
1234
|
+
).all(sessionId);
|
|
1235
|
+
return parseDevinMessages(rows);
|
|
1236
|
+
} catch (error) {
|
|
1237
|
+
diag("devin-cli", "session_db_read_failed", { dbPath, error: String(error) });
|
|
1222
1238
|
return [];
|
|
1239
|
+
} finally {
|
|
1240
|
+
try {
|
|
1241
|
+
db?.close();
|
|
1242
|
+
} catch {
|
|
1243
|
+
}
|
|
1223
1244
|
}
|
|
1224
1245
|
}
|
|
1225
1246
|
|