@herbertgao/pi-extensions 2026.8.11 → 2026.8.13

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

@@ -0,0 +1,164 @@
+# 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

@@ -0,0 +1,139 @@
+# 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

@@ -0,0 +1,74 @@
+# 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) |