roadmap: encode verify-before-store and update-not-re-store memory discipline

[EtanHey]

Ruling

Memory-writing discipline belongs in BrainLayer's MCP tool descriptions and the BrainLayer skill, not in a repository-level agent instruction that clients may never read.

Required behavior:

1. verify existing memory before storing;
2. use an initial store only as crash insurance when necessary;
3. after that, update/supersede the existing memory rather than creating repeated near-duplicates;
4. confirm with Etan when a proposed correction represents his intent rather than an objective system fact.

Scope

• audit the current descriptions for brain_search, brain_store, brain_update, brain_supersede, and brain_archive across BrainBar and Python MCP implementations;
• define the exact contract where current brain_update cannot edit content, including when callers should use update, supersede, archive, or store-with-supersedes;
• update the BrainLayer skill with the same decision flow;
• add contract tests/evals proving agents receive actionable guidance before creating duplicate memories;
• preserve personal-data and intent-confirmation safety gates.

Non-goal for the urgent nine-tool unblock

Do not expand the gated-tool error-message PR into this policy redesign. This issue records the follow-up roadmap work.

Acceptance criteria

• tool descriptions and skill agree on one decision flow;
• examples cover objective corrections, evolving project facts, and user-intent memories;
• tests/evals detect regressions to blind re-store behavior;
• rollout notes explain compatibility with existing chunks and lifecycle fields.