@vectorize-io/hindsight-coding-agents 0.0.1
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 +334 -0
- package/dist/antigravity-hook.js +1556 -0
- package/dist/antigravity-statusline.js +194 -0
- package/dist/antigravity-stop-hook.js +1453 -0
- package/dist/claude-hook.js +1556 -0
- package/dist/claude-sessionstart-hook.js +1814 -0
- package/dist/claude-stop-hook.js +1453 -0
- package/dist/cline.js +16373 -0
- package/dist/codex-hook.js +1556 -0
- package/dist/codex-sessionstart-hook.js +1814 -0
- package/dist/codex-stop-hook.js +1453 -0
- package/dist/copilot-hook.js +1556 -0
- package/dist/copilot-sessionstart-hook.js +1814 -0
- package/dist/copilot-stop-hook.js +1453 -0
- package/dist/cursor-hook.js +1556 -0
- package/dist/cursor-sessionstart-hook.js +1814 -0
- package/dist/cursor-stop-hook.js +1453 -0
- package/dist/deepen.js +1175 -0
- package/dist/devin-hook.js +1556 -0
- package/dist/devin-sessionstart-hook.js +1814 -0
- package/dist/devin-stop-hook.js +1453 -0
- package/dist/grok-hook.js +1556 -0
- package/dist/grok-sessionstart-hook.js +1814 -0
- package/dist/grok-stop-hook.js +1453 -0
- package/dist/hindsight-seed.js +180 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +28853 -0
- package/dist/installer.js +1313 -0
- package/dist/kilo.js +28853 -0
- package/dist/mcp-server.js +31888 -0
- package/dist/status.js +793 -0
- package/package.json +65 -0
- package/skill/SKILL.md +122 -0
package/package.json
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@vectorize-io/hindsight-coding-agents",
|
|
3
|
+
"version": "0.0.1",
|
|
4
|
+
"repository": {
|
|
5
|
+
"type": "git",
|
|
6
|
+
"url": "https://github.com/vectorize-io/hindsight.git",
|
|
7
|
+
"directory": "hindsight-integrations/coding-agents"
|
|
8
|
+
},
|
|
9
|
+
"description": "Reflect-only Hindsight long-term memory for coding agents (harness-pluggable: opencode, β¦), with automatic background ingestion (no setup CLI).",
|
|
10
|
+
"type": "module",
|
|
11
|
+
"main": "dist/index.js",
|
|
12
|
+
"types": "dist/index.d.ts",
|
|
13
|
+
"bin": {
|
|
14
|
+
"hindsight-coding-agents": "dist/installer.js",
|
|
15
|
+
"hindsight-claude-hook": "dist/claude-hook.js",
|
|
16
|
+
"hindsight-cursor-hook": "dist/cursor-hook.js",
|
|
17
|
+
"hindsight-cursor-sessionstart-hook": "dist/cursor-sessionstart-hook.js",
|
|
18
|
+
"hindsight-cursor-stop-hook": "dist/cursor-stop-hook.js",
|
|
19
|
+
"hindsight-copilot-hook": "dist/copilot-hook.js",
|
|
20
|
+
"hindsight-copilot-sessionstart-hook": "dist/copilot-sessionstart-hook.js",
|
|
21
|
+
"hindsight-copilot-stop-hook": "dist/copilot-stop-hook.js",
|
|
22
|
+
"hindsight-grok-hook": "dist/grok-hook.js",
|
|
23
|
+
"hindsight-grok-sessionstart-hook": "dist/grok-sessionstart-hook.js",
|
|
24
|
+
"hindsight-grok-stop-hook": "dist/grok-stop-hook.js",
|
|
25
|
+
"hindsight-codex-hook": "dist/codex-hook.js",
|
|
26
|
+
"hindsight-antigravity-hook": "dist/antigravity-hook.js",
|
|
27
|
+
"hindsight-antigravity-statusline": "dist/antigravity-statusline.js",
|
|
28
|
+
"hindsight-devin-hook": "dist/devin-hook.js"
|
|
29
|
+
},
|
|
30
|
+
"files": [
|
|
31
|
+
"skill",
|
|
32
|
+
"dist"
|
|
33
|
+
],
|
|
34
|
+
"cline": {
|
|
35
|
+
"plugins": [
|
|
36
|
+
{
|
|
37
|
+
"paths": [
|
|
38
|
+
"./dist/cline.js"
|
|
39
|
+
],
|
|
40
|
+
"capabilities": [
|
|
41
|
+
"hooks"
|
|
42
|
+
]
|
|
43
|
+
}
|
|
44
|
+
]
|
|
45
|
+
},
|
|
46
|
+
"scripts": {
|
|
47
|
+
"build": "tsup",
|
|
48
|
+
"clean": "rm -rf dist",
|
|
49
|
+
"prepublishOnly": "npm run clean && npm run build",
|
|
50
|
+
"test": "vitest run --exclude '**/*.e2e.test.ts'",
|
|
51
|
+
"test:harness-e2e": "npm run build && HINDSIGHT_HARNESS_E2E=1 vitest run src/harness.e2e.test.ts"
|
|
52
|
+
},
|
|
53
|
+
"dependencies": {
|
|
54
|
+
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
55
|
+
"zod": "^4.4.3"
|
|
56
|
+
},
|
|
57
|
+
"devDependencies": {
|
|
58
|
+
"@opencode-ai/plugin": "^1.18.9",
|
|
59
|
+
"@opencode-ai/sdk": "^1.18.9",
|
|
60
|
+
"@types/node": "^26.1.0",
|
|
61
|
+
"tsup": "^8.3.0",
|
|
62
|
+
"typescript": "^5.6.0",
|
|
63
|
+
"vitest": "^2.1.0"
|
|
64
|
+
}
|
|
65
|
+
}
|
package/skill/SKILL.md
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: hindsight-coding-agent
|
|
3
|
+
description: How this machine's Hindsight coding-agent memory works β the plugin behind the π§ banner. Use when the user says "store/remember this in hindsight", asks what the memory/knowledge pages are, wants to configure per-repo memory (disable, rename banks, git depth), or something memory-related looks broken.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Hindsight Coding-Agent Memory
|
|
7
|
+
|
|
8
|
+
This machine runs the `hindsight-coding-agents` plugin: long-term project memory for coding
|
|
9
|
+
sessions, backed by a Hindsight server. You (the agent) are already wired into it β this skill
|
|
10
|
+
explains what happens automatically, which tools you have, and how to configure or debug it.
|
|
11
|
+
|
|
12
|
+
## What happens automatically (no action needed)
|
|
13
|
+
|
|
14
|
+
- **Per-repo memory bank**: each repository resolves to a bank (shown in the session banner:
|
|
15
|
+
`β³ memory bank βcoding-agent::<repo>β`). Worktrees share the main repo's bank.
|
|
16
|
+
- **Ingestion builds itself**: on first open, the bank is seeded from recent commit messages and a
|
|
17
|
+
read-only codebase survey; every session start, a background engine tops it up (new commits, new
|
|
18
|
+
conversations) and keeps 5 knowledge pages current. There is NO ingest command to run.
|
|
19
|
+
- **Session synthesis**: the first prompt of a session triggers one deep memory synthesis
|
|
20
|
+
(`reflect`) injected into context. Later turns inject nothing automatically.
|
|
21
|
+
- **Write-back**: the session transcript is retained into the bank automatically at session end
|
|
22
|
+
(per-turn on opencode). The user never needs to "save" a conversation.
|
|
23
|
+
|
|
24
|
+
## Storing things deliberately
|
|
25
|
+
|
|
26
|
+
When the user says "store this in hindsight" / "remember this":
|
|
27
|
+
|
|
28
|
+
- The **current conversation** is captured automatically at session end β say so; no tool needed.
|
|
29
|
+
- An **external document, notes, or durable findings** β `hindsight_ingest_document(title, content)`.
|
|
30
|
+
- A **new feature/initiative being started** β `hindsight_capture_initiative(title, summary)`,
|
|
31
|
+
once, right after the plan is agreed and before code is written.
|
|
32
|
+
|
|
33
|
+
## Retrieving
|
|
34
|
+
|
|
35
|
+
- `hindsight_search_knowledge_pages(query)` β FIRST STOP for project questions (components,
|
|
36
|
+
conventions, past decisions, initiatives). Server-side hybrid search, fast.
|
|
37
|
+
- `hindsight_read_knowledge_page(page_id)` / `hindsight_list_knowledge_pages` β read pages fully.
|
|
38
|
+
- `hindsight_reflect(query)` β deep reasoning over the whole memory for WHY questions and exact
|
|
39
|
+
decided values; slower (seconds), use deliberately.
|
|
40
|
+
- Credit visibly whenever memory informs an answer: start that part with
|
|
41
|
+
`π§ From Hindsight memory (<page>): β¦` β and never credit memory that didn't contribute.
|
|
42
|
+
|
|
43
|
+
## Correcting wrong or stale memory
|
|
44
|
+
|
|
45
|
+
If you verify that something Hindsight served is wrong or outdated (the code, git, or an external
|
|
46
|
+
source contradicts it), FIX THE RECORD β don't just ignore it. Call
|
|
47
|
+
`hindsight_ingest_document` with:
|
|
48
|
+
|
|
49
|
+
- **title**: `Correction: <topic>` (e.g. `Correction: retry policy 4xx set`)
|
|
50
|
+
- **content**: (1) what memory claimed, (2) what is verifiably true now, (3) the evidence you
|
|
51
|
+
checked (file/commit/output). Quote exact values verbatim.
|
|
52
|
+
|
|
53
|
+
Newer facts supersede older ones in retrieval, so one clear correction permanently outranks the
|
|
54
|
+
stale memory. Do this whenever you catch a wrong injected memory, a stale knowledge-page claim, or
|
|
55
|
+
an outdated decision β silent disregard leaves the trap armed for the next session.
|
|
56
|
+
|
|
57
|
+
## Configuration β ONE file: `~/.hindsight/coding-agent.json`
|
|
58
|
+
|
|
59
|
+
No environment variables (exceptions: `HINDSIGHT_CONFIG` relocates this file;
|
|
60
|
+
`HINDSIGHT_DIAG_FILE`/`HINDSIGHT_LOG_FILE`/`HINDSIGHT_LOG_LEVEL` for diagnostics).
|
|
61
|
+
Layering, later wins: defaults β file β `harnesses.<name>` β `banks.<resolvedBankId>`.
|
|
62
|
+
|
|
63
|
+
```jsonc
|
|
64
|
+
{
|
|
65
|
+
"apiUrl": "http://localhost:8888", // your Hindsight server
|
|
66
|
+
"apiToken": "β¦", // Hindsight Cloud only
|
|
67
|
+
"gitIngest": "message", // "message" | "full" (per-commit diffs) | "none"
|
|
68
|
+
"harnesses": { "claude-code": { "disabled": true } }, // per-agent override of anything
|
|
69
|
+
"mapPathToBank": { "/Users/me/work/client-x": "client-x-memory" }, // path-prefix β bank
|
|
70
|
+
"banks": {
|
|
71
|
+
// per-repo control, keyed by RESOLVED bank id
|
|
72
|
+
"coding-agent::secret": { "disabled": true }, // blacklist a repo
|
|
73
|
+
"coding-agent::old": { "bank": "team::shared" }, // rename / converge banks (single hop)
|
|
74
|
+
"coding-agent::mono": { "gitIngest": "full", "retainSessions": false },
|
|
75
|
+
},
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Key behavioral fields (any of them valid per-harness or per-bank): `disabled`,
|
|
80
|
+
`retainSessions` (write-back opt-out), `gitIngest`, `reflectTimeoutMs` (default 120000; hooks cap
|
|
81
|
+
at 25s), `autoReflect` (true; false = no injected first-prompt synthesis β the agent is instead
|
|
82
|
+
told to call `hindsight_reflect` on new goals), `pageRefreshEveryTurns` (10), `autoSeed`/`seedLimit` (true/300),
|
|
83
|
+
`codebaseSurvey`/`surveyModel`/`surveyBudgetUsd` (true/haiku/2), `surveyRefreshCommits` (0=off),
|
|
84
|
+
`logLevel` ("info").
|
|
85
|
+
|
|
86
|
+
Blacklist a whole directory tree: map it to one bank and disable that bank β
|
|
87
|
+
`"mapPathToBank": {"~/scratch": "scratch"}` + `"banks": {"scratch": {"disabled": true}}`.
|
|
88
|
+
|
|
89
|
+
Bank resolution order: `mapPathToBank` longest prefix β static `bankId` β template
|
|
90
|
+
(default `coding-agent::{gitProject}`) β the matching `banks.<id>` section (its `bank` field
|
|
91
|
+
renames the destination). Two repos share memory by converging their `banks.<id>.bank` on one
|
|
92
|
+
name, or by one `mapPathToBank` prefix over their parent directory.
|
|
93
|
+
|
|
94
|
+
## Install / update (for setting up another machine or harness)
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
npm install -g hindsight-coding-agents && hindsight-coding-agents install # detects all agents
|
|
98
|
+
hindsight-coding-agents install codex # or specific: opencode|claude-code|codex|antigravity-cli|cursor-cli
|
|
99
|
+
hindsight-coding-agents uninstall # removes exactly what install added
|
|
100
|
+
npm update -g hindsight-coding-agents # update; wired paths stay valid
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Debugging
|
|
104
|
+
|
|
105
|
+
- **Readiness**: `hindsight_sync_status` β `synced: true` = seeded memory queryable; also shows
|
|
106
|
+
gitlog freshness, per-commit deepening progress, survey state (`surveyDocs` 0β4 = findings
|
|
107
|
+
present; baseline without findings retries automatically), and active extraction ops.
|
|
108
|
+
- **Logs**: `$TMPDIR/hindsight-coding-agent/plugin.log` (leveled; set `"logLevel": "debug"` or
|
|
109
|
+
`HINDSIGHT_LOG_LEVEL=debug` to mirror every event) and `/tmp/hindsight-plugin.log` (structured
|
|
110
|
+
JSONL diag events with timings: `session_start`, `reflect_ok`, `deepen_done`, `retain_ok`, β¦).
|
|
111
|
+
- **Reset a repo's memory**: delete its bank on the server β the bank is the ONLY state; the next
|
|
112
|
+
session is a true first-open. No client files to clean.
|
|
113
|
+
- **Rule of thumb**: memory silently missing β check the diag log for whether `session_start`/
|
|
114
|
+
`deepen_started` ever fired for that bank; a session started before the plugin was installed has
|
|
115
|
+
no SessionStart behind it (its first prompt after install self-heals).
|
|
116
|
+
- **Internal marker docs you may notice** (safe to ignore, safe to delete): `survey-baseline:<sha>`
|
|
117
|
+
β "π°οΈ researchingβ¦" while a codebase survey runs, flipped to "β
completed" once its findings
|
|
118
|
+
land. Retained under the `survey` strategy, whose marker rule extracts NOTHING from status markers;
|
|
119
|
+
powers the re-survey cadence and `surveyBaseline` in sync status. `gitlog:<repo>` is the
|
|
120
|
+
aggregated commit-message seed document.
|
|
121
|
+
- Failures never break the agent: reflect/pages/retain failures degrade to a normal memoryless
|
|
122
|
+
turn and are recorded in the logs.
|