CLAUDE.MD - PROJECT MEMORY

Every conversation starts fresh. The model doesn't remember yesterday. But you can give it memory through CLAUDE.md files.

What Is CLAUDE.md?

It's a markdown file that Claude Code reads at the start of every session. Think of it as a briefing document:

"Here's what you need to know about this project..."

Claude Code loads it automatically. No special command needed.

Where CLAUDE.md Lives

Two locations:

~/.claude/CLAUDE.md        Global - applies to ALL projects

./CLAUDE.md                Project - applies to current directory

Both are loaded if both exist. Project-specific adds to global.

Creating Project Memory

The easy way - let Claude Code do it:

cd ~/my-project
claude

# Then run:
/init

This scans your codebase and generates a CLAUDE.md with:

Project structure overview
Detected languages and frameworks
Build/test commands it found
Key directories and files

Review what it creates. It's a starting point, not gospel.

Manual CLAUDE.md

You can write it yourself. Here's a template:

# Project: My Web App

## Tech Stack
- Perl with Mojolicious framework
- SQLite database
- HTML/CSS frontend (no JavaScript frameworks)

## Directory Structure
- lib/           Perl modules
- templates/     HTML templates
- public/        Static files
- script/        CLI scripts
- t/             Tests

## Common Commands
- Run server: morbo script/my_app
- Run tests: prove -lv t/
- Database: sqlite3 data/app.db

## Coding Standards
- Use Allman brace style
- Prefer DBI over raw SQL
- All new code needs tests

## Things To Know
- Auth tokens are in config/secrets.conf (gitignored)
- User uploads go to public/uploads/
- The cron job in scripts/cleanup.pl runs nightly

Be specific. The more context you give, the better Claude understands your project.

Global CLAUDE.md

~/.claude/CLAUDE.md applies everywhere. Good for:

Your coding style preferences
Tools you always use
How you like explanations formatted

Example:

# Global Preferences

## Coding Style
- Allman brace style always
- Prefer vim for editing
- Use regex solutions when appropriate

## Explanations
- Break big ideas into small pieces
- Show simple examples with comments
- One concept at a time

## Environment
- macOS with Homebrew
- Perl 5.42 from brew
- Default shell is zsh

The # Shortcut

During a session, you can add notes to CLAUDE.md without opening it:

# Always use prepared statements for database queries

This gets appended to CLAUDE.md. Quick way to teach Claude mid-session.

Hierarchical Loading

Claude Code loads CLAUDE.md files in order:

~/.claude/CLAUDE.md (global)
./CLAUDE.md (project root)
./subdir/CLAUDE.md (nested directories)

Nested files add to or override earlier ones. You can have a general project CLAUDE.md and more specific ones in subdirectories.

What To Put In CLAUDE.md

GOOD things to include:

Project purpose and architecture
Build/run/test commands
Directory structure explanation
Coding standards and style guides
Known quirks or gotchas
File naming conventions
Database schema overview
API patterns used

BAD things to include:

Secrets, passwords, API keys
Huge code dumps (wastes context)
Generic programming tutorials
Stuff that changes constantly

CLAUDE.md is loaded every session. Keep it focused on stable knowledge.

Token Cost

Everything in CLAUDE.md uses context tokens. A 500-word CLAUDE.md is roughly 400 tokens. That's context you can't use for conversation.

Keep CLAUDE.md concise. Bullet points over paragraphs. Key facts over comprehensive documentation.

Viewing What's Loaded

Check what CLAUDE.md files are active:

/context

This shows which files Claude Code loaded and their token cost.

Ignoring CLAUDE.md

If a CLAUDE.md is causing problems:

claude --ignore-memory

Starts without loading CLAUDE.md files. Useful for debugging.

Example: Perl Web Project

Here's a real CLAUDE.md for a Perl Mojolicious project:

# techalicious-academy

Pay-per-tutorial platform built with Perl/Mojolicious.

## Stack
- Perl 5.42 with Mojolicious
- SQLite database
- Stripe for payments
- Brevo for email

## Running
- Dev: morbo script/academy
- Prod: hypnotoad script/academy
- URL: http://localhost:3000

## Structure
- lib/TechaliciousAcademy.pm - main app, routes
- lib/TechaliciousAcademy/Controller/* - route handlers
- lib/TechaliciousAcademy/Model/* - database access
- templates/* - HTML templates
- tutorials/* - tutorial content (text files)

## Key Files
- config/academy.conf - all configuration
- data/academy.db - SQLite database (gitignored)

## Style
- Allman braces
- DBI with prepared statements
- Test::More for tests

## Auth
- Token-based access (no user accounts)
- Master token in config for testing

Under 200 words. Gives Claude Code everything it needs.

Summary

CLAUDE.md = project memory that persists across sessions

Locations:
  ~/.claude/CLAUDE.md     Global preferences
  ./CLAUDE.md             Project-specific

Create it:
  /init                   Auto-generate from codebase
  # note                  Add quick notes during session

Keep it:
  - Concise (costs tokens)
  - Focused (stable knowledge)
  - Updated (review periodically)

Next chapter: Using Claude Code effectively.