Your ADRs become constraints the rest of the system can enforce.
The compiler treats docs/adr/*.md as source: it reads the frontmatter, checks the directives, resolves precedence, emits project_memory.json, and hands the result to the normal enforcement pipeline. This walkthrough uses Mneme's own ADR-005—no model or external service required.
The ADR stops being a document and starts doing work.
This walkthrough follows compilation through to a real WARN. The flagship demo shows the corrected pass.
ADR-005 · Brand versus package namespace. The Python namespace is mneme. MnemeHQ is a forbidden dependency token on code-bearing surfaces.
-
01 Decision
A Markdown ADR carries accepted status, foundational priority, code scope, and constraint directives.
docs/adr/ADR-005.md · FORBID_DEPENDENCY: MnemeHQ -
02 Guidance
The compiler validates the directive, resolves precedence, and emits the active constraint.
emit .mneme/project_memory.json · active set: 4 ADRsDemonstrated -
03 Violation
The enforcement input uses the brand token as if it were the Python package namespace.
from MnemeHQ.memory_store import MemoryStore -
04 Deny / warnWARN
The compiled rule fires through the normal checker and names its source ADR.
WARN [ADR-005] · trigger: mnemehq -
05 CorrectionN/A
The compiler walkthrough stops after proving the emitted rule can fire.
Not included in this walkthrough -
06 AllowN/A
A corrected import and passing rerun are demonstrated in the governed Python flagship instead.
See governed-python-agent
Run it yourself
Compile Mneme's own ADRs
The repository walkthrough previews the import, writes a fresh memory file, and checks a namespace violation.
git clone https://github.com/MnemeHQ/mneme
cd mneme
pip install -e .
python examples/demo-adr-import.pyUnknown directives and unresolved equal-precedence conflicts fail closed instead of being silently omitted.
What happened
Teams keep Markdown rationale and add structured metadata only where enforcement needs it.
Supersession, priority, scope, and date are resolved before any hook or CI gate consumes the corpus.
The same emitted decision record drives agent guidance, enforcement checks, and the architectural-drift proof.
Common questions
Does the compiler replace Markdown ADRs?
No. ADR files remain the source. The compiler emits a structured downstream artifact for enforcement.
What happens when two ADRs conflict?
If precedence cannot be resolved deterministically, compilation stops. A human must supersede one decision, change priority, narrow scope, or otherwise remove the ambiguity.
Why are correction and allow absent?
This page proves the compiler and one emitted WARN. The full corrected-import PASS is shown in the governed Python agent demo.
Compile the decisions you already maintain.
Keep the ADRs human-readable and make their active constraints executable.
pipx install "mneme-hq>=0.5.1"