@herbertgao/pi-extensions 2026.9.5 → 2026.9.7

package/node_modules/@luxusai/pi-hindsight/docs/adr/002-explicit-routing-strategy-seam.md

@@ -1,169 +0,0 @@
-# ADR 002: Explicit routing strategy seam
-
-## Status
-
-Superseded by [ADR-004](004-lifeos-dual-bank-design.md) (2026-07-03). Kept for historical record; not a live contract.
-
-The typed strategy seam, richer dry-run presenter output, and expanded eval fixtures shipped and were later removed. This ADR's routing-input/output shapes, safety policy, and eval-fixture taxonomy below describe the router as it existed, not current behavior. `userRetain.mode`/`globalRetain.mode` is `"explicit-only"` in every profile today; there is no router mode.
-
-Amendment (2026-06): the `hindsight_route_memory` dry-run tool was removed in the slim-surface rewrite (#417). References to the tool below are historical.
-
-Amendment (2026-07): ADR-004 decided to remove the heuristic memory router entirely rather than revive its dry-run visibility, because it only ever auto-engaged in the narrow "User Only" profile, its own dry-run visibility was already gone, and an unexplainable heuristic classifier making automatic User Bank writes was exactly the silent-pollution risk this ADR warned against. The router, the `RoutingStrategy` seam, and the `"router"` config value were removed; personal-fact retain routing is explicit tools/commands only, matching every other profile.
-
-## Context
-
-Pi Hindsight defaults to safe project-local automatic retain. User Bank automatic retain is disabled unless the user selects a profile or config mode that explicitly enables it. Legacy config/tool aliases still use `global` for this User Bank route.
-
-The current router is intentionally conservative and heuristic. It classifies candidate memory as `project`, `global`, `both`, or `skip`, where `global` is the legacy route name for the configured User Bank. `hindsight_route_memory` exposes the decision as a dry run in explicit-only mode. This is useful, but the seam needs a clear product contract before adding richer bank topologies such as per-user, per-agent, shared-knowledge, or explicit named banks.
-
-The main safety risk is silent User Bank pollution. Better routing must not make User Bank writes the default.
-
-## Decision
-
-Routing remains opt-in for automatic writes. `userRetain.mode = "explicit-only"` stays the default. `globalRetain.mode` remains a legacy compatibility alias, not the preferred user-facing term.
-
-Pi Hindsight treats routing as an explicit strategy seam with stable input and output shapes. The default strategy keeps today's project/User Bank behavior while preserving legacy route values (`project`, `global`, `both`, `skip`) for compatibility. Future strategies may route to additional bank topologies only behind explicit configuration and dry-run inspection.
-
-## Routing input shape
-
-Current implementation uses a compact typed seam:
-
-```ts
-interface RoutingCandidate {
-  content: string;
-  context?: string;
-  config: ResolvedConfig;
-  cwd?: string;
-  projectBankId?: string;
-  sessionFile?: string;
-}
-
-interface RoutingStrategyInput {
-  content: string;
-  context?: string;
-  config: ResolvedConfig;
-  missions: {
-    project: string;
-    global: string; // legacy route name for User Bank mission
-  };
-  cwd?: string;
-  projectBankId?: string;
-  sessionFile?: string;
-}
-```
-
-Future strategies may add normalized identity or channel context only after the source of that identity is documented.
-
-## Routing output shape
-
-The dry-run operation returns an explainable decision:
-
-```ts
-type MemoryRoute = "project" | "global" | "both" | "skip";
-type RoutingBankRole = "project" | "global";
-
-interface MemoryRouteDecision {
-  route: MemoryRoute;
-  confidence: number;
-  signals: Array<"project" | "global" | "skip">;
-  matchedSignals: string[];
-  reason: string;
-  mode: "explicit-only" | "router";
-  writes: RoutingBankRole[];
-  targets: Array<{
-    bankRole: RoutingBankRole;
-    bankId: string;
-    tags: string[];
-    willWrite: boolean;
-  }>;
-  safetyNotes: string[];
-  projectMission: string;
-  globalMission: string; // legacy route name for User Bank mission
-}
-```
-
-The legacy `global` route name should be preserved until a compatibility break is intentional. User-facing copy should describe that target as User Bank memory.
-
-## Safety policy
-
-- `explicit-only` means dry-run only. No automatic User Bank writes.
-- Router mode must be opt-in and visible in `/hindsight` status/config.
-- User Bank writes require high confidence or explicit user action.
-- Ambiguous project/User Bank content should prefer `both` with conservative tags, or ask/dry-run rather than silently picking User Bank.
-- Secrets, private URLs, bearer tokens, cookies, and transient artifact paths should route to `skip` or require redaction before retain.
-- Metadata records provenance; tags control scope and visibility.
-- Recalled memory must not be routed back into retain.
-
-## Strategy seam
-
-Implemented strategy:
-
-1. `project-global-default`: current project/User Bank/both/skip classifier using missions and heuristics. The implementation keeps `global` in type names as a legacy route value.
-
-Future strategies:
-
-1. `dry-run-only`: always produces an explainable decision but writes nothing.
-2. `named-bank`: resolves explicit named bank targets once config supports them.
-3. `identity-aware`: includes per-user/per-agent context only after identity source is documented.
-
-The seam should not know Pi provider internals. It should receive normalized routing input from lifecycle/tool code.
-
-## Eval fixture taxonomy
-
-Routing evals should continue to cover at least:
-
-- durable User Bank preference
-- stable identity preference
-- cross-project workflow habit
-- project architecture fact
-- project implementation decision
-- project delivery state
-- project-scoped user preference
-- identity-like fact embedded in project work
-- ambiguous project/User Bank content
-- secret or credential-like content
-- transient screenshot/artifact
-- temporary command/test output
-
-Fixtures should assert:
-
-- route
-- confidence band or minimum confidence
-- matched signal categories
-- safety notes where relevant
-- write targets in router mode
-- no writes in explicit-only mode
-
-## Tool and TUI implications
-
-`hindsight_route_memory` remains the primary dry-run surface for routing decisions. It should show:
-
-- suggested route
-- confidence
-- target bank roles and IDs
-- tags that would be applied
-- reason and matched signals
-- safety notes
-- whether the current mode would write or only preview
-
-A future `/hindsight` TUI route preview can call the same operation and should avoid duplicating routing logic.
-
-## Consequences
-
-- Safe defaults remain unchanged.
-- Future routing work has a stable contract instead of adding ad hoc conditions to lifecycle retain.
-- Richer bank topologies remain possible without coupling core to a specific platform identity model.
-- More tests are required before enabling any new automatic route.
-
-## Follow-up implementation status
-
-Completed:
-
-- #154: Update `hindsight_route_memory` presenter to include target bank roles, tags, safety notes, and explicit write/no-write status.
-- #155: Expand router eval fixtures with secret/noise/ambiguous confidence cases and safety-note assertions.
-- #156: Add a `RoutingStrategy` type and adapter boundary separate from current heuristic implementation.
-
-Still future:
-
-- Add a TUI route-preview action that calls the shared routing operation.
-- Design named-bank resolver config before supporting per-user/per-agent/shared-bank targets.

package/node_modules/@luxusai/pi-hindsight/docs/adr/003-tui-memory-mode-vocabulary.md

@@ -1,107 +0,0 @@
-# ADR 003: TUI memory mode vocabulary
-
-## Status
-
-Accepted and implemented for `normal`, `read-only`, and `ignored`. Reviewed 2026-05-09; still relevant.
-
-`tools-only` remains reserved vocabulary and must not appear as an enabled mode until behavior is implemented.
-
-## Context
-
-Pi Hindsight has separate controls for recall, automatic retain, explicit tools, imports, flush, and one-turn opt-out. Those controls are correct but too implementation-shaped for the `/hindsight` TUI. Users need a small vocabulary that explains what memory will do without changing the underlying safe defaults.
-
-The design should not add provider recall caching, prompt hashtag controls, automatic reflect prefetch, or new routing behavior.
-
-## Decision
-
-The TUI (and historically `/hindsight:mode`) describe session memory behavior with three implemented user-facing modes and one reserved future mode:
-
-1. `normal`
-2. `read-only`
-3. `ignored`
-4. future `tools-only`
-
-`normal` is the default mode. `read-only` and `ignored` map to existing session behavior. `tools-only` is reserved vocabulary for a future slice and must not appear as an enabled option until implemented.
-
-These names are TUI vocabulary, not a replacement for the lower-level config model. Existing config keys remain source of truth for recall, retain, import, and routing behavior.
-
-## Mode matrix
-
-| Mode                | Automatic recall | Automatic retain | Explicit tools and commands                                       | Import  | Flush queued jobs | Intended use                                             |
-| ------------------- | ---------------- | ---------------- | ----------------------------------------------------------------- | ------- | ----------------- | -------------------------------------------------------- |
-| `normal`            | on if configured | on if configured | allowed                                                           | allowed | allowed           | Default coding with project memory continuity.           |
-| `read-only`         | on if configured | off              | read tools allowed; explicit retain is blocked until mode changes | allowed | allowed           | Use existing memory without adding new transcript facts. |
-| `ignored`           | off              | off              | explicit operations remain available from commands/tools          | allowed | allowed           | Work without automatic memory participation.             |
-| future `tools-only` | off              | off              | allowed                                                           | allowed | allowed           | No automatic memory; user manually calls tools.          |
-
-## Semantics
-
-### `normal`
-
-`normal` means Pi Hindsight follows configured automatic behavior:
-
-- recall injects ephemeral memory before answer generation when enabled
-- retain queues sanitized transcript deltas at agent end when enabled
-- User Bank automatic retain stays governed by `userRetain.mode` and profile choices; `globalRetain.mode` remains only a legacy alias
-- explicit tools and TUI actions are available
-- imports and queue flushes are available
-
-### `read-only`
-
-`read-only` means automatic writes are disabled while reads stay available:
-
-- automatic recall can still run
-- automatic retain does not enqueue new transcript deltas
-- explicit retain is blocked until the session returns to `normal`; other deliberate write operations such as imports keep their own confirmations
-- imports remain deliberate operations, not automatic session retention
-- queue flush remains allowed because it drains already accepted jobs
-
-### `ignored`
-
-`ignored` means automatic memory is out of the provider path:
-
-- no automatic recall injection
-- no automatic retain
-- explicit commands and tools still exist for power users
-- imports and queue maintenance are not disabled by the mode
-- status should make the automatic-memory-off state obvious
-
-### future `tools-only`
-
-`tools-only` is a reserved term for a future mode where automatic memory is off but explicit tools are first-class. It should only ship after the command/tool behavior is tested and documented as distinct from `ignored`.
-
-## TUI presentation
-
-The `/hindsight` TUI should prefer these labels when explaining session memory state:
-
-- `normal`: "Automatic recall/retain follow config."
-- `read-only`: "Recall can read; automatic retain is off."
-- `ignored`: "Automatic recall and retain are off."
-- future `tools-only`: "Automatic memory is off; explicit tools stay available."
-
-The TUI should still expose underlying facts where useful, such as recall enabled/disabled, retain enabled/disabled, User Bank retain mode, queue state, and bank status.
-
-## Non-goals
-
-- Do not change defaults.
-- Do not add prompt hashtag controls.
-- Do not add provider recall caching.
-- Do not prefetch reflect results automatically.
-- Do not collapse import or explicit retain semantics into automatic retain.
-- Do not make User Bank automatic retain default.
-
-## Follow-up implementation status
-
-Completed:
-
-1. Add a presenter that derives the TUI mode label from resolved config plus session metadata.
-2. Add status facts for the mode matrix row currently in effect.
-3. Add TUI copy for `normal`, `read-only`, and `ignored`.
-
-Still future:
-
-1. Keep `tools-only` documented as reserved until behavior is implemented.
-
-## Consequences
-
-This gives the TUI a stable mental model without changing memory behavior. It also keeps safety boundaries explicit: automatic read/write behavior is separate from deliberate user operations such as imports, explicit retain, and queue flushing.

package/node_modules/@luxusai/pi-hindsight/docs/adr/004-lifeos-dual-bank-design.md

@@ -1,89 +0,0 @@
-# ADR 004: lifeOS dual-bank design (project + user memory)
-
-## Status
-
-Accepted 2026-07-03.
-
-Amendment (2026-07-10): **ADR-005** changes the long-term default **Project Bank** shape from “one path-derived bank per repo” toward a **coding domain bank + project tags**, and renames the user-facing cross-project bank path toward **Life Bank**. This ADR’s decision **(b)** still holds: Life/User Bank stays **opt-in**, automatic retain never writes there, and dual-bank recall budgets remain. Topology and agent-first surface details live in ADR-005; do not re-read this ADR as requiring one bank per absolute path forever.
-
-Amendment (2026-07): the "What stays in the web UI" section below cited `docs/surface-reference.md`'s deferred-surfaces table for "template management remains a Hindsight control-plane responsibility." That table (generated from the operation catalog) never actually listed template management as a row; the citation was inaccurate, not a decision this ADR made. Separately, #467 narrowed the underlying claim: `pi-hindsight` now bundles a small, fixed set of starter bank templates (`/hindsight:templates`, `/hindsight:template-apply`) applied via the official Hindsight client's bank-template import endpoint. Arbitrary template authoring, editing, export, and cross-bank template catalog browsing remain control-plane-only; applying one of the two bundled, reviewed templates to the already-selected bank does not. ADR-005 further allows **agent tools** for selected-bank mental-model and mission maintenance as core.
-
-## Context
-
-Pi Hindsight already supports two kinds of memory: a per-repo **Project Bank** and an optional cross-project **User Bank** (the "lifeOS" memory — durable preferences, recurring workflows, coding habits). #420 built tag-group scope isolation specifically so recall could merge both banks safely. This ADR answers the question #424 asked: should the User Bank become a first-class default next to the Project Bank, or stay opt-in, and what should happen to the heuristic memory router along the way.
-
-### Current state
-
-- Dual-bank recall already works. When a repo's config enables `banks.user`, `selectMemoryScopes` returns both a project scope and a user scope; `recallForContext` queries each bank independently and merges the rendered blocks. This is exposed today as the **"Project + User"** guided-setup profile (`docs-site/src/content/docs/start/memory-profiles.md`), alongside "Project Only", "User Only", and "Recall Only".
-- Automatic retain is project-only in every profile except "User Only". Even in "Project + User", the User Bank only receives writes through explicit tools (`hindsight_retain_global`) or commands — never automatically. This is a deliberate safety choice from ADR-002 ("User Bank writes require high confidence or explicit user action") and is unchanged by this ADR.
-- A heuristic memory router (`extensions/operations/memory-router.ts`, `extensions/lifecycle/routing-strategy.ts`) exists to auto-classify candidate retain content as `project`/`global`/`both`/`skip` using regex keyword patterns and mission-term matching. It only auto-engages when `userRetain.mode: "router"`, which the guided-setup writer only sets for the **"User Only"** profile (no project bank to fall back to). Its own dry-run inspection tool (`hindsight_route_memory`) was already removed in the slim-surface rewrite (#417), so it now runs with no user-visible explanation of its decisions. It carries ~580 lines of implementation plus 38 parametrized eval-fixture tests.
-- **Recall token budget is not split across banks.** `recallForContext` requests the full `config.recall.maxTokens` independently for every active scope. Enabling the User Bank alongside the Project Bank can silently double (or more) the memory tokens injected into every turn; nothing documents or bounds this today.
-- Config migration from the legacy `global` naming (`banks.global` → `banks.user`, `globalRetain` → `userRetain`, `globalQueryPreamble` → `userQueryPreamble`) already exists and is unaffected by this ADR.
-
-## Options considered
-
-**(a) Dual-bank default.** Enable both banks out of the box for new setups, with merged recall and routed retain.
-**(b) Opt-in User Bank with polished setup.** Keep today's model — User Bank is a deliberate choice via guided setup — and harden the gaps (budget split, router observability) rather than changing the default.
-**(c) Single project bank with user-visibility tags.** Drop the separate User Bank; mark durable facts with a tag inside the project bank instead.
-
-(c) is rejected outright: Hindsight banks are the isolation boundary, not tags. A single project bank is tied to one repo's bank ID (`deriveProjectBankId`); there is no way to recall those tagged facts while working in a _different_ repository without querying a different bank, which defeats the entire cross-project ("lifeOS") purpose. Collapsing to one bank would also regress ADR-001's invariant that project recall is repo-scoped, since "user-visible" facts would need to leak across repo tag boundaries to be found at all.
-
-The real choice is (a) vs (b).
-
-## Decision
-
-**(b): keep the User Bank opt-in; harden the existing design instead of changing the default.**
-
-This repo has a consistent, deliberate pattern of conservative defaults — `postRetainReflect` off, `userRetain.mode` explicit-only, User Bank disabled — and ADR-002 already states "Do not make User Bank automatic retain default" as a standing invariant. Defaulting the User Bank on would also mean every new install needs a second Hindsight bank configured before first use, and would silently increase the default token cost of every recall. Given Pi Hindsight's "Pi-first 1.0" scope and existing safe-by-default posture, that tradeoff is not justified today. Nothing here forecloses revisiting (a) once usage data suggests otherwise — that would be a new ADR, not a reinterpretation of this one.
-
-**The heuristic memory router is removed.** It only ever auto-engaged in the narrow "User Only" profile, its own dry-run visibility was already deleted, and a regex/keyword classifier with no user-facing explanation is exactly the kind of unmonitorable automatic write ADR-002 warned against ("The main safety risk is silent User Bank pollution"). The issue's own framing — "whether the pattern router earns its complexity or is replaced by explicit tools/commands" — is answered: replaced. "User Only" automatic retain falls back to the same explicit-only model every other profile already uses; users write User Bank memory with `hindsight_retain_global` or a command, same as "Project + User" users do today.
-
-## Recall merging and token budget split
-
-Each active scope must have a bounded, independent budget so enabling the User Bank cannot silently balloon per-turn token cost. Concretely:
-
-- `recall.maxTokens` keeps its current meaning and default (800) and continues to bound the **Project Bank** scope only. Existing project-only and project+user users see no change in Project Bank recall behavior.
-- A new `recall.userMaxTokens` (default: half of `recall.maxTokens`, i.e. 400) bounds the **User Bank** scope specifically when it participates in a recall call. User memory is meant to be a smaller, durable supplement to project context, not an equal-weight second corpus.
-- Both caps apply independently per bank query (as today), not as a shared pool — this keeps the change backward compatible and avoids new cross-scope coordination logic. The ceiling that changes is that User Bank recall no longer defaults to the same size as Project Bank recall.
-- This is a new config field with a real default, not a documentation-only fix, so it is implementation work for a follow-up issue, not this ADR.
-
-## Retain routing policy for personal vs. project facts
-
-- Automatic retain stays project-bank-only in every profile. There is no automatic classifier deciding "this fact is personal, route it to the User Bank."
-- Personal/durable facts reach the User Bank only through deliberate action: the `hindsight_retain_global` tool, or a future `/hindsight:retain-global`-style command if usage shows a need for one (not requested by this ADR).
-- `userRetain.mode` drops the `"router"` variant. The type becomes effectively single-valued (`"explicit-only"`) going forward; keeping the field (rather than deleting it outright) preserves config-file compatibility and gives room for a future, better-specified routing strategy without another rename.
-- Migration: existing configs with `userRetain.mode: "router"` (or the legacy `globalRetain.mode: "router"`) must normalize to `"explicit-only"` rather than erroring, consistent with how `enumValue()` already falls back to the default for invalid enum values today.
-
-## Bank missions and dispositions per use case
-
-No changes. `defaultProjectBankMissions()` and `defaultGlobalBankMissions()` (`extensions/banks/bank-operations.ts`) already give the Project Bank a repo-architecture/engineering-decision mission and the User Bank a durable-preferences/cross-project-workflow mission, and both are overridable via bank config. This split already matches "lifeOS vs coding" use cases well and needs no rework here.
-
-## Migration for existing configs
-
-- The existing `banks.global` → `banks.user` / `globalRetain` → `userRetain` / `globalQueryPreamble` → `userQueryPreamble` migration (`migrateUserMemoryConfigFile`) is unaffected.
-- New: `userRetain.mode: "router"` (and the legacy `globalRetain.mode: "router"`) must migrate/normalize to `"explicit-only"` once the router is removed, so existing "User Only" adopters keep working without a config error, just with automatic User Bank writes disabled until they explicitly retain.
-
-## What stays in the web UI
-
-Unchanged from the existing 1.0 support scope (`docs/surface-reference.md`'s "Deferred or non-goal upstream surfaces" table): cross-bank listing and bank deletion remain Hindsight control-plane responsibilities. Template management is narrower after #467: `pi-hindsight` bundles a small, fixed set of reviewed starter templates and can apply one to the already-selected bank, but arbitrary template authoring, editing, export, and a general template catalog stay control-plane-only. This ADR is only about which already-selected banks participate in a given repo's recall/retain and how routing between them works — not about managing banks themselves.
-
-## Consequences
-
-- No default behavior changes for existing Project Only, Recall Only, or Project + User users, other than the new `recall.userMaxTokens` cap (once #460 lands) applying to whichever of them already have the User Bank enabled.
-- "User Only" lost automatic classifier-driven retain; those users must use explicit retain (tool or future command) for User Bank writes going forward. This is a narrower, more predictable contract, consistent with every other profile.
-- `extensions/operations/memory-router.ts`, `extensions/lifecycle/routing-strategy.ts`, and `tests/memory-router.test.ts` are removed, along with the `"router"` value from `userRetain.mode`/`globalRetain.mode` and the router-eval-fixture taxonomy documented in ADR-002.
-- ADR-002 (explicit routing strategy seam) is superseded by this decision for the router's future; its routing-input/output shape documentation is historical context, not a live contract to maintain (see the amendment added to ADR-002).
-- A new `recall.userMaxTokens` config field, default value, and normalization will ship once #460 lands.
-
-## Follow-up implementation issues
-
-Filed from this ADR's acceptance, per #424's acceptance criteria:
-
-Completed:
-
-- #459: remove the heuristic memory router (`memory-router.ts`, `routing-strategy.ts`, router eval tests), drop `"router"` from the `userRetain.mode`/`globalRetain.mode` type, and add config migration/normalization so existing `"router"`-mode configs fall back to `"explicit-only"` without erroring. Also updated `CONTEXT.md`, `CONTRIBUTING.md`, `docs/architecture-todos.md`, `docs/memory-behavior.md`, and this ADR's ADR-002 amendment.
-
-Still future:
-
-- #460: add `recall.userMaxTokens` (default 400) and apply it to the User Bank recall scope in `recallForContext`, independent of `recall.maxTokens`.
-- Update `docs-site/src/content/docs/start/memory-profiles.md`, `docs-site/src/content/docs/concepts/memory-banks.md`, and `docs/compatibility.md` to reflect the per-bank token budget split once #460 lands.

package/node_modules/@luxusai/pi-hindsight/docs/adr/005-domain-banks-and-agent-first-surface.md

@@ -1,189 +0,0 @@
-# ADR 005: Domain banks, project tags, and agent-first surface
-
-## Status
-
-Accepted 2026-07-10 (direction). Implementation is phased via GitHub issues; defaults change only when the corresponding phase lands.
-
-Amends:
-
-- ADR-001 (scope: project isolation remains required; **how** isolation is achieved moves from “per-repo bank + path-hash tag” toward “domain bank + stable project tag”)
-- ADR-004 (User Bank stays opt-in; rename path toward **Life Bank**; “project bank = one bank per repo path” is no longer the long-term default)
-- Resolves direction for #450 (shared/untagged observations are **opt-in**, never implicit)
-
-Supersedes the temporary handoff note on mental-model tools + tag opacity (content moved to issues).
-
-## Context
-
-Three problems stacked:
-
-1. **Topology.** Default path-hashed Project Bank + `repo:<slug>-<pathHash>` is opaque, fragile on machine/path moves, and multiplies banks without improving mission quality.
-2. **Hindsight alignment.** Official best practices treat banks as hard walls (missions, privacy) and tags as soft scope. Mental models use tags for refresh and visibility. Observation scopes must not key on volatile session tags. Multi-client MCP is per-bank.
-3. **Surface.** Early TUI exposed too many edit/default/reset paths, then was cut back. Kai’s product intent: **the Pi agent does hard work** (missions, mental models, config, tags); the human gets **status + short onboarding + emergency actions**. Config remains the durable artifact on disk.
-
-oh-my-pi’s `per-project-tagged` default is a useful sketch (shared bank + project tags + two-tier MMs). We deliberately do **better**: strict project isolation by default, domain split (coding vs life), stable project identity (not basename-only), designed observation scopes, setup gate, migration, agent-first control plane, official client.
-
-## Decision
-
-### 1. Domain banks + project tags (target topology)
-
-| Role (config slot) | What it is                                                    | Typical Hindsight `bankId`      |
-| ------------------ | ------------------------------------------------------------- | ------------------------------- |
-| **Coding bank**    | Domain bank for engineering memory across repos               | e.g. `kai-coding` (user-chosen) |
-| **Life bank**      | Domain bank for personal/assistant memory (evolves User Bank) | e.g. `kai-life`                 |
-| **Isolated bank**  | Escape hatch: one bank dedicated to a sensitive repo          | e.g. `client-acme`              |
-
-**Role vs bankId (review clarification):**
-
-- `coding` / `life` are **stable role identifiers** in Pi config and tools (aliases), like today’s `project` / `global`.
-- `bankId` is the **concrete Hindsight bank name** and can change without renaming the role.
-- Example: `banks.coding.bankId = "kai-coding-v2"` still uses the **coding** slot for automatic project retain/recall; only the server-side bank string changes.
-
-**Scope mode:**
-
-| Mode                                 | Meaning                                                                                                                                                                                                                |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`domain-tagged`** (target default) | Use the **coding** domain bank for all normal repos. Soft-isolate repos with a stable **`project:<id>`** tag on retain and **strict** recall filter on that tag. Optional life bank for cross-cutting personal memory. |
-| **`isolated-bank`**                  | Hard wall: this repo uses its own bank id (legacy-like privacy). Project tags optional inside that bank.                                                                                                               |
-
-**`domain-tagged` in one sentence:** one shared coding bank for many repos; tags say which repo a memory belongs to; the bank’s mission stays “engineering.”
-
-### 2. Project identity (not path hash)
-
-Resolve `projectId` in order:
-
-1. Explicit pin (`scope.projectId` in project or global config)
-2. Normalized git remote (when present)
-3. Git root basename
-4. Cwd basename fallback
-
-Path-hash `repo:` remains only for **legacy detection / migration**, not new writes.
-
-**Documentation requirement:** `projectIdStrategy` and pin behavior need a dedicated short guide (not only a config field name). Humans and agents must see derivation in status (“`project:finalform` from pin” / “from remote `github.com/…`”).
-
-### 3. Where does a per-repo pin go? (review clarification)
-
-Per-repo `.pi/hindsight.json` fields such as `scope.projectId` **do not choose the life bank**. Routing:
-
-| Write path                        | Bank role                                     | Tags                                     |
-| --------------------------------- | --------------------------------------------- | ---------------------------------------- |
-| Automatic retain (coding profile) | **coding**                                    | `project:<id>`, `source:pi`, `session:…` |
-| Explicit project retain           | **coding** (or isolated bank if mode says so) | same                                     |
-| Explicit life / user retain       | **life**                                      | no project tag required; `source:pi`     |
-| Automatic life retain             | **never** (ADR-004 invariant stands)          | —                                        |
-
-So `scope.projectId` answers: **which project tag inside the coding bank**, not “which bank.” Bank selection is profile + `banks.coding` / `banks.life` / isolated mode.
-
-### 4. Shared observations (review clarification + #450)
-
-**Shared observation** means an observation consolidated under Hindsight’s **untagged / global observation scope** inside **one bank** — typically so cross-project coding preferences can form beliefs that are **not** tied to a single `project:` tag.
-
-It does **not** mean:
-
-- shared across different Hindsight banks
-- shared across users/tenants
-- automatic leakage of project A’s facts into project B’s strict recall
-
-Default recall stays **`any_strict` on `project:<id>`**. Reaching shared/untagged observations requires **explicit opt-in** (config or tool flag), composed as an additional filter path (exact empty tags / documented Hindsight pattern). This is the #450 decision: **(a)-style explicit include**, not silent OR, not “shared is unreachable forever.”
-
-Observation scopes on retain must **not** put volatile `session:` into the project observation scope (session tags fragment consolidation). Prefer scopes like `[["project:{projectId}"]]` plus optional `"shared"`.
-
-### 5. Mental models (two altitudes)
-
-Inside the coding bank:
-
-| Tier        | Tags on model                     | Purpose                                            |
-| ----------- | --------------------------------- | -------------------------------------------------- |
-| Bank-global | none (or non-project only)        | How the user codes / collaborates                  |
-| Project     | `project:<id>` + stable id suffix | This repo’s architecture / conventions / decisions |
-
-Inject must filter: bank-global ∪ models matching active project tag.  
-Refresh tags must be a subset of retain tags (Hindsight `all_strict` footgun).
-
-Selected-bank mental-model **tools are core**. Full control-plane catalog browsing stays web UI.
-
-### 6. Agent-first surface, thin TUI
-
-**Principle:** API-rich for the agent; UI-thin for the human; config is the durable artifact the agent maintains.
-
-| Human                                 | Agent                                              |
-| ------------------------------------- | -------------------------------------------------- |
-| Status (read-only, non-default tones) | Status tool (same fields)                          |
-| Short guided onboarding               | Setup / config patch tools                         |
-| Mode, next-opt-out, flush, doctor     | Full control plane tools for **selected** banks    |
-| No edit/default/reset farm            | MM CRUD, mission edit, scope info, migrate dry-run |
-
-**Agent discoverability (review fear):** rich tools only help if the agent knows they exist. Mitigations required in implementation issues:
-
-1. Prefer **grouped multi-action tools** with one clear name (`hindsight_mental_model` + `action`, `hindsight_config` + `action`) over a dozen similarly named tools when possible.
-2. Tool descriptions written as **operating instructions** (when to use, which bank role, safety), not one-line stubs.
-3. Generated surface reference + tools-and-commands docs stay truthful.
-4. Optional later: a short ephemeral “memory ops available” line in status/doctor only — not a second settings UI.
-5. Do **not** rely on TUI to teach the agent.
-
-Thin TUI is intentional; many extensions have no TUI. Status + onboarding + emergencies are enough for humans.
-
-### 7. Setup gate (first install **and** upgrades)
-
-**No bank ensure, auto-retain, or auto-recall network I/O until setup is satisfied.**
-
-Setup is satisfied when config clearly selects banks/mode, including:
-
-**New installs:** guided setup or agent setup tool writes bank ids + scope mode + `setupComplete` (or equivalent predicate).
-
-**Upgrades from older versions (review clarification):** treat as already set up when any of:
-
-- explicit `banks.project.bankId` / `banks.coding.bankId` / user-life bank id present
-- project/global config files already exist with bank/enable settings from prior pi-hindsight versions
-- durable local runtime state that only appears after real use (e.g. retain cursor / queue files) **together with** enabled project bank — normalize by writing `setupComplete: true` (or the equivalent flag) on first load so users are not forced through onboarding again
-
-Never force re-onboarding on upgrade solely because the new flag is missing. Prefer **silent migration to “configured”** for existing adopters; show status tones for “legacy path-hash identity — consider migrate” rather than blocking memory.
-
-Until configured (true first-run only): status says setup required; tools that need a bank return a clear setup error; **no silent path-derived bank creation**.
-
-### 8. Status tones
-
-Status is the primary human dashboard: banks, project tag + derivation, missions present, MM counts, queue, reachability. Compare to defaults:
-
-- quiet = default for profile
-- accent = non-default but valid
-- warn = broken / setup incomplete / scope mismatch
-- dim = intentionally disabled
-
-Read-only; changes go through agent tools or guided setup.
-
-## Consequences
-
-- Implementation is multi-phase (setup gate → stable projectId → domain default → agent tools → MM inject filter → shared recall → migrate). Do not ship a silent topology flip without migration docs.
-- ADR-004’s “User Bank opt-in / no automatic user retain” remains. Life Bank is the user-facing name; aliases stay during transition.
-- Core-vs-companion: selected-bank MM/mission/config tools move to **core**; platform-wide admin stays web.
-- #450: implement explicit include-shared path; document that shared ≠ cross-bank.
-- Tests must cover: setup gate, upgrade migration, projectId stability, MM inject isolation, no ensure without setup.
-
-## Out of scope for this ADR
-
-- Implementing all phases in one PR
-- One mega-bank for code + life + medical
-- Platform-wide bank list/delete in Pi
-- In-housing the Hindsight client
-
-## Follow-up issues
-
-Filed from this ADR (titles may be adjusted):
-
-1. Setup gate + upgrade migration + short onboarding
-2. Status fields with non-default tones
-3. Stable projectId + doctor scope diagnostics
-4. Domain coding bank default + profiles
-5. Agent tools (config, bank mission, mental models, scope)
-6. Slim TUI hub
-7. MM inject filter + template project tags
-8. includeSharedObservations (#450 implementation)
-9. Scope migrate dry-run / dual-tag
-10. MCP multi-client docs
-
-## References
-
-- Hindsight best practices (banks, tags, missions, MM tag strategy)
-- Hindsight 0.7–0.8.4 changelog (observation scopes, shared, exact untagged, export/import, MM stale/cron)
-- oh-my-pi Hindsight case study (inspiration, not ceiling)
-- #450, ADR-001, ADR-004

package/node_modules/@luxusai/pi-hindsight/docs/coding-memory-evaluation.md

@@ -1,54 +0,0 @@
-# Coding memory evaluation notes
-
-What Vectorize’s own evaluation surface implies for **pi-hindsight** defaults. Not a harness in this repo—alignment notes for agents and maintainers.
-
-## Sources
-
-| Source                                   | What it measures                                                                                                                 | Link                                                                                                                                                                                                                                               |
-| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Hindsight continuous perf monitor        | Retain throughput, recall p95, recall+obs, temporal recall, consolidation throughput, graph maintenance                          | [dashboard](https://vectorize-io.github.io/hindsight-continuous-performance-monitor)                                                                                                                                                               |
-| AMB (Agent Memory Benchmark)             | Accuracy **and** latency/token cost; modes `rag` / `agentic-rag` / `agent` (native reflect); datasets include PersonaMem (prefs) | [repo](https://github.com/vectorize-io/agent-memory-benchmark), [leaderboard](https://agentmemorybenchmark.ai)                                                                                                                                     |
-| sde-bench                                | Does a **coding agent** benefit from memory on non-guessable project decisions? `conversation` vs `history` source               | [repo](https://github.com/vectorize-io/sde-bench)                                                                                                                                                                                                  |
-| Best practices / oh-my-pi / MM deep dive | Retain/recall/reflect hygiene; MM seeds; delta refresh                                                                           | [best practices](https://hindsight.vectorize.io/best-practices), [oh-my-pi post](https://hindsight.vectorize.io/blog/2026/06/08/oh-my-pi-hindsight-memory), [MM deep dive](https://hindsight.vectorize.io/blog/2026/06/05/mental-models-deep-dive) |
-
-## Implications → pi-hindsight defaults
-
-| Learning                                                                             | Extension implication                                                                                        |
-| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
-| Conversation-only decisions are the hard discriminator for strong models (sde-bench) | Auto-**retain** of real Pi sessions is the product; do not rely on git alone                                 |
-| Ranking amid noise is the problem                                                    | Prefer observations + **narrow** mental models over dumping raw facts every turn                             |
-| Cost is co-equal with accuracy (AMB)                                                 | Cap MM `max_tokens` (600–800 seeds); keep recall budgets mid/low unless deep context is required             |
-| Consolidation is a server hot path (perf monitor)                                    | Client should not re-synthesize every turn: inject cached MMs; use **delta** + `refresh_after_consolidation` |
-| Prefs applied to multi-step work (PersonaMem / AMB)                                  | Bank-global prefs MM + explicit retain of durable prefs (not probe harness noise)                            |
-| Life vs coding user banks                                                            | Coding user bank: cross-project coding prefs missions; conversation/life: `defaultLifeBankMissions()`        |
-| Retain then same-turn recall is an anti-pattern                                      | Retain at `agent_end`; recall at `context` (already)                                                         |
-| One MM for everything is an anti-pattern                                             | One model per knowledge dimension (architecture / conventions / decisions / prefs)                           |
-
-## What we intentionally do **not** do
-
-- Auto-`reflect` every turn (expensive; tools already expose reflect).
-- Mega bank-global “everything about the user” models.
-- Pre-summarizing before retain.
-- Silent background MM create on every boot (setup / hub `t` is explicit).
-- Default session-start `reflect` or per-repo banks (ADR-005 domain-tagged + Pi `context`/`recall` stay).
-
-## Conversation / amended-rule eval tasks (in-repo)
-
-sde-bench treats **non-guessable project decisions from conversation** (including later amendments that must win) as the hard discriminator. We do **not** vendor sde-bench; we encode client-side signals that preserve that evaluation path:
-
-| Task id                 | Scenario                                                        | What must hold in pi-hindsight                                                                                                               | Enforced by                                                                       |
-| ----------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `conv-final-state`      | User proposes rule A, then amends to rule B in the same session | Project + conversation retain missions require FINAL/LAST state only; superseded proposals only as rejected                                  | `tests/coding-memory-eval.test.ts`, bank missions / `CONVERSATION_RETAIN_MISSION` |
-| `conv-not-git-only`     | Decision exists only in chat, not in git history                | Live session retain uses strategy `conversation` and remains the product core; git seed is opt-in only                                       | retain job strategy + seed tool dry-run defaults                                  |
-| `tool-noise`            | Assistant runs many tools with large args                       | Compact tool-call write-back keeps name + target, drops full args by default                                                                 | `retain.compactToolCalls` + retain projection tests                               |
-| `amended-cross-session` | Later session revises an earlier rule                           | Append + stable live document IDs + final-state mission text (server consolidation); client does not re-emit intermediate proposals as facts | missions + append/cursor design (docs)                                            |
-
-Release validation priority: **conversation-amended / cross-session consolidation** over git-only smoke. Prefer live or fixture paths that retain a short decision chat that revises itself, then recall/reflect for the **last** rule.
-
-## Related issues
-
-- Setup ensure project + bank-global starters: #528
-- Delta MM triggers on templates: #529
-- MM size discipline: #530
-- Mission wording vs best practices: #531
-- Coding-agents shortlist stack: #557–#562