# Hindsight Coding Agent > 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. - Skill: `vectorize-io/hindsight-coding-agent` (Agent Skill) - Install (CLI): `npx skillmds add vectorize-io/hindsight-coding-agent` - Raw SKILL.md: https://api.skillmd.com/api/skills/vectorize-io/hindsight-coding-agent/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: vectorize-io (https://skillmd.com/u/vectorize-io) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/vectorize-io/hindsight-coding-agent --- # 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. 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 (): …` β€” 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 ``` `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 `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`, `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](#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}"}` | | `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.` | β€” | 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 t …(truncated)