What are the problems with traditional Markdown-based ADRs in AI coding?

Poor searchability across many files, high token consumption from loading all files into the LLM context, and no guarantee that the AI agent will consistently read or update them.

How does sqlew store ADRs differently from traditional approaches?

sqlew stores ADRs in an RDBMS instead of Markdown files, enabling structured search by tags and keywords and retrieving only the relevant records without full-context loading.

How does sqlew ensure ADRs are always referenced during development?

sqlew uses Claude Code Hooks to automatically surface related past ADRs via MCP when the AI agent enters plan mode, so prior design decisions naturally come into view before coding begins.

How does sqlew prevent ADRs from becoming outdated?

When a new design decision is made during planning, Hooks detect it and trigger automatic ADR creation or update, eliminating the "forgot to document" problem at the tooling level.

Does sqlew require RAG or embedding setup?

No. sqlew operates as an MCP tool with RDBMS-backed storage and is operational immediately after installation, with no RAG or embedding configuration needed.

How sqlew Redefines ADR — AI-Native Design Memory

In the previous article, we explored how ADRs fell out of use because humans couldn't maintain them — and how AI coding now faces the same core problem ADRs were designed to solve.

In this article, we'll walk through how sqlew overcomes the weaknesses of traditional ADRs and reimagines them as AI-native design memory.

The Limitations of Markdown-Based ADRs

Traditional ADRs are Markdown files lined up in a docs/adr directory. Simple to start, but in the context of AI coding, several issues emerge.

First, searchability. Once ADRs number in the dozens, identifying the one relevant to your current task by filename alone becomes unreliable. Second, token efficiency. Loading every file into the LLM's context window consumes tokens on irrelevant information and can degrade reasoning quality. Third, operational uncertainty. There's no guarantee the AI agent will "always read" or "always update" the ADRs — both referencing and recording tend to become optional.

These aren't problems with Markdown as a format. They're structural problems with file-based static management in the context of AI collaboration.

sqlew's Approach

sqlew moves the storage layer for ADRs from Markdown files to an RDBMS. By structuring design decisions in database tables, ADRs become searchable by tags and keywords, and only the relevant records are retrieved — no full-context loading required.

But changing the storage layer alone doesn't guarantee that ADRs are consistently read and written. That's where sqlew leverages Claude Code's Hooks mechanism with two key features.

The first is automatic suggestion during plan mode. When the AI agent formulates an implementation plan, sqlew surfaces related past ADRs via MCP. Before the developer even begins a task, prior design decisions and their rationale naturally come into view.

The second is enforced ADR creation from plan files. When a new design decision is made during planning, Hooks detect it and trigger ADR creation or update. The tool itself ensures that "forgetting to document" simply doesn't happen.

ADR, Reborn AI-Native

Traditional ADRs failed because humans had to "write," "search," and "read" everything themselves. sqlew shifts all three of these responsibilities to AI and tooling, unlocking the original promise of ADRs: accumulating the reasoning behind design decisions and supporting consistent code generation.

Redefining ADRs — a practice that was ahead of its time for humans — as an AI-native system. sqlew is the first step in that direction.