CLAUDE.md & Memory

Use CLAUDE.md, rules, AGENTS.md, and auto memory as persistent context without bloating every session.

Persistent Context Sources

Claude Code has several ways to carry knowledge across turns and sessions:

Use CLAUDE.md for facts Claude must see frequently. Use rules for scoped behavior. Use skills for longer workflows that should not load every time.

CLAUDE.md File Hierarchy

Claude Code reads CLAUDE.md files at four scopes, loaded broadest → most specific:

1. Managed policy — /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux/WSL), C:\Program Files\ClaudeCode\CLAUDE.md (Windows). Deployed by IT via MDM / Group Policy; users can't override.
2. User — ~/.claude/CLAUDE.md. Your personal preferences across all projects.
3. Project — ./CLAUDE.md or ./.claude/CLAUDE.md. Team-shared, committed to git.
4. Local — ./CLAUDE.local.md. Your project-specific personal notes; add to .gitignore.

Files from your CWD up to the filesystem root are concatenated at session start. Subdirectory CLAUDE.md files (in folders below your CWD) load on demand when Claude reads files in that subdir — not merged at launch.

Imports. Any CLAUDE.md can pull in other files with @path/to/file (max depth 5). If your repo uses AGENTS.md for other AI tools, add @AGENTS.md at the top of CLAUDE.md so both tools share one source of truth.

Auto memory (v2.1.59+) is a parallel mechanism: Claude writes its own notes to ~/.claude/projects/<project>/memory/MEMORY.md. The first 200 lines (or 25 KB) of MEMORY.md load into every session. Run /memory to view; tell Claude "remember that…" to add an entry.

Rules

Rules live under .claude/rules/. They are useful when a convention applies only to part of the repository:

.claude/rules/
├── project.md
├── frontend.md
└── api.md

Use rules when a guideline is more specific than the whole project but more durable than a chat message. Keep each rule file short and operational.

AGENTS.md

If your repo already has AGENTS.md for other agent tools, do not duplicate it. Import it from CLAUDE.md:

@AGENTS.md

This keeps one source of truth for cross-agent instructions.

The Precision Principle

For every line in your CLAUDE.md, ask: if I remove this, will Claude make a mistake?

• If yes → keep it
• If no → remove it

A shorter, precise CLAUDE.md outperforms a long, generic one. Every token in the context window has a cost — irrelevant context dilutes Claude's attention on what matters.

What to Include

Build & Test Commands

The most impactful content. Claude will use these to run, test, and lint your code:

## Build & Test

- npm run dev # start dev server (port 3000)
- npm test # run all tests
- npm test -- -t "auth" # run tests matching "auth"
- npm run lint # eslint check
- npm run typecheck # tsc --noEmit

Architecture & Key Files

## Architecture

- Monorepo: apps/web (Next.js), apps/api (Express), packages/shared
- Database: PostgreSQL via Prisma (schema at prisma/schema.prisma)
- Auth: NextAuth.js with JWT strategy
- Key entry: apps/web/src/pages/\_app.tsx

Coding Conventions

Only include conventions that Claude would get wrong without explicit instruction:

## Conventions

- Use server actions instead of API routes for mutations
- All dates stored as UTC, displayed in user timezone
- Error boundaries wrap each route segment
- Never use any; prefer unknown + type narrowing

Project-Specific Warnings

## Warnings

- The payments module uses Stripe API v2023-10-16 (NOT latest)
- Do not modify migration files after they've been applied
- The legacy/ directory is being phased out; do not add new code there

Generating & Updating

• /init — Auto-generate a CLAUDE.md by scanning your project
• /memory — Open the in-session memory browser: lists every CLAUDE.md / CLAUDE.local.md / rules file currently loaded and lets you open any of them in your editor
• Asking Claude in chat — "add X to CLAUDE.md" edits the file directly; "remember that X" writes to auto memory instead
• Manual editing — Treat it like any other config file; review and trim regularly

Anti-Patterns

• Dumping your entire README — CLAUDE.md is not documentation. It is operational context.
• Listing every file — Claude can explore the filesystem. Only list files that are non-obvious entry points.
• Generic coding advice — "Write clean code" adds nothing. "Use server actions instead of API routes" is actionable.
• Never updating — Your project evolves. Revisit CLAUDE.md when major architecture changes happen.

Related Reading

• Getting Started — Quick setup including basic CLAUDE.md
• Hooks — Enforce rules that CLAUDE.md alone cannot guarantee
• Context Management — Understand what enters the window
• Skills — Move reusable procedures out of persistent context