Hindsight Coding-Agent Memory
This machine runs the hindsight-coding-agents plugin: long-term project memory for coding
sessions, backed by a Hindsight server. You (the agent) are already wired into it — this skill
explains what happens automatically, which tools you have, and how to configure or debug it.
What happens automatically (no action needed)
- Per-repo memory bank: each repository resolves to a bank (shown in the session banner:
↳ memory bank “coding-agent::<repo>”). Worktrees share the main repo's bank.
- Ingestion builds itself: on first open, the bank is seeded from recent commit messages and a
read-only codebase survey; every session start, a background engine tops it up (new commits, new
conversations) and keeps 5 knowledge pages current. There is NO ingest command to run.
- Session synthesis: by default, the first prompt of a session triggers one deep memory
synthesis (
reflect) injected into context. With autoReflect=false, the agent searches the
knowledge pages first and reflects only when they are too shallow.
- Write-back: the session transcript is retained into the bank automatically at session end
(per-turn on opencode). The user never needs to "save" a conversation.
Storing things deliberately
When the user says "store this in hindsight" / "remember this":
- The current conversation is captured automatically at session end — say so; no tool needed.
- An external document, notes, or durable findings →
hindsight_ingest_document(title, content).
- A new feature/initiative being started →
hindsight_capture_initiative(title, summary),
right after the plan is agreed and before code is written.
- A plan that materially changed (goal, scope, or rationale — including mid-implementation) →
call
hindsight_capture_initiative again with relates_to_page_id set to that initiative's page
id, summarising the current intent. Same page, updated plan — never a second page. Trivial
course-corrections don't count.
Retrieving
hindsight_search_knowledge_pages(query) — FIRST STOP for project questions (components,
conventions, past decisions, initiatives). Server-side hybrid search, fast.
hindsight_read_knowledge_page(page_id) / hindsight_list_knowledge_pages — read pages fully.
hindsight_reflect(query) — deep reasoning over the whole memory for WHY questions and exact
decided values; slower (seconds), use deliberately.
- Credit visibly whenever memory informs an answer: start that part with
🧠 From Hindsight memory (<page>): … — and never credit memory that didn't contribute.
Correcting wrong or stale memory
If you verify that something Hindsight served is wrong or outdated (the code, git, or an external
source contradicts it), FIX THE RECORD — don't just ignore it. Call
hindsight_ingest_document with:
- title:
Correction: <topic> (e.g. Correction: retry policy 4xx set)
- content: (1) what memory claimed, (2) what is verifiably true now, (3) the evidence you
checked (file/commit/output). Quote exact values verbatim.
Newer facts supersede older ones in retrieval, so one clear correction permanently outranks the
stale memory. Do this whenever you catch a wrong injected memory, a stale knowledge-page claim, or
an outdated decision — silent disregard leaves the trap armed for the next session.
Install / update
npx @vectorize-io/hindsight-coding-agents install all # every detected agent, wired natively
npx @vectorize-io/hindsight-coding-agents install claude-code # or just one
npx @vectorize-io/hindsight-coding-agents uninstall all # removes exactly what install added
npx @vectorize-io/hindsight-coding-agents update # refresh the runtime only, no rewiring
install takes an explicit target — all, or one or more harness names. A bare
npx @vectorize-io/hindsight-coding-agents install changes nothing and prints the choice, so wiring every agent on
the machine is never something that happens by accident. Updating is the same install
command again — it re-copies the runtime in place.
Day to day you should not have to: once a day, a session start checks npm and re-stages a newer
runtime in the background (autoUpdate, on by default — set it to false to pin the version you
have). That is the update command above, which refreshes the copy every wired agent already
points at and deliberately touches no host config; re-run install yourself after a release that
adds a new hook, or to wire another agent.
Local daemon settings (daemon mode)
Daemon settings keep the names the old per-agent Claude Code plugin used, so an existing
environment carries over unchanged:
| field |
env |
default |
meaning |
serverMode |
HINDSIGHT_SERVER_MODE |
cloud |
cloud | self-hosted | daemon |
apiPort |
HINDSIGHT_API_PORT |
9077 |
port the local daemon listens on |
daemonIdleTimeout |
HINDSIGHT_DAEMON_IDLE_TIMEOUT |
— |
deprecated, ignored: the daemon no longer exits on its own |
daemonProfile |
HINDSIGHT_DAEMON_PROFILE |
coding-agent |
which local database it uses |
embedVersion |
HINDSIGHT_EMBED_VERSION |
latest |
which hindsight-embed release to run |
embedPackagePath |
HINDSIGHT_EMBED_PACKAGE_PATH |
— |
run a local checkout instead (development) |
Any HINDSIGHT_API_* variable you export is forwarded to the daemon, so server-side settings need
no equivalent here.
Configuration
Configuration is one JSON file: ~/.hindsight/coding-agent.json. Layering, later wins per field:
- built-in defaults
- environment variables —
HINDSIGHT_API_URL, HINDSIGHT_API_TOKEN, and one per scalar setting
(HINDSIGHT_<FIELD_IN_CAPS>), for containers and CI that inject config rather than write a file
- the file's top level
- its
harnesses.<name> section — per-agent override
- its
banks.<resolvedBankId> section — per-repo override, applied after the bank is resolved
(see Per-repo opt-in/out)
Environment variables are a fallback: the file wins wherever it sets a value, so adding env to
an existing setup changes nothing. The two list-valued settings, retainTags and optInPaths, take
a comma-separated value (HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work"); entries are
trimmed and blanks dropped.
The map-valued settings (mapPathToBank, harnesses, banks, retainMetadata) are file-only —
per-key branching doesn't survive flattening into one variable. maxParallelRetains is available
as HINDSIGHT_MAX_PARALLEL_RETAINS for containers and CI.
HINDSIGHT_CONFIG moves the file itself — point it at another path for a container or a test
harness where $HOME is not the right anchor. It is still exactly one file; only its location
changes. (The other variables that are not settings are HINDSIGHT_LOG_FILE, HINDSIGHT_DIAG_FILE
and HINDSIGHT_LOG_LEVEL — see Diagnostics & logging.)
When a change takes effect
Config is read when a process starts — the file is not watched — so when an edit applies depends on
what reads it:
| host |
reads the file |
an edit applies |
| hook harnesses (Claude Code, Codex CLI, Cursor CLI, GitHub Copilot CLI, Grok Build, Antigravity CLI, Devin) |
once per hook invocation — each hook is its own short-lived process |
on your next prompt |
| persistent plugins (opencode, opencode 2, Kilo CLI, Cline CLI, pi, Prime Agent, DeepSeek Harness) |
once per workspace, when the host loads the plugin |
after restarting the agent |
the MCP server behind the hindsight_* tools |
once at startup |
in your next session |
apiToken is the exception. Every host re-reads it when the server rejects a request, so enabling
authentication or rotating the key is picked up on the next call with nothing to restart —
otherwise a rotation would leave a long-running agent failing every memory call until it was
restarted. Everything else follows the table: apiUrl, disabled, bank routing, gitIngest, and
the survey and knowledge-page settings.
hindsight_diagnose reports both sides of that gap — what the file says now, and what the running
client is actually using.
Opt-in only
By default every project gets memory — that is what makes the plugin zero-setup. If you would
rather nothing be remembered until you say so, turn memory off everywhere and name the projects
that may use it:
{
"optInOnly": true,
"optInPaths": ["~/work/client-x", "~/oss"],
}
Anything outside those paths is inert: no bank is created, nothing is retained, no seed runs,
and the agent behaves exactly as it would without the plugin. Approving costs nothing else —
optInPaths says which projects, not which bank, so an approved repo keeps its usual
coding-agent::{gitProject} name. Paths are prefixes, so approving ~/work approves every repo
under it while each still gets its own bank.
A mapPathToBank entry counts as opted in too, since routing a path to a named bank already
declares that project. A bare bankId does not: it names a bank rather than a project, so it
cannot say which work may be remembered, and a privacy switch has to fail closed.
There is no per-repo opt-in file, for the same reason there is no repo-carried config at all: a
cloned repository must not be able to turn memory on.
There is deliberately no repo-carried config file — per-repo bank routing is mapPathToBank,
per-agent differences are harnesses.<name>.
Each entry point knows which harness it is (the opencode plugin is loaded by opencode, the codex
hook by Codex...), so one shared config serves several agents side by side:
{
"apiUrl": "https://api.hindsight.vectorize.io",
"harnesses": {
"opencode": { "reflectTimeoutMs": 60000 },
"claude-code": { "disabled": true }, // e.g. memory off for Claude only
},
}
Reference
| field |
default |
meaning |
apiUrl |
https://api.hindsight.vectorize.io |
Hindsight API base URL (set to http://localhost:8888 for a local server) |
apiToken |
— |
bearer token (Hindsight Cloud). Picked up without restarting the agent: a long-lived host re-reads it after a rejected request, so enabling auth or rotating the key mid-session recovers on the next call |
bankId |
— |
explicit static bank; unset ⇒ per-repo dynamic resolution (below) |
dynamicBankId |
dynamic iff no bankId |
force dynamic (true) or static (false) resolution |
bankIdTemplate |
"coding-agent::{gitProject}" |
dynamic bank id format; the default makes every agent share one bank per repo |
mapPathToBank |
— |
absolute path → bank; longest prefix wins; linked worktrees inherit their main checkout's mapping; overrides everything |
optInOnly |
false |
run memory ONLY in opted-in projects — everything else is inert, with no bank created; see Opt-in only |
optInPaths |
— |
directories opted in, matched as prefixes with ~ expanded; each repo beneath and its linked worktrees are approved while keeping their own dynamic bank |
resolveWorktrees |
true |
linked worktrees inherit the main checkout's bank identity, path approval, and mapping |
retainTags |
— |
extra tags on every document written by the integration, e.g. ["project:{gitProject}"] — see Recording where a memory came from below |
retainMetadata |
— |
extra metadata on every document written by the integration, e.g. {"repo": "{gitProject}"} |
manageBankConfig |
true |
let the plugin shape the bank's own configuration — the retain strategies it writes under, the knowledge entity-label group, and, on a bank that has none, the missions. Writing is strictly additive: it adds what the bank does not define and never overwrites what is there, so your control-plane edits survive. Set false to keep it out of the bank config entirely — see A bank you shape yourself below |
observationScopes |
"shared" |
how consolidation groups observations: "shared" (default) = ONE global scope per bank, so every agent on a repo builds one set of beliefs; also "combined" (the server default), "per_tag", "all_combinations", [["t"]]; "per_source" adds a scope per source: kind alongside the global one, so commit knowledge and conversation knowledge consolidate apart |
disabled |
false |
hard off-switch (inert plugin/hook — a no-memory baseline) |
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) |
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 |
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 |
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 |
pageRefreshEveryTurns |
10 |
refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
pageTriggerType |
"cron" |
when NEW knowledge pages refresh, i.e. what keeping them current costs — "cron" (default) on pageTriggerCron only and only when actually stale, "auto-refresh" after every consolidation that produced new material, "manual" never on their own. Auto-refresh is the most current and by far the most expensive: one synthesis per page per consolidation. Maps to the page's trigger.refresh_cron, or trigger.refresh_after_consolidation in the Hindsight API (true for auto-refresh, false for manual) |
pageTriggerCron |
"H * * * *" |
schedule for pageTriggerType: "cron" — UTC, standard 5-field cron, e.g. "0 3 * * *". The default is hourly, each page on its own hashed minute. 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. Write a field as H to give each page its own value there — see Spreading refreshes with H below |
autoSeed |
true |
SessionStart: auto-seed a cold repo's bank from git history |
seedLimit |
300 |
auto-seed: most-recent-N-commits cap |
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 |
surveyModel |
haiku |
model for the survey — Claude recipe only (claude -p --model); other agents use their configured default |
surveyBudgetUsd |
2 |
survey spend cap — Claude recipe only (claude -p --max-budget-usd); other agents rely on their read-only sandbox |
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) |
retainSessions |
true |
session write-back, honored by every harness: hook harnesses write the transcript on Stop, Factory Droid also writes on its cancellation notification, and plugin harnesses (opencode, opencode 2, 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 |
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 |
logLevel |
"info" |
plugin-log verbosity ("debug" | "info" | "warn" | "error"); HINDSIGHT_LOG_LEVEL env overrides |
autoUpdate |
true |
keep the installed runtime current by itself: once a day a session start asks npm for the published version and, when it is newer, re-stages ~/.hindsight/coding-agents in the background. It rewires no host config, so a release adding a new hook entry point still needs a manual install. Set false to pin the installed version; disabled stops it too, since an inert plugin should stay inert. Only ever replaces a runtime installed the documented way, via npx — a copy installed with npm i -g, vendored as a project dependency, or built from a checkout is left to whoever manages it (update those the way you installed them), and it needs npx on PATH |
gitIngest |
"message" |
git depth for seeding AND staying current (same engine): "message" = commit messages only (one doc, re-upserted when HEAD moves); "full" = messages + per-commit full diffs (progressive, newest first); "none" = git off |
harnesses.<name> |
— |
per-harness override of any field above |
harness |
opencode |
deepen engine only: which session format --conversations is read as |
By default a page refreshes hourly, staggered: pageTriggerCron is "H * * * *", so every
page gets its own minute of the hour (see below) and a tick with nothing new to fold in is skipped
server-side. That keeps pages within an hour of the repo without paying auto-refresh's price — one
LLM synthesis per page per consolidation, on a repo that consolidates all day. Set
pageTriggerType: "auto-refresh" to go back to refreshing on every consolidation.
pageTriggerType/pageTriggerCron decide only when a page refreshes. How it refreshes
belongs to the server: Hindsight creates a knowledge page with a delta refresh (each pass edits the
page instead of rebuilding it) that doesn't reflect over sibling pages, and these settings merge
over those defaults rather than replacing them.
Spreading refreshes with H
One pageTriggerCron is shared by every page in every repo you point this plugin at. So a literal
"0 3 * * *" does not schedule a refresh at 03:00 — it schedules all of them at 03:00, five
pages per bank, on the same worker pool that serves retain. A session ingesting at 03:0x queues
behind the pile, and moving the hour just moves the pile.
Write a field as H and it is replaced, per page, by a value hashed from the bank id and the page
name. Each page gets its own slot, the same slot on every run:
pageTriggerCron |
what each page gets |
"H H * * *" |
once a day, at its own minute and hour |
"H * * * *" |
once an hour, at its own minute |
"H 3 * * *" |
daily at 03:MM — spread inside the hour you chose |
"H H(0-5) * * *" |
daily, spread across 00:00–05:59 only |
"0 3 * * *" |
no H, no hashing — exactly what it says, all at once |
H is Jenkins' syntax for the same
problem. It never reaches the API: the plugin resolves it to an ordinary cron expression
("41 17 * * *") when it creates the page, so the schedule you see in the control plane is a plain
one you can edit. Hashing spreads pages out, it does not partition them — two pages can still land
on the same minute, just not all of them.
**These settings apply t
…(truncated)
1---
2name: hindsight-coding-agent
3description: 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.
4metadata:
5 source: https://skillmd.com/skills/vectorize-io/hindsight-coding-agent
6---
7
8<!-- GENERATED from README.md (its skill:begin regions) + skill-src/preamble.md.
9 Edit those, then run: npm run skill:build -->
10
11# Hindsight Coding-Agent Memory
12
13This machine runs the `hindsight-coding-agents` plugin: long-term project memory for coding
14sessions, backed by a Hindsight server. You (the agent) are already wired into it — this skill
15explains what happens automatically, which tools you have, and how to configure or debug it.
16
17## What happens automatically (no action needed)
18
19- **Per-repo memory bank**: each repository resolves to a bank (shown in the session banner:
20 `↳ memory bank “coding-agent::<repo>”`). Worktrees share the main repo's bank.
21- **Ingestion builds itself**: on first open, the bank is seeded from recent commit messages and a
22 read-only codebase survey; every session start, a background engine tops it up (new commits, new
23 conversations) and keeps 5 knowledge pages current. There is NO ingest command to run.
24- **Session synthesis**: by default, the first prompt of a session triggers one deep memory
25 synthesis (`reflect`) injected into context. With `autoReflect=false`, the agent searches the
26 knowledge pages first and reflects only when they are too shallow.
27- **Write-back**: the session transcript is retained into the bank automatically at session end
28 (per-turn on opencode). The user never needs to "save" a conversation.
29
30## Storing things deliberately
31
32When the user says "store this in hindsight" / "remember this":
33
34- The **current conversation** is captured automatically at session end — say so; no tool needed.
35- An **external document, notes, or durable findings** → `hindsight_ingest_document(title, content)`.
36- A **new feature/initiative being started** → `hindsight_capture_initiative(title, summary)`,
37 right after the plan is agreed and before code is written.
38- A **plan that materially changed** (goal, scope, or rationale — including mid-implementation) →
39 call `hindsight_capture_initiative` again with `relates_to_page_id` set to that initiative's page
40 id, summarising the _current_ intent. Same page, updated plan — never a second page. Trivial
41 course-corrections don't count.
42
43## Retrieving
44
45- `hindsight_search_knowledge_pages(query)` — FIRST STOP for project questions (components,
46 conventions, past decisions, initiatives). Server-side hybrid search, fast.
47- `hindsight_read_knowledge_page(page_id)` / `hindsight_list_knowledge_pages` — read pages fully.
48- `hindsight_reflect(query)` — deep reasoning over the whole memory for WHY questions and exact
49 decided values; slower (seconds), use deliberately.
50- Credit visibly whenever memory informs an answer: start that part with
51 `🧠 From Hindsight memory (<page>): …` — and never credit memory that didn't contribute.
52
53## Correcting wrong or stale memory
54
55If you verify that something Hindsight served is wrong or outdated (the code, git, or an external
56source contradicts it), FIX THE RECORD — don't just ignore it. Call
57`hindsight_ingest_document` with:
58
59- **title**: `Correction: <topic>` (e.g. `Correction: retry policy 4xx set`)
60- **content**: (1) what memory claimed, (2) what is verifiably true now, (3) the evidence you
61 checked (file/commit/output). Quote exact values verbatim.
62
63Newer facts supersede older ones in retrieval, so one clear correction permanently outranks the
64stale memory. Do this whenever you catch a wrong injected memory, a stale knowledge-page claim, or
65an outdated decision — silent disregard leaves the trap armed for the next session.
66
67## Install / update
68
69```bash
70npx @vectorize-io/hindsight-coding-agents install all # every detected agent, wired natively
71npx @vectorize-io/hindsight-coding-agents install claude-code # or just one
72npx @vectorize-io/hindsight-coding-agents uninstall all # removes exactly what install added
73npx @vectorize-io/hindsight-coding-agents update # refresh the runtime only, no rewiring
74```
75
76`install` takes an explicit target — `all`, or one or more harness names. A bare
77`npx @vectorize-io/hindsight-coding-agents install` changes nothing and prints the choice, so wiring every agent on
78the machine is never something that happens by accident. **Updating is the same `install`
79command again** — it re-copies the runtime in place.
80
81Day to day you should not have to: once a day, a session start checks npm and re-stages a newer
82runtime in the background (`autoUpdate`, on by default — set it to `false` to pin the version you
83have). That is the `update` command above, which refreshes the copy every wired agent already
84points at and deliberately touches no host config; re-run `install` yourself after a release that
85adds a new hook, or to wire another agent.
86
87## Local daemon settings (daemon mode)
88
89Daemon settings keep the names the old per-agent Claude Code plugin used, so an existing
90environment carries over unchanged:
91
92| field | env | default | meaning |
93| ------------------- | ------------------------------- | -------------- | ---------------------------------------------------------- |
94| `serverMode` | `HINDSIGHT_SERVER_MODE` | `cloud` | `cloud` \| `self-hosted` \| `daemon` |
95| `apiPort` | `HINDSIGHT_API_PORT` | `9077` | port the local daemon listens on |
96| `daemonIdleTimeout` | `HINDSIGHT_DAEMON_IDLE_TIMEOUT` | — | deprecated, ignored: the daemon no longer exits on its own |
97| `daemonProfile` | `HINDSIGHT_DAEMON_PROFILE` | `coding-agent` | which local database it uses |
98| `embedVersion` | `HINDSIGHT_EMBED_VERSION` | `latest` | which `hindsight-embed` release to run |
99| `embedPackagePath` | `HINDSIGHT_EMBED_PACKAGE_PATH` | — | run a local checkout instead (development) |
100
101Any `HINDSIGHT_API_*` variable you export is forwarded to the daemon, so server-side settings need
102no equivalent here.
103
104## Configuration
105
106Configuration is **one JSON file**: `~/.hindsight/coding-agent.json`. Layering, later wins per field:
107
1081. built-in defaults
1092. environment variables — `HINDSIGHT_API_URL`, `HINDSIGHT_API_TOKEN`, and one per scalar setting
110 (`HINDSIGHT_<FIELD_IN_CAPS>`), for containers and CI that inject config rather than write a file
1113. the file's top level
1124. its `harnesses.<name>` section — per-agent override
1135. its `banks.<resolvedBankId>` section — per-repo override, applied after the bank is resolved
114 (see [Per-repo opt-in/out](#per-repo-opt-inout--banksbankid))
115
116Environment variables are a **fallback**: the file wins wherever it sets a value, so adding env to
117an existing setup changes nothing. The two list-valued settings, `retainTags` and `optInPaths`, take
118a comma-separated value (`HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work"`); entries are
119trimmed and blanks dropped.
120The map-valued settings (`mapPathToBank`, `harnesses`, `banks`, `retainMetadata`) are file-only —
121per-key branching doesn't survive flattening into one variable. `maxParallelRetains` is available
122as `HINDSIGHT_MAX_PARALLEL_RETAINS` for containers and CI.
123
124`HINDSIGHT_CONFIG` moves the file itself — point it at another path for a container or a test
125harness where `$HOME` is not the right anchor. It is still exactly one file; only its location
126changes. (The other variables that are not settings are `HINDSIGHT_LOG_FILE`, `HINDSIGHT_DIAG_FILE`
127and `HINDSIGHT_LOG_LEVEL` — see [Diagnostics & logging](#diagnostics--logging).)
128
129### When a change takes effect
130
131Config is read when a process starts — the file is not watched — so when an edit applies depends on
132what reads it:
133
134| host | reads the file | an edit applies |
135| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------- |
136| hook harnesses (Claude Code, Codex CLI, Cursor CLI, GitHub Copilot CLI, Grok Build, Antigravity CLI, Devin) | once per hook invocation — each hook is its own short-lived process | on your next prompt |
137| persistent plugins (opencode, opencode 2, Kilo CLI, Cline CLI, pi, Prime Agent, DeepSeek Harness) | once per workspace, when the host loads the plugin | after restarting the agent |
138| the MCP server behind the `hindsight_*` tools | once at startup | in your next session |
139
140`apiToken` is the exception. Every host re-reads it when the server rejects a request, so enabling
141authentication or rotating the key is picked up on the next call with nothing to restart —
142otherwise a rotation would leave a long-running agent failing every memory call until it was
143restarted. Everything else follows the table: `apiUrl`, `disabled`, bank routing, `gitIngest`, and
144the survey and knowledge-page settings.
145
146`hindsight_diagnose` reports both sides of that gap — what the file says now, and what the running
147client is actually using.
148
149### Opt-in only
150
151By default every project gets memory — that is what makes the plugin zero-setup. If you would
152rather nothing be remembered until you say so, turn memory off everywhere and name the projects
153that may use it:
154
155```jsonc
156{
157 "optInOnly": true,
158 "optInPaths": ["~/work/client-x", "~/oss"],
159}
160```
161
162Anything outside those paths is **inert**: no bank is created, nothing is retained, no seed runs,
163and the agent behaves exactly as it would without the plugin. Approving costs nothing else —
164`optInPaths` says _which projects_, not _which bank_, so an approved repo keeps its usual
165`coding-agent::{gitProject}` name. Paths are prefixes, so approving `~/work` approves every repo
166under it while each still gets its own bank.
167
168A `mapPathToBank` entry counts as opted in too, since routing a path to a named bank already
169declares that project. A bare `bankId` does not: it names a bank rather than a project, so it
170cannot say which work may be remembered, and a privacy switch has to fail closed.
171
172There is no per-repo opt-in file, for the same reason there is no repo-carried config at all: a
173cloned repository must not be able to turn memory on.
174
175There is deliberately no repo-carried config file — per-repo bank routing is `mapPathToBank`,
176per-agent differences are `harnesses.<name>`.
177
178Each entry point knows which harness it _is_ (the opencode plugin is loaded by opencode, the codex
179hook by Codex...), so one shared config serves several agents side by side:
180
181```jsonc
182{
183 "apiUrl": "https://api.hindsight.vectorize.io",
184 "harnesses": {
185 "opencode": { "reflectTimeoutMs": 60000 },
186 "claude-code": { "disabled": true }, // e.g. memory off for Claude only
187 },
188}
189```
190
191### Reference
192
193| field | default | meaning |
194| ----------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
195| `apiUrl` | `https://api.hindsight.vectorize.io` | Hindsight API base URL (set to `http://localhost:8888` for a local server) |
196| `apiToken` | — | bearer token (Hindsight Cloud). Picked up without restarting the agent: a long-lived host re-reads it after a rejected request, so enabling auth or rotating the key mid-session recovers on the next call |
197| `bankId` | — | **explicit static bank**; unset ⇒ per-repo dynamic resolution (below) |
198| `dynamicBankId` | dynamic iff no `bankId` | force dynamic (`true`) or static (`false`) resolution |
199| `bankIdTemplate` | `"coding-agent::{gitProject}"` | dynamic bank id format; the default makes every agent share one bank per repo |
200| `mapPathToBank` | — | absolute path → bank; **longest prefix wins**; linked worktrees inherit their main checkout's mapping; overrides everything |
201| `optInOnly` | `false` | run memory ONLY in opted-in projects — everything else is inert, with no bank created; see [Opt-in only](#opt-in-only) |
202| `optInPaths` | — | directories opted in, matched as prefixes with `~` expanded; each repo beneath and its linked worktrees are approved while keeping their own dynamic bank |
203| `resolveWorktrees` | `true` | linked worktrees inherit the main checkout's bank identity, path approval, and mapping |
204| `retainTags` | — | extra tags on every document written by the integration, e.g. `["project:{gitProject}"]` — see **Recording where a memory came from** below |
205| `retainMetadata` | — | extra metadata on every document written by the integration, e.g. `{"repo": "{gitProject}"}` |
206| `manageBankConfig` | `true` | let the plugin shape the bank's own configuration — the retain strategies it writes under, the `knowledge` entity-label group, and, on a bank that has none, the missions. Writing is strictly **additive**: it adds what the bank does not define and never overwrites what is there, so your control-plane edits survive. Set `false` to keep it out of the bank config entirely — see **A bank you shape yourself** below |
207| `observationScopes` | `"shared"` | how consolidation groups observations: `"shared"` (default) = ONE global scope per bank, so every agent on a repo builds one set of beliefs; also `"combined"` (the server default), `"per_tag"`, `"all_combinations"`, `[["t"]]`; `"per_source"` adds a scope per `source:` kind alongside the global one, so commit knowledge and conversation knowledge consolidate apart |
208| `disabled` | `false` | hard off-switch (inert plugin/hook — a no-memory baseline) |
209| `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) |
210| `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 |
211| `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 |
212| `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 |
213| `pageRefreshEveryTurns` | `10` | refetch the knowledge pages and re-inject the page roster + tool guide every N user turns |
214| `pageTriggerType` | `"cron"` | when NEW knowledge pages refresh, i.e. what keeping them current costs — `"cron"` (default) on `pageTriggerCron` only and only when actually stale, `"auto-refresh"` after every consolidation that produced new material, `"manual"` never on their own. Auto-refresh is the most current and by far the most expensive: one synthesis per page per consolidation. Maps to the page's `trigger.refresh_cron`, or `trigger.refresh_after_consolidation` in the Hindsight API (`true` for auto-refresh, `false` for manual) |
215| `pageTriggerCron` | `"H * * * *"` | schedule for `pageTriggerType: "cron"` — UTC, standard 5-field cron, e.g. `"0 3 * * *"`. The default is hourly, each page on its own hashed minute. 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. Write a field as `H` to give each page its own value there — see **Spreading refreshes with `H`** below |
216| `autoSeed` | `true` | SessionStart: auto-seed a cold repo's bank from git history |
217| `seedLimit` | `300` | auto-seed: most-recent-N-commits cap |
218| `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 |
219| `surveyModel` | `haiku` | model for the survey — Claude recipe only (`claude -p --model`); other agents use their configured default |
220| `surveyBudgetUsd` | `2` | survey spend cap — Claude recipe only (`claude -p --max-budget-usd`); other agents rely on their read-only sandbox |
221| `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) |
222| `retainSessions` | `true` | session write-back, honored by every harness: hook harnesses write the transcript on Stop, Factory Droid also writes on its cancellation notification, and plugin harnesses (opencode, opencode 2, 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 |
223| `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 |
224| `logLevel` | `"info"` | plugin-log verbosity (`"debug"` \| `"info"` \| `"warn"` \| `"error"`); `HINDSIGHT_LOG_LEVEL` env overrides |
225| `autoUpdate` | `true` | keep the installed runtime current by itself: once a day a session start asks npm for the published version and, when it is newer, re-stages `~/.hindsight/coding-agents` in the background. It rewires no host config, so a release adding a **new** hook entry point still needs a manual `install`. Set `false` to pin the installed version; `disabled` stops it too, since an inert plugin should stay inert. Only ever replaces a runtime installed the documented way, via `npx` — a copy installed with `npm i -g`, vendored as a project dependency, or built from a checkout is left to whoever manages it (update those the way you installed them), and it needs `npx` on `PATH` |
226| `gitIngest` | `"message"` | git depth for seeding AND staying current (same engine): `"message"` = commit messages only (one doc, re-upserted when HEAD moves); `"full"` = messages + per-commit full diffs (progressive, newest first); `"none"` = git off |
227| `harnesses.<name>` | — | per-harness override of any field above |
228| `harness` | `opencode` | **deepen engine only**: which session format `--conversations` is read as |
229
230By default a page refreshes **hourly, staggered**: `pageTriggerCron` is `"H * * * *"`, so every
231page gets its own minute of the hour (see below) and a tick with nothing new to fold in is skipped
232server-side. That keeps pages within an hour of the repo without paying auto-refresh's price — one
233LLM synthesis per page per consolidation, on a repo that consolidates all day. Set
234`pageTriggerType: "auto-refresh"` to go back to refreshing on every consolidation.
235
236`pageTriggerType`/`pageTriggerCron` decide only **when** a page refreshes. **How** it refreshes
237belongs to the server: Hindsight creates a knowledge page with a delta refresh (each pass edits the
238page instead of rebuilding it) that doesn't reflect over sibling pages, and these settings merge
239over those defaults rather than replacing them.
240
241### Spreading refreshes with `H`
242
243One `pageTriggerCron` is shared by every page in every repo you point this plugin at. So a literal
244`"0 3 * * *"` does not schedule _a_ refresh at 03:00 — it schedules **all** of them at 03:00, five
245pages per bank, on the same worker pool that serves retain. A session ingesting at 03:0x queues
246behind the pile, and moving the hour just moves the pile.
247
248Write a field as `H` and it is replaced, per page, by a value hashed from the bank id and the page
249name. Each page gets its own slot, the same slot on every run:
250
251| `pageTriggerCron` | what each page gets |
252| ------------------ | ------------------------------------------------------ |
253| `"H H * * *"` | once a day, at its own minute and hour |
254| `"H * * * *"` | once an hour, at its own minute |
255| `"H 3 * * *"` | daily at 03:MM — spread inside the hour you chose |
256| `"H H(0-5) * * *"` | daily, spread across 00:00–05:59 only |
257| `"0 3 * * *"` | no `H`, no hashing — exactly what it says, all at once |
258
259`H` is [Jenkins' syntax](https://www.jenkins.io/doc/book/pipeline/syntax/#cron-syntax) for the same
260problem. It never reaches the API: the plugin resolves it to an ordinary cron expression
261(`"41 17 * * *"`) when it creates the page, so the schedule you see in the control plane is a plain
262one you can edit. Hashing spreads pages out, it does not partition them — two pages can still land
263on the same minute, just not all of them.
264
265**These settings apply to the pages a repo already has, too.** Every session compares each page
266this plugin created — the seeded taxonomy and every captured initiative — against the config and
267re-syncs the ones that differ, so a bank seeded before this default changed moves onto the hourly
268schedule by itself, and a page you retriggered by hand in the control plane is put back on the
269configured policy the next time an agent runs. The config
270file is the source of truth for these pages: to give one a different schedule, change
271`pageTriggerType`/`pageTriggerCron` (per bank, if it is only that repo) rather than editing the
272page. Only the fields this plugin states are touched — a page's `mode`, its excluded siblings and
273its minimum refresh interval are left exactly as they are.
274
275### A bank you shape yourself — `manageBankConfig`
276
277Pointed at a bank, this plugin gives it the shape its ingestion needs: retain strategies for the
278kinds of document it writes (`git`, `gitlog`, `conversation`, `document`, `survey`), a `knowledge`
279entity-label group that routes facts to the knowledge pages, and — on a bank that has no missions of
280its own — the coding missions.
281
282**It only ever adds what is missing.** A strategy you defined, an edit you made to one of the
283plugin's, a reworded label group, a mission you rewrote in the control plane: each is left exactly
284as it is, on every session, forever. What the bank already says wins. The cost of that promise is
285that a plugin release which _rewords_ an existing strategy or label does not reach a bank that
286already has it. To take the current default back, clear that override on the bank (delete the
287strategy, or the whole `retain_strategies` entry, in the control plane): the next session finds the
288bank silent there and seeds it again.
289
290Set `manageBankConfig: false` to keep the plugin out of the bank's configuration altogether — the
291right setting for a bank you share with non-coding work, or one you configure yourself. That bank
292should then define the five strategies above itself. Note that the miss is **silent**: the server
293does not reject a retain naming a strategy the bank lacks, it logs a warning and extracts with the
294bank's own configuration — so a commit diff, a session transcript and a survey marker would all get
295the same generic treatment instead of the extraction each needs. Knowledge pages are seeded either
296way; `pageTriggerType` governs what they cost.
297
298Like every field here it can be set per bank, which is usually where it belongs:
299
300```json
301{
302 "bankId": "my-global-bank",
303 "banks": { "my-global-bank": { "manageBankConfig": false } }
304}
305```
306
307### Per-repo opt-in/out — `banks.<bankId>`
308
309Per-repo control lives in the SAME file, keyed by the **resolved bank id** (shown in the session
310banner) and applied AFTER bank resolution — so it works regardless of where the repo lives, and
311survives directory moves:
312
313```jsonc
314{
315 "banks": {
316 "coding-agent::secret-client": { "disabled": true }, // blacklist: no memory at all
317 "coding-agent::old-name": { "bank": "team::shared" }, // rename / converge banks
318 "coding-agent::big-mono": { "gitIngest": "full", "retainSessions": false },
319 },
320}
321```
322
323Any behavioral field can be overridden per bank, and `bank` **renames the destination** (single
324hop: the section is selected by the resolved id, the target is literal — several ids may converge
325on one shared bank, and the target's own section is not consulted). Other bank-resolution fields
326are ignored inside a bank section.
327
328#### Recipe: two repos, one shared bank
329
330Two ways, by what the natural key is:
331
332**By resolved id** — you know the repo names; works wherever the repos live (and keeps working if
333they move). Both ids converge on one literal target:
334
335```jsonc
336{
337 "banks": {
338 "coding-agent::backend": { "bank": "team::product" },
339 "coding-agent::frontend": { "bank": "team::product" },
340 },
341}
342```
343
344**By path prefix** — the repos live under one directory; a single `mapPathToBank` entry covers
345every repo (present and future) beneath it:
346
347```jsonc
348{
349 "mapPathToBank": { "/Users/me/work/client-x": "client-x-memory" },
350}
351```
352
353Rule of thumb: converge by **id** for a hand-picked set of repos; map by **path** when a folder is
354the boundary ("everything I clone under `work/client-x` shares memory").
355
356### Bank resolution
357
358Coding memory is **per repository**. Resolution order for the working directory:
359
3601. `mapPathToBank` — longest matching absolute-path prefix (mapping a repo root covers every
361 subdirectory; deeper mappings win; overrides even an explicit `bankId`).
3622. Static — `bankId` set (or `dynamicBankId: false`).
3633. Dynamic — `bankIdTemplate` with placeholders:
364 - `{gitProject}` — worktree-aware repo name: `git rev-parse --git-common-dir` resolves every
365 linked worktree to the **main** worktree's basename, so all worktrees of a repo share one bank
366 (bare repos use the bare dir name). **Outside a repo** there is nothing for git to resolve, so
367 it falls back to the basename of the directory the **session started in** — an agent that
368 `cd`s into a subdirectory keeps writing to one bank, and a subdirectory gets its own bank only
369 when you deliberately start a session there
370 - `{project}` — plain working-directory basename
371 - `{harness}` — the entry point asking (`opencode`, `claude-code`, `codex`, `antigravity-cli`, `cursor-cli`, `copilot-cli`)
372 - `{channel}` / `{user}` — `$HINDSIGHT_CHANNEL_ID` / `$HINDSIGHT_USER_ID`
373
374The default `"coding-agent::{gitProject}"` is **harness-neutral**, so opencode, Claude Code, and Codex
375all share one memory per repo — use `"{harness}-{gitProject}"` to split per agent instead.
376
377### Recording where a memory came from
378
379With a bank per repo, the bank _is_ the answer to "where did this come from". On a deliberately
380**shared** bank — one bank holding cross-project knowledge so facts recall everywhere — it isn't:
381every memory looks alike. `retainTags` and `retainMetadata` stamp that provenance onto conversations,
382git history and diffs, survey lifecycle documents, initiative markers, and documents saved through
383`hindsight_ingest_document`:
384
385```jsonc
386{
387 "bankId": "shared", // one bank for everything
388 "retainTags": ["project:{gitProject}", "env:work"],
389 "retainMetadata": { "repo": "{gitProject}" },
390}
391```
392
393Recalls can then filter by `project:<repo>`, and every document shows which repository it came out
394of. Both accept the same placeholders as `bankIdTemplate` — `{gitProject}`, `{project}`,
395`{harness}`, `{channel}`, `{user}` — plus `{bankId}`, `{sessionId}` and `{timestamp}`.
396`{gitProject}` is worktree-aware here too, so every linked worktree of a repo stamps one name.
397`{sessionId}` resolves to `unknown` for documents that do not originate from an agent session.
398
399The plugin's own `source:` and `harness:` tags are reserved: entries in those namespaces are ignored
400with a warning, so a document's agent attribution always reflects the agent that actually wrote it.
401
402### One set of beliefs per repo
403
404Every document this integration writes carries provenance tags — `source:chat`, `harness:<id>`,
405`knowledge:<kind>`, plus anything from `retainTags`. Those tags say **who wrote** a memory; they are
406what filters recall and draws each document's agent logo, and they stay on the facts.
407
408They are not, however, a good boundary for
409[observations](https://hindsight.vectorize.io/developer/observations). Consolidation's own
410default (`combined`) builds one observation set per distinct tag set, so the same repository
411worked on by two agents would grow two parallel sets of beliefs — one per harness — that never
412merge, each blind to the other, at double the consolidation cost. Which agent happened to be typing
413does not change whether a convention or a decision is true.
414
415So the integration retains with `observationScopes: "shared"`: one global, untagged observation
416scope per bank, which is what a bank already is — one project's memory. Set the field to change it:
417
418```jsonc
419{
420 "observationScopes": "combined", // one observation set per distinct tag set (server default)
421 "banks": {
422 "coding-agent::mono": { "observationScopes": "per_tag" }, // per-repo, like any behavioral field
423 },
424}
425```
426
427### Splitting code from conversation — `per_source`
428
429`shared` puts every document a repo produces into one belief set. `"per_source"` keeps that set and
430adds one per origin, so "what the commits say" and "what was decided in conversation" can be asked
431apart:
432
433```jsonc
434{ "observationScopes": "per_source" }
435```
436
437Each document consolidates into the global scope **plus** one named for each `source:` tag it
438carries — `[[], ["source:chat"]]` for a session transcript, `[[], ["source:git"]]` for a commit
439diff. Read an axis back with `tags: ["source:git"], tags_match: "exact"`, and the merged view with
440`tags: [], tags_match: "exact"`.
441
442A document carrying two `source:` tags gets a scope for each, and that is deliberate rather than
443duplication. The commit-message seed is tagged `source:git` and `source:git-log`, so
444`source:git-log` is fed only by the seed — what the commit _messages_ say — while `source:git` also
445collects every per-commit diff under `gitIngest: "full"`. Two questions, two answers, each
446deduplicated within itself by consolidation. A fact belonging to more than one axis is the point.
447
448This cannot be expressed as a scope list. The server treats an explicit `list[list[str]]` as
449unconditional — it is not filtered against the memory's own tags — so a configured
450`[[], ["source:git"], ["source:chat"]]` writes every document into all three, and the `source:git`
451scope fills with beliefs built from chat transcripts. Only a per-document decision separates them.
452
453It costs one extra consolidation pass per document, and it reads only `source:`, so a volatile
454provenance tag never becomes a scope. The global scope is still written first and unchanged, so the
455untagged observations knowledge pages read are unaffected.
456
457`"per_tag"` and `"all_combinations"` split further still, and an explicit `[["project:demo"], …]`
458declares the scopes literally. `HINDSIGHT_OBSERVATION_SCOPES` sets the scalar modes; a scope list is
459file-only. Changing this does not rewrite observations already consolidated under the old scoping —
460they stay where they were built, and new work accrues under the new setting.
461
462## Diagnostics & logging
463
464Two files, two audiences:
465
466**Leveled plugin log** (humans debugging): `$TMPDIR/hindsight-coding-agent/plugin.log` (override
467`HINDSIGHT_LOG_FILE`) — timestamped `LEVEL [scope] message` lines from every component, including
468the ingestion engine. Level defaults to `info`; set `"logLevel": "debug"` in config or
469`HINDSIGHT_LOG_LEVEL=debug` for ad-hoc debugging (at `debug`, every diag event below is mirrored
470here too, so one file tells the whole story).
471
472**Structured diag events** (machines/harnesses): every reflect and page-fetch outcome is appended
473as a JSON line to `/tmp/hindsight-plugin.log` (override with `HINDSIGHT_DIAG_FILE`):
474
475```json
476{
477 "ts": "2026-07-27T07:05:52Z",
478 "harness": "claude-code",
479 "event": "reflect_ok",
480 "ms": 14210,
481 "chars": 792,
482 "query": "..."
483}
484```
485
486`reflect_failed` / `pages_failed` record the error; if you're comparing memory-on vs memory-off,
487check this file — a run whose reflects failed is a no-memory run. Seed starts are logged as
488`seed_started`.
489
490### Is the memory ready yet?
491
492`hindsight_sync_status` — the agent-facing tool, `dist/status.js` for scripts — answers exactly
493that: `"synced": true` means the seeded memory is queryable. It also reports gitlog freshness, how
494far per-commit deepening has got, the codebase survey's state (`surveyBaseline` is the HEAD the last
495survey started from, `surveyDocs` counts the findings documents that have landed, 0–4 — a baseline
496with no findings retries automatically), and the extraction operations still in flight.
497
498### Resetting a repo's memory
499
500Delete its bank on the server. The bank is the **only** state this integration keeps, so the next
501session in that repo is a true first open — seed and survey run again from scratch. There are no
502client-side files to clean up.
503
504### Marker documents you may notice
505
506Two document ids exist for the machinery's own bookkeeping. Both are safe to ignore and safe to
507delete:
508
509- `survey-baseline:<sha>` — reads "🛰️ researching…" while a codebase survey runs and flips to
510 "✅ completed" once its findings land. It is retained under the `survey` strategy, whose marker
511 rule extracts **nothing** from a status marker, and it drives the re-survey cadence
512 (`surveyRefreshCommits`) and `surveyBaseline` in sync status.
513- `gitlog:<repo>` — the aggregated commit-message seed document, re-upserted rather than duplicated
514 when the seed runs again.
515
516### When memory seems to be missing
517
518Failures never break the agent: a reflect, page fetch or retain that fails degrades to an ordinary
519memoryless turn and is recorded in the logs. "No memory" is therefore a log question — check the
520diag file for whether `session_start` and `deepen_started` ever fired for that bank. A session that
521was already running when the plugin was installed has no SessionStart behind it; its first prompt
522after the install self-heals.