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

1. Structured Storage: ADRs are stored as markdown files in .tokencap/memory/adrs/ with title, date, status, context, decision, and consequences.
2. Symbol Association: Decisions can be linked to specific modules or symbol clusters.
3. 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 with strict SERIALIZABLE transaction isolation to prevent race conditions.
Consequence: Do not refactor ledger operations to ORM abstractions.

CLI and MCP Tooling

You can create and manage ADRs via the CLI or MCP tool:

tokencap ask adr --list

CLI Output:

Registered Architecture Decision Records (4):
  - ADR-001: CommonJS only for core modules (No build step)
  - ADR-002: Vendored WASM grammars for tree-sitter
  - ADR-003: Staged memory pipeline before repository commit
  - ADR-004: Raw SQL for ledger operations

With ADRs in place, AI agents respect established team choices instead of endlessly proposing architectural rewrites.

Read more at tokencap.vansharora.app