How do coding agents remember architectural decisions?

A model session is not project memory

A coding agent can reason over the context supplied to its current run, but a later run may begin without the earlier conversation. Even products that retain conversation history cannot make an informal chat the authoritative record for every IDE, CLI, CI runner and model a team uses.

Project memory therefore needs to exist independently of the agent. The agent should consume it, not own it. A versioned repository record gives humans and tools the same inspectable source at the commit where work occurs.

Use a memory hierarchy

Keep broad operating instructions at the repository entry point, durable rationale in decision records, and objective consequences in tests or policy checks. Retrieval joins those layers for the current task without copying the entire history into every prompt.

• Instructions: how the agent should work in this repository.
• Decisions: what the team chose, why, and what was rejected.
• Checks: which consequences can be verified mechanically.
• Citations: which exact records informed the proposed change.

Make recall reproducible

For authoritative questions, the same query against the same commit should return the same records. Stable identifiers let plans, pull requests and review comments cite the source instead of relying on an agent's paraphrase. If nothing matches, the system should expose the gap rather than manufacture an answer.

Test the memory with real tasks

Choose a decision reviewers repeatedly explain, begin a clean agent session, and ask for a change that touches it. Verify that the agent finds the accepted record before implementation, cites it correctly and preserves its consequences. Repeat from another supported agent to confirm that the memory is vendor-neutral.