Claude.Md - Project Memory

Deep dive

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:

1. ~/.claude/CLAUDE.md (global)
2. ./CLAUDE.md (project root)
3. ./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.