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

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

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:

# 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

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

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

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

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