Project Configuration – CLAUDE.md & Memory

Claude Code can be customized per-project using a CLAUDE.md file and has a memory system that persists information across sessions. These features make Claude Code smarter about your specific project over time.

What is CLAUDE.md?

CLAUDE.md is a markdown file you place in your project root. Claude Code reads it at the start of every session, using it as persistent instructions for how to work with your project.

Creating CLAUDE.md

Use the init command to create one interactively:

claude /init

Or create it manually. Here’s an example:

# CLAUDE.md

## Project Overview
E-commerce API built with FastAPI and PostgreSQL.

## Tech Stack
- Python 3.11, FastAPI, SQLAlchemy 2.0
- PostgreSQL 15, Redis for caching
- pytest for testing

## Commands
- Run tests: `pytest tests/`
- Start dev server: `uvicorn app.main:app --reload`
- Run migrations: `alembic upgrade head`

## Conventions
- Use snake_case for Python, camelCase for JavaScript
- All API endpoints must have input validation
- Write tests for all new features

## Architecture
- app/models/ - SQLAlchemy models
- app/routes/ - API route handlers
- app/services/ - Business logic
- app/schemas/ - Pydantic schemas

What to Include in CLAUDE.md

• Project overview — What the project does, its tech stack
• Common commands — How to build, test, run, and deploy
• Coding conventions — Style guides, naming patterns, preferences
• Architecture — Directory structure and key file locations
• Rules — Things Claude should always or never do

CLAUDE.md Hierarchy

Claude Code supports multiple CLAUDE.md files at different levels:

~/.claude/CLAUDE.md          # Global (all projects)
project-root/CLAUDE.md       # Project-level
project-root/src/CLAUDE.md   # Directory-level (scoped)

Directory-level files are loaded when Claude reads files in that directory, giving you scoped instructions.

Claude Code Memory

Claude Code has a persistent memory system that stores information across sessions. It automatically saves useful patterns it discovers about your project.

Memory is stored in ~/.claude/projects/<project-hash>/memory/.

Managing Memory

# Ask Claude to remember something
> Remember that we always use UTC timestamps in this project

# Ask Claude to forget something
> Forget the convention about UTC timestamps

# Memory is automatically updated as Claude learns about your project

Settings Files

Claude Code also supports .claude/settings.json for configuration:

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Read",
      "Write"
    ]
  }
}

This auto-approves specific tools and commands so you’re not prompted every time.

Summary

CLAUDE.md and memory make Claude Code smarter about your project over time. The more context you provide, the better Claude Code performs. Next, we’ll explore MCP servers and how they extend Claude Code’s capabilities.

Previous: Writing Tests with Claude Code

Next: Using MCP Servers with Claude Code