The distinction between project state and project memory is the part I find most useful here. A repository can tell an agent what the system looks like today, while the “why” explains why certain seemingly unnecessary constraints should not be removed.
The abandoned-change example also highlights an important retrieval problem. Storing the rationale is only half the solution; the agent needs a deterministic way to discover when that rationale is relevant. In production AI work at IT Path Solutions, I’d treat those entries almost like architectural constraints with searchable scope and provenance, rather than generic documentation.
There’s also an interesting failure mode here: a stale or incorrect “why” can actively mislead an agent. Versioning the rationale alongside the code and making it clear which assumptions caused the decision could make repo-native memory much safer to rely on during future refactors.