Mneme HQ vs Claude Code Memory

What Claude Code memory does

• Reads CLAUDE.md files at session start and injects them into the system prompt as instructions
• Supports project-level, user-level, and global memory files with simple text concatenation
• Lets the developer write conventions, build commands, and rules in free-form markdown
• Provides orientation context so the model behaves coherently across a project
• Operates entirely as guidance: every instruction is something the model may follow

CLAUDE.md solves a real problem: without a memory file, every session starts cold and the model has no project context. With one, the model arrives oriented. What it does not do is make any of those instructions binding — the model reads them and decides.

What Mneme HQ does differently

When CLAUDE.md is the right choice

• You need to orient the model on how a project is laid out, what build commands to run, what conventions exist
• The rules are advisory — "prefer this," "we usually do that" — not invariants
• You are only working in Claude Code and have no need for the same rules to govern Cursor, codex, or a custom agent
• The cost of the model occasionally ignoring an instruction is low: a small style miss, a PR comment, a re-prompt
• You want a single file you can read top-to-bottom, not a structured corpus

When Mneme HQ is required

• You need enforcement, not instructions. If the cost of a violation is more than a re-prompt — a banned dependency reaches main, a storage backend rule gets quietly broken, a service boundary gets crossed — instructions in CLAUDE.md are not enough. Mneme HQ blocks the Edit/Write at the tool-call boundary, before the file is written.
• Your rules are scope-specific. services/payments/** has different storage rules than analytics/**. CLAUDE.md is flat — one file, one global block of instructions. Mneme decisions carry a glob and only fire where they apply.
• You have conflicting rules. An org-wide policy, a team override, and a temporary exception cannot coexist in a flat markdown file without ambiguity. Mneme's precedence engine resolves the conflict deterministically; the model is told exactly which rule applies and why.
• You run more than one agent. CLAUDE.md is Claude Code's surface. Cursor reads .cursorrules; codex reads its own config; custom MCP clients read whatever you wire. A Mneme decision corpus exports to all of them from a single source of truth.
• Decision history matters. When a rule changed, why, and what it replaced — CLAUDE.md is a file you overwrite. Mneme tracks supersedes chains so the lineage of every architectural decision is queryable.

Using both together

These layers are not in tension. CLAUDE.md is for the context the model needs to do useful work in your repo: layout, commands, conventions, the kind of orientation a new contributor would get from a README. Mneme HQ is for the decisions that must not be violated regardless of what the model does with that context.

A practical division: anything in CLAUDE.md that starts with always, never, or must belongs in Mneme. Everything else — the build commands, the layout, the "we tend to do it this way" — stays in CLAUDE.md. The model is oriented by the markdown and constrained by the hook.

Why instructions cannot enforce

CLAUDE.md is loaded as part of the system prompt. As the conversation grows, that prompt competes with everything else in the context window. Sections can be paraphrased, conflated, or quietly deprioritized by the attention mechanism. The model has no obligation to surface that it ignored a rule; from the outside it looks like a normal edit. By the time the diff is visible, the violation is already on disk.

A hook at the Edit/Write boundary does not depend on the model reading anything. The tool call is intercepted; the decision corpus is consulted; the call is allowed or blocked. That is a different category of guarantee than "the system prompt said so."

For the broader argument that prompt-level instructions are not architectural governance, see prompt engineering is not governance.

Decision matrix — choose in 30 seconds

Both layers earn their place. The question is what each is best at:

• Use CLAUDE.md alone if your rules are advisory, your team is one or two people, you only work in Claude Code, and "the model usually does the right thing" is an acceptable bar.
• Use Mneme HQ alone only if you have already moved all orientation context elsewhere (a README the model reads, or skill files) and you want a single source of truth for enforceable rules. Most teams do not go this route — CLAUDE.md is the right place for orientation.
• Use both — the typical pattern. CLAUDE.md carries the orientation; Mneme carries the architectural decisions. The model is primed by the markdown; the hook prevents violations the priming missed.

FAQ