Claude Code Memory and Context Persistence

Claude Code Memory. Understanding Claude Code memory is key to consistent results. This guide explains the CLAUDE.md hierarchy, project rules, user memory, and how context persists across sessions.

Claude Code Memory: What You’ll Learn

In this guide to Claude Code Memory, you’ll work through practical, hands-on steps with real examples. Claude Code Memory is explained from the ground up so you can apply it immediately in your own projects.

In Claude Code, “memory” refers to context that carries over between sessions. While the conversation window resets each time you start fresh, memory files are loaded automatically every time Claude Code launches. This lesson explains the hierarchy of memory files, how to create and update them, and how auto memory operates in the background.

The Claude Code Memory Hierarchy

Claude Code has two main memory systems: CLAUDE.md files that you write, and auto memory that Claude writes for itself. The officially documented CLAUDE.md locations include managed policy (org-wide), project instructions (CLAUDE.md or .claude/CLAUDE.md), user instructions (~/.claude/CLAUDE.md), and local instructions (./CLAUDE.local.md, personal project-specific, gitignored).

Project memory is the one you’ll use most. It’s a markdown file committed to git and shared with your team. Put your tech stack, naming conventions, common commands, and non-obvious gotchas here. User memory is for personal preferences that apply across all your projects: your preferred patterns, how you like code explained, tools you always use.

In practice: Use project memory for everything a teammate would need to understand the codebase: setup steps, testing commands, architecture decisions. Use user memory for how you personally like to work, not what the project does. When a project memory entry only matters to you (for example, a custom alias or local shortcut), put it in CLAUDE.local.md instead so it stays private.

For larger projects, split instructions into .claude/rules/*.md files. Rules can be global to the project or scoped to paths with frontmatter. A rule with paths: src/api/**/*.ts only activates when Claude works with matching files:

---
paths: src/api/**/*.ts
---
All API endpoints must validate input with Zod. Return 400 with field-level errors on validation failure.

Creating and Updating Claude Code Memory

The fastest way to start is /init. Run it in your project directory and Claude analyzes the codebase to generate a starter CLAUDE.md. Use CLAUDE_CODE_NEW_INIT=1 claude for an interactive multi-phase setup flow.

For larger edits, /memory opens your memory files in your system editor. Make changes, save, and Claude reloads them automatically. If you want Claude to remember something automatically, ask it naturally, like “remember that the API tests require Redis.” If you want it written into CLAUDE.md, ask Claude explicitly to add it there. The @path/to/file import syntax lets you reference existing documentation rather than duplicating it:

# Project Standards

@README.md
@docs/architecture.md
@package.json

Imports support a maximum depth of four hops. First-time imports from external paths trigger an approval dialog.

Auto Memory

Auto memory is a directory where Claude writes its own notes during sessions: patterns it discovers, project-specific behaviors, debugging insights. The first 200 lines or 25KB of ~/.claude/projects/<project>/memory/MEMORY.md, whichever comes first, load automatically at session start. Additional topic files (debugging.md, api-conventions.md) are loaded on demand.

Subagents can also maintain their own auto memory. See the subagent configuration documentation for details.

You don’t need to maintain auto memory manually; Claude handles writes itself. You can read and edit the files if you want to correct or add to Claude’s notes. You can toggle it in /memory, disable it for a session with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude, or set autoMemoryEnabled in settings. To move the directory to a synced location or a custom path, set autoMemoryDirectory in user settings (not project or local settings; project and local settings can redirect writes to sensitive locations and are not accepted):

{
  "autoMemoryEnabled": true,
  "autoMemoryDirectory": "/path/to/shared/memory"
}

In large monorepos with many CLAUDE.md files, use claudeMdExcludes in settings to skip irrelevant ones:

{
  "claudeMdExcludes": ["packages/legacy-app/CLAUDE.md", "vendors/**/CLAUDE.md"]
}

Claude also loads CLAUDE.md files it finds above your current working directory, and it loads subdirectory CLAUDE.md files on demand when Claude reads files in those directories. In monorepos, claudeMdExcludes helps keep unrelated instructions out of context.

Real-World Code Examples: Claude Code Memory Configuration

Example 1: Project CLAUDE.md

A comprehensive project configuration file that defines architecture, standards, and conventions:

# Project Configuration

## Project Overview
- Name: E-commerce Platform
- Tech Stack: Node.js, PostgreSQL, React 18, Docker
- Team Size: 5 developers

## Architecture
@docs/architecture.md
@docs/api-standards.md
@docs/database-schema.md

## Development Standards

### Code Style
- Use Prettier for formatting
- Use ESLint with airbnb config
- Maximum line length: 100 characters

### Naming Conventions
- Files: kebab-case (user-controller.js)
- Classes: PascalCase (UserService)
- Functions/Variables: camelCase (getUserById)

### Git Workflow
- Branch names: feature/description or fix/description
- Commit messages: Follow conventional commits
- PR required before merge

Example 2: Personal CLAUDE.local.md (Not Committed to Git)

Personal preferences that stay local and are never shared with the team:

# My Development Preferences

## About Me
- Experience Level: 8 years full-stack development
- Preferred Languages: TypeScript, Python
- Communication Style: Direct, with examples

## Code Preferences

### Error Handling
I prefer explicit error handling with try-catch blocks.
Avoid generic errors. Always log errors for debugging.

### Testing
I prefer TDD (test-driven development).
Write tests first, then implementation.

### Architecture
I prefer modular, loosely-coupled design.
Use dependency injection for testability.

Example 3: Directory-Scoped Rules for src/api/

A CLAUDE.md file placed in src/api/ that overrides root settings for that directory:

# API Module Standards

This file overrides root CLAUDE.md for everything in /src/api/

### Request Validation
- Use Zod for schema validation
- Always validate input
- Return 400 with validation errors

### Authentication
- All endpoints require JWT token
- Token in Authorization header
- Token expires after 24 hours

### Response Format
{
  "success": true,
  "data": {},
  "timestamp": "2025-11-06T10:30:00Z",
  "version": "1.0"
}

### Rate Limiting
- 1000 requests per hour for authenticated users
- 100 requests per hour for public endpoints

The Four Claude Code Memory Layers in Detail

Claude Code Memory is built from four layers that load at session start and combine into the working context the assistant uses. Understanding what each layer is for, and where its file lives, is the difference between a Claude Code Memory setup that helps and one that fights you. From lowest to highest priority, the layers are enterprise policy, user memory, project memory, and project-local memory; higher priority wins when two layers disagree.

Enterprise memory is set by administrators and lives in a path controlled by the deployment. It usually encodes policy: which tools are allowed, which data may not leave the machine, how authentication is handled. Enterprise Claude Code Memory is the floor; nothing below it can relax those rules, which is the point. Most individual users never edit this layer directly and only need to know it exists so they understand why a tool is unavailable in a work environment.

User memory lives at ~/.claude/CLAUDE.md and follows you across every project on the machine. This is the right place for personal preferences that have nothing to do with a specific codebase: your preferred commit message style, the language you want explanations in, the fact that you prefer tabs over spaces in prose notes. User-level Claude Code Memory is loaded for every session, so keep it short and high-signal; a long user file dilutes every conversation.

Project memory lives at CLAUDE.md in the repository root and is committed to version control. This is the most important layer because it is shared with everyone who works on the project. Good project Claude Code Memory records the build, test, and lint commands; the architecture’s load-bearing decisions; the conventions that a new contributor needs to follow; and the answers to “where do I start” questions. Because it is version-controlled, changes to project Claude Code Memory are reviewed through normal pull requests, which keeps it trustworthy.

Project-local memory lives at CLAUDE.local.md and is gitignored. It holds personal project preferences that should never be shared: a local database connection string, a scratch note about a debugging hypothesis, a reminder specific to your machine. Project-local Claude Code Memory is the safety valve that keeps personal context out of the shared CLAUDE.md; add CLAUDE.local.md to .gitignore the moment you create it so the personal file never gets committed by accident.

Imports and File References in Claude Code Memory

A single CLAUDE.md file is fine for a small project, but as a codebase grows, Claude Code Memory benefits from being split into focused files that are imported on demand. The import syntax is @path/to/file.md written anywhere in a CLAUDE.md file; the referenced file’s contents are loaded as if they were inline, up to a maximum import depth of five levels. This lets you keep the top-level CLAUDE.md short while still giving the assistant access to detailed rules when relevant.

A typical split keeps the root CLAUDE.md to the essentials (project summary, build commands, where to find things) and pushes detail into imported files such as docs/ai/code-style.md, docs/ai/testing.md, and docs/ai/architecture.md. Each imported Claude Code Memory file can focus on one concern, which makes the files easier to maintain and review than one giant file would be. Because imports are resolved relative to the file that references them, moving a file means updating the import path, which is the only real maintenance cost.

The depth limit exists to prevent accidental import cycles and runaway context loading. If you nest deeper than five levels, Claude Code Memory stops resolving and logs a warning, which tells you the import graph has grown too tangled. The fix is to flatten: bring a deeply nested import up one level, or consolidate several small files into one. The goal of imports is focus, not maximal decomposition; a handful of well-chosen imported files beats dozens of tiny ones.

Directory-scoped rule files are a related mechanism. A CLAUDE.md placed inside a subdirectory such as src/api/ applies only when the assistant is working with files under that directory. This is how you encode “in this part of the codebase, follow these extra rules” without cluttering the root Claude Code Memory with rules that only matter in one corner of the project.

Claude Code Memory for Monorepos and Multi-Project Workflows

Monorepos and multi-project setups are where Claude Code Memory design gets interesting, because the assistant needs context from more than one root. The /add-dir command brings an additional directory into the session’s working set, and each added directory loads its own CLAUDE.md and directory-scoped rule files. This means a monorepo with several services can have a root-level Claude Code Memory for cross-cutting concerns and a per-service CLAUDE.md for service-specific conventions, and the assistant sees the union of whichever directories are active.

For users who work across two separate repositories at once, the --mcp-config flag and the multi-root session model let Claude Code Memory from both repositories coexist. The typical use case is a frontend repo and a backend repo developed in lockstep: you open both, and the assistant can reason about the API contract between them because both project files are loaded. Conflicts are resolved by priority (project-local beats project beats user beats enterprise), so when two project files disagree, the one in the active working directory wins.

Parent and child CLAUDE.md files handle the case where a project sits inside a larger workspace. A CLAUDE.md at ~/work/ applies to every project under ~/work/, and each project’s own CLAUDE.md adds project-specific rules on top. This is useful for personal conventions that apply across a portfolio of projects, such as a consistent branching model or a shared definition of done, without copying the same text into every repository.

Auto Memory: What Claude Code Memory Captures Automatically

Auto Memory is the layer that writes Claude Code Memory for you, by recording useful facts the assistant learns during a session. When Auto Memory is on, the assistant may write a rule such as “the user prefers conventional commits” into the appropriate memory file when it observes that preference repeated across sessions. The goal is to reduce the manual upkeep of Claude Code Memory, since the hardest part of maintaining a memory file is noticing that a convention has emerged and writing it down.

What Auto Memory captures is deliberately conservative: stable preferences, project facts, and corrections the user has made more than once. It does not capture one-off requests or transient context, because those would clutter Claude Code Memory with noise. The captured rules land in the user-level or project-level file depending on scope, and they are always visible in the file itself, so you can read exactly what was written and prune anything you disagree with.

Tuning Auto Memory is straightforward. If it is too aggressive and writes rules you find obvious or wrong, raise the bar by editing the captured rules out and it will learn from the correction. If you want Auto Memory off entirely, disable it in settings; Claude Code Memory then only contains what you write by hand, which is the right choice for environments where every memory rule must be reviewed before it lands. The middle ground is leaving Auto Memory on but reviewing the memory file weekly, which captures most of the benefit with none of the drift.

Claude Code Memory Maintenance and Pruning Patterns

Claude Code Memory decays without maintenance. Rules that were right three months ago may be stale today after a framework upgrade, a directory rename, or a team convention change. A monthly review cadence is enough for most projects: open the project and user CLAUDE.md files, read each rule, and ask whether it is still accurate, still useful, and still specific enough to change the assistant’s behavior. Anything that fails one of those tests gets pruned or rewritten.

Signal-to-noise is the metric that matters. A short Claude Code Memory file full of rules that each change behavior is far more effective than a long file full of generic advice. Rules like “write clean code” add nothing because they never change what the assistant does; rules like “run npm test -- --silent before declaring a change done, and do not commit if any test fails” add a lot because they encode a concrete, checkable step. When pruning, prefer deleting a vague rule over keeping it.

For teams, the project CLAUDE.md is a shared artifact and deserves the same review discipline as any other documentation. Adding a line to the project template that says “review this file when you change the build system” helps catch staleness at the moment it is introduced. The Claude Code Memory hierarchy means the cost of a bad rule is bounded (a higher-priority layer can override it), but bounded cost is not zero cost, so periodic pruning keeps the whole system honest.

Claude Code Memory Anti-Patterns

Most Claude Code Memory problems trace back to a handful of anti-patterns, and recognizing them by name makes them easier to avoid. The first is the giant file: a CLAUDE.md that has accreted rules for years until it is hundreds of lines long. A file that size loads into every session, dilutes the signal the assistant actually needs, and is rarely read by anyone including the person who wrote it. The fix is to split by concern using imports and directory-scoped files, and to prune anything that no longer changes behavior.

The second anti-pattern is contradictory rules. One rule says to use tabs, another says to use spaces; one says to write tests first, another says to write them after. When Claude Code Memory contradicts itself, the assistant picks one based on context, which is unpredictable. The fix is to resolve the contradiction once, in the file, and delete the losing rule. A periodic read-through catches these because they stand out when you actually read the file end to end.

The third is duplicating what already lives elsewhere. Claude Code Memory should not restate the README, the CONTRIBUTING guide, or the architecture decision records verbatim; it should reference them. A rule that says “see docs/architecture/0007 for why the API is split this way” is more durable than copying the rationale into CLAUDE.md and watching the two drift apart. Claude Code Memory is at its best when it points at the source of truth rather than replacing it.

The fourth is encoding transient information. A debugging hypothesis, a TODO for next week, a note about a temporary workaround: these belong in project-local Claude Code Memory (CLAUDE.local.md) or in a commit message, not in the shared project file. The shared file should contain rules that are true for the foreseeable future. Putting transient notes in the shared file guarantees they will outlive their usefulness and mislead future sessions.

The fifth, and the most serious, is committing sensitive data to a shared CLAUDE.md. Connection strings, API keys, internal hostnames, and customer data must never land in a version-controlled memory file. The project-local file exists precisely for personal context that should not be shared, and secrets belong in a proper secrets manager rather than in any memory file at all. Treating the shared CLAUDE.md as a public artifact, because it is one, prevents the worst Claude Code Memory mistakes.

A Worked Multi-Layer Memory Example

Seeing Claude Code Memory resolve across all four layers on a concrete query makes the priority model click. Imagine a company with an enterprise policy file that denies network access to non-approved hosts, a user-level CLAUDE.md that says “I prefer conventional commits and explanations in English,” a project CLAUDE.md that says “run tests with pnpm test and never commit to main,” and a project-local CLAUDE.local.md that says “my local API endpoint is on port 4000.”

When a session starts in that project, Claude Code Memory loads all four files and merges them by priority. Enterprise wins on the things it covers (no out-of-policy network calls), user-level wins on personal preferences (commit style, explanation language), project-level wins on project workflow (the test command, the branch protection), and project-local fills in personal details (the local port). None of these layers fights another, because each owns a distinct concern.

Now add a directory-scoped file at src/api/CLAUDE.md that says “all handlers return a typed Result object, never throw.” When the assistant works on a file under src/api/, that rule loads on top of everything else, and it takes precedence over any vaguer rule in the root file about error handling. When the assistant moves to src/web/, the api-scoped rule unloads, and a src/web/CLAUDE.md (if present) takes its place. This is directory-scoped Claude Code Memory doing its job: the right rules for the right corner of the codebase.

The same resolution governs conflicts. If the root project CLAUDE.md said “use Promises” and an enterprise policy said “use async/await with a specific linter,” the enterprise layer wins because it is higher priority. If two project-level files disagree, the one in the active working directory wins. Claude Code Memory is designed so that priority is predictable, which is what makes a multi-layer setup trustworthy rather than confusing.

The practical takeaway is that each layer should own a concern rather than overlap with the others. Enterprise owns policy, user owns personal preferences, project owns shared workflow, project-local owns personal project details, and directory-scoped files own sub-area conventions. When each layer has a clear job, Claude Code Memory composes cleanly and the assistant gets exactly the context it needs for the task at hand.

Debugging Claude Code Memory Issues

When the assistant ignores a rule that is clearly written in a CLAUDE.md file, the temptation is to assume the feature is broken. Almost always, the real cause is one of a small set of Claude Code Memory issues that are easy to diagnose once you know where to look. The first diagnostic step is /context, which lists every file and rule currently loaded into the session. If the rule you expected is not in that list, it is not loaded, and the question becomes why.

The most common reason a rule is not loaded is that it sits in the wrong file. A rule meant for the whole project that was accidentally written to CLAUDE.local.md is invisible to teammates, and a rule that was meant to be personal but landed in the shared CLAUDE.md is loaded for everyone. Checking which file the rule is in, and whether that file is on the load path for the current directory, resolves most Claude Code Memory complaints in under a minute.

The second most common reason is a conflict that a higher-priority layer wins. If a user-level rule and a project rule disagree, the project rule wins, which is the design. But if you wrote the user rule expecting it to apply everywhere, the override is surprising. /context shows the priority of each loaded rule, which makes the resolution visible. The fix is to move the rule to the layer where it should actually take effect, or to resolve the contradiction by deleting the losing rule.

The third reason is a syntax problem in the CLAUDE.md file itself. An unclosed code block, a malformed import path, or a stray character can cause the parser to stop reading partway through the file, which silently drops every rule after the error. Opening the file in an editor that highlights markdown problems, or temporarily trimming the file to the last rule that works and re-adding the rest in chunks, isolates the break. Claude Code Memory is robust to most content, but a structural error in the file can hide a whole section.

The fourth reason is staleness: the rule was right once but the codebase moved on. A rule that references a directory that no longer exists, or a command that was renamed, does not change behavior because the target is gone. Pruning the stale rule, or updating it to point at the new location, is the fix. This is why the periodic review cadence matters; a rule that has been wrong for a month is hard to distinguish from a rule that is being ignored.

The fifth, and hardest to spot, is a rule that is technically loaded but too vague to change behavior. “Write clean code” and “be careful with the database” are examples: they are in the file, they show up in /context, and they have zero effect on what the assistant does, because they do not tell it anything it would not do anyway. Rewriting these into specific, checkable instructions is what turns Claude Code Memory from a documentation file into a behavior-changing one. When a rule feels ignored, ask first whether it actually says something specific enough to follow.

Claude Code Memory and Security

Because Claude Code Memory is loaded into every session and the shared files are version-controlled, security is a first-class concern rather than an afterthought. The rule that prevents almost every Claude Code Memory security problem is simple: never put a secret in a shared file. API keys, database passwords, internal hostnames, customer data, and proprietary algorithms all belong outside the version-controlled CLAUDE.md, in a secrets manager or a personal CLAUDE.local.md at most.

Treating the shared CLAUDE.md as a public document is the right mental model. Anything written into it is readable by everyone with repository access, survives in git history even after deletion, and may be indexed by tools that crawl the codebase. Claude Code Memory that follows this model is safe; Claude Code Memory that treats the shared file as a private notebook will eventually leak something it should not. A pre-commit check that scans for high-entropy strings or known secret patterns is a cheap safety net against accidental leakage.

The credential file at ~/.claude/.credentials.json deserves the same discipline. On Linux and Windows it is created with mode 0600, which is correct, but anyone who copies the file or restores it from a backup should verify the permissions are intact. On macOS the keychain entry inherits the keychain’s own access controls. Claude Code Memory rules never need to reference credentials directly; the assistant reads them from the environment or the credential store at runtime, so there is no workflow reason to put a secret into a memory file.

For teams subject to compliance regimes, the enterprise Claude Code Memory layer is where policy gets enforced. Data residency rules, allowed-tool lists, and redaction requirements can be encoded there so that no lower layer can relax them. Reviewing the enterprise layer periodically, and confirming it still matches the compliance posture, is the equivalent of the project-level pruning discipline applied at the policy level. Claude Code Memory is most trustworthy when each layer is owned and reviewed by the people accountable for its concern.

Pro Tips

• Keep CLAUDE.md under 300 lines (ideally under 100). LLMs are stateless. CLAUDE.md is the only file loaded into every conversation. Large files waste context. Use @imports for the rest.
• Never store secrets in CLAUDE.md. API keys, passwords, tokens, and credentials must never appear in memory files, especially project-level files committed to git.
• Use the right memory level for the job. Managed policy for company-wide rules, project memory for team standards (git-tracked), user memory for personal preferences, and directory-specific files for module overrides.
• Be specific, not vague. Write “Use 2-space indentation for all JavaScript files”, not “follow best practices.” Concrete rules produce consistent behaviour; generic statements are ignored.
• Use @imports to avoid duplication. Instead of copying README content into CLAUDE.md, write @README.md or @docs/api-standards.md. Imports support up to 5 levels of recursion and load automatically.

Hands-On Challenge: Set Up a Multi-Layer Memory System

Task: Create a three-tier memory hierarchy: project-level CLAUDE.md, a directory-specific override, and personal user preferences, then verify each is loaded correctly.

Steps

1. Run /init in a project to generate a root CLAUDE.md with project overview, tech stack, and coding conventions
2. Add an @docs/architecture.md import to reference existing documentation without duplicating it
3. Create src/api/CLAUDE.md with API-specific rules (e.g., “all endpoints must use Zod validation and return a standard JSON envelope”)
4. Create ~/.claude/CLAUDE.md with personal preferences (e.g., preferred indentation, testing framework, communication style)
5. Start a new Claude Code session and ask: “What conventions should I follow for the API module?” Claude should pull from both the project and directory-specific memory files

Expected Outcome

Claude should apply project-wide conventions from the root CLAUDE.md, override them with the more specific API rules from src/api/CLAUDE.md, and also respect your personal preferences from ~/.claude/CLAUDE.md, demonstrating the hierarchical memory system in action.

Hint: Use the @ import syntax to reference files like @README.md or @package.json inside your CLAUDE.md. This avoids duplication. Claude reads the referenced file at load time.

Knowledge Check: Claude Code Memory System

Test your understanding with these quiz questions. Try to answer each question before revealing the answer.

1. How many levels does the Claude Code memory hierarchy have, and what has the highest priority?

1. 5 levels, User Memory is highest
2. 7 levels, Managed Policy is highest
3. 3 levels, Project Memory is highest
4. 7 levels, Auto Memory is highest

Correct Answer: B. The hierarchy has 7 levels: Managed Policy > Project Memory > Project Rules > User Memory > User Rules > Local Project Memory > Auto Memory. Managed Policy (set by admins) has the highest priority.

2. How do you quickly add a new rule to memory during a conversation?

1. Use the /memory slash command or ask conversationally
2. Prefix your message with # (e.g., # always use TypeScript)
3. Type /rule “rule text”
4. Use @add-memory “rule text”

Correct Answer: A. The recommended ways to add memory are the /memory command (opens memory files in your editor) or asking Claude conversationally. The # prefix was discontinued.

3. What is the maximum depth for @path/to/file imports in CLAUDE.md?

1. 3 levels deep
2. 5 levels deep
3. 10 levels deep
4. Unlimited

Correct Answer: B. The @import syntax supports recursive imports up to a maximum depth of 5 to prevent infinite loops.

4. How do you scope a rule file to only apply to files in src/api/?

1. Put the rule in src/api/CLAUDE.md
2. Add paths: src/api/** YAML frontmatter to a .claude/rules/*.md file
3. Name the file .claude/rules/api.md
4. Use @scope: src/api in the rule file

Correct Answer: B. Files in .claude/rules/ support a paths: frontmatter field with glob patterns to scope rules to specific directories.

5. How do you disable Auto Memory completely?

1. Delete the ~/.claude/projects directory
2. Set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
3. Add auto-memory: false to CLAUDE.md
4. Use /memory disable auto

Correct Answer: B. Setting CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 disables auto memory. Value 0 forces it on. Unset = default on.

Additional Resources

What is the difference between project and user memory?

Project memory is committed and shared with the team; user memory holds personal, machine-specific notes that never get pushed.

How often should I review memory?

Every few weeks. Delete stale facts so the assistant is never steered by outdated rules.

Can rules conflict?

Yes, and the more specific, more trusted layer wins. Path-specific rules beat repository-wide ones.

Putting It All Together

Strong project memory is less about writing more and more about writing the right things in the right place. When the committed file captures the conventions everyone shares and the local layers hold personal detail, the assistant behaves consistently for the whole team without anyone having to repeat themselves each session.

Think of the memory file as a living contract between you and the assistant. It states how the project is built, how it is tested, and the handful of rules that matter most. Keep that contract short, specific, and current, and the assistant will follow it closely instead of guessing at conventions you never wrote down.

The payoff compounds over time. Every rule you record once is a correction you never have to make again, every recorded command is work the assistant can verify on its own, and every pruned stale note is one less chance for the assistant to act on something that is no longer true.

Claude Code Memory: Frequently Asked Questions

Why does it matter at all?

Claude Code Memory is the system of CLAUDE.md files and settings that let the assistant persist project conventions, commands, and rules across sessions, so you never have to re-explain your stack or standards every time you start a new session.

What should go in a committed CLAUDE.md file versus local settings?

Durable, team-wide conventions belong in the committed file everyone shares. Machine-specific paths and personal preferences belong in local, uncommitted settings. Mixing the two breaks the file for every other teammate who checks it out.

How are conflicts between memory layers resolved?

The more specific and more trusted layer wins: an organisation-managed policy overrides a project file, a project file overrides personal preferences, and a path-specific rule overrides a broad repository-wide one.

How often should I review or prune CLAUDE.md?

Review it every few weeks and delete anything that is no longer true. Stale facts left unpruned quietly steer the assistant toward outdated behavior, which is one of the most common causes of confusing results.

What makes a memory rule effective instead of vague?

Short, imperative, checkable statements work best: “never edit files in the build output folder” is concrete, while “write clean code” gives the assistant nothing reliable to act on.

Claude Code Memory gives you a solid, repeatable workflow. Bookmark this Claude Code Memory guide and revisit the steps whenever you need them.

Claude Code Memory: Common Mistakes to Avoid

Even experienced developers trip over the same issues when they start with Claude Code Memory. Watch for these and you will save real debugging time.

• Putting machine-specific paths into the committed CLAUDE.md, which then breaks for every other teammate.
• Writing long, vague rules the assistant cannot follow literally instead of short imperative statements.
• Never pruning memory, so stale facts accumulate and quietly steer the assistant toward outdated behavior.
• Duplicating the same rule across project and user memory, which makes conflicts hard to track down.

How the Hierarchy Resolves Conflicts

When two layers disagree, the more specific and more trusted layer wins. A managed policy set by an organisation overrides a project file, a project file overrides personal preferences, and a path-specific rule overrides a broad repository-wide one. Knowing this order saves you from chasing “why is it ignoring my rule” bugs.

Keep each layer doing the job it is best at. Put durable, team-wide conventions where everyone shares them, and keep machine-specific paths or personal style notes in a layer that never gets committed. That separation keeps the shared file clean and stops one developer’s local quirks from leaking into everyone else’s sessions.

A Practical Project-File Example

A strong project file is short and scannable. Open with one or two sentences describing the product, then list the exact build, test, and lint commands so the assistant can verify its own work. Follow that with a handful of imperative rules, each on its own line, written so they can be followed literally.

Resist the urge to write an essay. A wall of vague guidance is harder for the assistant to apply than five sharp, high-signal rules. Review the file every few weeks, delete anything that is no longer true, and treat it like code: small, reviewed changes beat a sprawling document nobody trusts.

Finally, write rules as outcomes rather than wishes. “Use tabs for indentation” and “never edit files in the build output folder” are concrete and checkable. “Write clean code” is not, and it quietly trains you to expect results the assistant has no reliable way to deliver.

Claude Code Memory: Best Practices

• Keep project-wide rules in CLAUDE.md at the repo root; keep machine-specific notes in local memory.
• Use path-specific rules so subfolders get their own conventions without bloating the root file.
• Write rules as short imperative statements the assistant can follow literally.
• Review memory periodically and delete stale facts so context stays accurate.
• Prefer a few high-signal rules over a long wall of low-value text.