feat(memory): ensure project MMs, delta refresh, lean budgets, eval docs

astro.config.mjs

@@ -63,6 +63,10 @@ export default defineConfig({
               label: "Starter mental model suggestions",
               slug: "concepts/starter-mental-model-suggestions",
             },
+            {
+              label: "Coding memory evaluation",
+              slug: "concepts/coding-memory-evaluation",
+            },
           ],
         },
         {

docs-site/src/content/docs/concepts/coding-memory-evaluation.md

@@ -0,0 +1,40 @@
+---
+title: "Coding memory evaluation"
+---
+
+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)                            |
+| 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).
+
+## 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

docs-site/src/content/docs/concepts/hindsight-core-functions.md

@@ -112,9 +112,9 @@ Good mental model examples:
 - “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. Pi's `/hindsight` TUI shows a read-only list/detail view and hands off create, edit, refresh, and delete to the Hindsight web interface. The extension must not auto-create mental models from routine sessions or refresh them in the background unless a future issue designs that policy. Starter suggestions are documented in [Starter mental model suggestions](/pi-hindsight/concepts/starter-mental-model-suggestions/).
+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](/pi-hindsight/concepts/starter-mental-model-suggestions/). Evaluation alignment notes: [Coding memory evaluation](/pi-hindsight/concepts/coding-memory-evaluation/).
 
-Creating a mental model preserves a source query. Hindsight runs that query through reflect and stores the generated content. Refresh reruns the stored source query against newer memory.
+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).
 
 ```text
 Observations  = facts learned from repetition

docs-site/src/content/docs/concepts/index.mdx

@@ -42,3 +42,4 @@ Concept pages explain how Pi Hindsight uses Hindsight. They should describe stab
 - [Memory behavior](./memory-behavior/) explains the automatic one-turn lifecycle.
 - [Hindsight core functions](./hindsight-core-functions/) links Pi behavior back to Hindsight primitives.
 - [Starter mental model suggestions](./starter-mental-model-suggestions/) explains seed material for mental models managed in the Hindsight web UI.
+- [Coding memory evaluation](./coding-memory-evaluation/) ties defaults to AMB, sde-bench, and Hindsight perf-monitor learnings.

docs-site/src/content/docs/concepts/starter-mental-model-suggestions.md

@@ -1,5 +1,5 @@
 ---
-title: Starter mental model suggestions
+title: "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.
@@ -15,6 +15,14 @@ Starter suggestions live here and in `extensions/banks/bank-templates.ts` (keep
 - **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
 
@@ -48,6 +56,13 @@ Starter suggestions live here and in `extensions/banks/bank-templates.ts` (keep
 | 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             |

docs-site/src/content/docs/start/setup-tui.md

@@ -39,7 +39,7 @@ Guided setup handles:
 2. memory profile
 3. **agent use** (coding vs conversation)
 4. project and/or user bank target (existing vs create; one-line `Server: … · Bank: …` status)
-5. optional starter mental models (dry-run + confirm; skipped offline / when catalog already present)
+5. optional starter mental models (dry-run + confirm; skipped offline / when **all expected** bank-global + this-project starters are already present — other projects' models on a shared coding bank do not skip)
 6. optional dry-run-first historical import (skipped offline)
 
 Setup also prints docs links for the current area, such as [memory profiles](/pi-hindsight/start/memory-profiles/) and [imports](/pi-hindsight/guides/importing-sessions/).

docs/coding-memory-evaluation.md

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

docs/hindsight-core-functions.md

@@ -110,9 +110,9 @@ Good mental model examples:
 - “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. Pi's `/hindsight` TUI shows a read-only list/detail view and hands off create, edit, refresh, and delete to the Hindsight web interface. The extension must not auto-create mental models from routine sessions or refresh them in the background unless a future issue designs that policy. Starter suggestions are documented in [`starter-mental-model-suggestions.md`](starter-mental-model-suggestions.md).
+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. Refresh reruns the stored source query against newer memory.
+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).
 
 ```text
 Observations  = facts learned from repetition

docs/starter-mental-model-suggestions.md

@@ -13,6 +13,14 @@ Starter suggestions live here and in `extensions/banks/bank-templates.ts` (keep
 - **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