@herbertgao/pi-extensions 2026.9.6 → 2026.9.8

package/node_modules/@luxusai/pi-hindsight/docs/next-opt-out-design.md

@@ -1,164 +0,0 @@
-# One-turn memory opt-out design
-
-This document defines the preferred one-turn memory control for Pi Hindsight. It intentionally avoids prompt hashtag parsing such as `#nomem`.
-
-## Problem
-
-Users sometimes need a fast way to keep the next agent run out of automatic memory retention without changing the whole session mode.
-
-Examples:
-
-- The next prompt contains throwaway sensitive material.
-- The next run is exploratory noise that should not become project memory.
-- The user wants a quick one-shot control discoverable through Pi command autocomplete.
-
-## Decision
-
-Implemented in PR #55.
-
-Use an explicit command:
-
-```text
-/hindsight:next-opt-out
-```
-
-Do not parse prompt hashtags.
-
-## Why command-based control
-
-Pi command autocomplete makes the command discoverable by typing `next`, `opt`, or `out`.
-
-A command is better than prompt parsing because it is:
-
-- explicit in command history
-- independent of Markdown syntax
-- testable without parsing arbitrary prose
-- less likely to be copied by agents into generated content
-- easier to reason about during import and cursor handling
-
-## Current semantics
-
-`/hindsight:next-opt-out` applies once to the next completed agent run in the current session.
-
-It disables automatic retain for that run only.
-
-It does not disable recall. The user may still want memory context to answer the prompt, while not retaining the new prompt/result.
-
-It does not affect explicit memory tools. If an agent or user explicitly calls `hindsight_retain`, that explicit retain remains intentional and should still work.
-
-It does not affect historical import. Import reads the transcript as source material and is governed by import commands, not transient one-turn state.
-
-It stores state outside provider-visible messages, alongside existing session memory metadata.
-
-After the next completed agent run is skipped, the opt-out flag is consumed and cleared.
-
-## Interactions
-
-### `/hindsight:mode ignored`
-
-Ignored mode already disables recall and retain for the session. `next-opt-out` is redundant while ignored mode is active.
-
-### `/hindsight:mode read-only`
-
-Read-only mode already disables retain while allowing recall. `next-opt-out` is redundant while read-only mode is active.
-
-### `/hindsight:retain off`
-
-Retain off already disables automatic retain for the session. `next-opt-out` is redundant while retain is off.
-
-### Retain cursor
-
-When `next-opt-out` skips a run, the retain cursor should mark the skipped projected messages as handled. Otherwise those messages could be retained on a later overlapping `agent_end` event after the one-turn opt-out expires.
-
-This matches current read-only and ignored mode behavior.
-
-### Recall
-
-Recall remains enabled unless another session mode disables it. This keeps the command narrow and avoids surprising users who only wanted to prevent storage.
-
-A future command could add recall control explicitly, but it should not be overloaded into this first command.
-
-## User-facing behavior
-
-Command:
-
-```text
-/hindsight:next-opt-out
-```
-
-Success message:
-
-```text
-Hindsight will skip automatic retain for the next agent run in this session. nextRetain=off
-```
-
-Session status should show pending one-turn opt-out:
-
-```text
-Hindsight session mode=normal; recall=true; retain=true; nextRetain=off; tags=none
-```
-
-When consumed, the activity notification says:
-
-```text
-Hindsight skipped retain for this run due to next-opt-out.
-```
-
-## Storage shape
-
-Extend session memory metadata with a non-provider-visible field:
-
-```json
-{
-  "nextRetainMode": "off"
-}
-```
-
-The default is `"normal"`.
-
-Clearing the one-turn opt-out normalizes the field back to `"normal"`.
-
-## Implemented tests
-
-Tests assert external behavior, not internal helper details.
-
-Covered:
-
-- session metadata persists and consumes a one-turn retain opt-out
-- next `agent_end` skips automatic retain
-- skipped messages are added to retain cursor so they are not retained later
-- opt-out clears after one completed agent run
-
-Additional coverage added after implementation:
-
-- command handler sets a pending one-turn retain opt-out
-- `/hindsight:session` reports pending opt-out
-- explicit `hindsight_retain` still queues normally while next opt-out is pending
-- historical import ignores next opt-out state
-
-Additional coverage added after fail-closed hardening:
-
-- recall still runs while next retain is off
-- ignored/read-only/retain-off modes remain stronger than next opt-out
-- next opt-out remains pending if retain cursor marking fails
-
-## Out of scope
-
-- `#nomem` or any prompt hashtag parsing
-- routing control through prompt text
-- disabling explicit retain tool calls
-- changing historical import behavior
-- provider recall cache
-- persisted recall transcript messages
-
-## Future options
-
-Possible future commands, only if real use justifies them:
-
-```text
-/hindsight:next-recall off
-/hindsight:next-mode ignored
-/hindsight:next-retain off
-```
-
-Do not add aliases until the core command proves useful.

package/node_modules/@luxusai/pi-hindsight/docs/risky-memory-modes.md

@@ -1,139 +0,0 @@
-# Risky memory modes
-
-Pi Hindsight keeps several tempting memory features deferred on purpose. The project is pre-release, so the reason is not backward compatibility. The reason is memory correctness: a feature that makes memory harder to reason about is not worth adding until it has a strong use case and a small, testable design.
-
-## Baseline policy
-
-The safe default path is:
-
-```text
-ephemeral recall
-fresh recall per turn
-queue-first retain
-stable document IDs
-strict tag scope
-explicit commands for user control
-```
-
-Do not implement persisted recall, provider recall caching, or prompt hashtag controls unless a future design re-justifies them.
-
-## Persisted recall messages in Pi transcript history
-
-Persisted recall means writing recalled memories into the Pi session transcript as messages so they are visible after restart.
-
-This is deferred.
-
-Risks:
-
-- Old recall blocks can be resent to model providers if filtering is absent or the extension is disabled incorrectly.
-- Uninstalling the extension can turn custom recall blocks into ordinary prompt content.
-- Recalled memory can accidentally be retained back into Hindsight, causing memory echo.
-- Transcript import and cleanup logic becomes harder to reason about.
-- Prompt-cache behavior becomes more fragile if historical recall blocks appear in the provider context.
-
-Safe alternative:
-
-- Keep recall ephemeral by default.
-- Use `recall.storeLastRecall` to write the latest recall snapshot to a local sidecar file under `.pi/hindsight/`.
-- Inspect that sidecar on disk when debugging; there is no public last-recall slash command.
-
-Design rule:
-
-```text
-Visibility is OK. Provider reuse is not OK by default.
-```
-
-## Provider recall cache
-
-Provider recall cache means reusing previous recall results as context for later model calls.
-
-This is deferred.
-
-Risks:
-
-- Recall is query-dependent; different prompts need different memory.
-- Cached recall can serve stale or irrelevant memory.
-- Wrong cached memory makes answers confidently wrong.
-- Cache invalidation adds complexity without improving correctness.
-- It hides retrieval failures behind old results.
-
-Safe alternative:
-
-- Run fresh recall for each turn.
-- Cache only for inspection, not provider injection.
-- Keep the sidecar snapshot local, explicit, and opt-in.
-
-Design rule:
-
-```text
-Recall returns candidates for this query, not reusable truth for future queries.
-```
-
-## Prompt hashtag controls such as `#nomem`
-
-Prompt hashtag controls mean parsing user text for markers like `#nomem`, `#private`, `#global`, or `#project`.
-
-This is deferred.
-
-Risks:
-
-- Markdown headings and normal prose use `#`.
-- Prompt parsing creates invisible policy decisions inside normal conversation text.
-- Agent-written text can accidentally copy or transform control markers.
-- Retain cursor behavior becomes harder for one-turn skip semantics.
-- Historical import semantics become ambiguous: should old `#nomem` markers still apply?
-- Routing tags in prompts invite accidental cross-scope writes.
-
-Safe alternative:
-
-- Use explicit commands:
-  - `/hindsight` hub key `m` → `read-only`
-  - `/hindsight` hub key `m` → `ignored`
-  - `/hindsight:retain off`
-- Use `/hindsight:next-opt-out` for command-based one-turn automatic retain opt-out instead of hashtag parsing.
-
-Implemented one-turn direction:
-
-```text
-/hindsight:next-opt-out
-```
-
-Why this is better:
-
-- Pi command autocomplete makes it discoverable by typing `next`, `opt`, or `out`.
-- The command is explicit in command history.
-- The behavior can be tested without parsing arbitrary user prose.
-- It does not conflict with Markdown.
-
-Current semantics:
-
-- Applies once to the next agent run in the current session.
-- Disables automatic retain for that run.
-- Leaves recall enabled unless a later design adds an explicit recall option.
-- Does not affect explicit `hindsight_retain` tool calls.
-- Does not affect historical import.
-- Stores non-provider-visible session metadata for inspectability.
-
-Design rule:
-
-```text
-Use commands for policy. Do not hide policy in prompt text.
-```
-
-## Decision summary
-
-| Feature                              | Status   | Safe alternative                                    |
-| ------------------------------------ | -------- | --------------------------------------------------- |
-| Persisted recall transcript messages | Deferred | ephemeral recall + last-recall sidecar              |
-| Provider recall cache                | Deferred | fresh recall per turn + local inspection snapshot   |
-| `#nomem` / prompt hashtag controls   | Deferred | explicit commands such as `/hindsight:next-opt-out` |
-
-## Reopening criteria
-
-A deferred memory mode can be reconsidered only if all are true:
-
-- The use case happens often enough to justify product complexity.
-- The behavior can be explained in one paragraph.
-- It has deterministic tests for recall, retain, import, and session mode interaction.
-- It does not store recalled memory back into Hindsight.
-- It fails closed instead of silently leaking memory across scopes.

package/node_modules/@luxusai/pi-hindsight/docs/starter-mental-model-suggestions.md

@@ -1,74 +0,0 @@
-# Starter mental model suggestions
-
-Mental models are a **core** Hindsight feature. Pi Hindsight provisions them through use-profile-aware bank templates (guided setup or `/hindsight` → `t`), then injects non-empty model content into automatic context.
-
-## Placement decision
-
-Starter suggestions live here and in `extensions/banks/bank-templates.ts` (keep in sync). Applying a bundled template creates these models via Hindsight's bank-template import endpoint — dry-run gated, confirm before write. Arbitrary mental-model authoring remains in the Hindsight control-plane web UI.
-
-For quality criteria and when agents should **propose** create/update/refresh (never silent), see [Mission and mental-model quality](mission-and-mental-model-quality.md).
-
-## Product rules
-
-- Suggestions are explicit opt-in (setup/TUI), never silent bank mutation on every boot.
-- Creation shows name, bank, source query, and tags before submission.
-- **Agent use** selects which seed set applies: `coding` vs `conversation` (real-life / chat agents).
-- Tags on seeds must be a subset of retain tags (`source:pi`) so refresh is not empty.
-- When models have content, automatic context injects them ephemerally under `<hindsight-mental-models>`; retain strips that injection like recall blocks.
-- Seed `max_tokens` stays lean (600 prefs / 800 project) so inject does not dominate every turn (see [coding-memory-evaluation.md](coding-memory-evaluation.md)).
-- Template triggers use `mode: delta`, `refresh_after_consolidation: true`, observation-first refresh, and `exclude_mental_models` (oh-my-pi / Claude Code pattern).
-
-## Coding bank-global (shared coding bank)
-
-| Name                                   | Source query (summary)                                                             | Why              |
-| -------------------------------------- | ---------------------------------------------------------------------------------- | ---------------- |
-| Coding assistant operating preferences | Durable plan/verify/commit/tool + clarification style; exclude probe harness rules | Cross-repo prefs |
-
-## Coding project bank
-
-| Name                           | Source query                                                                             | Why                   |
-| ------------------------------ | ---------------------------------------------------------------------------------------- | --------------------- |
-| Project architecture and seams | What are the stable architecture boundaries, modules, and seams in this project?         | Where changes belong  |
-| Project conventions            | What are this project's conventions for code style, build, testing, release, and review? | Consistency           |
-| Project decisions              | What durable architectural or product decisions have been made…?                         | Stable decisions only |
-
-## Conversation / life-task project bank
-
-| Name                         | Source query                                                               | Why                    |
-| ---------------------------- | -------------------------------------------------------------------------- | ---------------------- |
-| Active goals and commitments | What goals, commitments, deadlines, and open loops is the user tracking…?  | Ongoing work           |
-| People and context           | Which people, roles, relationships, and recurring situations matter…?      | Durable social context |
-| Decisions and preferences    | What durable decisions, preferences, and constraints has the user stated…? | Stable choices         |
-
-## Coding user bank
-
-| Name                                   | Source query                                                 | Why              |
-| -------------------------------------- | ------------------------------------------------------------ | ---------------- |
-| User collaboration preferences         | Durable collaboration/review/autonomy preferences            | Cross-repo style |
-| Coding assistant operating preferences | How coding assistants should plan, verify, commit, use tools | Agent behavior   |
-| Cross-project workflow habits          | Issue/PR/release habits across repos                         | Process          |
-
-## Conversation user bank
-
-| Name                                | Source query                           | Why             |
-| ----------------------------------- | -------------------------------------- | --------------- |
-| Communication preferences           | Tone, length, language preferences     | Response shape  |
-| Life and task workflow habits       | Real-life planning and task habits     | LifeOS patterns |
-| Priority and scheduling preferences | How the user prioritizes and schedules | Trade-offs      |
-
-## What not to seed
-
-- Secrets, credentials, private URLs
-- One-off session status
-- Speculative personality profiles
-- Project facts in the user bank (and vice versa for coding vs conversation mismatch)
-
-## Template ids
-
-| Id                        | Target  | Agent use             |
-| ------------------------- | ------- | --------------------- |
-| `pi-coding-project`       | project | coding                |
-| `pi-conversation-project` | project | conversation          |
-| `pi-coding-user`          | user    | coding                |
-| `pi-conversation-user`    | user    | conversation          |
-| `pi-user-preferences`     | user    | coding (legacy alias) |