# Claude Code Memory: CLAUDE.md, Auto-Memory, and Making Claude Remember Your Project

Canonical: https://clawdocx.com/blog/claude-code-memory-claude-md-guide
Author: Theo Marsh
Published: 2026-03-16
Updated: 2026-03-16

> A practical guide to Claude Code's memory systems — CLAUDE.md instruction files, auto-memory, .claude/rules, and memory management.

## The Problem: Claude Forgets Everything

Every Claude Code session starts with a blank slate. You open a new session, and Claude has no memory of:

- Your coding standards
- Your project's architecture
- The build commands that actually work
- That one weird config quirk that breaks everything
- The conversation you had yesterday about the auth refactor

This is by design — clean context means no stale assumptions. But it also means you're re-explaining the same things every session.

Claude Code solves this with two complementary memory systems: **CLAUDE.md files** (instructions you write) and **auto-memory** (notes Claude writes itself).

---

## CLAUDE.md: Your Persistent Instructions

A `CLAUDE.md` file is a plain Markdown file that Claude reads at the start of every session. Whatever you put in it becomes part of Claude's context — coding rules, project conventions, build commands, architectural decisions.

### Where to Put It

CLAUDE.md files work at different scopes. More specific locations override broader ones:

| Scope | Location | Who It Affects |
|-------|----------|---------------|
| **Project** | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Anyone working on this repo |
| **User** | `~/.claude/CLAUDE.md` | All your sessions, every project |
| **Managed/Org** | `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS) | All users on this machine |

**Most common setup:** One `CLAUDE.md` at the root of your project, committed to git so the whole team benefits.

### What to Put In It

Start with the essentials and add over time. Here's a solid starting template:

```markdown
# Project: MyApp

## Stack
- Next.js 14 with App Router
- TypeScript (strict mode)
- Prisma + PostgreSQL
- Tailwind CSS

## Build & Test
- `npm run dev` — start dev server
- `npm test` — run Jest tests
- `npm run lint` — ESLint + Prettier
- `npm run build` — production build

## Coding Standards
- Use named exports, not default exports
- All API routes return typed responses using `ApiResponse<T>`
- Error handling: use `AppError` class, never throw raw strings
- Database queries go in `src/lib/db/` — never inline Prisma calls in route handlers
- Tests: one test file per module, co-located in `__tests__/` directories

## Architecture
- `/src/app/` — Next.js routes (thin handlers, delegate to services)
- `/src/services/` — business logic
- `/src/lib/db/` — database access layer
- `/src/components/` — React components (no business logic)

## Gotchas
- The `auth` middleware checks `X-API-Key` header, not Bearer tokens
- PostgreSQL connection string uses `?sslmode=require` in production
- Don't modify `prisma/migrations/` manually — always use `npx prisma migrate dev`
```

### What NOT to Put In It

- **Secrets or API keys** — CLAUDE.md may be committed to git
- **Entire architecture docs** — keep it concise; Claude reads this every session
- **Overly detailed instructions** — the more specific and shorter your rules, the more consistently Claude follows them

> **Tip**
>
> Aim for under 200 lines. Long CLAUDE.md files eat context and reduce how consistently Claude follows the rules. If you need more detail, use `.claude/rules/` for scoped rules (see below).

---

## .claude/rules/ — Scoped Rules for Specific Files

For rules that only apply to certain file types or directories, use rule files in `.claude/rules/`:

```
.claude/
├── CLAUDE.md           # Main project instructions
└── rules/
    ├── typescript.md   # TypeScript-specific rules
    ├── testing.md      # Testing conventions
    └── api-routes.md   # API route patterns
```

Each rule file is a Markdown file with optional YAML frontmatter for glob matching:

```markdown
---
globs: ["src/app/api/**/*.ts"]
---

# API Route Rules

- Every route must validate input using Zod schemas
- Return `NextResponse.json()` with proper status codes
- Log errors to the structured logger, never console.log
- Include rate limiting middleware on all public endpoints
```

Rules are loaded lazily — they only enter context when Claude works with matching files. This keeps context clean while providing detailed guidance where needed.

---

## Auto-Memory: Let Claude Take Notes

Auto-memory is the inverse of CLAUDE.md — instead of you writing instructions for Claude, Claude writes notes for itself.

When you correct Claude or it discovers something important about your project, it saves a note to `.claude/auto-memory.md`. These notes persist across sessions and are loaded automatically (first 200 lines).

### What Claude Remembers

- Build commands that failed and what actually works
- Coding patterns you corrected ("don't use default exports")
- Project-specific quirks it discovered
- Preferences you expressed ("I prefer functional components")

### Managing Auto-Memory

```bash
# View current auto-memory
/memory

# Clear all auto-memory
/memory clear

# Set the auto-memory directory (for multi-worktree setups)
# In settings.json:
{
  "autoMemoryDirectory": ".claude"
}
```

### Sub-Agent Memory

Sub-agents can also maintain their own auto-memory. If you have a custom sub-agent that specializes in your test suite, it can accumulate knowledge about common test failures and fixes independently of your main session.

Enable it in the sub-agent definition:

```markdown
---
name: test-expert
auto_memory: true
---
```

---

## Memory Hierarchy: What Loads When

When Claude Code starts a session, it loads memory in this order (later entries override earlier):

1. **Managed/Org CLAUDE.md** — system-wide policies
2. **User CLAUDE.md** — your personal preferences
3. **Project CLAUDE.md** — this repo's instructions
4. **Auto-memory** — Claude's accumulated notes (first 200 lines)
5. **.claude/rules/** — scoped rules (loaded lazily as files are accessed)

If two sources conflict, the more specific one wins. Your project CLAUDE.md overrides your user-level file, and scoped rules override the project CLAUDE.md for matching files.

---

## Practical Tips

### Keep CLAUDE.md in Git

Commit your project's `CLAUDE.md` so the whole team benefits. It functions as living documentation — not just for Claude, but for any developer reading it.

### Use Corrections, Not Instructions

The fastest way to build auto-memory: just correct Claude when it does something wrong.

> ❌ "Use named exports" (instruction you have to write yourself)
> ✅ "No, use a named export here, not a default export" (Claude saves this for next time)

### Review Auto-Memory Regularly

Run `/memory` every week or two. Delete stale entries, promote important patterns to CLAUDE.md, and keep the auto-memory file lean.

### Use /context to Debug

If Claude isn't following your rules, the `/context` command (v2.1.74+) now tells you:

- Which CLAUDE.md files are loaded
- How much context they consume
- Which rules are active for current files
- Specific optimization suggestions

This is the first thing to check when Claude seems to be ignoring your instructions.

### CLAUDE.md for Teams

For team projects, establish a convention:

```
CLAUDE.md                    # Shared project rules (committed)
.claude/CLAUDE.md            # Alternative location (committed)
.claude/rules/*.md           # Scoped rules (committed)
.claude/auto-memory.md       # Auto-memory (gitignored)
~/.claude/CLAUDE.md          # Personal preferences (not committed)
```

Add `.claude/auto-memory.md` to `.gitignore` — auto-memory is personal and may contain context specific to one developer's workflow.

---

## For OpenClaw Users

If you're running Claude Code through OpenClaw's ACP bridge, CLAUDE.md works the same way — it's read by Claude Code, not OpenClaw.

However, OpenClaw has its own memory systems (AGENTS.md, SOUL.md, MEMORY.md, daily memory files). The two are complementary:

- **CLAUDE.md** → project-specific coding instructions (lives in the repo)
- **OpenClaw memory** → personal context, preferences, cross-project knowledge (lives in workspace)

When OpenClaw delegates a task to Claude Code via ACP, Claude Code reads the project's CLAUDE.md independently. You don't need to duplicate instructions between the two systems.

---

## Quick Start Checklist

1. ☐ Create `CLAUDE.md` at your project root
2. ☐ Add stack, build commands, and top 5 coding rules
3. ☐ Commit it to git
4. ☐ Work normally — correct Claude when it gets things wrong
5. ☐ Check `/memory` after a week and clean up
6. ☐ Add `.claude/rules/` for file-specific conventions

Memory is what turns Claude Code from "smart autocomplete" into a teammate that actually knows your project. Invest 15 minutes in a good CLAUDE.md and it pays dividends every session.

---

*For team-wide CLAUDE.md templates, organization policy examples, and advanced memory management, check out the premium guides on ClawDocx.*