hindsight-coding-agent

<!-- GENERATED from README.md (its skill:begin regions) + skill-src/preamble.md. Edit those, then run: npm run skill:build --> # 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 ```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 ``` `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. ## 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` | — | seconds of inactivity before it exits | | `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_<FIELD_IN_CAPS>`), for containers and CI that inject config rather than write a file 3. the file's top level 4. its `harnesses.<name>` section — per-agent override 5. its `banks.<resolvedBankId>` 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, Kilo CLI, Cline CLI, 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.<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: ```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 |