Preventing AI Architecture Reversals with In-Repo Architecture Decision Records

A common frustration when working with AI coding tools is architectural amnesia. You carefully decide to avoid an ORM for specific performance reasons. Two days later, a new AI session opens and immediately suggests installing Prisma. In TokenCap, we solve this by embedding Architecture Decision Records (ADRs) directly into the agent intelligence layer in src/memory/adrs.js. How ADR Intelligence Works Structured Storage: ADRs are stored as markdown files in .tokencap/memory/adrs/ with title, date, status, context, decision, and consequences. Symbol Association: Decisions can be linked to specific modules or symbol clusters. Prompt Context Injection: When an agent edits files associated with an ADR, TokenCap injects the rationale into the top of the context pack: ### Active Architecture Decision Record: ADR-004 Title: Use Raw SQL for Ledger Entries (Do Not Use ORM) Status: Accepted (2026-07-15) Decision: Ledger balance operations must use raw SQL parameterized queries