How to use CLAUDE.md files and the /memory command in Claude Code to give Claude persistent context about your project, team conventions, and architecture.
Claude Code's memory system lets you give Claude persistent, project-specific context that survives across sessions. This guide covers the full memory hierarchy and what to put in each layer.
| File | Scope | When to use |
|---|---|---|
~/.claude/CLAUDE.md | All projects (global) | Personal preferences, tools you always use, output format preferences |
./CLAUDE.md | This project only | Architecture, build commands, conventions, active WIP context |
./src/CLAUDE.md | This subdirectory | Module-specific conventions, local APIs, subsystem quirks |
# Run in your project root — Claude Code will analyze:
# - package.json / pyproject.toml / Cargo.toml
# - Directory structure (top 2 levels)
# - Recent git history (last 20 commits)
# - Existing README / docs
/init
# Review the output and edit before committing.
# Typical generated sections:
# ## Project Overview
# ## Tech Stack
# ## Build & Test Commands
# ## Key Directories
# ## Coding Conventions
# My API Service
## Stack
Python 3.12, FastAPI, SQLAlchemy 2.0, PostgreSQL 15, pytest
## Commands
- Run: `uvicorn app.main:app --reload`
- Test: `pytest tests/ -x -q`
- Lint: `ruff check . && mypy app/`
- Migrate: `alembic upgrade head`
## Architecture
- `app/routers/` — FastAPI route handlers (one file per domain)
- `app/services/` — Business logic (pure functions, no DB access)
- `app/models/` — SQLAlchemy ORM models
- `app/schemas/` — Pydantic request/response models
- `tests/` — pytest tests, fixtures in `conftest.py`
## Conventions
- Services receive and return Pydantic models (not ORM objects)
- Never call the DB directly from routers — always via services
- All datetime fields use UTC, stored as TIMESTAMP WITH TIME ZONE
- Environment variables loaded via `app/config.py` (pydantic-settings)
## Off-limits
- `alembic/versions/` — never edit migration files manually
- `app/config.py` — only add settings here, don't inline env reads
## Active WIP
- Migrating auth from JWT to session tokens (branch: feature/session-auth)
- Do not add new JWT dependencies
# Open your project's CLAUDE.md in the default editor:
/memory
# After saving, Claude Code picks up changes immediately in the next message.
# No restart required.
# ~/.claude/CLAUDE.md — applies to every project
## My preferences
- Always prefer functional style over classes for utility functions
- When writing Python, use type hints for all function signatures
- For CLI commands, show the full command before running it
- Code comments: only add when the WHY is non-obvious
- Test file names: test_.py (not _test.py)
## Tools I always have
- ripgrep (rg), fd, jq, bat, httpie (http)
- Use these instead of grep/find/cat when they fit
# Commit CLAUDE.md with your project code so teammates inherit it:
git add CLAUDE.md
git commit -m "Add Claude Code project context (CLAUDE.md)"
# Team members who run Claude Code in this repo automatically get
# the same project context without any setup.
# Tip: treat CLAUDE.md like a living document.
# Update it when architecture changes, new conventions are adopted,
# or active WIP context changes.
For a complete reference of Claude Code's built-in commands, see Claude Code slash commands. For setting up automated behaviors like linting on file save, see Claude Code hooks.