Mneme HQ — Q&A and Glossary

Mneme HQ is the architectural governance layer for AI-assisted development: it compiles your architectural decision records into a deterministic active constraint set and enforces those decisions at the prompt boundary, blocking AI coding agents from generating code that contradicts decisions your team already made.

pip install mneme

Dependencies: anthropic >= 0.25.0, python-dotenv >= 1.0.0. That's the whole list. Python 3.11+. Optional [api] extra adds FastAPI and Uvicorn for the HTTP layer. No vector database, no model server, no background service.

Three steps. First, pip install mneme. Second, create a project_memory.json at your repo root with three to ten of the architectural decisions you care most about (or compile your existing docs/adr/ directory via compile_adrs). Third, install the Claude Code hook with python scripts/install_claude_code.py, or wire mneme check --mode warn into your CI on PRs. Start in warn mode; promote to strict once the corpus stabilizes.

No. Mneme HQ is local-first. Your project_memory.json, your ADRs, your code, and your enforcement verdicts all stay in your repo. The only outbound call is to the LLM provider you've configured (Anthropic, OpenAI, etc.) when you're running the demo or the API layer. There is no Mneme HQ-hosted service in the verdict loop.

Intervention at the prompt boundary, before the model generates code. The alternative — catching architectural drift in code review — is too late. By the time generated code lands in a PR, the diff exists, the context is loaded, the reviewer's attention is finite, and the rejected pattern has been written enough times that a future model call will see it in the conversation history and treat it as accepted. Governance-before-generation moves the intervention point upstream.

The gradual erosion of architectural decisions as code is added without enforcement. Drift is invisible in any single change but compounds over time. AI-assisted development accelerates drift because code output increases without a corresponding increase in review capacity. A team that catches 95% of architectural violations in review still ships compounding drift if AI is generating five times more code than humans are reviewing carefully.

Teams that already write ADRs or maintain an internal architecture document, run AI coding agents at meaningful volume (multiple devs on Claude Code, Cursor, or Copilot), and care about architectural consistency more than they care about raw generation speed. The fit is strongest for: mid-size eng orgs (50-500 engineers), regulated industries (fintech, health, gov-adjacent), open-source projects with strict scope discipline, and any team where "we already decided this six months ago" is a familiar phrase.

Teams without explicit architectural decisions to enforce. Mneme HQ enforces what you've already decided; it doesn't generate decisions for you. A team that has never written down its architectural choices won't benefit from a governance layer until they do. The right onboarding step for such a team is to write five to ten ADRs first.

It's a narrow slice of AI safety: governance of AI-generated code at the project level. It's not AI alignment, not model safety, not RLHF. It's the boring, auditable, deterministic kind of safety that matters when AI is actually shipping code into production. The relevant safety claim is reproducibility: every verdict is reconstructable, no black box, no model in the verdict loop.

The mechanism is general — Decisions and ADRs are not code-specific. In practice, the v0.x integrations and benchmark focus on code. Governance of generated docs, configs, or prompts is a plausible extension but is not currently in scope.

The repository governs itself with Mneme. Read CLAUDE.md and the freeze artifact (docs/architecture/layer1-freeze-e73ff7d.md) before opening a PR. Changes to decision_retriever.py, enforcer.py, benchmark.py, or any benchmark fixture are charter-level changes requiring the freeze doc's amendment procedure. Docs, tooling, integrations, the site, and examples proceed normally with [memory] prefix discipline for project_memory.json edits.

Yes, MIT licensed. The repository is at github.com/TheoV823/mneme. The mechanism, the benchmark methodology, the freeze artifact, the ADR compiler, and all integrations are open. Commercial offerings (managed governance, hosted policy packs, enterprise audit log) are planned for Layer 2 but the core stays open.

Mneme HQ ships a PreToolUse hook for Claude Code that intercepts every Edit, Write, and MultiEdit operation. The hook reconstructs the full post-edit file, runs mneme check against the active constraint set, and either blocks the write (strict mode) or surfaces the violation without blocking (warn mode). Install with pip install mneme then python scripts/install_claude_code.py. The installer is idempotent and writes .claude/settings.json, slash commands (/mneme-check, /mneme-context, /mneme-record, /mneme-review), and a discovery skill.

Mneme HQ generates Cursor rules files (.cursor/rules/) from your Decision corpus. The same decisions that drive the Claude Code hook compile to Cursor's rules format. This gives you a single source of truth (your ADRs or project_memory.json) and consistent enforcement across both agents.

Copilot integration is generation-based, not hook-based: Mneme HQ compiles your decisions into Copilot-compatible instruction files. Copilot does not expose a pre-tool-use hook surface comparable to Claude Code's, so enforcement is at the prompt layer rather than the edit layer. The same decision corpus drives Copilot, Cursor, and Claude Code.

Yes. Mneme HQ exposes a Python API (MemoryStore, DecisionRetriever, ContextBuilder, Pipeline) and a minimal HTTP API (POST /complete). Either can be wired into an agent's planning or tool-use loop. The pattern is: build the context packet, inject as system prompt, run the agent step, optionally run ConflictDetector against the output.

Yes. The Claude Code hook is one integration; the rest of the system is independent. Use Pipeline programmatically against any LLM, run mneme check in CI against any repo, generate Cursor rules, or call the HTTP API from an agent framework. The Claude Code hook is the flagship integration because Claude Code exposes a clean PreToolUse hook surface; other agents are reached via generated rules or pipeline integration.

A human-editable JSON file that holds your architectural decisions. It contains three top-level arrays: items (legacy rules, anti-patterns, preferences, facts, architecture_decisions, examples — auto-migrated to Decisions at load time), examples (decision examples with task/decision/rationale), and decisions (the modern typed Decision schema). The file is plain JSON — no tooling required to edit.

{
  "id": "mneme_storage_json",
  "decision": "Use JSON storage only",
  "rationale": "Avoid infra complexity and keep local-first.",
  "scope": ["storage", "backend"],
  "constraints": ["no postgres", "no external database"],
  "anti_patterns": ["introduce ORM", "add migration layer"]
}

Only id and decision are required. The remaining fields shape retrieval scoring and the enforcement check.

Field-weighted keyword overlap, fully deterministic:

score =
    overlap(query, decision)      * 1.0
  + overlap(query, scope)         * 2.0
  + overlap(query, constraints)   * 1.5
  + overlap(query, anti_patterns) * 1.5
  + overlap(query, rationale)     * 0.5

The top N decisions by score are injected (default DEFAULT_MAX_DECISIONS = 3). Rules and anti-patterns always surface regardless of query relevance. Same query plus same memory file produces byte-identical retrieval order on every run.

Three reasons. First, determinism: same query plus same memory must produce identical output, run to run. Embeddings drift with model updates. Second, debuggability: a keyword match is reconstructable; a vector similarity is not. Third, scope: governance corpora are small (tens to low hundreds of decisions). Embeddings solve a problem you don't have at this scale and cost reproducibility you can't afford to lose.

An Architectural Decision Record. Mneme HQ's ADR format is YAML frontmatter plus markdown body:

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

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

When two ADRs cover the same scope, the compiler resolves them in a strict order: first, explicit supersedes references remove ADRs from consideration (chain-aware, including N-node chains). Second, within the same scope, higher priority wins (foundational > normal > exception). Third, same scope and same priority, newer date wins. If still ambiguous, the compiler raises ADRPrecedenceError rather than silently picking a winner. Broader and narrower scopes coexist; output is sorted most-specific-first.

validate_corpus aggregates every detected problem before raising — one pass surfaces every error so maintainers fix the corpus once instead of discovering problems serially. Checks include: required fields present, ADR id format and uniqueness, valid status and priority enum values, ISO 8601 date, scope grammar (lowercase dotted path, no leading or trailing dot), supersedes references resolving to known ADRs, and no supersession cycles (self-cycles, two-node cycles, and N-node cycles all detected).

Mark the corresponding ADR with status: deprecated or status: superseded, and (in the superseded case) add the superseding ADR's id to the new ADR's supersedes array. The compiler will remove deprecated and superseded ADRs from the active constraint set automatically. The history stays in the corpus — the active set updates.

Three properties matter. First, specificity: the decision field should be unambiguous and falsifiable ("Use JSON file storage" beats "Be careful with storage"). Second, scope: the scope array names the modules or domains where the decision applies, used by the retriever to surface the decision when relevant queries come in. Third, the constraints and anti_patterns arrays should list the terms an LLM would use when violating the decision — these are what the conflict detector matches against. A Decision with rich anti_patterns enforces; a Decision with only decision and rationale informs but cannot block.

In the Decision schema, both are flagged by the conflict detector. The distinction is editorial: constraints describe what must be true ("REST only", "no external database"); anti_patterns describe what must not be done ("introduce ORM", "add migration layer"). Both fields contribute to retrieval scoring with weight 1.5.

strict and warn. In strict mode, mneme check exits non-zero on any violation and the Claude Code hook blocks the write. In warn mode, violations are surfaced without blocking — useful for adopting Mneme HQ on an existing repo where you want visibility before turning on enforcement. The default Claude Code hook mode is strict; the default GitHub Actions workflow mode is warn (so PRs see governance feedback without blocking merges during rollout).

It runs a governance pass over a diff or working tree. For each changed file, it derives a query from the file path, retrieves the relevant decisions, and runs the conflict detector against the file contents. Output is a list of verdicts: which decision matched, which rule triggered, which term in the input fired it. In strict mode, any violation exits non-zero. In warn mode, violations are printed and the exit code is zero.

ConflictDetector scans the LLM response (or the post-edit file contents) for constraint and anti-pattern terms drawn from the injected decisions. A term is flagged when it appears with a positive recommendation signal and no negation nearby. "Do not use Postgres" is not a conflict. "Switch to Postgres" is. Each conflict carries the violated decision id, the reason, and a snippet for human review.

No. The retrieval, the injection, the conflict detection, and the verdict are all deterministic. The model is in the generation loop (it's the thing being governed), but the governance verdict itself is reconstructable without any model call. This is intentional: "deterministic > clever" is a charter principle. The upgrade path to a model-based judge is explicit in the code (replace two functions) and remains opt-in.

No. Mneme HQ blocks. The human or model fixes. Auto-fixing is explicitly out of scope: a deterministic governance layer cannot also be the thing that decides how to comply, or it becomes the same kind of opinionated agent it's meant to govern.

The Claude Code hook blocks the write and surfaces the violation. Options: amend the prompt to comply with the decision, override the verdict if the decision needs to evolve (and update the ADR first, with a supersedes if applicable), or temporarily set MNEME_HOOK_MODE=warn if you're in the middle of an intentional architectural change that the corpus hasn't caught up to. Strict mode is meant to make you stop and think — not to be circumvented as a workflow habit.

The hook adds milliseconds, not seconds. Retrieval is keyword scoring over a small JSON file; injection is a string concatenation; conflict detection is regex over the post-edit file. The variable cost is the LLM call itself, which Mneme HQ does not perform — it just shapes the prompt and checks the result.

The Mneme HQ core mechanism — retrieval mechanics, enforcement semantics, benchmark methodology — is pinned at commit e73ff7d. No behavioral change is permitted to those modules without an explicit charter amendment. The freeze exists because validation requires a stable mechanism: you cannot prove a governance layer prevents drift if the layer itself drifts.

Layer 2 covers multi-repo governance, team policy synchronization, shared policy packs, org-wide policy distribution, and deeper IDE integrations (LSP, JetBrains). All explicitly out of scope for Layer 1. It opens only after Layer 1 exit criteria are met: real-world drift prevention, design-partner feedback, governance wedge validation. The discipline is deliberate — Layer 1 is a wedge, not a platform.

A regression and integrity instrument, not a generalization claim. It uses canned LLM responses, fixed retrieval, and rule-text matching to make every change to retrieval or enforcement visible. Two-layer scoring: Layer 1 (retrieval) and Layer 2 (enforcement) are recorded independently per scenario. The WEAK_RETRIEVAL verdict explicitly flags coincidental passes — cases where enforcement happened to succeed without the relevant decision actually being retrieved. Recall@1 is reported but never optimized against.

For every scenario in the benchmark fixture set, the relevant decision appears in the top three retrieved decisions. K=3 is the canonical injection cutoff — the enforcer reads the top three retrieved decisions and only those. Recall@3 = 1.00 means no scenario in the suite has its critical decision pushed below the injection cutoff by the retriever.

Recall@1 is the sharpest tuning dial under fixed methodology. Optimizing against it on a small fixture set leads to overfitting — you end up with a retriever that aces the suite and fails on real corpora. Reporting without optimizing keeps the dial visible (so a regression shows up) without rewarding suite-specific tweaks.

Cursor Rules and CLAUDE.md are unstructured text blobs pasted into the prompt. They have no precedence semantics, no validation, no conflict detection, and no enforcement. When two rules contradict each other, the model picks one — usually whichever appears later or sounds more confident. There is no audit trail of what was injected, no way to verify it ran, and no scoring of whether the output followed the rules. Mneme HQ replaces this with a typed schema (Decisions and ADRs), deterministic retrieval, deterministic precedence resolution, pre-flight enforcement, and post-response conflict detection — every step reconstructable from artifacts.

RAG retrieves information. Mneme HQ retrieves decisions. RAG's goal is to inform the response; Mneme HQ's goal is to shape the response. RAG asks "did the model use the right source?"; Mneme HQ asks "did the model respect the constraint?" RAG is fuzzy by design (vector similarity, top-k chunks); Mneme HQ is deterministic by design (same query plus same memory always returns the same ranking).

A linter checks syntax, style, and known bug patterns against the source code after it's written. Mneme HQ checks proposed changes against architectural decisions before generation. Linters operate on syntax; Mneme HQ operates on intent. A linter cannot block "rebuild the retrieval system with embeddings" because there's no syntactic signature for that decision — but Mneme HQ can.

LLM-as-judge introduces a second model to evaluate the first model's output. It's powerful but nondeterministic — the judge's verdict varies run to run and degrades with model updates. Mneme HQ's evaluator is deterministic by design. The upgrade path to a model judge is explicit in the code (replace two functions) but is opt-in and not the default. In Layer 1, the deterministic evaluator is canonical.