@herbertgao/pi-extensions 2026.9.5 → 2026.9.7

package/node_modules/@luxusai/pi-hindsight/docs/compatibility.md

@@ -1,75 +0,0 @@
-# Compatibility matrix
-
-Pi Hindsight 1.0 is a Pi-first Hindsight integration. This page is the support contract for the 1.0 line.
-
-## Supported runtime matrix
-
-| Component                   | 1.0 support policy                                                                                                                                                                                                          | Source of truth                                                      |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| Node.js                     | `>=20`                                                                                                                                                                                                                      | `package.json#engines.node`                                          |
-| npm                         | `>=10`                                                                                                                                                                                                                      | `package.json#engines.npm`                                           |
-| Pi runtime packages         | Tested with the `@earendil-works/pi-*` versions pinned in `devDependencies`; peer dependencies accept Pi runtime packages supplied by the host Pi installation.                                                             | `package.json#devDependencies` and `package.json#peerDependencies`   |
-| TypeBox                     | `>=1.1.24 <2`                                                                                                                                                                                                               | `package.json#peerDependencies.typebox`                              |
-| Hindsight TypeScript client | `@vectorize-io/hindsight-client ^0.9.0`                                                                                                                                                                                     | `package.json#dependencies`                                          |
-| Hindsight server            | **Hindsight 0.8+** with append `update_mode` support, compatible with `@vectorize-io/hindsight-client ^0.9.0`. Knowledge pages need server routes that match the 0.9 client; other advanced surfaces stay capability-gated. | `/hindsight:doctor`, live smoke, and official Hindsight API behavior |
-
-## Required Hindsight capabilities
-
-The automatic memory path requires:
-
-- retain
-- recall
-- reflect
-- append-style retain updates (`updateMode: "append"`)
-- deterministic document IDs accepted by retain
-- tag filters for scoped recall
-
-If append retain is unavailable, live automatic retain is not considered supported for 1.0. Upgrade to Hindsight 0.8+; `/hindsight:doctor` documents the server floor and remediation action.
-
-## Capability-gated surfaces
-
-These surfaces are part of the 1.0 Pi surface, but the exact fields and behavior can depend on the connected Hindsight server version:
-
-- advanced recall/reflect options such as trace, source facts, included chunks, response schemas, and tool-call facts
-- knowledge pages (`hindsight_knowledge` tree/search/get/export and dry-run mutating ops) — requires `@vectorize-io/hindsight-client ^0.9.0` and a server that exposes knowledge-base APIs
-- read-only bank config/stats facts in status
-
-When a server does not expose one of these endpoints or fields, Pi Hindsight should fail with a clear unsupported-capability message rather than silently changing request shape. Admin and browsing surfaces (documents, entities, graphs, tags, memory units, mental models, directives, bank templates, operations) live in the Hindsight control-plane web UI.
-
-## 1.0 scope decision
-
-For 1.0, Pi Hindsight chooses **stable Pi-first integration** over full upstream global-admin parity.
-
-In scope:
-
-- Pi lifecycle recall/retain integration
-- queue-first retain and diagnostics
-- deterministic project/user bank routing
-- explicit retain/recall/reflect tools
-- Pi session import
-- live smoke and package/release verification
-
-Out of scope for 1.0 unless a follow-up issue explicitly pulls them in:
-
-- cross-bank `list_banks`
-- arbitrary cross-bank `create_bank`
-- full-bank `delete_bank`
-- platform-wide bank statistics/admin dashboards
-- audit log and webhook administration
-- generic non-Pi framework adapters in this package
-
-Rationale: global-admin and platform surfaces carry broader safety, permission, and UX obligations than the Pi memory lifecycle. Pi Hindsight can still expose scoped bank operations that directly help Pi users inspect, repair, or configure their selected project/user banks.
-
-## Diagnostics contract
-
-`/hindsight:doctor` and status-style diagnostics should report:
-
-- Pi Hindsight package version and user agent
-- supported runtime ranges from this matrix
-- configured Hindsight base URL without secrets
-- official Hindsight client package and supported range
-- health reachability
-- server floor (Hindsight 0.8+ append retain) and remediation action
-- memory profile, routes, selected banks, queue state, import state, and activity
-
-Diagnostics must redact API keys and avoid printing raw retained payloads in normal mode.

package/node_modules/@luxusai/pi-hindsight/docs/hindsight-core-functions.md

@@ -1,300 +0,0 @@
-# Hindsight core functions
-
-This page is infographic copy and onboarding text for explaining how Hindsight memory works.
-
-## One-sentence model
-
-**Hindsight is a memory system that separates storage, retrieval, and reasoning.**
-
-```text
-Retain  = store memory
-Recall  = retrieve memory
-Reflect = analyze memory
-```
-
-Everything happens inside a **Memory Bank**, which controls memory scope and prevents leakage.
-
-## Core functions
-
-### Memory Bank — isolated memory namespace
-
-A memory bank decides which memories belong together.
-
-Use memory banks to separate users, projects, agents, work vs personal memory, and sensitive vs general memory. A bank can have its own mission, such as “remember durable project architecture decisions” or “remember cross-project user preferences.”
-
-**Why it matters:** memory banks prevent leakage, simplify governance, and make memory easier to inspect.
-
-### Retain — store raw experience
-
-Retain writes source material into Hindsight after a conversation turn, agent session, document, note, log, decision, or event.
-
-Best input:
-
-- structured JSON conversation
-- raw notes
-- documents
-- logs with context
-- session deltas
-- decisions with source information
-
-Avoid:
-
-- pre-summarized content when raw content exists
-- random `document_id`s
-- missing `context`
-- mixing unrelated projects
-- retaining recalled memory back into memory
-
-Retain does not mean “store this exact wording as final truth.” It means “here is source material; extract useful memory from it.”
-
-**Purpose:** store raw data so the system can extract truth.
-
-### Recall — retrieve relevant memory candidates
-
-Recall searches memory before an AI generates an answer.
-
-Recall answers: “What past memories are relevant to this current query?”
-
-Recall is query-dependent. Different prompts should retrieve different memories. Recall may use semantic search, keyword matching, graph relationships, temporal ranking, tags, and filters.
-
-Use recall for giving an agent useful context, retrieving past facts, remembering project decisions, recalling user preferences, and grounding current work in past sessions.
-
-**Killer rule:** recall returns candidates, not answers.
-
-**Purpose:** bring relevant past memory into the current moment.
-
-### Reflect — analyze memory for this question
-
-Reflect performs ad-hoc, agentic analysis over memory. It is not normal search. It asks Hindsight to reason across memories and synthesize an answer for a specific question.
-
-Reflect answers: “Analyze the memories and reason through this question now.”
-
-Use reflect for:
-
-- investigating patterns
-- comparing past decisions
-- finding contradictions
-- understanding changes over time
-- synthesizing lessons from many sessions
-- answering complex “why did this happen?” questions
-- doing ad-hoc project or workflow analysis
-
-Reflect is less ideal for stable recurring summaries like user profiles, coding preferences, project architecture overviews, or always-on assistant guidance. Those fit better as mental models.
-
-**Purpose:** memory-grounded reasoning for one specific question.
-
-### Observations — facts learned from repetition
-
-Observations are consolidated beliefs created from retained memories. They are usually not written directly by the app. Hindsight creates and updates them after retain.
-
-Examples:
-
-- “User consistently prefers simple, minimal tooling.”
-- “This project favors project-scoped memory over global shared memory.”
-
-Observations can gather repeated evidence, strengthen over time, weaken when contradicted, become stale, and preserve supporting source memories.
-
-**Brutal distinction:** observations are facts learned from repetition.
-
-**Purpose:** reduce duplicate evidence into durable knowledge.
-
-### Mental Models — reusable answers to recurring questions
-
-Mental models are persistent syntheses over memory. They are useful when the same kind of memory question comes up often.
-
-Good mental model examples:
-
-- “What are this user’s coding preferences?”
-- “What is this project’s architecture?”
-- “How should this agent collaborate with this user?”
-- “What recurring workflow habits matter?”
-- “What does this project consider good design?”
-
-Mental models are not raw recall. They are reusable synthesized answers. In Pi Hindsight they are explicit advanced resources (setup / hub `t` / agent control plane). The extension must not auto-create mental models from routine sessions. Starter suggestions are documented in [`starter-mental-model-suggestions.md`](starter-mental-model-suggestions.md). Evaluation alignment notes: [`coding-memory-evaluation.md`](coding-memory-evaluation.md).
-
-Creating a mental model preserves a source query. Hindsight runs that query through reflect and stores the generated content. Bundled templates set `trigger.mode: delta` and `refresh_after_consolidation: true` so consolidation folds new observations without full rewrites every time (server-side; not a Pi background job).
-
-Agents should treat missions and mental models as tunable policy: propose improvements with dry-run tools, do not mutate silently. See [Mission and mental-model quality](mission-and-mental-model-quality.md).
-
-```text
-Observations  = facts learned from repetition
-Mental Models = answers built from remembered facts
-```
-
-**Purpose:** provide fast, consistent high-level memory understanding.
-
-## Do / Don’t
-
-### Do
-
-- Store raw, contextual data.
-- Use consistent `document_id`s.
-- Set useful `context`.
-- Tag aggressively.
-- Separate unrelated memory into banks.
-- Use recall before answer generation.
-- Use reflect for deeper ad-hoc analysis.
-- Use mental models for recurring stable context.
-
-### Don’t
-
-- Summarize before retain when raw data exists.
-- Use random document IDs for the same source.
-- Mix unrelated projects in one memory bank.
-- Store recalled memory back into memory.
-- Use metadata as the main filter.
-- Rely on recall alone for complex analysis.
-- Treat observations and mental models as the same thing.
-
-## Common failure modes
-
-| Failure          | Result                                          | Fix                                                                       |
-| ---------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
-| Bad retain       | missing context → weak extraction → weak recall | retain raw structured data, add clear `context`, use stable `document_id` |
-| No tags          | wrong memories retrieved                        | tag by project, user, source; use strict filtering when scope matters     |
-| No reflect       | shallow answers for complex questions           | use recall for candidates and reflect for analysis                        |
-| Too many banks   | fragmented knowledge                            | separate only meaningful scopes; use tags inside banks when enough        |
-| Too much summary | lost evidence                                   | retain raw source when possible                                           |
-
-## Important supporting fields
-
-### `context`
-
-Tells Hindsight what kind of content is being retained.
-
-Example: `Pi coding session for repo pi-hindsight`
-
-**Purpose:** improve extraction quality.
-
-### `document_id`
-
-Stable ID for the same source document or session.
-
-Same `document_id` means: “this is more content for the same memory source.”
-
-**Purpose:** prevent duplicate memory documents.
-
-### `update_mode`
-
-Controls how retained content updates an existing document.
-
-Use `append` for live ongoing sessions and incremental logs. Use `replace` for deterministic historical imports, full rebuilds, or reprocessing the same source from scratch.
-
-**Purpose:** control whether new memory extends or replaces a source document.
-
-### `tags`
-
-Tags control scope and filtering.
-
-Examples: `user:luxus`, `repo:pi-hindsight`, `session:abc123`, `source:pi`, `harness:pi`.
-
-**Purpose:** recall the right memories and avoid cross-scope leakage.
-
-### `metadata`
-
-Metadata stores provenance.
-
-Use tags for filtering. Use metadata for traceability.
-
-**Purpose:** trace memory back to its source.
-
-### `timestamp`
-
-Gives temporal context.
-
-**Purpose:** support recency ranking, timeline reasoning, change detection, and stale-vs-current judgment.
-
-### Observation scopes
-
-Observation scopes tell Hindsight how to group evidence when creating observations.
-
-Examples: `["harness:pi"]`, `["repo:pi-hindsight"]`, `["user:luxus"]`.
-
-**Purpose:** keep consolidated knowledge in the right scope.
-
-## Simple flow
-
-```mermaid
-flowchart TD
-  A[Conversation happens] --> B[Retain raw structured content]
-  B --> C[Extract facts, entities, events, relationships]
-  C --> D[Observations consolidate repeated evidence]
-  D --> E[Mental models provide reusable understanding]
-  F[Future prompt arrives] --> G[Recall retrieves memory candidates]
-  G --> H{Need deeper reasoning?}
-  H -- Yes --> I[Reflect analyzes memory]
-  H -- No --> J[Answer with retrieved context]
-  I --> K[Answer with retrieved + synthesized context]
-```
-
-## Function summary
-
-```text
-Memory Bank   = isolated memory namespace
-Retain        = store raw experience
-Recall        = retrieve relevant memory candidates
-Reflect       = ad-hoc analysis over memory
-Observations  = facts learned from repetition
-Mental Models = answers built from remembered facts
-```
-
-## Infographic generation prompt
-
-Use this prompt with ChatGPT or another image/layout model:
-
-```text
-Create a clean technical infographic explaining Hindsight memory core functions for AI agents.
-
-Audience: developers and technical product people. Style: modern, minimal, high-contrast, readable in 30 seconds. Use a dark or light professional SaaS style. Avoid clutter. Use simple icons and clear arrows.
-
-Main title:
-Hindsight Core Functions
-
-Top banner:
-Hindsight separates storage, retrieval, and reasoning.
-Retain = store memory. Recall = retrieve memory candidates. Reflect = analyze memory.
-
-Section 1: Memory Bank
-Label: Isolated memory namespace
-Text: Controls which memories belong together. Prevents leakage and simplifies governance.
-Examples: users, projects, agents, work vs personal.
-
-Section 2: Retain
-Label: Store raw experience
-Text: Writes raw contextual source material into memory so Hindsight can extract facts, entities, relationships, observations, and changes over time.
-Do: raw JSON, notes, documents, logs with context.
-Avoid: summaries when raw data exists, random document IDs, missing context.
-
-Section 3: Recall
-Label: Retrieve relevant memory candidates
-Text: Searches memory before an answer. Recall returns candidates, not answers.
-Signals: semantic search, keywords, graph relationships, time, tags.
-
-Section 4: Reflect
-Label: Analyze memory for this question
-Text: Ad-hoc agentic analysis over memories. Use for patterns, contradictions, decision evolution, lessons, and why/how questions.
-Note: user profiles and recurring summaries fit Mental Models better.
-
-Section 5: Observations
-Label: Facts learned from repetition
-Text: Auto-generated beliefs created from repeated evidence. Can strengthen, weaken, or become stale.
-
-Section 6: Mental Models
-Label: Answers built from remembered facts
-Text: Reusable stable understanding for recurring questions like user preferences, project architecture, and collaboration style.
-
-Add a small distinction strip:
-Observations = facts learned from repetition.
-Mental Models = answers built from those facts.
-Reflect = ad-hoc analysis for one question.
-
-Add a DO / DON’T strip:
-DO: store raw contextual data; use stable document_id; tag aggressively; separate unrelated memory.
-DON’T: summarize before retain; use random IDs; mix unrelated memory; treat recall as final answer.
-
-Add a flow diagram:
-Conversation → Retain → Extraction → Observations → Mental Models
-Future prompt → Recall → optional Reflect → Answer with retrieved + synthesized context
-
-Output: one-page infographic, strong visual hierarchy, concise text, enough whitespace, developer-friendly.
-```

package/node_modules/@luxusai/pi-hindsight/docs/mission-and-mental-model-quality.md

@@ -1,158 +0,0 @@
-# Mission and mental-model quality (agent guide)
-
-How bank **missions** and **mental models** should look in pi-hindsight — and when the agent should **propose** create / update / refresh (never silent bank mutation).
-
-Official Hindsight guidance: [Best practices](https://hindsight.vectorize.io/best-practices), [Mental models](https://hindsight.vectorize.io/developer/api/mental-models). Seeds: [Starter mental model suggestions](starter-mental-model-suggestions.md). Eval context: [Coding memory evaluation](coding-memory-evaluation.md).
-
-## Hard rules (always)
-
-- **Propose, don’t invent silently.** Create/update/refresh/delete use tools with **dry-run first** (`hindsight_mental_model`, `hindsight_bank`); user confirms via dry-run false or hub `t`.
-- **Tags ⊆ retain tags.** Project models need `source:pi` + `project:<id>`; bank-global prefs: `source:pi` only. Tags not written at retain → empty refresh.
-- **One dimension per mental model.** Not “everything about the user/project.”
-- **Lean inject:** prefs ~600 tokens, project ~800. Fat content burns every turn.
-- **Refresh:** prefer `mode: delta` + `refresh_after_consolidation` on templates; agent create may only set consolidation refresh until the TS client maps full trigger fields.
-- **Missions** steer extraction/consolidation/reflect — vague missions → noisy memory (Hindsight #1 quality failure).
-
-## Bank missions — what “good” looks like
-
-Three strings per bank (retain / observations / reflect):
-
-| Mission          | Job                                        | Good                                                               | Bad                                |
-| ---------------- | ------------------------------------------ | ------------------------------------------------------------------ | ---------------------------------- |
-| **retain**       | What to extract / ignore from raw sessions | Concrete fact types + ignore list (greets, secrets, probe harness) | “Be helpful”, “extract everything” |
-| **observations** | Durable patterns after retain              | Patterns, contradictions, durable only                             | Transient task state               |
-| **reflect**      | Persona for synthesis                      | Domain role + grounded + opinionated when supported                | Generic chatbot                    |
-
-### Coding bank (project)
-
-- Retain: decisions, trade-offs, blockers, conventions, durable project prefs.
-- Observations: stable architecture/process patterns; not TODOs of the day.
-- Reflect: senior developer for _this_ repo.
-
-### Coding user bank (life bank **off** / cross-project prefs)
-
-- Retain: cross-project assistant prefs, workflows, clarification style.
-- **Not** file paths, project bugs, PR noise unless it generalizes.
-
-### Life / conversation user bank
-
-- Retain: commitments, people/context, planning habits, communication prefs.
-- **Not** repo engineering detail unless it’s truly personal durable preference.
-- Reflect: personal/life-task assistant, not code reviewer.
-
-Defaults live in `extensions/banks/bank-operations.ts` (`defaultProjectBankMissions`, `defaultGlobalBankMissions`, `defaultLifeBankMissions`).
-
-### When to propose mission changes
-
-Propose `hindsight_bank` `update_mission` (dry-run) when:
-
-- Extraction is consistently wrong (too much noise / missing decisions).
-- User says prefs are “wrong” or “missing” after several sessions.
-- Switching coding ↔ conversation use without matching missions.
-
-Do **not** churn missions every session.
-
-## When optimization is worth it (signals)
-
-Optimize only when a **repeatable problem** shows up—not because content is imperfect once.
-
-### Mental-model signals (inspect inject + `hindsight_mental_model` list/get)
-
-| Signal                        | What you see                                                                                                 | Likely fix                                                                                                                                                                   | Priority                                    |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
-| **Broken / empty content**    | Inject or get shows `"#"`, empty body, “Generating…”, or only a title                                        | `refresh`; if still empty: tags ⊆ retain tags; **prefs** MMs need `fact_types` world+experience+observation (not observation-only after clear); clear+full rebuild if needed | **High** — do this session                  |
-| **Wrong durable policy**      | Prefs MM contradicts the user’s stated preference (e.g. “never ask” vs wants high-signal questions)          | Explicit `hindsight_retain` of the correct pref → then refresh prefs MM; tighten `source_query` if probe noise keeps winning                                                 | **High**                                    |
-| **Missing project starters**  | Active `project:<id>` has no architecture/conventions/decisions models; bank only has other projects’ models | Propose apply/create starters for **this** project (+ bank-global prefs if missing)                                                                                          | **High** on setup / first real work in repo |
-| **Inject always truncated**   | Blocks end mid-sentence; one model dominates (multi‑k chars, e.g. 8k–12k) while others starve                | Cap `max_tokens` (600–800), refresh fat model; don’t add more models                                                                                                         | **Medium**                                  |
-| **Stale after big decisions** | User finished a real architecture/product choice; MM still describes the old world                           | Wait until retain finished (next turn+); refresh `project-decisions` (and architecture if seams changed)                                                                     | **Medium** — after the decision is retained |
-| **Recurring same question**   | Every session user asks the same durable “how do we X?”                                                      | One new MM for that **single** dimension, lean max_tokens                                                                                                                    | **Medium**                                  |
-| **Cross-project bleed**       | Prefs or decisions clearly about another repo appear under this project’s inject                             | Fix tags (project vs bank-global); never “fix” by editing another project’s ids while working here                                                                           | **High** if isolation broken                |
-| **Noise as “facts”**          | Probe/bait/test harness text treated as durable prefs                                                        | Retain correction + refresh; mission ignore-list for probes; don’t import bait sessions                                                                                      | **Medium**                                  |
-| **Slightly imperfect prose**  | Wording could be nicer but policy is right                                                                   | Leave it; delta refresh after consolidation is enough                                                                                                                        | **Low** — do not nag                        |
-
-### Mission signals (`hindsight_bank` get + memory quality over several sessions)
-
-| Signal                      | What you see                                                                  | Likely fix                                                             | Priority                          |
-| --------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------- |
-| **Noise flood**             | Recall full of greets, scheduling, tool-probe rules, one-off chat             | Tighten **retain** mission ignore-list                                 | Medium–High if multi-session      |
-| **Missing decisions**       | Real architecture choices never appear in recall/MMs after real work          | Broaden retain “extract decisions/trade-offs”; keep ignore list        | Medium                            |
-| **Transient as durable**    | Observations track active TODOs / “today we…” as eternal truth                | Observations mission: durable only, contradictions, not task state     | Medium                            |
-| **Wrong persona**           | Reflect answers like a generic chatbot or wrong domain (coding vs life)       | Align reflect mission with bank role (coding project vs life user)     | Medium when reflect is used       |
-| **Coding vs life mismatch** | Life bank extract file paths/PRs; coding bank extract pure calendar chit-chat | Use life vs global defaults (`defaultLifeBankMissions` vs coding user) | High only if life bank is enabled |
-
-### Cadence (how often to even look)
-
-| Cadence                                        | Action                                                                                |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------- |
-| **Session start / first work in a repo**       | Quick: expected project starters present? Prefs MM non-empty and not obviously wrong? |
-| **After a major decision or multi-hour slice** | Optional: refresh decisions/architecture **after** retain has had a chance to land    |
-| **User complains about memory**                | Full inspect (status, scope, list MMs, bank missions); propose a **small** patch list |
-| **Not every turn**                             | No “shall I refresh mental models?” spam                                              |
-
-### Priority order when several things look off
-
-1. Broken/empty MM content or isolation bleed
-2. Prefs contradicting the user
-3. Missing starters for **this** project
-4. Fat inject / truncation
-5. Mission noise (only if pattern spans sessions)
-6. Polish / “could be nicer”
-
-### Cost check before proposing
-
-Ask: will this change save **future** turns or only rephrase once?
-
-- **Yes (optimize):** empty prefs, wrong “never ask”, 12k decisions eating inject, missing project MMs.
-- **No (skip):** single awkward sentence, one stale bullet that recall already covers, speculative “maybe add 5 more models.”
-
-## Mental models — what “good” looks like
-
-| Field            | Good                                                                     | Bad                                  |
-| ---------------- | ------------------------------------------------------------------------ | ------------------------------------ |
-| **name**         | Short dimension label                                                    | Marketing fluff                      |
-| **source_query** | Natural-language reflect question; “durable only”; exclude probe/one-off | Keyword dump; “summarize everything” |
-| **tags**         | Subset of retain tags; project vs bank-global deliberate                 | Random tags never retained           |
-| **max_tokens**   | 600–800 for seeds                                                        | Unbounded essays                     |
-| **content**      | Stable background; inject preamble says not instructions                 | Session task lists, secrets          |
-
-### Standard dimensions (coding)
-
-| Id pattern                               | Dimension                            |
-| ---------------------------------------- | ------------------------------------ |
-| `coding-assistant-operating-preferences` | Bank-global agent prefs              |
-| `project-architecture-and-seams--<slug>` | Where changes belong                 |
-| `project-conventions--<slug>`            | Build/test/review style              |
-| `project-decisions--<slug>`              | Durable product/architecture choices |
-
-Conversation/life seeds: goals, people/context, decisions/preferences (see starter doc).
-
-### When to propose mental-model actions
-
-Use the **signals table above** (broken content, wrong prefs, missing starters, fat inject, post-decision refresh, recurring questions). Same tool path: dry-run create/update/refresh → user confirms.
-
-### When **not** to propose
-
-- Every turn “should we refresh mental models?”
-- Creating models from probe/bait sessions.
-- Duplicating recall (raw facts) as a mental model.
-- Editing other projects’ tagged models while working in this project.
-- Optimizing for polish when policy and inject budget are already fine.
-
-## Agent workflow (copy pattern)
-
-On user **memory complaints**, load skill `hindsight-memory-doctor` (`/skill:hindsight-memory-doctor`) — same inspect → diagnose → dry-run propose flow.
-
-1. **Inspect:** `hindsight_status`, `hindsight_scope`, `hindsight_mental_model` list/get, `hindsight_bank` get.
-2. **Diagnose** against this doc (tags, size, empty content, wrong prefs, missing project starters).
-3. **Propose** in plain language: what changes, why, dry-run payload.
-4. **Apply** only after user ok: `dryRun: false` on the same tool, or hub `t`.
-5. **Verify:** list/get again; warn that inject list cache can lag (~`mentalModels.cacheTtlMs`).
-
-## Anti-patterns
-
-- Pre-summarizing before retain.
-- Random `document_id`s / missing `context` on retain.
-- Metadata for filtering (use tags).
-- One mega mental model.
-- Mission “extract all information.”
-- Refreshing before new retains are available (same turn).