Comparative 5 min read · May 2026

# Mneme HQ vs Claude Code Memory

Claude Code's CLAUDE.md is a memory file the model reads as context. Mneme HQ is an enforcement layer the model cannot ignore. One is instructions. The other is a hook that blocks the Edit/Write call before the violation lands on disk.

By Theo Valmis · Published May 2026

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

Dimension | Claude Code memory | Mneme HQ
--- | --- | ---
Format | Markdown instructions file | Structured JSON decision corpus
Enforcement | Model reads and may follow | Hook blocks Edit/Write at violation
Scope | Whole project, flat | Per-file glob pattern matching
Conflict resolution | Model judgment | Deterministic precedence engine
Decision versioning | None | draft / active / superseded chain
Multi-agent | Single file, Claude-Code specific | Shared corpus for all agents
Specificity | Free-form prose | Typed fields: id, scope, rationale, supersedes
Open source | Built into Claude Code (closed) | MIT, self-hosted

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

The fundamental distinction: CLAUDE.md gives the model instructions it may follow. Mneme HQ blocks violations before they're written. For solo developers who can re-prompt when the model drifts, CLAUDE.md is often enough. For teams that need an architectural decision to hold across sessions, agents, and contributors, instructions are not enforcement.

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

Does Mneme HQ replace CLAUDE.md, or do they coexist?
They coexist. CLAUDE.md is the right place for project conventions, build commands, and orientation context that the model benefits from reading at session start. Mneme HQ is the right place for architectural decisions that must not be violated regardless of what the model decides to do with the CLAUDE.md context. The two layers serve different purposes: CLAUDE.md primes the model, Mneme enforces at the tool-call boundary.
Why isn't a well-written CLAUDE.md enough?
Because CLAUDE.md is read as context, not enforced as a constraint. The model may follow it, may partially follow it, may miss a section as the context window fills, or may decide a rule does not apply to the current edit. There is no deterministic stop. For rules where "the model usually does the right thing" is not good enough, you need a hook that blocks the Edit/Write call before the file is written. See prompt engineering is not governance for the longer form of the argument.
Does Mneme HQ work for agents other than Claude Code?
Yes. The decision corpus is agent-agnostic. Claude Code is the first integration because of its hook surface, but the same corpus exports to Cursor rules, can be queried from any agent that supports MCP, and can be enforced in CI for agents that do not have a hook layer. CLAUDE.md is Claude-Code-specific by design.
What does a Mneme decision look like compared to a CLAUDE.md instruction?
A CLAUDE.md instruction is a sentence of prose: "Use the repository pattern in services/payments." A Mneme decision is a structured record with an `id`, scope `glob`, `status` (draft/active/superseded), `constraints` field, `supersedes` chain, and `rationale`. The model still sees a human-readable explanation, but the hook can match the scope deterministically and the precedence engine can resolve conflicts.
Related governance concepts

- Multi-agent continuity

  Decisions persist across agents, sessions, and time. Decision-side memory, not agent-side memory.

- Enforcement provenance

  Every verdict traceable back to the authoring ADR. Opaque enforcement is theater.

- Governance infrastructure

  The platform layer that encodes, distributes, versions, and enforces decisions across agents and CI.

- Deterministic enforcement

  Same input, same verdict — every run, every agent, every consumer. The precondition for auditability.