Reference Architecture · Simulated Scenario
How Mneme HQ Prevents Coding Assistants from Violating Architecture Rules
Stop Cursor, Claude Code, and Copilot from ignoring your ADRs, service boundaries, and team conventions — session after session.
The Problem
Your coding assistant has no memory of yesterday's decisions.
Every session with a coding assistant starts fresh. It doesn't know that you decided in March to never bypass the service layer. It doesn't know that the embeddings approach was ruled out after a spike. It doesn't know your team's naming conventions or which abstractions are off-limits.
The result: repeated architectural violations, slow code review, and "we've discussed this" conversations that happen every sprint.
Without Mneme HQ — Cursor suggests:
Prompt: "Add a search endpoint to the API"
Let me query the database directly from the route handler for simplicity. I'll add a raw SQL query to the endpoint to filter results...
With Mneme HQ — pre-flight check:
mneme check --mode strict
✗ FAIL decision/no-direct-db-queriesRule: All database access must go through the repository layer.
Context: Direct queries in route handlers bypass transaction management and were banned in ADR-004.
→ Surfaced 1 violation before code generation.
Why Existing Tools Fall Short
RAG and system prompts don't hold across sessions.
| Approach | Limitation | With Mneme HQ |
|---|---|---|
| System prompt | Truncated at context limit; can't cover full decision history; manually maintained | Decisions retrieved at query time — only relevant decisions are surfaced |
| RAG over docs | Documents aren't decisions; no enforcement layer; retrieves text, not rules | Structured decision store with explicit violation detection |
| Code review | Catches violations after the fact; wastes reviewer time on avoidable issues | Pre-flight check catches violations before code is written |
| CLAUDE.md / .cursorrules | Flat text; no semantic retrieval; decays as teams add more rules | Mneme HQ generates optimized rules files from structured decision store |
How Mneme HQ Solves It
Decision-aware pre-flight checks for every AI request.
1
Capture decisions in structured YAML
Record architectural decisions, constraints, and anti-patterns in decisions/. Each entry has a rule, rationale, and enforcement metadata.
2
Run mneme check before prompting
Pass your intended prompt or planned change through Mneme HQ. It retrieves relevant decisions and checks for potential violations.
3
Generate assistant-specific rules files
mneme cursor generate outputs .cursor/rules/mneme.mdc — a distilled ruleset the assistant sees in every session.
4
Gate CI on decision compliance
Add mneme check --mode strict to your CI pipeline. PRs that violate architectural decisions fail before review.
Technical Implementation
What the setup looks like.
decisions/adr-004-no-direct-db.yml
id: no-direct-db-queries title: All database access via repository layer status: accepted rule: Never query the database directly from route handlers or services. rationale: Direct queries bypass transaction management and make testing impossible. Banned after incident in sprint 14 (ADR-004). enforcement: strict tags: [architecture, database, anti-pattern]
Terminal — mneme check output
$ mneme check "add a search endpoint that filters by tag" --mode strict Retrieving relevant decisions... (3 matched) ✓ PASS decision/use-repository-pattern ✓ PASS decision/tag-filtering-via-indexed-column ✗ FAIL decision/no-direct-db-queries Reason: Prompt implies direct query construction in handler layer. See: decisions/adr-004-no-direct-db.yml Result: FAIL (1 violation, strict mode)
CI — .github/workflows/mneme.yml
- name: Check decision compliance run: mneme check --mode strict --ci
Simulated Outcome
What teams report after adding decision enforcement.
Pre-flight
violations surfaced before code generation, not at review
0
repeated "we discussed this" review comments per sprint
~2 min
to add a new decision to the enforcement layer
⚠ These figures are based on Mneme HQ's internal benchmark harness across 18 simulated violation scenarios — not live customer data.
FAQ
Common questions.
Does Mneme HQ work with Cursor, Claude Code, and Copilot?
Yes. Mneme HQ works at the workflow level — it's not an IDE plugin.
mneme check runs before you prompt, and mneme cursor generate writes a rules file that Cursor picks up automatically. Claude Code users can source the generated rules file via CLAUDE.md.What's the difference between Mneme HQ and just writing better system prompts?
System prompts are static and have a context limit. As your decision history grows, a system prompt can't hold it. Mneme HQ uses semantic retrieval — only the decisions relevant to the current query are surfaced, so context stays focused and accurate as the project evolves.
How long does it take to set up?
Under 5 minutes for a project with existing documentation.
pip install mneme-hq, add your first decision to .mneme/project_memory.json, and run mneme check. See the README for the quickstart.Can I enforce decisions in CI without blocking the pipeline during setup?
Yes. Use
--mode warn for a non-blocking run that logs violations without failing the build. Switch to --mode strict once you're confident in your decision set.