Mneme HQ vs CLAUDE.md (Project Instructions)

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

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.

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