Persist context across every conversation — teach Claude your codebase, team conventions, and personal preferences once, and it remembers forever.
CLAUDE.mdPersistent ContextAuto-MemoryGlobal + Local
🧠 What It Is
Project Memory is Claude's 4-layer persistent context system. Unlike a chat window that resets every session, Project Memory makes Claude increasingly more useful over time — learning your stack, your rules, and your preferences through markdown files it reads automatically at the start of every conversation.
The four layers work from broadest to narrowest: global user settings → project-level rules → session notes → inline instructions. Each layer overrides the previous, giving you fine-grained control over what Claude knows and how it behaves.
🌍
Layer 1 — Global
~/.claude/CLAUDE.md
Your personal preferences across ALL projects: tone, formatting style, tools you like, things to avoid.
📁
Layer 2 — Project
./CLAUDE.md (checked into repo)
Architecture decisions, coding conventions, tech stack details, deployment instructions for this repo.
💬
Layer 3 — Session
Auto-memory files (per project)
Facts Claude learns during conversations — saved automatically and recalled in future sessions.
💡
Layer 4 — Inline
In the prompt itself
One-time instructions that override everything else just for this response.
Key rule: Put stable, permanent facts in CLAUDE.md. Put session-specific context in auto-memory. Put one-off overrides inline. Never repeat yourself — write it once, let Claude remember it.
🛠️ 5 Real-World Examples
Example 01
Project CLAUDE.md — Team Standards
Check a CLAUDE.md into your repo so every engineer gets the same Claude behavior: correct test runner, no forbidden patterns, deployment process documented.
markdown — CLAUDE.md
# Project: PayAPI## Stack
- Node 20, TypeScript 5.4, Express 4
- PostgreSQL 16 via Prisma ORM
- Jest for tests, Supertest for API tests
## Conventions
- No `any` types — use `unknown` + type guards
- All DB queries in `/services/`, not controllers
- Never commit .env files
- Error format: `{ error: string, code: string }`
## Commands
- Test: `npm test`
- Dev: `npm run dev` (port 3001)
- DB migrate: `npx prisma migrate dev`
Example 02
Global CLAUDE.md — Personal Preferences
Set your global preferences so Claude behaves the same way across every project you work on — tone, output format, what to never do.
~/.claude/CLAUDE.md# My Preferences
- Concise responses — no padding or filler text
- No apologies or unnecessary caveats
- Code first, explanation after (not before)
- Prefer functional patterns over OOP classes
- Always write TypeScript, never plain JavaScript
Example 03
Auto-Memory — Teach Claude About Your Team
Tell Claude facts about your project mid-conversation and ask it to remember them. It saves structured memory files that persist across all future sessions.
PromptRemember: our team uses Conventional Commits format (feat/fix/chore/docs). PRs must reference a Linear ticket ID. Staging is deployed via GitHub Actions on every merge to main. Production deploys are manual via the /deploy-prod slash command in Slack.
Example 04
Multi-Repo Memory Structure
For monorepos or multi-service architectures, place CLAUDE.md files at multiple levels — root for shared context, package-level for service-specific rules.
Sometimes you want Claude to ignore its usual rules just for one response — use an inline instruction at the top of your prompt to override memory without rewriting your CLAUDE.md.
Prompt[For this response only: write a Python version even though the project CLAUDE.md says TypeScript only — I'm writing a migration script for a Python data pipeline.]
Write a script that reads all users from PostgreSQL and exports them to CSV.
🧠 Memory System Simulator interactive
Claude Code — Project Memory System
Simulate reading, writing, and querying memory.
$ _
$
Pro tip: The best CLAUDE.md files answer: "What would a new developer need to know to contribute to this project in their first hour?" — tech stack, key commands, gotchas, and team conventions. If it's in the README, skip it. If it's tribal knowledge, write it down.