@herbertgao/pi-extensions 2026.9.6 → 2026.9.8

package/node_modules/@luxusai/pi-hindsight/docs/surface-reference.md

@@ -1,261 +0,0 @@
-<!-- This file is generated by scripts/generate-surface-reference.ts. Do not edit by hand. -->
-
-This reference is generated from the operation catalog and config editing registry.
-
-## 1.0 support scope
-
-Pi Hindsight 1.0 supports a stable Pi-first Hindsight integration. Core and Pi workflow tools are part of the stable 1.0 contract. Capability-gated tools are supported when the connected Hindsight server exposes the required upstream endpoint or field; unsupported servers should return a clear capability error.
-
-| Tool                      | Scope                |
-| ------------------------- | -------------------- |
-| `hindsight_recall`        | core 1.0             |
-| `hindsight_retain`        | core 1.0             |
-| `hindsight_retain_global` | core 1.0             |
-| `hindsight_reflect`       | core 1.0             |
-| `hindsight_status`        | supported 1.0        |
-| `hindsight_seed_git`      | supported 1.0        |
-| `hindsight_scope`         | supported 1.0        |
-| `hindsight_config`        | supported 1.0        |
-| `hindsight_bank`          | supported 1.0        |
-| `hindsight_mental_model`  | capability-gated 1.0 |
-| `hindsight_knowledge`     | capability-gated 1.0 |
-| `hindsight_scope_migrate` | supported 1.0        |
-
-## Deferred or non-goal upstream surfaces
-
-| Surface                 | 1.0 status | Rationale                                                                                   |
-| ----------------------- | ---------- | ------------------------------------------------------------------------------------------- |
-| Cross-bank list/create  | Deferred   | No public `list_banks` or arbitrary cross-bank `create_bank` tool in 1.0.                   |
-| Full-bank deletion      | Deferred   | No public `delete_bank` tool in 1.0; selected-bank reset/delete-like repair remains scoped. |
-| Platform bank stats     | Deferred   | No global `get_bank_stats` dashboard/tool in 1.0.                                           |
-| Audit logs and webhooks | Non-goal   | Platform administration is outside the Pi-first 1.0 memory lifecycle.                       |
-
-## Tools
-
-### `hindsight_recall`
-
-Recall raw memories from Hindsight for this project.
-
-| Parameter                   | Type                                            | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| --------------------------- | ----------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `query`                     | string                                          | yes      | Natural language memory query                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `bank`                      | string                                          | no       | Optional bank id. Defaults to project bank.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `types`                     | array<world \| experience \| observation>       | no       | Optional Hindsight fact types to retrieve.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `preferObservations`        | boolean                                         | no       | When recalling raw facts ('world'/'experience') together with 'observation', drop raw facts superseded by a returned observation. Defaults to the configured recall.preferObservations.                                                                                                                                                                                                                                                                                            |
-| `minScores`                 | object                                          | no       | Optional per-stage score floors. Omitted stages impose no floor. No floor by default.                                                                                                                                                                                                                                                                                                                                                                                              |
-| `budget`                    | low \| mid \| high                              | no       | Optional Hindsight recall budget override for this tool call.                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `maxTokens`                 | integer                                         | no       | Optional Hindsight recall token cap override for this tool call. Use 0 for metadata/source-only recall when supported by Hindsight.                                                                                                                                                                                                                                                                                                                                                |
-| `queryTimestamp`            | string                                          | no       | Optional ISO timestamp for time-scoped recall.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `includeChunks`             | boolean                                         | no       | Ask Hindsight to include source chunks when supported.                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `recallChunksMaxTokens`     | integer                                         | no       | Optional token cap for included recall chunks.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `includeSourceFacts`        | boolean                                         | no       | Ask Hindsight to include source facts when supported.                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `maxSourceFactsTokens`      | integer                                         | no       | Optional token cap for included source facts.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `includeEntities`           | boolean                                         | no       | Ask Hindsight to include entities when supported.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `trace`                     | boolean                                         | no       | Ask Hindsight to include recall trace/debug data.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `tags`                      | array<string>                                   | no       | Additional tag filter.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `tagsMatch`                 | any \| all \| any_strict \| all_strict \| exact | no       | How to match tags. Always enforced together with the automatic Pi project/user scope tag filter. 'exact' folds the automatic scope tags into the exact-match set (memory tags must equal scope tags plus these tags, no more, no less) instead of AND-ing a separate scope group, since scope tags must still be present. To also include Hindsight shared/untagged observations (exact empty tags), set includeSharedObservations=true or config.scope.includeSharedObservations. |
-| `tagGroups`                 | array<object>                                   | no       | Compound Hindsight tag_groups filter. AND-ed with the automatic Pi project/user scope filter.                                                                                                                                                                                                                                                                                                                                                                                      |
-| `includeSharedObservations` | boolean                                         | no       | When true, also match exact-empty (shared/untagged) observations inside the bank via tag_groups OR. Defaults to config.scope.includeSharedObservations (false). Not cross-bank.                                                                                                                                                                                                                                                                                                    |
-
-### `hindsight_retain`
-
-Retain explicit raw content in Hindsight. Use for durable facts or decisions.
-
-| Parameter           | Type                                                                      | Required | Description                                                                                                                                                                                             |
-| ------------------- | ------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `content`           | string                                                                    | yes      | Raw content to retain, not summary if source content is available.                                                                                                                                      |
-| `context`           | string                                                                    | yes      | Source context for this memory.                                                                                                                                                                         |
-| `bank`              | string                                                                    | no       | Optional bank id. Defaults to project bank.                                                                                                                                                             |
-| `tags`              | array<string>                                                             | no       |                                                                                                                                                                                                         |
-| `entities`          | array<object>                                                             | no       | Optional Hindsight entities to associate with this retained content.                                                                                                                                    |
-| `documentId`        | string                                                                    | no       | Optional Hindsight document ID. Defaults to the existing deterministic explicit retain document ID.                                                                                                     |
-| `timestamp`         | string                                                                    | no       | Optional Hindsight timestamp string, including ISO-ish strings or literal unset, passed through as provided.                                                                                            |
-| `metadata`          | object/map                                                                | no       | Optional caller metadata string map. Reserved provenance keys such as cwd, pi_session_file, source, and retainSource are set by pi-hindsight and cannot be overridden.                                  |
-| `updateMode`        | append \| replace                                                         | no       | Optional Hindsight update mode for this explicit retain call.                                                                                                                                           |
-| `observationScopes` | per_tag \| combined \| all_combinations \| shared \| array<array<string>> | no       | Optional Hindsight observation scopes. Use per_tag, combined, all_combinations, shared, or explicit string groups. When provided, overrides configured default observation scopes for this retain call. |
-| `documentTags`      | array<string>                                                             | no       | Optional Hindsight document_tags for this retained document when supported.                                                                                                                             |
-| `async`             | boolean                                                                   | no       | Optional Hindsight async extraction flag for this retain call. Defaults to configured retain.async.                                                                                                     |
-
-### `hindsight_retain_global`
-
-Retain explicit durable user memory in the configured user bank. Use for stable user identity, preferences, and cross-project workflows only.
-
-| Parameter           | Type                                                                      | Required | Description                                                                                                                                                                                             |
-| ------------------- | ------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `content`           | string                                                                    | yes      | Raw memory content to retain.                                                                                                                                                                           |
-| `context`           | string                                                                    | yes      | Why this memory is durable user context.                                                                                                                                                                |
-| `tags`              | array<string>                                                             | no       |                                                                                                                                                                                                         |
-| `entities`          | array<object>                                                             | no       | Optional Hindsight entities to associate with this retained content.                                                                                                                                    |
-| `documentId`        | string                                                                    | no       | Optional Hindsight document ID. Defaults to the existing deterministic explicit retain document ID.                                                                                                     |
-| `timestamp`         | string                                                                    | no       | Optional Hindsight timestamp string, including ISO-ish strings or literal unset, passed through as provided.                                                                                            |
-| `metadata`          | object/map                                                                | no       | Optional caller metadata string map. Reserved provenance keys such as cwd, pi_session_file, source, and retainSource are set by pi-hindsight and cannot be overridden.                                  |
-| `updateMode`        | append \| replace                                                         | no       | Optional Hindsight update mode for this explicit retain call.                                                                                                                                           |
-| `observationScopes` | per_tag \| combined \| all_combinations \| shared \| array<array<string>> | no       | Optional Hindsight observation scopes. Use per_tag, combined, all_combinations, shared, or explicit string groups. When provided, overrides configured default observation scopes for this retain call. |
-| `documentTags`      | array<string>                                                             | no       | Optional Hindsight document_tags for this retained document when supported.                                                                                                                             |
-| `async`             | boolean                                                                   | no       | Optional Hindsight async extraction flag for this retain call. Defaults to configured retain.async.                                                                                                     |
-
-### `hindsight_reflect`
-
-Ask Hindsight to synthesize an answer from memory. Use explicitly, not for default recall.
-
-| Parameter                   | Type                                            | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| --------------------------- | ----------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `query`                     | string                                          | yes      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `context`                   | string                                          | no       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `bank`                      | string                                          | no       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `budget`                    | low \| mid \| high                              | no       | Optional Hindsight reflect budget override for this tool call.                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `maxTokens`                 | integer                                         | no       | Optional Hindsight reflect token cap override for this tool call.                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `responseSchema`            | object/map                                      | no       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `includeFacts`              | boolean                                         | no       | Ask Hindsight reflect to include facts when supported.                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `includeToolCalls`          | boolean                                         | no       | Ask Hindsight reflect to include tool-call trace data when supported.                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `includeToolCallOutput`     | boolean                                         | no       | When includeToolCalls is set, include tool-call outputs (default true); set false for an inputs-only trace.                                                                                                                                                                                                                                                                                                                                                                        |
-| `factTypes`                 | array<world \| experience \| observation>       | no       | Restrict reflection to these Hindsight fact types.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `excludeMentalModels`       | boolean                                         | no       | Exclude all mental models from reflection.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `excludeMentalModelIds`     | array<string>                                   | no       | Exclude specific mental models by id from reflection.                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `tags`                      | array<string>                                   | no       | Additional tag filter.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `tagsMatch`                 | any \| all \| any_strict \| all_strict \| exact | no       | How to match tags. Always enforced together with the automatic Pi project/user scope tag filter. 'exact' folds the automatic scope tags into the exact-match set (memory tags must equal scope tags plus these tags, no more, no less) instead of AND-ing a separate scope group, since scope tags must still be present. To also include Hindsight shared/untagged observations (exact empty tags), set includeSharedObservations=true or config.scope.includeSharedObservations. |
-| `tagGroups`                 | array<object>                                   | no       | Compound Hindsight tag_groups filter. AND-ed with the automatic Pi project/user scope filter.                                                                                                                                                                                                                                                                                                                                                                                      |
-| `includeSharedObservations` | boolean                                         | no       | When true, also match exact-empty (shared/untagged) observations inside the bank via tag_groups OR. Defaults to config.scope.includeSharedObservations (false). Not cross-bank.                                                                                                                                                                                                                                                                                                    |
-
-### `hindsight_status`
-
-Inspect Pi Hindsight status: setup gate, coding/life banks, project scope tags (basis), recall/retain flags, queue, and sync readiness (queue depth, git seed receipt, knowledge-page capability). Use before changing memory config. Read-only.
-
-| Parameter | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-
-### `hindsight_seed_git`
-
-Opt-in cold-repo seed: retain recent git commit messages (strategy gitlog) into the project bank. Not automatic — conversation retain remains primary. dryRun defaults true; set dryRun=false to enqueue (and flush by default).
-
-| Parameter | Type    | Required | Description                                                      |
-| --------- | ------- | -------- | ---------------------------------------------------------------- |
-| `limit`   | integer | no       | Max commits to include (default 300).                            |
-| `dryRun`  | boolean | no       | Default true (preview). Set false to enqueue retain.             |
-| `flush`   | boolean | no       | When dryRun=false, flush the queue after enqueue (default true). |
-
-### `hindsight_scope`
-
-Show active project identity: project:<id> tag, derivation (pin/remote/basename), scope.mode (domain-tagged vs isolated-bank), coding/life bank ids. Read-only.
-
-| Parameter | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-
-### `hindsight_config`
-
-Get or patch allowlisted Pi Hindsight config (project or global file). action=get returns effective values (no secrets) and the allowlist. action=patch updates only typed allowlisted keys (setupComplete, scopeMode, projectId, projectIdStrategy, includeSharedObservations, projectBankId, enableGlobalBank, globalBankId, agentUse, mentalModelsInject, memoryProfile, recall/retain knobs, baseUrl, apiKeyEnvVar, timeoutMs). dryRun defaults true for patch. Domain-tagged setupComplete requires projectBankId. Never pass raw API keys — use apiKeyEnvVar.
-
-| Parameter | Type              | Required | Description                                                      |
-| --------- | ----------------- | -------- | ---------------------------------------------------------------- |
-| `action`  | get \| patch      | yes      |                                                                  |
-| `patch`   | object            | no       | Typed allowlisted config fields only (no free-form keys).        |
-| `scope`   | project \| global | no       | Which config file to write (default project .pi/hindsight.json). |
-| `dryRun`  | boolean           | no       | When true (default for patch), preview only; set false to write. |
-
-### `hindsight_bank`
-
-Inspect or update the selected coding/life bank. action=get returns profile/stats/config. action=update_mission patches retain/reflect/observations mission (dryRun default true for safety).
-
-| Parameter             | Type                  | Required | Description                                                              |
-| --------------------- | --------------------- | -------- | ------------------------------------------------------------------------ |
-| `action`              | get \| update_mission | yes      |                                                                          |
-| `bank`                | string                | no       | Bank id or alias project\|global\|user. Defaults to coding/project bank. |
-| `retainMission`       | string                | no       |                                                                          |
-| `reflectMission`      | string                | no       |                                                                          |
-| `observationsMission` | string                | no       |                                                                          |
-| `dryRun`              | boolean               | no       | When true (default for update_mission), preview only.                    |
-
-### `hindsight_mental_model`
-
-Agent control plane for mental models on the selected bank. Actions: list|get|create|update|refresh|delete. list returns metadata only (id, name, tags, max_tokens, last_refreshed_at); use get for full content/reflect_response. Project-tier create defaults tags to source:pi + project:<activeId>. Optional tagsMatch sets refresh tag matching on create/update trigger. Mutating actions default dryRun=true; set dryRun=false to apply.
-
-| Parameter     | Type                                                 | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ------------- | ---------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `action`      | list \| get \| create \| update \| refresh \| delete | yes      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `bank`        | string                                               | no       | Bank id or alias project\|global\|user.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `id`          | string                                               | no       | Mental model id for get/update/refresh/delete.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `name`        | string                                               | no       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `sourceQuery` | string                                               | no       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `tags`        | array<string>                                        | no       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `maxTokens`   | integer                                              | no       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `tagsMatch`   | any \| all \| any_strict \| all_strict \| exact      | no       | How to match tags. Always enforced together with the automatic Pi project/user scope tag filter. 'exact' folds the automatic scope tags into the exact-match set (memory tags must equal scope tags plus these tags, no more, no less) instead of AND-ing a separate scope group, since scope tags must still be present. To also include Hindsight shared/untagged observations (exact empty tags), set includeSharedObservations=true or config.scope.includeSharedObservations. |
-| `dryRun`      | boolean                                              | no       | Mutating actions default true (preview). Set false to apply.                                                                                                                                                                                                                                                                                                                                                                                                                       |
-
-### `hindsight_knowledge`
-
-Agent control plane for knowledge pages (living docs over bank observations). Actions: tree|search|get|export|seed_taxonomy|create_page|create_folder|update|delete. Prefer search then get for routine Q&A (pages are not auto-injected). seed_taxonomy creates the fixed five-page coding taxonomy (idempotent; degrades when pages unavailable). Use export only for a portable full-bank markdown bundle. Project-tier create_page defaults tags to source:pi + project:<activeId>. Mutating actions default dryRun=true. Requires Hindsight client/server knowledge-base support.
-
-| Parameter     | Type                                                                                                 | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ------------- | ---------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `action`      | tree \| search \| get \| export \| seed_taxonomy \| create_page \| create_folder \| update \| delete | yes      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `bank`        | string                                                                                               | no       | Bank id or alias project\|global\|user.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `id`          | string                                                                                               | no       | Page or folder id for get/update/delete.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `query`       | string                                                                                               | no       | Search query for action=search (hybrid page search).                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `limit`       | integer                                                                                              | no       | Search result limit (1–50).                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `name`        | string                                                                                               | no       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `sourceQuery` | string                                                                                               | no       | Page question for create_page / update.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `parentId`    | string \| null                                                                                       | no       | Folder parent. Omit for root create; pass null on update to move to root.                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `tags`        | array<string>                                                                                        | no       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `maxTokens`   | integer                                                                                              | no       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `tagsMatch`   | any \| all \| any_strict \| all_strict \| exact                                                      | no       | How to match tags. Always enforced together with the automatic Pi project/user scope tag filter. 'exact' folds the automatic scope tags into the exact-match set (memory tags must equal scope tags plus these tags, no more, no less) instead of AND-ing a separate scope group, since scope tags must still be present. To also include Hindsight shared/untagged observations (exact empty tags), set includeSharedObservations=true or config.scope.includeSharedObservations. |
-| `dryRun`      | boolean                                                                                              | no       | Mutating actions (seed_taxonomy\|create_page\|create_folder\|update\|delete) default true (preview). Set false to apply.                                                                                                                                                                                                                                                                                                                                                           |
-
-### `hindsight_scope_migrate`
-
-Dry-run only: plan dual-tag / legacy repo:<path-hash> → project:<id> migration. Writes a local receipt under .pi/hindsight/. Never rewrites Hindsight tags or documents. Prefer Hindsight export/import or Pi transcript reimport for actual rebuilds.
-
-| Parameter      | Type          | Required | Description                                                                                           |
-| -------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------- |
-| `bankTags`     | array<string> | no       | Optional tag inventory sample from the coding bank (e.g. listTags). Used only for counts in the plan. |
-| `writeReceipt` | boolean       | no       | Write .pi/hindsight/scope-migrate-receipt.json (default true).                                        |
-
-## Commands
-
-| Command                   | Description                                                                                          |
-| ------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `/hindsight`              | Open Hindsight memory hub (status, mode, next-opt-out, mental models, import, flush, doctor, setup). |
-| `/hindsight:next-opt-out` | Skip automatic retain for the next agent run in this session.                                        |
-
-## Config fields
-
-| Field                       | Tab        | Kind         | Default                              | Choices                                                | Advanced | Reset key                          | Description                                                                                                                                                                                         |
-| --------------------------- | ---------- | ------------ | ------------------------------------ | ------------------------------------------------------ | -------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `enabled`                   | Connection | boolean      | enabled                              |                                                        | no       | enabled                            | Master switch. When off, automatic recall and retain are skipped.                                                                                                                                   |
-| `baseUrl`                   | Connection | text         | http://localhost:8888                |                                                        | no       | hindsight.baseUrl                  | Server endpoint used for recall, retain, reflect, and bank setup.                                                                                                                                   |
-| `apiKeyEnv`                 | Connection | text         | not set                              |                                                        | no       | hindsight.apiKey                   | Recommended: environment variable name that contains the API key. Editing writes a safe env SecretRef, not the raw secret.                                                                          |
-| `apiKeyDirect`              | Connection | text         | not set                              |                                                        | yes      | hindsight.apiKey                   | Advanced. Writes raw API key only to user/global config. Prefer API key source/env var whenever possible.                                                                                           |
-| `timeoutMs`                 | Connection | positive-int | 30000 ms                             |                                                        | no       | hindsight.timeoutMs                | Maximum time to wait for Hindsight network calls.                                                                                                                                                   |
-| `memoryProfile`             | Banks      | select       | project-only                         | project-only, project+global, global-only, recall-only | no       | banks.profile                      | Coding (project-only) is recommended: shared coding bank. Coding+Life (project+global) adds a personal bank. Isolated is a hard-wall escape hatch. Life-only / recall-only are special cases.       |
-| `agentUse`                  | Banks      | select       | coding                               | coding, conversation                                   | no       | agentUse                           | Selects starter mental-model sets. Coding: architecture/conventions/decisions. Conversation: goals, people/context, and life-task preferences.                                                      |
-| `mentalModelsInject`        | Banks      | boolean      | enabled                              |                                                        | no       | mentalModels.inject                | When models exist on the active bank(s), inject their content into automatic context alongside recall.                                                                                              |
-| `projectBankId`             | Banks      | text         | auto-derived                         |                                                        | no       | banks.project.bankId               | Shared coding bank for domain-tagged mode (prefer user/global config). Isolated mode may pin a per-repo bank.                                                                                       |
-| `globalBankEnabled`         | Banks      | boolean      | disabled                             |                                                        | no       | banks.global.enabled               | Allows cross-project recall from a shared bank.                                                                                                                                                     |
-| `globalBankId`              | Banks      | text         | not set                              |                                                        | no       | banks.global.bankId                | Shared user bank used only when user memory is enabled.                                                                                                                                             |
-| `recallEnabled`             | Recall     | boolean      | enabled                              |                                                        | no       | recall.enabled                     | Looks up memory before answer generation and injects it ephemerally.                                                                                                                                |
-| `recallBudget`              | Recall     | select       | mid                                  | low, mid, high                                         | no       | recall.budget                      | Low, mid, or high retrieval effort.                                                                                                                                                                 |
-| `recallMaxTokens`           | Recall     | positive-int | 800                                  |                                                        | no       | recall.maxTokens                   | Maximum Project Bank memory tokens injected into context.                                                                                                                                           |
-| `recallUserMaxTokens`       | Recall     | positive-int | 400                                  |                                                        | yes      | recall.userMaxTokens               | Maximum User Bank memory tokens injected into context, independent of the Project Bank limit.                                                                                                       |
-| `recallStoreLast`           | Recall     | boolean      | disabled                             |                                                        | yes      | recall.storeLastRecall             | Advanced. Writes the latest successful recall snapshot to a local sidecar under .pi/hindsight/ for debugging.                                                                                       |
-| `recallStoreFailures`       | Recall     | boolean      | disabled                             |                                                        | yes      | recall.storeLastRecallFailures     | Advanced. Also records redacted failed recall attempts in the last-recall sidecar. Requires storing last recall snapshots.                                                                          |
-| `recallPreferObservations`  | Recall     | boolean      | enabled                              |                                                        | yes      | recall.preferObservations          | Advanced. When recalling raw facts together with observations, drop raw facts superseded by a returned observation.                                                                                 |
-| `retainEnabled`             | Retain     | boolean      | enabled                              |                                                        | no       | retain.enabled                     | Stores raw structured conversation deltas after turns.                                                                                                                                              |
-| `retainAsync`               | Retain     | boolean      | enabled                              |                                                        | yes      | retain.async                       | Writes retain jobs through durable queue instead of blocking UI.                                                                                                                                    |
-| `retainDelivery`            | Retain     | select       | immediate                            | immediate, coalesced                                   | yes      | retain.delivery                    | immediate flushes after every turn (default); coalesced merges compatible deltas and defers delivery to session end or periodic flush (retain.flushIntervalMs) to cut database write amplification. |
-| `queuePath`                 | Retain     | text         | .pi/hindsight/retain-queue.jsonl     |                                                        | yes      | retain.queuePath                   | JSONL retry queue used when Hindsight is unavailable.                                                                                                                                               |
-| `globalRetainMode`          | Retain     | select       | explicit-only                        | explicit-only                                          | yes      | globalRetain.mode                  | Advanced. explicit-only keeps User Bank writes manual (the only supported mode).                                                                                                                    |
-| `importMode`                | Import     | select       | curated                              | curated, raw, forensic                                 | no       | import.mode                        | Curated drops noisy successful tool results from preview metrics; raw keeps current raw branch import behavior; forensic preserves recall blocks too.                                               |
-| `importQualityProfile`      | Import     | select       | compatible                           | compatible, strict                                     | no       | import.qualityProfile              | Compatible preserves current curated behavior; strict drops process/UI-like, oversized, or repeated successful tool output in curated mode.                                                         |
-| `importBranches`            | Import     | select       | current-only                         | current-only, all-leaves                               | no       | import.includeBranches             | Import current branch only, or every leaf branch explicitly.                                                                                                                                        |
-| `importToolResults`         | Import     | select       | errors-only                          | errors-only, summary, content                          | no       | import.toolResults                 | Curated import defaults to errors-only; summary keeps bounded low-noise successful tool output; content keeps allowed full successful tool content.                                                 |
-| `importToolSummaryMaxChars` | Import     | positive-int | 500                                  |                                                        | yes      | import.toolResultSummaryMaxChars   | Maximum characters kept for successful tool summaries in curated imports.                                                                                                                           |
-| `importManifest`            | Import     | text         | .pi/hindsight/import-manifest.json   |                                                        | yes      | import.manifestPath                | Tracks imported sessions so reimports stay deterministic.                                                                                                                                           |
-| `importCheckpoint`          | Import     | text         | .pi/hindsight/import-checkpoint.json |                                                        | yes      | import.checkpointPath              | Tracks import progress so interrupted imports can resume safely.                                                                                                                                    |
-| `importReplaceExisting`     | Import     | boolean      | enabled                              |                                                        | yes      | import.replaceExistingImportedDocs | Uses deterministic replace mode for historical reimports instead of appending duplicates.                                                                                                           |
-| `importResume`              | Import     | boolean      | enabled                              |                                                        | yes      | import.resume                      | Skips completed import documents when checkpoint content hashes match.                                                                                                                              |
-| `statusStyle`               | UI         | select       | text                                 | off, text, emoji, nerdfont                             | no       | status.style                       | Off, plain text, emoji, or nerdfont symbols.                                                                                                                                                        |
-| `statusDetail`              | UI         | select       | activity                             | minimal, project, activity, verbose                    | no       | status.detail                      | How much Hindsight info appears in Pi footer.                                                                                                                                                       |
-| `statusMaxLength`           | UI         | positive-int | 24                                   |                                                        | no       | status.maxLength                   | Maximum characters used by Hindsight footer status.                                                                                                                                                 |
-| `statusActivity`            | UI         | boolean      | enabled                              |                                                        | no       | status.showActivity                | Displays recall/retain activity in the status line.                                                                                                                                                 |
-| `notifyStartup`             | UI         | boolean      | enabled                              |                                                        | no       | notifications.startup              | Shows selected Hindsight bank when Pi session starts.                                                                                                                                               |
-| `notifyRecall`              | UI         | boolean      | disabled                             |                                                        | no       | notifications.recall               | Shows a toast when automatic recall runs.                                                                                                                                                           |
-| `notifyRetain`              | UI         | boolean      | disabled                             |                                                        | no       | notifications.retain               | Shows a toast when automatic retain queues memory.                                                                                                                                                  |

package/node_modules/@luxusai/pi-hindsight/extensions/banks/bank-operations.ts

@@ -1,151 +0,0 @@
-import type { AgentUseProfile, BankMissionSettings, HindsightLikeClient } from "../types.js";
-
-const DEFAULT_PROJECT_REFLECT_MISSION =
-  "You are a senior developer helping a Pi coding agent. Prefer past technical decisions, architecture trade-offs, conventions, and constraints. Be direct and opinionated when memory supports it; do not invent facts not grounded in memory.";
-
-const DEFAULT_PROJECT_RETAIN_MISSION =
-  "Always extract technical decisions, API/architecture trade-offs, blockers, error resolutions, repo conventions, and durable project-local preferences. " +
-  "CRITICAL for conversations: record ONLY the FINAL settled state as what is in effect — when the same rule is amended, keep only the LAST choice; superseded proposals appear only as rejected alternatives, never as active decisions. " +
-  "Ignore greetings, small talk, scheduling logistics, secrets, probe/bait harness instructions (e.g. temporary 'do not ask questions' test rules), and resurfaced recalled memory unless it adds a new correction or decision.";
-
-const DEFAULT_PROJECT_OBSERVATIONS_MISSION =
-  "Identify evolving durable project patterns, recurring constraints, architectural preferences, and contradictions with prior knowledge. Focus on stable repo-relevant knowledge — not transient task state, one-off plans, or test-harness noise.";
-
-const DEFAULT_GLOBAL_REFLECT_MISSION =
-  "You are a coding assistant with durable cross-project context. Personalize using stable user preferences, workflows, and communication style. Be direct; prefer high-signal clarifications over speculation.";
-
-const DEFAULT_GLOBAL_RETAIN_MISSION =
-  "Extract durable cross-project memory: user preferences (including clarification/communication style), recurring workflows, coding habits, and stable assistant behavior. Ignore greetings, secrets, probe/bait session rules, repo-specific code facts, file paths, and project-local bugs unless they generalize across projects.";
-
-const DEFAULT_GLOBAL_OBSERVATIONS_MISSION =
-  "Identify durable cross-project preferences, recurring workflows, coding habits, and stable assistant behavior patterns. Highlight contradictions with prior knowledge. Ignore repo-specific implementation details and one-off probe constraints unless they generalize.";
-
-/** Life / conversation user bank — personal durable context, not coding-repo facts. */
-const DEFAULT_LIFE_REFLECT_MISSION =
-  "You are a personal assistant with durable life and task context. Use stable preferences, commitments, people/context, and planning habits. Be concise and practical; prefer high-signal clarifications over speculation. Do not invent personal facts not grounded in memory.";
-
-const DEFAULT_LIFE_RETAIN_MISSION =
-  "Extract durable personal and life-task memory: communication preferences, commitments, deadlines, people/roles/context, planning and prioritization habits, and stable constraints. Ignore greetings, secrets, probe/bait harness rules, and repo-specific engineering details (file paths, bugs, PR mechanics) unless they are truly personal durable preferences.";
-
-const DEFAULT_LIFE_OBSERVATIONS_MISSION =
-  "Identify durable life and task patterns: recurring preferences, commitments, relationship/context patterns, and planning habits. Highlight contradictions with prior knowledge. Ignore transient chat filler, one-off logistics, and coding-repo implementation noise.";
-
-export interface BankMissionDefaults {
-  reflectMission: string;
-  retainMission: string;
-  observationsMission: string;
-}
-
-export function defaultProjectBankMissions(): BankMissionDefaults {
-  return {
-    reflectMission: DEFAULT_PROJECT_REFLECT_MISSION,
-    retainMission: DEFAULT_PROJECT_RETAIN_MISSION,
-    observationsMission: DEFAULT_PROJECT_OBSERVATIONS_MISSION,
-  };
-}
-
-export function defaultGlobalBankMissions(): BankMissionDefaults {
-  return {
-    reflectMission: DEFAULT_GLOBAL_REFLECT_MISSION,
-    retainMission: DEFAULT_GLOBAL_RETAIN_MISSION,
-    observationsMission: DEFAULT_GLOBAL_OBSERVATIONS_MISSION,
-  };
-}
-
-/** Defaults for Life / conversation user bank (agentUse conversation). */
-export function defaultLifeBankMissions(): BankMissionDefaults {
-  return {
-    reflectMission: DEFAULT_LIFE_REFLECT_MISSION,
-    retainMission: DEFAULT_LIFE_RETAIN_MISSION,
-    observationsMission: DEFAULT_LIFE_OBSERVATIONS_MISSION,
-  };
-}
-
-/** User/life bank defaults: conversation → life missions; coding → cross-project coding prefs. */
-export function defaultUserBankMissions(agentUse: AgentUseProfile = "coding"): BankMissionDefaults {
-  return agentUse === "conversation" ? defaultLifeBankMissions() : defaultGlobalBankMissions();
-}
-
-export interface BankMissionConfig extends BankMissionSettings {
-  enableObservations?: boolean;
-  /** Selects life vs coding-user mission defaults when creating a user bank. */
-  agentUse?: AgentUseProfile;
-}
-
-export function resolveBankMissions(
-  config: BankMissionSettings,
-  defaults: BankMissionDefaults,
-): BankMissionDefaults {
-  return {
-    reflectMission: config.reflectMission ?? defaults.reflectMission,
-    retainMission: config.retainMission ?? defaults.retainMission,
-    observationsMission: config.observationsMission ?? defaults.observationsMission,
-  };
-}
-
-function isNotFoundError(error: unknown): boolean {
-  if (typeof error !== "object" || !error) return false;
-  const fields = error as {
-    status?: unknown;
-    statusCode?: unknown;
-    code?: unknown;
-    message?: unknown;
-  };
-  return (
-    fields.status === 404 ||
-    fields.statusCode === 404 ||
-    fields.code === 404 ||
-    fields.code === "404" ||
-    (typeof fields.message === "string" && /\b404\b|not found/i.test(fields.message))
-  );
-}
-
-async function bankNeedsCreate(client: HindsightLikeClient, bankId: string): Promise<boolean> {
-  if (!client.getBankProfile) return false;
-  try {
-    await client.getBankProfile(bankId);
-    return false;
-  } catch (error) {
-    if (isNotFoundError(error)) return true;
-    throw error;
-  }
-}
-
-export async function ensureProjectBank(
-  client: HindsightLikeClient,
-  bankId: string,
-  config: BankMissionConfig = {},
-): Promise<void> {
-  if (!client.createBank || !(await bankNeedsCreate(client, bankId))) return;
-  const missions = resolveBankMissions(config, defaultProjectBankMissions());
-  await client.createBank(bankId, {
-    name: bankId,
-    ...missions,
-    retainExtractionMode: "concise",
-    enableObservations: config.enableObservations ?? true,
-    ...(config.retainStructuredChunkSize !== undefined
-      ? { retainStructuredChunkSize: config.retainStructuredChunkSize }
-      : {}),
-  });
-}
-
-export async function ensureGlobalBank(
-  client: HindsightLikeClient,
-  bankId: string,
-  config: BankMissionConfig = {},
-): Promise<void> {
-  if (!client.createBank || !(await bankNeedsCreate(client, bankId))) return;
-  const missions = resolveBankMissions(
-    config,
-    defaultUserBankMissions(config.agentUse ?? "coding"),
-  );
-  await client.createBank(bankId, {
-    name: bankId,
-    ...missions,
-    retainExtractionMode: "concise",
-    enableObservations: config.enableObservations ?? true,
-    ...(config.retainStructuredChunkSize !== undefined
-      ? { retainStructuredChunkSize: config.retainStructuredChunkSize }
-      : {}),
-  });
-}

package/node_modules/@luxusai/pi-hindsight/extensions/banks/bank-selection.ts

@@ -1,18 +0,0 @@
-import type { ResolvedConfig } from "../types.js";
-
-export function resolveOperationBank(args: {
-  requestedBank: string | undefined;
-  config: ResolvedConfig;
-  projectBankId: string;
-}): string {
-  const requested = args.requestedBank?.trim();
-  if (!requested || requested === "project") return args.projectBankId;
-  if (requested === "global") {
-    if (!args.config.banks.user.enabled)
-      throw new Error("User Hindsight bank is disabled. Enable banks.user first.");
-    if (!args.config.banks.user.bankId)
-      throw new Error("User Hindsight bank ID is not configured.");
-    return args.config.banks.user.bankId;
-  }
-  return requested;
-}

package/node_modules/@luxusai/pi-hindsight/extensions/banks/bank-settings-presenter.ts

@@ -1,46 +0,0 @@
-import { isRecord } from "../config/config-normalize.js";
-
-export type BankSettingsLocation = "Project" | "User";
-
-export interface BankSettingsTarget {
-  location: BankSettingsLocation;
-  bankId: string;
-}
-
-export interface BankSettingsTargetDisplay {
-  location: BankSettingsLocation;
-  bankId: string;
-  locationLabel: string;
-  bankLabel: string;
-  optionLabel: string;
-  reviewLine: string;
-}
-
-export function bankSettingsTargetDisplay(target: BankSettingsTarget): BankSettingsTargetDisplay {
-  return {
-    location: target.location,
-    bankId: target.bankId,
-    locationLabel: `Location: ${target.location}`,
-    bankLabel: `Bank: ${target.bankId}`,
-    optionLabel: `${target.location} bank (${target.bankId})`,
-    reviewLine: `${target.location} → Bank: ${target.bankId}`,
-  };
-}
-
-export function bankSettingsTargetLines(target: BankSettingsTarget): string[] {
-  const display = bankSettingsTargetDisplay(target);
-  return [display.locationLabel, display.bankLabel];
-}
-
-function objectCount(value: unknown): number {
-  return isRecord(value) ? Object.keys(value).length : 0;
-}
-
-export function bankConfigOverrideSummaryLines(response: unknown): string[] {
-  if (!isRecord(response)) return ["Bank overrides: unavailable"];
-  const overrides = isRecord(response.overrides) ? response.overrides : undefined;
-  const config = isRecord(response.config) ? response.config : undefined;
-  const overrideCount = objectCount(overrides);
-  const resolvedCount = objectCount(config);
-  return [`Bank overrides: ${overrideCount}`, `Resolved config fields: ${resolvedCount}`];
-}