@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/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.