The ADR compiler — turn architectural decisions into infrastructure.
Most teams have ADRs. They sit in docs/adr/, written in good faith, referenced in onboarding, and then quietly ignored by every AI coding agent that touches the codebase. The ADR compiler reads those same files, parses an optional ## Constraints section, and emits enforceable, precedence-aware decisions that govern generation and CI. No rewrite. No new format. Decisions become infrastructure.
Why this is the centerpiece
Every governance pitch eventually runs into the same objection: we already document our architecture; the problem isn't documentation. That objection is correct. The documentation is fine. What is missing is the compilation step that turns it into something an AI agent — or a CI gate — can actually answer to.
Prompt files (CLAUDE.md, .cursor/rules) try to bridge this gap by asking the model to respect the rules. The result is probabilistic. Vector stores try to bridge it by retrieving relevant text. The result is fuzzy. Neither produces a structured, precedence-aware decision a hook can block on.
The ADR compiler closes that gap by treating ADRs the way a compiler treats source: parse, validate, resolve conflicts, emit something downstream can execute against. The downstream artifact is project_memory.json — a structured decision corpus that drives the editor hook, the CI gate, and the conflict detector with the same precedence rules.
What changes for the team
Nothing structural. The ADRs stay where they are. Authors add an optional six-line YAML frontmatter and an optional ## Constraints block when a decision should be machine-enforceable. Everything else is preserved as rationale. The compiler does not require the team to adopt a new tool or a new format — it reframes the artifact they already maintain.
The pipeline
Five stages. Deterministic. No vector store, no ML.
Same query into the resolved corpus returns the same decision set every time. That property is non-negotiable: if retrieval is non-deterministic, the governance layer cannot block on it.
See it live: same prompt, same model, different answer
The animation below runs the same prompt — "Refactor the storage backend for scalability" — through the same model twice. The two outputs disagree because one of them is governed by ADR-001 (JSON storage only), ADR-003 (no ORM in v1), and ADR-005 (extend before rebuild). The decisions reach the model through the compiler, not through a freeform prompt.
The model is the same. The prompt is the same. The decisions are the same on disk in both cases. The only difference is that one run uses the compiled corpus and the other does not.
What an ADR looks like to the compiler
The compiler reads YAML frontmatter for metadata, free-form Markdown for rationale, and an optional ## Constraints section for machine-readable directives. The example below is one of Mneme's own ADRs:
---
id: ADR-005
title: Brand vs Package Namespace Enforcement
status: accepted
priority: foundational
date: "2026-05-04"
scope: code
---
The package namespace is `mneme`. The brand name is "Mneme HQ".
These must never be conflated in code-bearing surfaces.
## Constraints
- FORBID_DEPENDENCY: MnemeHQ
- FORBID_PATH: site/use-cases/**/Mneme HQ*Three directive kinds are supported in this version: FORBID_DEPENDENCY, FORBID_PATH, and REQUIRE_PATH. Unknown directive kinds raise a parse error rather than being silently dropped — a typo should not defeat governance. The full directive reference lives in the ADR import integration page.
Conflict resolution is part of the contract
Two ADRs cannot silently disagree. If two accepted ADRs share the same scope, priority, and date, the compiler cannot pick a winner deterministically and refuses to emit until the contradiction is resolved. The fix is human: mark one superseded, give one a higher priority, or change the date. The compiler will not paper over the conflict.
Why this matters. Most "AI memory" tools resolve conflicts statistically — the most-recently-retrieved chunk wins, or the longest match wins. That works for search. It does not work for governance. A precedence engine that refuses to emit on ambiguity is the right primitive for a layer that gates pull requests.
Run it against Mneme's own ADRs
The repo ships a Python walkthrough that runs the compiler end-to-end against Mneme's own architectural decisions. No API key. No external services. Local Mneme pipeline:
git clone https://github.com/TheoV823/mneme
cd mneme/mneme-project-memory
pip install -e .
python examples/demo-adr-import.pyThe walkthrough runs three stages: a dry-run preview of what would be imported, an apply step that writes the compiled decisions to a fresh memory file, and an enforcement check that runs mneme check against a namespace violation so ADR-005 fires on the wrong import path.
Expected output (abbreviated)
-- Step 2: Preview (dry-run -- no writes)
ADR import preview
============================================================
Active set (4 ADRs):
[ADR-001] status=active
[ADR-005] status=active
constraint: no MnemeHQ
constraint: FORBID_PATH site/use-cases/**/Mneme HQ*
...
-- Step 4: Enforcement check (namespace violation)
WARN [ADR-005] constraint "no MnemeHQ" -- trigger: mnemehq
Brand vs Package Namespace Enforcement
Result: WARNSame decision corpus, same retrieval engine, same enforcement output every time. If you fork the repo and edit an ADR, the next run reflects the edit. That is the loop a governance layer has to close.
Where this fits
The compiler is the upstream half of the loop. The downstream half is the editor hook (Claude Code, Cursor) and the CI gate (GitHub Actions). The same compiled corpus drives all three, so the constraints a developer sees mid-edit are the same constraints CI evaluates at merge.
- → ADR import integration — the operational reference for the compiler CLI.
- → Claude Code integration — pre-generation hook that injects the compiled decisions.
- → GitHub Actions integration — post-generation enforcement gate on PRs.
Dogfooding
Mneme HQ enforces its own ADRs through the compiler. The docs/adr/ directory in this repo holds the team's architectural decisions; the compiler keeps .mneme/project_memory.json in sync. When an AI-assisted task in this codebase generates a brand/namespace conflation, ADR-005 fires before the change reaches review. The walkthrough above is the same loop the maintainers use day-to-day.
Why this is strategically the most important demo
The drift demo shows the failure mode. The multi-agent demo shows where governance has to scale to. The compiler is the artifact that makes both of them tractable — it is the step that turns existing architectural documentation into the executable substrate the other two flagships rely on. Without a compiler, governance stays advisory. With one, it becomes infrastructure.