--- name: hindsight-coding-agent 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. --- # 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::”`). 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. `autoInject` switches the source: `pages` (knowledge page search hits), `recall` (recalled observations), or `none` (nothing injected; 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 (): …` β€” 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: ` (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 ```bash 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 npx @vectorize-io/hindsight-coding-agents stats # how often each agent uses Hindsight ``` `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: 1. built-in defaults 2. environment variables β€” `HINDSIGHT_API_URL`, `HINDSIGHT_API_TOKEN`, and one per scalar setting (`HINDSIGHT_`), for containers and CI that inject config rather than write a file 3. the file's top level 4. its `harnesses.` section β€” per-agent override 5. its `paths.` section β€” per-directory override, applied after the bank is resolved (see [Per-directory overrides](#per-directory-overrides--pathsprefix)) 6. its `banks.` section β€” per-repo override, applied after the bank is resolved (see [Per-repo opt-in/out](#per-repo-opt-inout--banksbankid)) 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`, `paths`, `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`, `HINDSIGHT_USAGE_FILE` and `HINDSIGHT_LOG_LEVEL` β€” see [Diagnostics & logging](#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: ```jsonc { "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.`. 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: ```jsonc { "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](#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}"}` | | `retainContext` | see description | the `context` sent with every session write-back. Extraction reads it to decide whose claim a sentence is, so the default names both speakers, and asks for an agent's own "fixed" or "passes" to be stored as its claim rather than as fact. Accepts the same `{placeholder}` templates as `retainTags` | | `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 **additive**: it adds what the bank does not define and never overwrites what is there, so your control-plane edits survive β€” the one exception is the extraction mode of its own strategies, which follows `retainExtractionMode`. Set `false` to keep it out of the bank config entirely β€” see **A bank you shape yourself** below | | `retainExtractionMode` | `"concise"` | how the server extracts memories from sessions, commits and documents: `"concise"`, `"verbose"`, `"verbatim"` or `"chunks"` (store the text, no extraction). Every Stop writes the session back, so this is what each turn costs β€” `"verbose"` pulls more detail for several times the tokens. Kept in sync on the plugin's own retain strategies every session, so a change reaches existing banks too (not with `manageBankConfig: false`) | | `defaultBankConfig` | β€” | bank-config fields of your own for the banks the plugin shapes, e.g. `{"enable_observations": false, "enable_auto_consolidation": false, "mental_model_min_refresh_interval_seconds": 21600}`. Keys are the bank-config API's own field names. Written under the same additive rule as the rest: only where the bank does not define the field, so a bank the plugin creates is born with these instead of the server's defaults and a value you set in the control plane is never overwritten. Wins over the template on a key both name (`enable_observations`); `retain_strategies`, `entity_labels` and `retain_extraction_mode` are refused, since the plugin governs them itself. Ignored with `manageBankConfig: false` β€” see **A bank you shape yourself** below. File-only, like `recallOptions`; in a `banks.` section it replaces the global map rather than merging into it | | `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` | `20000` | **automatic** session-reflect timeout; on hook harnesses the installer registers a 30s prompt-hook timeout, so going above ~20s also means raising that hook's `timeout` in the host's config, or the host kills the hook mid-reflect; on timeout or a 5xx the hook falls back to knowledge-page search, then to a raw recall of observations (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 | | `injectTimeoutMs` | `7000` | retrieval timeout in milliseconds for `autoInject: "pages"` and `autoInject: "recall"`; also the **shared** budget for page search then recall after a reflect timeout/5xx (recall gets only the time left after page search). Set e.g. `2000` to limit turn latency or `15000` for a slower self-hosted bank. Environment fallback: `HINDSIGHT_INJECT_TIMEOUT_MS`. On hook harnesses, injection must fit the host's prompt-hook timeout (30s by default); for reflect with fallback, allow for **`reflectTimeoutMs` + `injectTimeoutMs`**, and raise the host hook's `timeout` when needed | | `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 | | `autoInject` | `"reflect"` | what to inject once, on the session's **first prompt**: `"reflect"` = a low-budget reflect synthesis (on timeout/5xx it falls back to page search, then recall); `"pages"` = the knowledge pages matching the prompt by search; `"recall"` = the bank's memories recalled for the prompt (what it asks for is `recallOptions`, observations by default); `"none"` = nothing β€” the agent searches knowledge pages first and reflects only when they are too shallow. `"pages"` and `"recall"` are retrieval only (no LLM), their time budget is `injectTimeoutMs` | | `autoReflect` | `true` | **deprecated** β€” use `autoInject`. Still honoured (`false` = `autoInject: "none"`), ignored when `autoInject` is set, and logs a deprecation warning | | `pageSearchLimit` | `3` | knowledge pages ONE search returns. Applies to every search of the bank β€” the `autoInject: "pages"` injection, the reflect fallback, and the agent's own `hindsight_search_knowledge_pages` tool β€” because the limit lives on the client they all share | | `recallOptions` | see description | overrides merged key-by-key into the body of every recall β€” the `autoInject: "recall"` source and the reflect fallback. Keys are the API's own recall parameters, passed straight through, so anything recall accepts is settable without a new option here; `query` is the one field it cannot replace. The default body is `{"types": ["observation"], "budget": "low", "max_tokens": 2000, "include": {"entities": null}}`, and what you set is merged over it one key at a time β€” `{"max_tokens": 4000}` changes the budget and leaves the rest alone. Observations are the consolidated layer, so they answer best per token, but a bank with **consolidation disabled never grows any** and the default recall comes back empty on it: set `{"types": ["world", "experience"]}` there, or `{"types": null}` for every type. File-only, like `retainMetadata` β€” an object does not flatten into an env var | | `toolGuideExtra` | β€” | your own guidance on how the agent should treat memory, added **after** the built-in tool guide (at session start and on every refresh) and after the crediting note returned with `hindsight_search_knowledge_pages` results. It adds to the built-in text, never replaces it. Set it per harness or per bank like any other key, e.g. `"Memory is a past record, not current state: verify any claim against the code before acting on it."` | | `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 | | `pages` | every page | per-page configuration for the seeded knowledge pages, keyed by page name (case-insensitive): `false` skips a page entirely, `{"source_query": "..."}` seeds it with your question instead of the built-in one. Omitted, all five pages are seeded with their built-in queries. This is the supported way to own a page's wording β€” the plugin re-syncs a page whose live query differs from the one it is configured to have, so a query edited through the API or the control plane is replaced on the next session. A skipped page is **not deleted**: one already seeded keeps its content and stops being re-synced. The scoping clause is appended to your query too, so a reworded page cannot start reporting a dependency's decisions as this project's. File-only, like `recallOptions`; in a `banks.` section it replaces the global map rather than merging into it | | `customPages` | β€” | knowledge pages of your own, seeded alongside the five above and keyed by the name they get: `{"Security posture": {"source_query": "...", "tags": ["knowledge:decision"]}}`. `source_query` is required; `tags` picks which facts feed the page and is optional β€” omitted, the page draws on everything the bank holds. A separate setting from `pages` on purpose, so that an unknown name there stays a typo warning rather than quietly creating a page. File-only, and replaced (not merged) by a `banks.` section | | `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` and `npm` on `PATH` | | `gitIngest` | `"message"` | git depth for seeding AND staying current (same engine): `"message"` = commit messages only (one doc, re-upserted when HEAD has a commit it lacks); `"full"` = messages + per-commit full diffs (progressive, newest first); `"none"` = git off | | `harnesses.` | β€” | 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](https://www.jenkins.io/doc/book/pipeline/syntax/#cron-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 to the pages a repo already has, too.** Every session compares each page this plugin created β€” the seeded taxonomy and every captured initiative β€” against the config and re-syncs the ones that differ, so a bank seeded before this default changed moves onto the hourly schedule by itself, and a page you retriggered by hand in the control plane is put back on the configured policy the next time an agent runs. The config file is the source of truth for these pages: to give one a different schedule, change `pageTriggerType`/`pageTriggerCron` (per bank, if it is only that repo) rather than editing the page. Only the fields this plugin states are touched β€” a page's `mode`, its excluded siblings and its minimum refresh interval are left exactly as they are. ### Customize Knowledge Pages β€” `pages` Every repo gets the same five pages. They are a **taxonomy**, not a summary of your source: each one is synthesized from what the bank ingested β€” commit history and past conversations β€” and each is pinned to one knowledge tier, so a page draws only on the facts the extractor routed to it. | Page | What it answers | Tier tag | | ------------------------------ | ------------------------------------------------------------------------------------------------------- | ------------------------ | | `Component map` | the main components/modules/subsystems, what each is responsible for, and how they depend on each other | `knowledge:component` | | `Core concepts` | the domain abstractions and key entities β€” the vocabulary a developer has to know | `knowledge:concept` | | `Conventions and patterns` | how THIS project does things: testing, error handling, naming, structure, how changes are made | `knowledge:convention` | | `Key decisions and rationale` | the significant technical decisions and the durable "why we do it this way" behind them | `knowledge:decision` | | `Initiatives and enhancements` | the major initiatives and features over time, linking out to each captured initiative's own page | `knowledge:feature-work` | `pages` says which of them to seed and what each one asks. Keys are the page names above, matched ignoring case and surrounding spaces: ```jsonc { "pages": { // don't seed this page at all "Component map": false, // seed it, but ask your question instead of the built-in one "Key decisions and rationale": { "source_query": "What did we decide about data retention, encryption and PII handling, and why? Prefer decisions that constrain what new code may do.", }, }, } ``` Omit `pages` entirely β€” the default β€” and all five are seeded with their built-in queries. **Fewer pages.** Each page costs one LLM synthesis per refresh, so a repo that only wants the architecture ones turns the rest off: ```jsonc { "pages": { "Initiatives and enhancements": false, "Conventions and patterns": false, "Key decisions and rationale": false, }, } ``` **Per repo**, like every other field β€” usually where this belongs, since what a page should ask is a property of the project, not of your machine: ```jsonc { "banks": { "coding-agent::payments-api": { "pages": { "Core concepts": { "source_query": "What are the payment domain's entities β€” orders, ledgers, settlement states β€” and what does each mean in OUR model?", }, }, }, }, } ``` Four things worth knowing before you reach for it: - **This is the only durable way to reword a page.** Every session compares each seeded page against the query it is configured to have and re-syncs the ones that differ, so a `source_query` edited through the API or the control plane is replaced the next time an agent runs. Setting it here makes your wording the configured one. When a re-sync does replace a query, the plugin now says which page in the plugin log rather than doing it silently. - **Your query still gets the scoping clause.** The sentence that keeps a dependency's decisions off your project's page is appended to a custom query too β€” a bank holds facts about the libraries and services a repo merely uses, and without that clause a page will present them as yours. - **The tier tag stays the taxonomy's.** It selects which facts the synthesis reads; rewording the question changes what is asked of those facts, not which ones are in scope. - **`false` does not delete anything.** A page already seeded keeps its content and simply stops being re-synced β€” remove it in the control plane if you want it gone. A name that matches no page above is ignored with a warning in the plugin log, so a typo fails loudly instead of looking like it disabled something. Adding pages of your own is not what this setting is for: the agent's `hindsight_capture_initiative` tool already creates pages, one per initiative, each with its own query. #### Pages of your own β€” `customPages` `pages` only reworks the five above. To add a page, name it under `customPages`: ```jsonc { "customPages": { "Security posture": { "source_query": "What are this project's security decisions β€” authn, secrets handling, PII, dependency policy β€” and what do they constrain in new code?", "tags": ["knowledge:decision"], }, "Operational runbook": { "source_query": "How does this project get deployed, monitored and rolled back? What has broken in production, and what fixed it?", }, }, } ``` `source_query` is required. `tags` is optional and picks which facts feed the page β€” one of the tier tags above, or any tag you stamp on your own writes with `retainTags`. Omit it and the page draws on everything the bank holds: a refresh matches tags with `all`, so no tags means no tag constraint, **not** an empty page. Your pages are seeded at the same root as the taxonomy, on the same refresh schedule, and re-synced from the config the same way β€” reword one here and the live page follows on the next session. They compose with `pages`, so trading two built-ins for one of your own is just both settings at once. **Why it is a separate setting.** `pages` refuses a name that matches no seeded page, and that is what makes a typo loud: if an unknown key there meant "create this page", `"Componnet map"` would quietly create an empty second page instead of rewording the one you meant. For the same reason, naming a seeded page under `customPages` is refused β€” reword it under `pages`. A page you create yourself in the control plane is a third thing again, and the plugin never touches it: the seed pass only visits the pages it is configured to own. ### A bank you shape yourself β€” `manageBankConfig` Pointed at a bank, this plugin gives it the shape its ingestion needs: retain strategies for the kinds of document it writes (`git`, `gitlog`, `conversation`, `document`, `survey`), a `knowledge` entity-label group that routes facts to the knowledge pages, and β€” on a bank that has no missions of its own β€” the coding missions. **It only ever adds what is missing.** A strategy you defined, an edit you made to one of the plugin's, a reworded label group, a mission you rewrote in the control plane: each is left exactly as it is, on every session, forever. What the bank already says wins. The cost of that promise is that a plugin release which _rewords_ an existing strategy or label does not reach a bank that already has it. To take the current default back, clear that override on the bank (delete the strategy, or the whole `retain_strategies` entry, in the control plane): the next session finds the bank silent there and seeds it again. One field is the exception: the extraction mode of the plugin's own four strategies (`git`, `gitlog`, `conversation`, `document`) follows `retainExtractionMode` and is put back on every session if it drifts β€” the same way a seeded page's query is. Change it in `coding-agent.json`, not in the control plane. The strategies' other fields, and your own strategies, are still left alone. **Your own defaults for new banks β€” `defaultBankConfig`.** Everything the template does not name, a bank the plugin creates gets from the server: auto-consolidation on, observations on, a 60s floor between mental-model refreshes. With one bank per repo those are the settings that cost money, and a new repo an agent touches spawns a new bank with all of them switched on β€” while every bank you had hand-tuned in the control plane sits at a cheaper baseline. `defaultBankConfig` names the baseline once, in the plugin's config, and it travels in the same import that creates the bank: ```json { "defaultBankConfig": { "enable_observations": false, "enable_auto_consolidation": false, "mental_model_min_refresh_interval_seconds": 21600 } } ``` The keys are the bank-config API's own field names, passed straight through, so anything the bank-config accepts can go here. They follow the same additive rule as the template: written only where the bank is silent, so an existing bank picks them up on its next session **except** for the fields it already sets β€” a value you chose in the control plane stays, even one equal to the server default, and so does a value an earlier plugin release seeded (the template writes `enable_observations: true` alongside the missions; clear that override on the bank to let your default in). On a key the template also names, your default wins. The three fields the plugin governs itself β€” `retain_strategies`, `entity_labels` and `retain_extraction_mode` β€” are refused with a warning: the first two are merged entry by entry, the last is `retainExtractionMode`'s. Set `manageBankConfig: false` to keep the plugin out of the bank's configuration altogether, `defaultBankConfig` included β€” the right setting for a bank you share with non-coding work, or one you configure yourself. That bank should then define the five strategies above itself. Note that the miss is **silent**: the server does not reject a retain naming a strategy the bank lacks, it logs a warning and extracts with the bank's own configuration β€” so a commit diff, a session transcript and a survey marker would all get the same generic treatment instead of the extraction each needs. Knowledge pages are seeded either way; `pageTriggerType` governs what they cost. Like every field here it can be set per bank, which is usually where it belongs: ```json { "bankId": "my-global-bank", "banks": { "my-global-bank": { "manageBankConfig": false } } } ``` ### Per-repo opt-in/out β€” `banks.` Per-repo control lives in the SAME file, keyed by the **resolved bank id** (shown in the session banner) and applied AFTER bank resolution β€” so it works regardless of where the repo lives, and survives directory moves: ```jsonc { "banks": { "coding-agent::secret-client": { "disabled": true }, // blacklist: no memory at all "coding-agent::old-name": { "bank": "team::shared" }, // rename / converge banks "coding-agent::big-mono": { "gitIngest": "full", "retainSessions": false }, }, } ``` Any behavioral field can be overridden per bank, and `bank` **renames the destination** (single hop: the section is selected by the resolved id, the target is literal β€” several ids may converge on one shared bank, and the target's own section is not consulted). Other bank-resolution fields are ignored inside a bank section. #### Recipe: two repos, one shared bank Two ways, by what the natural key is: **By resolved id** β€” you know the repo names; works wherever the repos live (and keeps working if they move). Both ids converge on one literal target: ```jsonc { "banks": { "coding-agent::backend": { "bank": "team::product" }, "coding-agent::frontend": { "bank": "team::product" }, }, } ``` **By path prefix** β€” the repos live under one directory; a single `mapPathToBank` entry covers every repo (present and future) beneath it: ```jsonc { "mapPathToBank": { "/Users/me/work/client-x": "client-x-memory" }, } ``` Rule of thumb: converge by **id** for a hand-picked set of repos; map by **path** when a folder is the boundary ("everything I clone under `work/client-x` shares memory"). ### Per-directory overrides β€” `paths.` When a folder is the boundary for something other than the bank β€” typically a different server or tenant for client work β€” key the override by directory instead of by bank id: ```jsonc { "apiToken": "personal-key", "paths": { "~/work/client-x": { "apiToken": "client-x-key" }, "~/work/acme": { "apiUrl": "https://hindsight.acme.internal", "apiToken": "acme-key" }, "~/oss": { "serverMode": "daemon" }, }, } ``` Every repo under the prefix, present and future, keeps its own bank but uses the entry's settings. The longest matching prefix wins, and a linked worktree outside the tree uses its main checkout's entry, as with `mapPathToBank`. The section applies after bank resolution and before `banks.`, so a bank section still wins for its one repo. Bank-resolution and approval fields (`bankId`, `mapPathToBank`, `bank`, `optInOnly`, `optInPaths`, ...) are ignored inside a path section. Any connection setting can be overridden β€” `serverMode`, `apiUrl`, `apiPort`, `apiToken` β€” so one directory can use a local daemon while another uses Cloud or a self-hosted server. The token is re-read on a rejected request, like the top-level `apiToken`, but only while the directory still points at the same server. ### Bank resolution Coding memory is **per repository**. Resolution order for the working directory: 1. `mapPathToBank` β€” longest matching absolute-path prefix (mapping a repo root covers every subdirectory; deeper mappings win; overrides even an explicit `bankId`). 2. Static β€” `bankId` set (or `dynamicBankId: false`). 3. Dynamic β€” `bankIdTemplate` with placeholders: - `{gitProject}` β€” worktree-aware repo name: `git rev-parse --git-common-dir` resolves every linked worktree to the **main** worktree's basename, so all worktrees of a repo share one bank (bare repos use the bare dir name). **Outside a repo** there is nothing for git to resolve, so it falls back to the basename of the directory the **session started in** β€” an agent that `cd`s into a subdirectory keeps writing to one bank, and a subdirectory gets its own bank only when you deliberately start a session there - `{project}` β€” plain working-directory basename - `{harness}` β€” the entry point asking (`opencode`, `claude-code`, `codex`, `antigravity-cli`, `cursor-cli`, `copilot-cli`) - `{channel}` / `{user}` β€” `$HINDSIGHT_CHANNEL_ID` / `$HINDSIGHT_USER_ID` The default `"coding-agent::{gitProject}"` is **harness-neutral**, so opencode, Claude Code, and Codex all share one memory per repo β€” use `"{harness}-{gitProject}"` to split per agent instead. ### Recording where a memory came from With a bank per repo, the bank _is_ the answer to "where did this come from". On a deliberately **shared** bank β€” one bank holding cross-project knowledge so facts recall everywhere β€” it isn't: every memory looks alike. `retainTags` and `retainMetadata` stamp that provenance onto conversations, git history and diffs, survey lifecycle documents, initiative markers, and documents saved through `hindsight_ingest_document`: ```jsonc { "bankId": "shared", // one bank for everything "retainTags": ["project:{gitProject}", "env:work"], "retainMetadata": { "repo": "{gitProject}" }, } ``` Recalls can then filter by `project:`, and every document shows which repository it came out of. Both accept the same placeholders as `bankIdTemplate` β€” `{gitProject}`, `{project}`, `{harness}`, `{channel}`, `{user}` β€” plus `{bankId}`, `{sessionId}` and `{timestamp}`. `{gitProject}` is worktree-aware here too, so every linked worktree of a repo stamps one name. `{sessionId}` resolves to `unknown` for documents that do not originate from an agent session. The plugin's own `source:` and `harness:` tags are reserved: entries in those namespaces are ignored with a warning, so a document's agent attribution always reflects the agent that actually wrote it. ### One set of beliefs per repo Every document this integration writes carries provenance tags β€” `source:chat`, `harness:`, `knowledge:`, plus anything from `retainTags`. Those tags say **who wrote** a memory; they are what filters recall and draws each document's agent logo, and they stay on the facts. They are not, however, a good boundary for [observations](https://hindsight.vectorize.io/developer/observations). Consolidation's own default (`combined`) builds one observation set per distinct tag set, so the same repository worked on by two agents would grow two parallel sets of beliefs β€” one per harness β€” that never merge, each blind to the other, at double the consolidation cost. Which agent happened to be typing does not change whether a convention or a decision is true. So the integration retains with `observationScopes: "shared"`: one global, untagged observation scope per bank, which is what a bank already is β€” one project's memory. Set the field to change it: ```jsonc { "observationScopes": "combined", // one observation set per distinct tag set (server default) "banks": { "coding-agent::mono": { "observationScopes": "per_tag" }, // per-repo, like any behavioral field }, } ``` ### Splitting code from conversation β€” `per_source` `shared` puts every document a repo produces into one belief set. `"per_source"` keeps that set and adds one per origin, so "what the commits say" and "what was decided in conversation" can be asked apart: ```jsonc { "observationScopes": "per_source" } ``` Each document consolidates into the global scope **plus** one named for each `source:` tag it carries β€” `[[], ["source:chat"]]` for a session transcript, `[[], ["source:git"]]` for a commit diff. Read an axis back with `tags: ["source:git"], tags_match: "exact"`, and the merged view with `tags: [], tags_match: "exact"`. A document carrying two `source:` tags gets a scope for each, and that is deliberate rather than duplication. The commit-message seed is tagged `source:git` and `source:git-log`, so `source:git-log` is fed only by the seed β€” what the commit _messages_ say β€” while `source:git` also collects every per-commit diff under `gitIngest: "full"`. Two questions, two answers, each deduplicated within itself by consolidation. A fact belonging to more than one axis is the point. This cannot be expressed as a scope list. The server treats an explicit `list[list[str]]` as unconditional β€” it is not filtered against the memory's own tags β€” so a configured `[[], ["source:git"], ["source:chat"]]` writes every document into all three, and the `source:git` scope fills with beliefs built from chat transcripts. Only a per-document decision separates them. It costs one extra consolidation pass per document, and it reads only `source:`, so a volatile provenance tag never becomes a scope. The global scope is still written first and unchanged, so the untagged observations knowledge pages read are unaffected. `"per_tag"` and `"all_combinations"` split further still, and an explicit `[["project:demo"], …]` declares the scopes literally. `HINDSIGHT_OBSERVATION_SCOPES` sets the scalar modes; a scope list is file-only. Changing this does not rewrite observations already consolidated under the old scoping β€” they stay where they were built, and new work accrues under the new setting. ## Diagnostics & logging All logs live in `~/.hindsight/coding-agents-logs/` (owner-only). Each file rotates to `.1` at 10 MB. **Leveled plugin log** (humans debugging): `~/.hindsight/coding-agents-logs/plugin.log` (override `HINDSIGHT_LOG_FILE`) β€” timestamped `LEVEL [scope] message` lines from every component, including the ingestion engine. Level defaults to `info`; set `"logLevel": "debug"` in config or `HINDSIGHT_LOG_LEVEL=debug` for ad-hoc debugging (at `debug`, every diag event below is mirrored here too, so one file tells the whole story). **Structured diag events** (machines/harnesses): every reflect and page-fetch outcome is appended as a JSON line to `~/.hindsight/coding-agents-logs/diag.jsonl` (override with `HINDSIGHT_DIAG_FILE`): ```json { "ts": "2026-07-27T07:05:52Z", "harness": "claude-code", "event": "reflect_ok", "ms": 14210, "chars": 792, "query": "..." } ``` `reflect_failed` / `pages_failed` record the error; if you're comparing memory-on vs memory-off, check this file β€” a run whose reflects failed is a no-memory run. When the failure was a timeout or a 5xx, the hook falls back to knowledge-page search and, if no page matches, to a raw recall of the bank's memories: `reflect_fallback_pages` / `reflect_fallback_observations` record what each step returned (`*_failed` when it errored). Seed starts are logged as `seed_started`. When `autoInject` names a retrieval source instead of reflect, that source records its own outcome with the number of items it returned: `inject_pages` for `"pages"`, `inject_recall` for `"recall"` (`inject_pages_failed` / `inject_recall_failed` when the call errored). No reflect event is written on those turns β€” nothing reflected. **Tool usage** (is the agent using Hindsight?): one JSON line per finished user turn in `~/.hindsight/coding-agents-logs/usage.jsonl` (override `HINDSIGHT_USAGE_FILE`) β€” the `hindsight_*` tools the agent called during that turn, and whether its reply credited Hindsight memory ("From Hindsight memory"). The credit rate counts only turns that called a retrieval tool (search, list, read, reflect); saving a document is not expected to be credited. Recorded when the session is written back, so a scope with `retainSessions: false` records none. It never leaves your machine. Summarize it per agent with: ```bash npx @vectorize-io/hindsight-coding-agents stats ``` ### Is the memory ready yet? `hindsight_sync_status` β€” the agent-facing tool, `dist/status.js` for scripts β€” answers exactly that: `"synced": true` means the seeded memory is queryable. It also reports gitlog freshness, how far per-commit deepening has got, the codebase survey's state (`surveyBaseline` is the HEAD the last survey started from, `surveyDocs` counts the findings documents that have landed, 0–4 β€” a baseline with no findings retries automatically), and the extraction operations still in flight. ### Resetting a repo's memory Delete its bank on the server. The bank is the **only** state this integration keeps, so the next session in that repo is a true first open β€” seed and survey run again from scratch. There are no client-side files to clean up. ### Marker documents you may notice Two document ids exist for the machinery's own bookkeeping. Both are safe to ignore and safe to delete: - `survey-baseline:` β€” reads "πŸ›°οΈ researching…" while a codebase survey runs and flips to "βœ… completed" once its findings land. It is retained under the `survey` strategy, whose marker rule extracts **nothing** from a status marker, and it drives the re-survey cadence (`surveyRefreshCommits`) and `surveyBaseline` in sync status. - `gitlog:` β€” the aggregated commit-message seed document, re-upserted rather than duplicated when the seed runs again. ### When memory seems to be missing Failures never break the agent: a reflect, page fetch or retain that fails degrades to an ordinary memoryless turn and is recorded in the logs. "No memory" is therefore a log question β€” check the diag file for whether `session_start` and `deepen_started` ever fired for that bank. A session that was already running when the plugin was installed has no SessionStart behind it; its first prompt after the install self-heals.