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

astro.config.mjs

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

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

@@ -0,0 +1,43 @@
+---
+title: "Coding memory evaluation"
+---
+
+# 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).
+
+## 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,11 @@ 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).
+
+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](/pi-hindsight/concepts/mission-and-mental-model-quality/).
 
 ```text
 Observations  = facts learned from repetition

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

@@ -42,3 +42,5 @@ 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.
+- [Mission and mental-model quality](./mission-and-mental-model-quality/) tells agents when to propose mission/MM create, update, or refresh.