Instruction Files 6 min read · June 2026

# Mneme HQ vs CLAUDE.md (Project Instructions)

A `CLAUDE.md` tells the model how your project works. Mneme HQ makes the rules that matter actually hold. They are not competitors — they are two layers of the same workflow, and most teams end up running both.

By Theo Valmis · Published June 2026 · Updated June 2026

If you use Claude Code, you almost certainly have a `CLAUDE.md`. It is the file Claude reads at the start of a session to learn your conventions: the framework you use, the patterns you prefer, the things you have asked it not to do. The same pattern shows up everywhere now — `AGENTS.md`, `.cursorrules`, `.github/copilot-instructions.md`. One markdown file, injected as context, telling the model how to behave.

This is a genuinely useful workflow, and Mneme is not here to take it away. The question this page answers is narrower and more practical: what does an instructions file do well, where does it quietly stop working, and what do you add when "the model should follow this" becomes "the model must"?

## What CLAUDE.md / project instructions are

- A single markdown file at the repo root (or a small set of them), written in prose
- Injected into the model's context at the start of a session as system-prompt preamble
- Authored by hand — no schema, no typed fields, no scope, no status
- Tool-specific: `CLAUDE.md` for Claude Code, `.cursorrules` for Cursor, and so on — each tool reads its own
- Advisory: the model receives the text as guidance and may still generate something that contradicts it

For a small repo with a short file and a single developer, that is often all you need. The model reads the conventions, mostly follows them, and you move on. The trouble starts at scale — and it is worth being precise about why, because it is not a quality problem you can fix by writing the file better. We unpacked the full mechanism in why CLAUDE.md stops scaling.

## What Mneme HQ does differently

Dimension | CLAUDE.md / project instructions | Mneme HQ
--- | --- | ---
Format | Markdown prose | Structured JSON (typed: id, scope, status, rationale, supersedes)
Enforcement | Advisory context the model may ignore | Hook-level blocking on Edit/Write operations
Scope | One file, applied to the whole repo | Per-file glob (e.g. `services/payments/**`)
Conflicting rules | Resolved by the model's attention | Deterministic precedence engine
Behavior as it grows | Degrades — context dilution, skipped rules | Retrieval surfaces only the relevant decisions
Versioning | Git diff over prose | Typed status: draft / active / superseded + supersedes chain
Tool coverage | One file per tool (CLAUDE.md, AGENTS.md, .cursorrules) | One corpus governing every agent and editor
Audit | "The model read it" — unprovable | Provenance: which decision blocked which edit, and why
CI | Not enforced outside an editor session | `mneme check` gates pull requests

The one-line version: a CLAUDE.md is something the model is asked to respect. Mneme is something the toolchain enforces. The first is configuration; the second is enforcement. Whenever a rule has to hold rather than merely be suggested, that rule has outgrown the file.

## They overlap on purpose

This is the part teams get wrong when they frame it as a choice. CLAUDE.md and Mneme are not two answers to one question — they are two layers of one workflow, and the healthiest setup keeps both.

Think of your `CLAUDE.md` as the README the model reads: narrative context, onboarding, soft preferences, the "how we think about this codebase" that genuinely helps an agent do better work. It is good at that, and a typed decision corpus would be a worse place to put it. Then take the handful of rules in that file that are actually load-bearing — the ones where a violation is a bug, not a style nit — and promote them into Mneme decisions, where they get scope, precedence, and a hook that blocks the edit if it breaks them.

Keep the prose. Promote the rules. The CLAUDE.md stays as the human-and-model-readable intent surface. The subset that must never be violated moves into Mneme, where "must" is a guarantee rather than a hope. Nothing is deleted; the load-bearing rules just stop depending on the model paying attention.

## When CLAUDE.md alone is enough

- You are a solo developer, or a small team that all work the same way
- The file is short — it still fits comfortably in context without crowding out the task
- Your conventions apply uniformly to the whole repo, with no per-directory exceptions
- Advisory is acceptable — you have not yet shipped a violation because the model ignored a rule
- No agents run outside an interactive editor session (no CI agents, no async runs)

## When you have outgrown the file

- The file has grown and the model started missing things. This is the most common trigger, and it is structural, not a wording problem — see why CLAUDE.md stops scaling.
- A rule has to block, not suggest. "Never call the payments API directly from the UI layer" is not a preference. If it can be ignored, it will eventually be ignored.
- Different areas need different rules. A flat file cannot say "strict here, relaxed there." Glob-scoped decisions can.
- You run more than one tool or agent. Keeping `CLAUDE.md`, `.cursorrules`, and a Copilot file in sync by hand is a losing game. One corpus governs all of them.
- Rules conflict. Org policy vs team exception vs personal preference — without precedence, the model arbitrates. Mneme resolves it deterministically.
- You need to prove it held. Compliance and incident review need "this decision blocked this edit," not "we wrote it down and hoped."

## How they coexist, concretely

1. Keep your `CLAUDE.md`. It is still the best place for narrative context and onboarding.
2. Run `mneme init` to scaffold a decision corpus at the repo root.
3. Walk the file and pull out every rule that must hold. Convert each into a typed entry: id, scope (file glob), status, rationale.
4. Enable the Claude Code hook so Edit, Write, and MultiEdit operations check the corpus before applying.
5. Add `mneme check` to CI so the same decisions gate pull requests, including those opened by agents.

The CLAUDE.md gets shorter and clearer (the enforcement-grade rules have moved out), and the rules that matter now actually hold across every tool and every session.

## Decision matrix — choose in 30 seconds

If most of these are true, a CLAUDE.md alone is fine:

- Solo or small same-editor team; short instructions file.
- Conventions apply uniformly across the whole repo.
- You have never shipped a violation because the model ignored an instruction.
- No agents touch the codebase outside an interactive session.

If any of these are true, add Mneme underneath the file:

- The file has grown past a screen and the model has started skipping parts of it.
- At least one rule must block a diff rather than be a suggestion.
- Different parts of the codebase need different constraints.
- You run Claude Code, Cursor, Copilot, or a CI agent — more than one instruction surface to keep in sync.
- You need an audit trail of which decision governed which change.

## A note on Claude Code Memory specifically

This page is about the instructions file as a cross-tool workflow artifact. If your question is specifically about Claude Code's built-in memory feature — how it persists across sessions and where it stops — the Mneme HQ vs Claude Code Memory comparison covers that angle directly. For the per-repo rules-file equivalent in Cursor, see Mneme HQ vs Cursor Rules.

## FAQ

Can I keep my CLAUDE.md and use Mneme HQ?
Yes, and most teams do. CLAUDE.md stays as the human-readable intent surface that onboards engineers and gives the model narrative context. Mneme holds the subset of decisions that must actually be enforced, as typed entries with scope and precedence. The instructions file explains; Mneme enforces. They operate on different layers and do not conflict — see the Claude Code integration guide.
Does Mneme HQ replace CLAUDE.md?
No. It is complementary, not a replacement. A CLAUDE.md is good at narrative onboarding and soft conventions; it is bad at guaranteeing a rule holds. Mneme does not try to be a prose doc. It takes the load-bearing rules out of the file and makes them deterministic and blocking, while CLAUDE.md keeps doing what prose does well.
Why does CLAUDE.md stop working as it grows?
An instructions file is advisory context competing for attention in the model's window. As it grows past a screen or two, the model starts skipping rules, applying them inconsistently, or letting later sessions drift from earlier intent. The rules are still correct; they are just no longer reliably applied. Enforcement that runs at edit time does not have this failure mode — the full argument is in why CLAUDE.md stops scaling.
Does this apply to AGENTS.md and Copilot instructions too?
Yes. CLAUDE.md, AGENTS.md, `.cursorrules`, and `.github/copilot-instructions` are the same pattern: a per-tool markdown file injected as advisory context. Each is tied to one tool and each is non-binding. Mneme is the tool-agnostic enforcement layer underneath all of them, so the same decision governs every agent and every editor that touches the repo — the architectural argument is on the heterogeneous-agents article.
Related governance concepts

- Governance before generation

  Enforce architectural constraints before the model produces output, not after it ships.

- Deterministic enforcement

  Same input, same verdict, every time — the property an advisory file cannot offer.

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