Claude Memory vs CLAUDE.md: Which Context System Should You Use?

TL;DR: CLAUDE.md is your project's instruction manual — checked into the repo, shared with every team member, and loaded deterministically at the start of every conversation. Claude Memory is your personal notebook — auto-generated, per-user, and selectively recalled based on relevance. Use CLAUDE.md for project rules and conventions that the whole team needs. Use Claude Memory for personal preferences, learned context, and cross-session continuity. Most teams need both, and they work best together.

Overview: Claude Memory

Claude Memory is Claude Code's persistent, file-based context system that automatically saves information across conversations. When Claude learns something important during a session — your role, your preferences, how you like to work, the state of an ongoing project — it writes that knowledge to markdown files stored locally in .claude/projects/*/memory/. The next time you start a conversation, relevant memories are recalled automatically, so Claude picks up where you left off without you repeating yourself.

Memory is organized into four types: user memories (your role, expertise, preferences), feedback memories (corrections and confirmed approaches), project memories (ongoing work, deadlines, decisions), and reference memories (pointers to external systems like Linear boards or Grafana dashboards). Each memory is a standalone markdown file with frontmatter metadata, indexed in a central MEMORY.md file that Claude reads at conversation start.

The key characteristic of Claude Memory is that it is personal and automatic. It belongs to a specific user on a specific machine. It evolves organically as you work. And it is never committed to the repository — your teammates have their own separate memory stores. For a deeper look at how the memory system works in practice, see our Claude Code memory system guide.

Overview: CLAUDE.md

CLAUDE.md is a project-level instruction file that lives in the root of your repository and is loaded by Claude Code at the start of every conversation. Think of it as a README for your AI — it tells Claude what the project is, how to build and test it, what conventions to follow, and what mistakes to avoid. Unlike Memory, CLAUDE.md is deterministic: every team member, every session, every time, Claude reads the same instructions.

A well-structured CLAUDE.md typically includes build commands, test commands, architectural constraints, coding style rules, workflow requirements, and references to other configuration files like skill definitions. It is checked into version control, reviewed in pull requests, and evolves with the codebase. When your project's conventions change — a new linter rule, a migration to a different test framework, a renamed environment variable — you update CLAUDE.md and the entire team gets the change on their next git pull.

CLAUDE.md is part of a broader programmable layer system in Claude Code. It sits at the project level, above user-level settings and below task-specific skill files. This hierarchy means CLAUDE.md defines the baseline behavior that all other customizations build on. Our complete guide to Claude Code covers how CLAUDE.md fits into the full stack.

Feature Comparison

Feature	Claude Memory	CLAUDE.md	Winner
Scope	Per-user, per-project	Per-project, shared by team	Depends on use case
Persistence	Local filesystem only	Checked into git	CLAUDE.md
Creation	Auto-generated by Claude	Manually written and maintained	Claude Memory
Loading	Selectively recalled by relevance	Fully loaded every conversation	Tie
Content type	Learned context, preferences, feedback	Rules, commands, constraints	Tie
Team sharing	Not shared — each user has their own	Shared via repository	CLAUDE.md
Version control	Not version-controlled	Full git history	CLAUDE.md
Maintenance burden	Low — Claude manages it	Medium — requires manual updates	Claude Memory
Determinism	Variable — recalls may differ	Deterministic — same every time	CLAUDE.md
Capacity	Grows over time, ~200 line index limit	Single file, typically 50-200 lines	Claude Memory

Context Persistence: How Each System Remembers

Claude Memory and CLAUDE.md solve the same fundamental problem — giving Claude context it would otherwise lose between conversations — but they approach it from opposite directions.

Claude Memory persists learned knowledge automatically. When you tell Claude "I'm a data scientist focused on observability," or when Claude notices you prefer bundled PRs over small ones, it writes a memory file without you doing anything. The next session, it reads MEMORY.md to find relevant memories and loads them into context. This eliminates the repetitive "remind Claude who I am and what I'm working on" overhead that plagues stateless AI interactions.

The tradeoff is non-determinism. Memory recall depends on relevance matching — Claude decides which memories to load based on what seems relevant to the current conversation. Two sessions about different topics may recall different subsets of your memories. This is usually the right behavior, but it means you cannot guarantee that a specific piece of context will always be present.

CLAUDE.md persists project rules deterministically. Every conversation begins by loading the full contents of CLAUDE.md. There is no relevance filter, no selection process — everything in the file is always present. This makes it the right place for rules that must never be forgotten: build commands, quality gates, architectural constraints, and the list of things Claude should never do.

The tradeoff is maintenance burden. CLAUDE.md does not update itself. When your project changes — a new test framework, a renamed directory, an updated deployment process — someone needs to edit CLAUDE.md manually. If the file falls out of sync with reality, Claude follows outdated instructions. Teams that treat CLAUDE.md as a living document reviewed alongside code changes get the most value from it.

Team Collaboration: Shared vs Personal Context

This is the sharpest difference between the two systems, and it drives most of the "which should I use?" decisions.

CLAUDE.md is a team artifact. When you commit a CLAUDE.md that says "run npm test before every commit" and "never import Next.js modules in pipeline scripts," every developer on the team gets those constraints automatically. New team members who clone the repo inherit all of your project's AI conventions on day one. Changes to CLAUDE.md go through pull review, which means the team can discuss and agree on AI behavior rules the same way they discuss code changes.

This matters enormously for consistency. Without shared CLAUDE.md conventions, each developer's Claude operates with different assumptions. One developer's Claude uses Vitest, another's defaults to Jest. One follows your commit message format, another invents its own. CLAUDE.md eliminates this divergence. The extension stack architecture in Claude Code is specifically designed around this principle — shared configuration files create consistent behavior across an entire team.

Claude Memory is personal. Your memories about your role ("I'm a frontend specialist new to this repo's backend"), your preferences ("I prefer terse responses with no trailing summaries"), and your feedback ("don't mock the database in integration tests — we got burned last quarter") belong to you. They shape how Claude works with you specifically, not how it works with the project in general.

This is valuable because different team members have different needs. A senior backend engineer and a junior frontend developer working on the same repo need different explanations, different levels of detail, and different guardrails. Memory provides this personalization without polluting the shared CLAUDE.md with individual preferences.

The interaction rule is simple: if the context applies to everyone on the team, it belongs in CLAUDE.md. If it applies to you specifically, let Memory handle it. If you are unsure, default to CLAUDE.md — shared knowledge is more durable and more auditable than personal memory.

Content Organization: What Goes Where

Understanding what each system stores clarifies when to use which.

What belongs in CLAUDE.md

Build and test commands: npm run build, npm test, npm run lint
Quality gates: "All tests must pass before commit"
Architectural constraints: "Never import Next.js modules in pipeline scripts"
Forbidden patterns: "Never skip failing tests or comment out lint rules"
Workflow rules: "New feature → discuss design first, get approval before coding"
Style guidelines: "Newsletter tone: sharp tech insider briefing a busy founder"
File and directory conventions: "Skill files live in skills/*/SKILL.md"
Documentation update rules: "When modifying pipeline scripts, update PIPELINE.md"

These are project truths — objective, stable, and relevant to every contributor.

What belongs in Claude Memory

User profile: "User is a data scientist focused on logging and observability"
Working preferences: "User wants terse responses, no trailing summaries"
Feedback corrections: "Don't mock the database — user reported a prod incident from mock/prod divergence"
Confirmed approaches: "User prefers bundled PRs over many small ones for refactors"
Project state: "Merge freeze begins March 5 for mobile release cut"
External references: "Pipeline bugs tracked in Linear project INGEST"

These are contextual, personal, and often time-sensitive. They help Claude work with a specific person on a specific day, not enforce universal rules.

The gray zone

Some information could plausibly live in either system. A team convention like "we prefer integration tests over unit tests for database code" could be a CLAUDE.md rule or a personal feedback memory. The deciding factor: does the whole team need to follow this, or is it one person's learned preference?

If your team has agreed on the convention, put it in CLAUDE.md. If it is something you personally learned the hard way and want Claude to remember, let Memory capture it. When a personal memory proves universally valuable, promote it to CLAUDE.md — that is exactly how good engineering teams evolve their standards.

Maintenance and Lifecycle

CLAUDE.md requires intentional upkeep. It is a static file that only changes when someone edits it. The best teams treat CLAUDE.md updates as part of their definition of done — when you change the build system, you update CLAUDE.md in the same PR. When CLAUDE.md drifts from reality, Claude's behavior degrades: it runs outdated commands, follows deprecated conventions, or misses new constraints.

A practical approach: review CLAUDE.md during sprint retrospectives or quarterly cleanups. Ask whether every rule still applies, whether new conventions need to be added, and whether the file has grown too large. CLAUDE.md works best when it stays focused — the skills system exists specifically so that task-specific instructions can live in separate files rather than bloating the main configuration.

Claude Memory is largely self-maintaining. Claude creates, updates, and occasionally removes memory files as it learns. The MEMORY.md index has a practical limit of about 200 lines, which naturally constrains growth. Stale memories — about completed projects, outdated deadlines, or changed preferences — get updated or removed when Claude notices the contradiction.

That said, Memory is not perfectly self-cleaning. Over long periods, outdated memories can accumulate. Periodically reviewing the memory directory (.claude/projects/*/memory/) and removing files that no longer apply is good hygiene. You can also explicitly tell Claude to forget something: "forget the merge freeze — that shipped last week."

Loading Behavior: How Context Reaches Claude

Understanding the loading mechanics helps you design an effective context strategy.

CLAUDE.md loads fully and unconditionally. At conversation start, Claude reads the entire CLAUDE.md file (plus any user-level ~/.claude/CLAUDE.md). Every rule, every command, every constraint is present in context from the first message. This is why CLAUDE.md should stay concise — everything in it consumes context window space, and bloated CLAUDE.md files leave less room for actual work.

Memory loads selectively via an index. Claude reads the MEMORY.md index file, which contains one-line summaries of each memory. Based on the current conversation topic, it loads the full content of relevant memory files. This means Memory can store far more total context than CLAUDE.md without consuming excessive context window space — but individual memories may not be recalled if Claude judges them irrelevant to the current task.

This design has a practical implication: critical rules that must always apply go in CLAUDE.md; contextual information that is useful when relevant goes in Memory. Do not put quality gates in Memory — they might not be recalled during a quick bugfix conversation. Do not put your personal role description in CLAUDE.md — it is not relevant to your teammates.

Advanced Patterns: Using Both Systems Together

The most effective Claude Code setups use CLAUDE.md and Memory as complementary layers, not alternatives.

Pattern 1: CLAUDE.md sets the floor, Memory raises the ceiling. CLAUDE.md defines the minimum acceptable behavior: run tests, follow conventions, never skip quality gates. Memory adds personalization on top: your role context, your preferred explanation style, lessons learned from past sessions. This gives you consistent project behavior plus personalized interaction.

Pattern 2: Memory as CLAUDE.md incubator. When Claude captures a useful feedback memory — "this user wants integration tests for all database code" — evaluate whether it should be promoted to a CLAUDE.md rule. If the convention benefits the whole team, add it to CLAUDE.md and let the personal memory expire naturally. This creates a feedback loop where individual learning improves team standards.

Pattern 3: CLAUDE.md references, Memory remembers state. CLAUDE.md might say "pipeline cron runs at 4am SGT, Mon-Fri" — a stable fact. Memory might record "pipeline failed Tuesday due to API rate limit, user is investigating" — a transient state. Together, Claude understands both the system design and its current condition.

Anthropic's memory upgrade features continue to expand what Memory can track, including importing context from external sources. As these capabilities grow, the division of labor between CLAUDE.md and Memory becomes even more important to get right.

When to Choose Claude Memory

Use Claude Memory as your primary context mechanism when:

You are a solo developer and do not need to share AI conventions with a team. Memory captures everything Claude learns about your project and preferences without requiring you to maintain a separate file.
Your context is personal. Your role, expertise level, communication preferences, and working style are yours — they should not be in a shared project file.
You value low maintenance. If you would rather Claude figure out what matters over time than write and maintain an explicit instruction file, Memory is the lower-friction option.
You are working across many short-lived projects where writing a detailed CLAUDE.md for each one is not worth the effort. Memory carries your personal preferences across all of them.

Memory is weakest when consistency across team members matters. If two developers need Claude to behave identically, Memory cannot guarantee that — each person's memories diverge based on their own interactions.

When to Choose CLAUDE.md

Use CLAUDE.md as your primary context mechanism when:

You are on a team and need consistent AI behavior across all contributors. CLAUDE.md is the only way to guarantee every developer's Claude follows the same rules.
Your project has strict quality gates. Build commands, test requirements, linting rules, and deployment constraints must be deterministically enforced — not subject to Memory's relevance-based recall.
You need auditability. CLAUDE.md changes are tracked in git history. You can see when a rule was added, who added it, and why. Memory files have no version control.
You are onboarding new team members. A well-written CLAUDE.md means a new developer's Claude works correctly from the first conversation, with zero personal memory built up.

CLAUDE.md is weakest for personal context and evolving project state. It cannot adapt to individual users, and it requires manual updates to stay current.

Verdict

For teams: CLAUDE.md is non-negotiable, Memory is a valuable addition. Start with a focused CLAUDE.md that covers build commands, quality gates, and architectural constraints. Let each team member's Memory layer add personal context on top. Review CLAUDE.md in PRs and keep it concise — delegate task-specific instructions to skill files rather than expanding the main configuration file.

For solo developers: both systems add value, but Memory has lower friction. You still benefit from a minimal CLAUDE.md for project-specific commands and constraints, but Memory handles most of the context accumulation automatically. The combination gives you the best of both worlds: deterministic project rules plus adaptive personal context.

The wrong approach is choosing one and ignoring the other. CLAUDE.md without Memory means repeating yourself every session. Memory without CLAUDE.md means no guaranteed consistency. Use CLAUDE.md as the foundation and Memory as the intelligence layer — together, they give Claude Code the context it needs to work as a genuine agentic coding partner rather than a stateless autocomplete engine.

Frequently Asked Questions

Can Claude Memory override rules set in CLAUDE.md?

No. CLAUDE.md instructions are loaded unconditionally at conversation start and take priority over Memory content. If CLAUDE.md says "never skip tests" and a Memory file suggests otherwise, the CLAUDE.md rule wins. Memory is designed to add context, not contradict project-level constraints.

Does Claude Memory sync across machines?

No. Claude Memory files are stored locally in .claude/projects/*/memory/ on your machine. If you switch to a different computer, your memories do not follow. CLAUDE.md, by contrast, lives in the repository and syncs via git. For cross-machine continuity, your CLAUDE.md provides the baseline while Memory rebuilds organically through new conversations.

How large should CLAUDE.md be?

Keep it under 200 lines. CLAUDE.md loads fully into every conversation's context window, so bloated files waste token budget. Focus on rules that apply to every session — build commands, quality gates, architectural constraints, workflow requirements. Move task-specific instructions into skill files and let Memory handle personal context.

Can I manually edit Claude Memory files?

Yes. Memory files are plain markdown stored in .claude/projects/*/memory/. You can edit, delete, or add files directly. You can also tell Claude to remember or forget specific things during a conversation. Periodic cleanup of outdated memories improves recall quality.

Should I commit Memory files to the repository?

No. Memory files are personal and per-user. Committing them would impose one person's preferences and context on the entire team. Keep Memory in .gitignore (it is excluded by default) and use CLAUDE.md for shared project context.

Want more AI insights? Subscribe to LoreAI for daily briefings.