[codex] document brain evolution rules

[kgarg2468]

Summary

This PR updates the Pulse product/spec docs to clarify how the two-brain memory model should evolve across customer interactions.

What Changed

• Added a Brain Evolution Rule to heyg_spec.md.
• Clarified that the Customer Brain evolves after every call and accumulates richer customer context over time.
• Clarified that the Company Brain is business-owned source-of-truth data and should not silently evolve from raw customer calls.
• Updated the architecture wording from save_preferences to save_interaction so writes are framed as customer-fact updates.
• Updated the GBrain layer notes so customers/{name}.md is enriched after each call and insights/weekly.md is reviewable aggregate business intelligence.
• Added build-plan implementation rules for default write behavior.
• Updated the Vapi system prompt memory rules so learned facts write to Customer Brain by default, while Company Brain changes become candidate insights for owner review.
• Added backend checklist items for updating Customer Brain after completed calls and keeping Company Brain writes behind approval.
• Added demo-data notes that live calls read Company Brain but mutate only Customer Brain.
• Updated Judge Q&A to describe the GBrain integration accurately.

Agent Review Checklist

• Verify heyg_spec.md clearly says Customer Brain evolves after every call.
• Verify heyg_spec.md clearly says Company Brain does not silently change from individual customer calls.
• Verify the architecture diagram/write path sends learned facts to customer memory, not company memory.
• Verify dream-cycle wording produces candidate Company Brain updates for owner/admin approval.
• Verify the build plan includes explicit default write behavior for individual calls.
• Verify the Vapi prompt tells the agent to write learned facts to Customer Brain and not rewrite Company Brain.
• Verify backend checklist items match the intended implementation behavior.
• Verify demo GBrain data notes make Company Brain read-only during live calls and Customer Brain updateable.
• Verify Judge Q&A no longer implies every call writes directly to Company Brain.

Validation

• Ran git diff --check -- heyg_spec.md pulse_final_build_plan_with_vapi_v2.0.md.
• No automated tests run because this is a documentation-only change.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
web	Error		May 17, 2026 2:20am