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.
For the end-to-end product loop, see the Governed Python agent demo. This page explains the compiler step that turns ADRs into the governance corpus used by that demo.
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.
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.
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.
The animation below runs the same task two ways: once as a plain agent reading ADRs as documentation, and once through the ADR compiler. The difference is not the model. The difference is that the compiler parses frontmatter, extracts constraints, resolves precedence, and emits a deterministic governance corpus that hooks and CI can enforce.
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.
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.
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.
-- 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.
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.
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.
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 demos rely on. Without a compiler, governance stays advisory. With one, it becomes infrastructure. The product experience that demonstrates this end-to-end is the Governed Python agent demo.
Prefer video? Watch the full ADR compiler walkthrough — ADRs compiled into executable constraints, end-to-end.