For Staff & Principal Engineers

# Stop Repeating Architectural Decisions in Every PR Review

You've explained the service boundary three times this sprint. The AI didn't know. The developer didn't check. Mneme HQ puts your decisions in the loop — before the code is written.

By Theo Valmis · Published Apr 2026 · Updated May 2026

The Problem

## Your review time is being consumed by violations the AI caused.

01

Repeated PR comments for the same violations — different developers, same mistake

02

AI coding assistants have no memory of past reviews

03

Every session starts from zero — no institutional context

04

Senior engineer time consumed by architectural correction that should be automatic

The Fix

## Record decisions once. Enforce them everywhere.

"An ADR in a docs folder informs. An ADR in Mneme HQ enforces."
1

Record architectural decisions in `project_memory.json` (or import existing ADRs)

2

Set scope patterns so decisions fire only where relevant

3

Install the Claude Code hook — violations are blocked before the file is written

4

Decision stays enforced across all developers, all sessions, all agents

What This Looks Like

## Before and after

Without Mneme

AI writes payments handler using raw SQL → reviewer catches it → back-and-forth on PR → merged 3 days later → pattern repeats next sprint

With Mneme

AI attempts raw SQL write → hook fires → violation blocked → constraint surfaced in-context → developer fixes before PR opens

## How it works in practice

Most principal engineers we talk to are not short on architectural taste. They are short on time to repeat themselves. The arc is consistent: a decision gets made, an ADR gets written, six weeks pass, three new engineers join, the AI session does not know any of this, and the same review comment appears on a new PR for the third time.

Mneme HQ inverts that loop. Architectural decisions live in `project_memory.json` as typed records (id, scope, status, rationale, supersedes). The retriever scores each prompt against the corpus and surfaces only the relevant constraints to the AI session. The hook intercepts every Edit, Write, and MultiEdit before the file lands — violations come back as feedback the model can act on, not as a blocked operation a human has to debug.

When a decision changes, you update one record. The corpus is version-controlled with the code, so the change shows up in PR review the same way any other change does. Override events (overriding a rule explicitly for a specific PR) are themselves tracked, so weakening a constraint is a visible decision rather than a silent merge. None of this is configuration that the model can ignore. It is enforcement at the seam where every AI agent eventually has to write to disk.

The same corpus drives interactive sessions through Claude Code or Cursor and the GitHub Actions enforcement gate. You write the rule once. It applies in the editor, in CI, and in any custom SDK agent the platform team builds — without per-tool duplication. See the architectural governance article for the design rationale.

## FAQ

How is this different from writing a stricter CLAUDE.md?
CLAUDE.md is static text injected at session start — the model reads it and is asked to respect it. The Mneme hook runs at every Edit, Write, and MultiEdit and can block the operation outright if it violates a decision. Compliance is not probabilistic. See why prompt memory fails at scale.
What if a rule needs to be temporarily overridden?
Override events are tracked. The override is itself a decision record with a rationale, scope, and expiry — visible in PR review like any other diff. Weakening a constraint costs the same as introducing one: a few lines of structured edit. Silent overrides are not possible.
Does this work in CI as well as the editor?
Yes. `mneme check --mode strict` runs in CI via the GitHub Actions enforcement gate and blocks PRs on hard FAIL verdicts. The same decision corpus drives interactive Claude Code sessions and CI checks — no per-tool duplication.