Skip to content

v0.4.0 — Architectural Compiler Foundation

Choose a tag to compare

View all tags
@TheoV823 TheoV823 released this 04 May 12:19
v0.4.0
47b4b0e

v0.4.0 — Architectural Compiler Foundation

Mneme is now the architectural compiler for AI-assisted development.

ADRs become the source of truth; the compiler is the deterministic rule
for turning them into the constraints the runtime injects.

What's new

ADR corpus  ->  parse  ->  validate  ->  resolve precedence
            ->  active constraint set  ->  Decision records  ->  runtime
  • mneme/adr_schema.py — ADR dataclass, ADRStatus /
    ADRPriority enums, typed errors (ADRParseError,
    ADRValidationError, ADRPrecedenceError).
  • mneme/adr_parser.py — parse_adr_file,
    parse_adr_directory. YAML frontmatter parser; structural failures
    only (missing / unterminated / malformed frontmatter).
  • mneme/adr_compiler.py — three public stages plus an
    orchestrator and a Decision bridge:
    • validate_corpus(adrs) — aggregates required-field, enum, id /
      date / scope grammar, supersedes reference resolution, and
      cycle-detection errors into a single ADRValidationError. One
      pass, every error.
    • resolve_precedence(adrs) — returns the active constraint set:
      status filter → explicit supersedes (chain-aware) → same-scope
      priority → newer date → ADRPrecedenceError if still ambiguous.
      The compiler never silently picks a winner.
    • compile_adrs(adr_dir) — end-to-end: parse → validate →
      precedence; output ordered most-specific-first.
    • adrs_to_decisions(adrs) — bridge into the existing Decision
      schema so the v0.3.x runtime pipeline (DecisionRetriever,
      ConflictDetector, ContextBuilder) consumes ADR-driven corpora
      without code changes.

ADR frontmatter

---
id: ADR-001
title: Use JSON file storage
status: accepted          # proposed | accepted | deprecated | superseded
priority: foundational    # foundational | normal | exception
date: 2026-01-10
scope: storage            # dotted path; empty string = global
supersedes: []
---

Body markdown follows.

Usage

from mneme.adr_compiler import compile_adrs, adrs_to_decisions
from mneme.decision_retriever import DecisionRetriever

decisions = adrs_to_decisions(compile_adrs("docs/adr"))
retriever = DecisionRetriever(decisions)

Why this matters

Until v0.4.0, Mneme was a retrieval + enforcement layer on top of a
hand-edited JSON file. Useful, but not a foundation: nothing told you
what the correct set of constraints was at any given point in time.

v0.4.0 makes the corpus declarative and the resolution deterministic.
The same ADR set always compiles to the same active constraint set;
conflicts surface as compile errors rather than as silent drift in
behavior. That is the foundation the rest of the governance roadmap
(retry/remediation, drift detection, cross-project memory) builds on.

Migration

No migration needed. ADR ingestion is opt-in and additive:

  • Existing project_memory.json workflows are unchanged.
  • MemoryStore, Pipeline, the v0.3.x enforcement modes, and the
    Claude Code hook all keep working as-is.
  • Adopt ADRs by wiring compile_adrs → adrs_to_decisions into your
    retriever construction; mix freely with JSON-backed decisions.

Tests and compatibility

  • 47 new tests across parser, validator, precedence, integration.
  • Full suite: 217 passed, 2 skipped (same e2e skips as v0.3.2).
  • Zero regressions; MemoryStore / Pipeline / DecisionRetriever
    unchanged.

Deferred (not in this release)

  • mneme adr compile <dir> CLI subcommand (library API is sufficient
    for v1; CLI is a v0.5 candidate).
  • Pipeline.from_adr_dir() classmethod (callers can wire
    adrs_to_decisions(compile_adrs(dir)) themselves).
  • Structured constraints: / anti_patterns: frontmatter fields.
  • Hyphenated scope segments and multi-scope lists.
  • Body-section parsing.
  • The formal docs/adr/ADR-003-architectural-constraint-metadata-schema.md
    spec doc — schema is described in the README, CHANGELOG, and code;
    authoring the canonical ADR is queued for v0.5.

Strategic framing

Version Theme
v0.3 Enforcement / governance checks
v0.4 Architectural compiler foundation
v0.5+ Advanced precedence / drift detection / structured constraint fields
Assets 2
Loading