## Why the compiler is the foundation

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.

Parse docs/adr/*.md
→
Validate frontmatter + directives
→
Resolve precedence + supersession
→
Emit project_memory.json
→
Enforce hook + CI + retry

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.

Live animation

## See it live: ADRs as source, governance as output

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.

Without the compiler
With the compiler
mneme check --mode strict

## 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.py

The 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: WARN

Same 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.

## The compiler is the engine room

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.

## Video walkthrough

Prefer video? Watch the full ADR compiler walkthrough — ADRs compiled into executable constraints, end-to-end.

Related governance concepts

- Architectural compiler

  The pipeline that converts documentation-form decisions into machine-evaluable constraint records.

- Precedence semantics

  Ordered rules that resolve overlapping decisions deterministically — supersession, scope, recency.

- Governance infrastructure

  The platform layer that encodes, distributes, versions, and enforces decisions across agents and CI.

- Verification contracts

  Pre-registered, machine-evaluable assertions that define what a governance check must prove.

Flagship 01 · Centerpiece

#### Governed Python agent

See the full product loop: a Python agent proposes a violating import, Mneme blocks it using this compiled corpus, the agent retries with correct code.

See the product demo →
Flagship 03

#### Governance continuity across actors

Where the compiler has to scale to once AI execution becomes parallel and persistent.

See the trace →