What is CLAUDE.md and how does it work in Claude Code?

CLAUDE.md is a markdown file that Claude Code reads automatically at the start of every session. A global file at ~/.claude/CLAUDE.md loads your universal preferences in every conversation. Project-level CLAUDE.md files in each project folder add project-specific context. They stack hierarchically — global, then project root, then subdirectory — giving Claude persistent memory of who you are and what you're building.

Can Claude Code remember context between sessions?

Claude Code has built-in memory that persists between sessions. CLAUDE.md files load your instructions automatically at session start. Auto Memory (MEMORY.md) lets Claude save notes for itself about your preferences, decisions, and project patterns. Together with the .claude/rules/ directory and an optional Obsidian vault, Claude carries forward context without you re-explaining anything.

How do you set up Obsidian as memory for an AI coding assistant?

Create an Obsidian vault with a CLAUDE.md at the root listing your projects and navigation rules. Add your vault path and keyword triggers to your global ~/.claude/CLAUDE.md. When you mention a project name, Claude reads the vault, finds the project folder, and loads all the context — decisions, status, workflows, and constraints. Any folder of markdown files works the same way.

How long does it take to set up persistent memory for Claude Code?

About 20 minutes for the complete setup: 5 minutes for the global CLAUDE.md (or use the /init command to generate one), 5 minutes for an Obsidian vault structure, and 5 minutes for your first project-level CLAUDE.md. Skills are optional and take about 3 minutes each. Auto Memory requires zero setup — it works automatically from your first session.

What is the difference between CLAUDE.md and Auto Memory (MEMORY.md)?

CLAUDE.md contains instructions you write manually — project context, coding rules, workflow preferences. Auto Memory (MEMORY.md) is knowledge Claude learns on its own during sessions, like your coding patterns, corrections you've made, and decisions that came up in conversation. Both load automatically at session start. Think of CLAUDE.md as the playbook you write, and Auto Memory as the meeting notes Claude takes.

Does Claude Code memory work with Cursor, Copilot, or other AI coding tools?

CLAUDE.md and Auto Memory are specific to Claude Code. However, the Obsidian vault approach works with any AI tool that can read markdown files. Cursor uses .cursorrules and .cursor/rules/ for similar functionality. GitHub Copilot supports .github/copilot-instructions.md for project instructions. The vault-as-long-term-memory pattern is tool-agnostic — only the instruction file format differs.

What should you NOT put in CLAUDE.md?

Never put API keys, passwords, or secrets in CLAUDE.md — it's plain text and often committed to git. Avoid vague instructions like 'write clean code' which get only 35% compliance. Don't exceed 200 lines — compliance drops significantly beyond that. Don't include information Claude can discover from your code itself, like listing every file in your project. Keep it focused on decisions, rules, and context that isn't obvious from the codebase.

How does Claude Code's .claude/rules/ directory work?

The .claude/rules/ directory holds markdown files with path-scoped instructions. Each rule file uses frontmatter with a globs field to specify which files it applies to — for example, rules for frontend components or API routes. Rules load automatically when Claude works with matching files. Use rules for path-specific standards and CLAUDE.md for project-wide context. This keeps your CLAUDE.md under the recommended 200-line limit.

Claude Code Memory: The Complete Setup Guide (CLAUDE.md + Obsidian + Skills)

Q: What are Claude Code skills?

Skills are reusable workflow templates stored as markdown files in ~/.claude/skills/. Each skill has a name, trigger description, and step-by-step process. Invoke them with /skill-name during a conversation. They're optional but compound over time — every workflow you document saves time in future sessions. Examples include code review checklists, content planning processes, and deployment procedures.

You spend 30 minutes explaining your project to Claude. The context. The decisions. The style. The constraints. Then you close the terminal.

Next session? Blank slate. Claude has no idea who you are, what you're building, or why you made those choices last week.

You're not using an AI assistant. You're training a goldfish. Every. Single. Day.

There's a fix. It takes 20 minutes. And once it's set up, Claude remembers:

Your preferences across all projects
Project-specific context and decisions
Workflows you use repeatedly
Progress and history over time

Here's exactly how to build it.

How Claude Code memory actually works

Before we set anything up, here's the mental model.

Claude Code has a layered memory system. When you start a session, Claude loads context from multiple sources — automatically, before you type a single word:

CLAUDE.md files load at session start. Global first (~/.claude/CLAUDE.md), then project-level (your-project/CLAUDE.md), then any subdirectory CLAUDE.md files deeper in the tree. They stack — global rules apply everywhere, project rules apply in that folder.
Auto Memory (MEMORY.md) loads alongside CLAUDE.md. These are notes Claude writes for itself — things it learned about you and your project during previous sessions.
Rules (.claude/rules/) load based on the file paths you're working with. They're like CLAUDE.md but scoped to specific directories or file types.
Skills load on demand when you invoke them with a slash command.

Think of it like this: CLAUDE.md is the briefing you write. Auto Memory is the notes Claude took in past meetings. Rules are the style guides pinned to specific parts of the codebase. Skills are the playbooks you pull off the shelf when needed.

The beauty of this system is that layers 1-3 are automatic. You set them up once, and Claude loads the right context every time. No commands to run, no "load my preferences" prompts. It just works.

Now let's build each layer.

How do you set up global CLAUDE.md?

This file loads every time you use Claude Code. It's your baseline.

The fast way: use `/init`

If you already have a project, Claude can generate your CLAUDE.md automatically:

claude /init

This scans your project structure, dependencies, and existing code, then generates a CLAUDE.md tailored to what it finds. It's a solid starting point — you'll want to edit it, but it beats starting from scratch.

The manual way

Create the file:

mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md

What to put in it:

# Global Instructions for Claude

## About Me
[1-2 sentences about who you are and what you work on]

## Preferences
- [How you like Claude to communicate]
- [Level of detail you want]
- [Any formatting preferences]

## Default Behaviors
- Always research current information before advising
- Ask clarifying questions when requirements are unclear
- Create project documentation when starting new work

## Obsidian Vault
**Location:** `/Users/YOURNAME/Documents/MyVault`

When I say "check the vault" or mention a project by name:
1. Read the vault's CLAUDE.md first
2. Navigate to the relevant project folder
3. Read context before responding

### Triggers

| When I Say | Check This Location |
|------------|---------------------|
| "check the vault" | Vault root |
| "Project A" | `/Projects/ProjectA/` |
| "Project B" | `/Projects/ProjectB/` |

That's it. Claude now knows who you are and where your memory lives.

How to write rules that actually stick

Here's a stat worth knowing: according to Builder.io, specific rules in CLAUDE.md get 89% compliance. Vague rules? 35%.

The difference:

Vague: "Write clean code" (35% compliance — Claude interprets this however it wants)
Specific: "Always use async/await instead of .then() chains. Never use any type in TypeScript." (89% compliance)

Also keep it under 200 lines. Compliance drops noticeably beyond that. If your CLAUDE.md is growing past 200 lines, move specialized instructions to project-level files or the .claude/rules/ directory.

The file hierarchy

Claude loads CLAUDE.md files in order of specificity:

~/.claude/CLAUDE.md                    ← Global (loads always)
  └── ~/Projects/my-app/CLAUDE.md      ← Project root (loads in this project)
        └── ~/Projects/my-app/src/CLAUDE.md  ← Subdirectory (loads for files here)

More specific files override more general ones. Use this to keep your global config lean and push project details down to where they belong.

Auto Memory and MEMORY.md

This is the feature most people don't know about yet — and it changes how Claude Code works in a fundamental way.

What Auto Memory does

Auto Memory lets Claude write notes for itself between sessions. When Claude learns something important about you or your project — your preferences, a decision you made, a correction you gave, a pattern in your codebase — it saves that knowledge to a file called MEMORY.md.

Next session, Claude reads those notes automatically. No action required from you.

For example: if you tell Claude "I prefer early returns over nested if-else" during a code review, Auto Memory might save that preference. Next session, Claude applies it without being told. If you correct Claude's approach to error handling, it remembers that too. Over time, Claude builds a profile of how you work — not because you wrote it down, but because it was paying attention.

Where it lives

~/.claude/projects/<project-path-hash>/memory/MEMORY.md

The path is hashed from your project directory, so each project gets its own memory file. You can also view and manage it with the /memory command inside Claude Code.

What goes in there

MEMORY.md has a simple structure. Each entry is a note with metadata:

- [User role and preferences](user_role.md) — Misha's background, skills, and communication preferences
- [Project architecture](project_arch.md) — Next.js app with Supabase backend, deployed on Vercel
- [Code style decisions](code_style.md) — Prefers functional components, uses Tailwind, avoids CSS modules

Notes have types: user (your preferences), feedback (corrections you've given), project (project-specific knowledge), and reference (useful links or docs).

The 200-line limit

MEMORY.md is capped at roughly 200 lines. Claude manages this automatically — when it gets close to the limit, older or less relevant notes get consolidated or removed. You don't need to prune it yourself, but you can edit it if Claude remembered something incorrectly.

The key difference

CLAUDE.md = instructions you write. You're telling Claude how to behave, what your project is, what rules to follow.

Auto Memory = knowledge Claude learns on its own. Claude is noting things it discovered — your patterns, corrections you've made, decisions that came up in conversation.

They work together. You write the playbook (CLAUDE.md). Claude takes the meeting notes (Auto Memory). Both load at session start.

The `.claude/rules/` directory

For more granular control, Claude Code supports a rules directory. This is useful when you have instructions that only apply to specific parts of your codebase.

How it works

Create rules as markdown files inside .claude/rules/ at your project root:

my-project/
├── .claude/
│   └── rules/
│       ├── frontend.md      ← Rules for frontend code
│       ├── api.md           ← Rules for API routes
│       └── testing.md       ← Rules for test files
├── src/
├── CLAUDE.md

Each rule file can specify which paths it applies to using a glob pattern in the frontmatter:

---
description: Frontend component standards
globs: ["src/components/**", "src/pages/**"]
---

- Use functional components with TypeScript
- Every component gets a co-located test file
- Use Tailwind for styling, no CSS modules

When to use rules vs CLAUDE.md

Use CLAUDE.md for project-wide context: what the project is, key architecture decisions, general coding standards.

Use .claude/rules/ for path-specific instructions: frontend conventions that don't apply to backend code, test file formatting, API response structures.

The rules directory keeps your CLAUDE.md lean (remember: under 200 lines) while still giving Claude detailed instructions where they matter. Rules load automatically based on which files Claude is working with during the session.

How do you use Obsidian as Claude Code's long-term memory?

CLAUDE.md and Auto Memory handle session-to-session context. But what about the bigger picture — project history, architectural decisions from three months ago, notes about clients, research you've done?

That's where a vault comes in. This is Claude's long-term memory. Context that persists forever and grows over time.

Why Obsidian?

It's just markdown files (Claude can read them natively)
You can edit them yourself — it's your knowledge base too
They sync across devices via iCloud, Dropbox, or Obsidian Sync
It's free
It doubles as your personal second brain — useful beyond just Claude

The Obsidian vault approach is tool-agnostic. Any AI assistant that can read files on disk can use it. But Claude Code's trigger system in CLAUDE.md makes it especially seamless — mention a project name, and Claude automatically navigates to the right folder.

Set it up:

Download Obsidian from obsidian.md (or use any folder of markdown files)
Create structure (or ask Claude to do it):

MyVault/
|── CLAUDE.md          ← Navigation instructions
└── Projects/
    |── Project-A/
    │   └── Project-A.md
    |── Project-B/
    │   └── Project-B.md

Add the vault's CLAUDE.md:

# Vault Navigation

## Active Projects

| Project | Location | Status |
|---------|----------|--------|
| Project A | `/Projects/Project-A/` | Active |
| Project B | `/Projects/Project-B/` | Planning |

## How to Navigate
Read the main markdown file in each project folder.

Now when you say, "Let's work on Project A," Claude reads the vault, finds the project, and loads all the context. I use this to manage 15+ projects including a personal dashboard pulling data from 7 APIs.

How do project-level CLAUDE.md files work?

Every project gets its own CLAUDE.md with specific context.

Put it in the project folder:

~/Projects/my-project/CLAUDE.md

Template that works for anything:

# [Project Name] — Guide for Claude

## Overview
[One paragraph: what is this and what's the goal?]

## Current Status
- [x] What's done
- [ ] What's in progress
- [ ] What's next

## Key Information

| Aspect | Details |
|--------|--------|
| Goal | [What success looks like] |
| Audience | [Who this is for] |
| Constraints | [Limitations, deadlines, requirements] |

## Workflows

### [Main Process Name]
1. Step one
2. Step two
3. Step three

## Style & Voice
- Tone: [casual/professional/educational]
- Format: [specific preferences]

## Important Context
[Anything Claude should always remember about this project]

---
*Last Updated: YYYY-MM-DD*

The key is making these specific enough to be useful. Generic instructions produce generic output. Real project context — the tech stack, the decisions you've made, the constraints you're working with — that's what makes Claude actually helpful session after session.

What are Claude Code skills and how do you create them?

Skills are reusable workflows. Invoke them with /skill-name.

Create a skill:

mkdir -p ~/.claude/skills/my-workflow
touch ~/.claude/skills/my-workflow/SKILL.md

Skill structure:

---
name: skill-name
description: When to use this. Be specific.
---

# Skill Title

## Before Starting
Questions to ask / context to gather.

## Process
Step-by-step workflow.

## Output
What the final result should look like.

Here are a couple of real examples to show what this looks like in practice:

A content planning skill (/content-planning):

---
name: content-planning
description: Brainstorm and plan content for YouTube or blog posts
---
# Content Planning
## Process
1. Read the project's content calendar from the vault
2. Analyze what topics haven't been covered yet
3. Propose 5 ideas with titles, hooks, and outlines
4. After selection, create a content brief in the project folder

A code review skill (/review):

---
name: review
description: Review staged changes before committing
---
# Code Review
## Process
1. Run git diff --staged
2. Check for: unused imports, console.logs, type errors, missing error handling
3. Verify test coverage for changed files
4. Summarize findings with severity ratings

Skills are optional when you're starting out. But they compound fast. Every workflow you document is time saved forever. For a deeper look at building an extensive skills library, check out the advanced setup guide.

Claude Code memory vs Cursor Rules vs Copilot instructions

If you're choosing between AI coding tools or using multiple, here's how their memory systems compare:

Feature	Claude Code	Cursor	GitHub Copilot
Project instructions	`CLAUDE.md` (hierarchical)	`.cursorrules` / `.cursor/rules/`	`.github/copilot-instructions.md`
Auto memory	MEMORY.md (Claude writes notes for itself)	Memory Banks (experimental)	None
Path-scoped rules	`.claude/rules/` with glob patterns	`.cursor/rules/` with glob patterns	None
Reusable workflows	Skills (`.claude/skills/`)	None built-in	None built-in
Long-term vault	Any markdown folder (e.g., Obsidian)	Not built-in	Not built-in
Session memory	Auto Memory persists between sessions	Context resets each session	Context resets each session

Claude Code's memory system is the most layered of the three. The key advantage is that Claude Code memory persists between sessions natively with Auto Memory — you don't need to rebuild context each time. The Obsidian vault approach described in this guide works with any tool that can read markdown files, so your long-term memory investment isn't locked to one editor. But the CLAUDE.md hierarchy, Auto Memory, and skills system are unique to Claude Code.

Common mistakes to avoid

After using this system daily for months and helping others set it up, here are the mistakes that trip people up most often:

CLAUDE.md is too long. Past 200 lines, Claude starts ignoring instructions. If your CLAUDE.md is a novel, split it — move path-specific rules to .claude/rules/, move project details to project-level files.

Instructions are too vague. "Write good code" means nothing. "Use early returns instead of nested if-else. Prefer const over let. Always handle errors with try-catch in async functions." — that Claude can follow.

Not using /init. If you're manually writing CLAUDE.md from scratch for an existing project, you're doing extra work. Run /init first, then edit what it generates.

Never updating after sessions. CLAUDE.md isn't write-once. After a big session where you made architectural decisions or changed patterns, tell Claude: "Update CLAUDE.md with what we decided." Auto Memory catches some of this, but explicit instructions in CLAUDE.md carry more weight.

Putting secrets in CLAUDE.md. Never put API keys, passwords, or tokens in CLAUDE.md. It's a plain text file, often committed to git. Use environment variables and reference them by name.

Duplicating what's in the code. Don't list every file in your project or describe what each function does — Claude can read the code itself. CLAUDE.md should contain things Claude can't infer: why you chose this architecture, what the business constraints are, which patterns you prefer when there are multiple valid options.

How does everything work together?

Scenario: You open Claude to work on your YouTube channel.

Claude loads ~/.claude/CLAUDE.md (your global preferences)
Claude loads Auto Memory (what it learned in past sessions)
You say: "Let's work on the next video."
Claude sees "video" in your triggers, reads your vault
Claude reads /Projects/YouTube/ in your vault
Claude now knows your style, current status, what video you're on, your workflow
You say: "/content-planning" to brainstorm ideas
Claude follows your documented planning process

No re-explaining. No context lost. Every session picks up where you left off.

The important thing to notice: you didn't do anything special in steps 2-6. You just talked normally. The memory system loaded the right context because of the triggers and structure you set up once. That's the whole point — front-load 20 minutes of setup, then forget about the plumbing forever.

The 20-minute setup checklist

Create ~/.claude/CLAUDE.md with your preferences — or run /init (5 min)
Create vault folder with CLAUDE.md navigation (3 min)
Add vault location and triggers to global config (2 min)
Create one project folder with its own CLAUDE.md (5 min)
Test it: mention the project name and see if Claude loads context
Optional: Create one skill for a workflow you repeat (3 min)

Tips after setup

Keep it updated. After big sessions, ask Claude, "Update the project file with what we accomplished."

Log decisions. Add a "Decisions" section to project files. Future you will thank present you.

Use consistent triggers. Train yourself to use the same phrases ("check the vault," project names) so Claude reliably loads context.

Start simple. One project file is enough to start. Add more as needed.

Skills compound. Every workflow you document is time saved forever.

Let Auto Memory do its thing. Don't try to micromanage MEMORY.md. Let Claude take notes naturally. Check in occasionally with /memory to see what it's learned, and correct it if something's off.

What's next

This guide gets you from zero to a working memory system in 20 minutes. But after a few weeks of daily use, you'll start wanting more — a deeper skills library, automation hooks, project dispatch patterns.

I wrote about exactly that evolution: The Advanced Claude Code Setup Nobody Shows You. It covers what happened after 5 weeks of building on this foundation — 60+ skills, vault automation, subagent orchestration, and the patterns that emerged from using Claude Code as a genuine daily driver across 15+ projects.

If you're just starting out, that post is for later. Get the basics working first. Come back to the advanced setup when you've been using the memory system for a few weeks and start wanting more control.

Finally

Claude stops being a tool you fight with.

It becomes a tool that knows you.

20 minutes of setup. Permanent memory. Worth it.

For the official documentation on Claude Code's memory system, see the Memory documentation and the CLAUDE.md reference on Anthropic's site.