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

[luxus]

Summary

Bundles the coding-memory optimization backlog into one PR:

1. Setup ensure (fix(setup): ensure project + bank-global mental models under domain-tagged coding bank #528) — do not skip starter MMs when the shared coding bank already has other projects’ models; ensure bank-global + active-project starter ids.
2. Delta MM triggers (perf(mm): switch starter mental models to delta refresh #529) — bundled templates use mode: delta, refresh_after_consolidation, observation-first refresh, exclude_mental_models.
3. Lean max_tokens (perf(mm): cap mental-model size and trim fat project decisions models #530) — prefs 600 / project 800; tests enforce ≤800.
4. Mission wording (chore(banks): audit coding bank missions vs Hindsight best practices #531) — coding/user default missions aligned with Hindsight best practices (ignore probe noise, durable decisions).
5. Eval docs (docs(research): coding-memory learnings from AMB, sde-bench, Hindsight perf monitor #532) — docs/coding-memory-evaluation.md (+ docs-site) from AMB / sde-bench / perf-monitor.

Linked issue

• Closes fix(setup): ensure project + bank-global mental models under domain-tagged coding bank #528
• Closes perf(mm): switch starter mental models to delta refresh #529
• Closes perf(mm): cap mental-model size and trim fat project decisions models #530
• Closes chore(banks): audit coding bank missions vs Hindsight best practices #531
• Closes docs(research): coding-memory learnings from AMB, sde-bench, Hindsight perf monitor #532

Scope

• extensions/tui/guided-setup.ts — expected-id ensure for MM offer
• extensions/banks/bank-templates.ts — bank-global coding prefs seed, delta trigger, max_tokens
• extensions/banks/bank-operations.ts — mission strings
• extensions/operations/memory-control-operations.ts — create still maps refreshAfterConsolidation (client limitation)
• docs + docs-site + tests

Verification

• npm run check
• npm run check:coverage (source, tests, critical paths, or ci:coverage) — covered by CI coverage gate on this PR
• npm run typecheck:tsc (source/critical paths or full CI) — covered by CI TypeScript compiler fallback on this PR
• full matrix requested/passed (release PRs/release verification, manual dispatch, platform-sensitive changes, or ci:full) — skipped because this is not a release PR and has no platform-sensitive changes; CI correctly skips full matrix
• package verification requested/passed (release/package changes or ci:package) — package verification job passed on this PR
• npm run pack:verify (release/package changes) — skipped because no package/release packaging path change
• npm run smoke:hindsight or configured Hindsight Integration pass (memory-path behavior changes or ci:live-smoke; document unavailable live proof) — CI live-smoke job passed on this PR

Release impact

Check exactly one:

• No release impact
• User-visible change
• Package/release path change

Setup no longer skips starters when other projects already provisioned models on the shared coding bank. New template applies get delta refresh + lean budgets. Default bank missions wording changes for new bank creates (existing banks unchanged until reconfigured).

Risk and rollback

• Risk: Mission text changes only affect new bank ensures; template re-apply can change MM triggers on import; delta mode behavior is Hindsight-side.
• Rollback/revert path: Revert this PR; existing banks/MMs keep prior trigger/missions until re-applied.

Follow-ups

• N/A for repo code. Live bank ops (delta/max_tokens on existing Hindsight models) done outside this PR. Upstream client only maps refreshAfterConsolidation on create — full delta fields ride template import.

Memory invariants

• Retain still stores raw rich content, not summaries.
• Recall Blocks remain ephemeral and are not retained back into Hindsight.
• Project Bank and User Bank isolation is preserved.
• Retain Queue behavior remains queue-first and retry-safe.
• Debug output and sidecars remain opt-in and redacted.
• Import behavior remains deterministic and idempotent when touched.

Guidance sync

• If this changes source-of-truth order, contributor workflow, verification expectations, memory policy, or definition of done, AGENTS.md and CONTRIBUTING.md were updated together. (N/A — docs only for eval alignment)

Agent checklist

• I read and followed AGENTS.md and CONTRIBUTING.md.
• I linked the issue before implementation.
• I kept the diff focused on one vertical slice.
• Final branch contains only focused, reviewable commits.
• I did not bypass hooks or checks.
• I documented skipped checks with reasons.

Notes

Sources: Hindsight best practices, oh-my-pi blog, MM deep dive, AMB, sde-bench, continuous perf monitor.

[Copilot]

Pull request overview

This PR bundles several coding-memory optimizations: it makes guided setup “starter mental model” provisioning aware of the expected starter model IDs (bank-global + active-project), updates bundled bank templates to use delta refresh defaults with lean max_tokens budgets, revises default bank mission strings to better align with Hindsight best practices, and adds evaluation-alignment documentation.

Changes:

• Guided setup now probes mental model IDs and only skips starter provisioning when all expected starter IDs are already present (avoids “other project’s models” causing an incorrect skip on shared coding banks).
• Bundled templates now emit delta refresh triggers (mode: delta, refresh_after_consolidation, fact_types: ["observation"], exclude_mental_models) and enforce lean max_tokens caps (prefs 600 / project 800).
• Adds coding-memory evaluation notes to docs + docs-site and updates related concept/setup documentation and unit tests.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/mental-models.test.ts	Updates assertions to account for bank-global vs project-stamped model IDs.
tests/guided-setup.test.ts	Adds coverage for “expected starter IDs” skip/offer behavior and ID-aware probing.
tests/bank-templates.test.ts	Verifies delta trigger defaults + max_tokens caps; checks expected starter IDs.
tests/bank-operations.test.ts	Updates expectations for revised default bank mission text.
package.json	Publishes new docs/coding-memory-evaluation.md in package files.
extensions/tui/guided-setup.ts	Probes modelIds, computes expected starter IDs, and offers starters only when missing.
extensions/operations/memory-control-operations.ts	Notes client trigger-field limitation; keeps create mapping to refreshAfterConsolidation.
extensions/banks/bank-templates.ts	Adds bank-global coding starter MM, delta-trigger defaults, token budgets, and expected-ID helper.
extensions/banks/bank-operations.ts	Revises default reflect/retain/observations missions for project + global banks.
docs/starter-mental-model-suggestions.md	Documents lean token budgets + delta trigger defaults; adds bank-global coding starter section.
docs/hindsight-core-functions.md	Updates mental model positioning and documents delta+refresh trigger rationale.
docs/coding-memory-evaluation.md	New evaluation-alignment note (AMB / sde-bench / perf monitor) and default implications.
docs-site/src/content/docs/start/setup-tui.md	Documents “skip only when all expected starters present” behavior.
docs-site/src/content/docs/concepts/starter-mental-model-suggestions.md	Mirrors starter MM doc updates (budgets, delta triggers, what-not-to-seed).
docs-site/src/content/docs/concepts/index.mdx	Adds concept link for Coding memory evaluation.
docs-site/src/content/docs/concepts/hindsight-core-functions.md	Mirrors core-functions doc updates for docs-site.
docs-site/src/content/docs/concepts/coding-memory-evaluation.md	Adds docs-site page for evaluation alignment.
astro.config.mjs	Adds sidebar/nav entry for Coding memory evaluation concept page.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.