How to Give AI Agents Project Memory: The CLAUDE.md Guide
Every Claude Code session starts with amnesia. Your AI agent doesn't know your project uses Prisma instead of TypeORM. It doesn't know your API responses always follow a specific shape. It doesn't know that the auth module was just refactored last week. It has no memory of the conventions you've established, the architectural decisions you've made, or the gotchas that have bitten you before. Every session, you start over.
CLAUDE.md fixes this. It's a simple markdown file that gives Claude Code persistent memory across sessions — and it transforms the quality of AI-assisted development. Instead of spending the first five minutes of every session re-explaining your project, Claude reads your memory file and already knows everything it needs to know. This guide shows you exactly what to put in it.
The Amnesia Problem
AI coding agents are stateless by default. Every time you start a new Claude Code session, it knows nothing about your project beyond what it can infer from the files it reads. It doesn't carry context from yesterday's session. It doesn't remember that you spent twenty minutes explaining your authentication flow, or that you decided to use server actions instead of API routes for mutations.
The result is a frustrating ritual at the start of every session. You find yourself repeating the same things over and over: "We use Express with TypeScript." "Our tests use Vitest, not Jest." "The database is PostgreSQL with Prisma." "API responses always follow this shape." You become a human readme, manually loading context into your AI assistant every single time you sit down to code.
This doesn't just waste time — it leads to inconsistent code. When Claude doesn't know your conventions, it makes assumptions. It might generate Jest tests when you use Vitest. It might suggest TypeORM patterns when you use Prisma. It might put business logic in your route handlers when you have a dedicated service layer. Each wrong assumption costs you time to correct, and some slip through entirely.
The fix is surprisingly simple: write it down once and let Claude read it automatically at the start of every session.
What Is CLAUDE.md?
CLAUDE.md is a markdown file placed in your project root that Claude Code reads automatically at the start of every session. It contains everything Claude needs to know about your project — your tech stack, architecture, coding conventions, key decisions, and known gotchas. Think of it as an onboarding document, but for your AI assistant.
When Claude Code starts a new session and detects a CLAUDE.md file in your working directory, it reads the file before doing anything else. This means Claude already has full context about your project before you type your first prompt. No re-explaining, no correcting wrong assumptions, no wasted time.
Creating one is straightforward. If you use Beam, the "Install Project Memory" toolbar button creates a CLAUDE.md with a structured template — fill in the sections and you're done. You can also create it manually: just add a file called CLAUDE.md to your project root and start writing. There's no special syntax or format required. It's just markdown.
What to Put in Your CLAUDE.md
The most effective CLAUDE.md files share a common structure. They cover five key areas, each serving a distinct purpose in giving Claude the context it needs. Let's walk through each one.
Project Overview
Start with the basics: what is this project, and what is it built with? Include the project name, a one-line description of its purpose, and a complete list of your tech stack. This section is short but critical — it immediately grounds Claude in the right mental model for your project.
A good project overview looks something like: "InvoiceFlow — A B2B invoicing platform. Stack: Next.js 14 (App Router), PostgreSQL via Prisma, NextAuth.js with JWT, Stripe for payments, Tailwind CSS, Vitest for testing." In just two lines, Claude knows the framework, database layer, auth strategy, payment provider, styling approach, and test runner. That's enough to prevent dozens of wrong assumptions.
Architecture
Describe how your project is structured: the key directories, the layers of abstraction, and how data flows through the system. This section prevents Claude from putting code in the wrong place, which is one of the most common problems when working with AI agents on established codebases.
Be specific about directory purposes: "app/ contains Next.js pages and API routes. src/services/ contains business logic with no framework dependencies. src/db/ contains the Prisma client, models, and migrations. src/lib/ contains shared utilities." If you have a clear data flow pattern, state it explicitly: "Requests flow through middleware, then router, then handler, then service, then repository." Claude will follow this architecture instead of inventing its own.
Coding Conventions
This is where you define the patterns Claude should follow when generating code. Cover naming conventions, error handling patterns, API response shapes, and test patterns. The more specific you are here, the less time you spend reformatting Claude's output to match your codebase.
Good entries include: "File names use kebab-case (invoice-service.ts). Component names use PascalCase (InvoiceTable.tsx). All errors use the AppError class with a status code and message. API routes return { data: T } for success and { error: string, code: number } for errors. Tests use one file per module with describe/it blocks and factory functions for test data." These conventions become Claude's default behavior for your project.
Key Decisions
Document the architectural and tooling decisions you've already made, especially the ones where Claude might suggest an alternative. This section acts as guardrails that prevent Claude from going down wrong paths.
For example: "We chose Prisma over TypeORM for type safety" stops Claude from suggesting TypeORM patterns. "Auth uses JWT with refresh tokens, not sessions" prevents Claude from adding session middleware. "We deploy to Vercel, not AWS" ensures Claude generates the right configuration files and deployment scripts. "Server actions are used for mutations, not API routes" keeps Claude from creating unnecessary API endpoints. Each decision you record here saves a future correction.
Known Gotchas
Every project has quirks that trip people up — and they trip up AI agents too. Document the things that are surprising, non-obvious, or different from the defaults. This section saves debugging time by preventing mistakes before they happen.
Common entries include: "The ORM auto-pluralizes table names — the 'User' model maps to the 'users' table." "Dev server runs on port 3001, not 3000, because 3000 is used by the API." "The environment variable is DATABASE_URL, not DB_URL." "Prisma needs npx prisma generate after any schema change." "The Stripe webhook secret differs between dev and prod — always check .env." These are the kinds of things you'd tell a new developer on their first day. Tell Claude too.
A Complete CLAUDE.md Example
Here's what a fully fleshed-out CLAUDE.md looks like for a realistic project. You can use this as a starting template and adapt it to your own codebase.
Notice how every section is concise and scannable. You don't need to write paragraphs — bullet points work best. The goal is to give Claude the highest-signal information in the smallest number of lines. A CLAUDE.md file between 30 and 80 lines covers most projects well.
Keeping Your Memory File Updated
CLAUDE.md is a living document, not a one-time setup. As your project evolves, your memory file should evolve with it. The most effective teams treat it the same way they treat their code — it gets updated alongside the changes it documents.
Get into the habit of updating CLAUDE.md at key moments. After making a major architectural decision, add it to the Key Decisions section so Claude doesn't suggest the approach you just moved away from. After discovering a gotcha that cost you debugging time, add it to the Gotchas section so it never happens again. After introducing a new convention, add it to Conventions so all future code follows the same pattern.
Beam's "Save Project Memory" toolbar button makes this easy — it helps you update the file without breaking your flow. You can also ask Claude directly: "Add to CLAUDE.md that we switched from REST to GraphQL for the admin API." Claude will update the file for you, and every future session will know about the change.
It's worth reviewing your CLAUDE.md monthly. Remove information that's no longer accurate, update sections that have drifted from reality, and add new patterns you've established. A stale memory file is worse than no memory file — it actively misleads Claude into generating wrong code.
Memory Files for Multiple Projects
Each project gets its own CLAUDE.md in its own root directory. This creates complete isolation between project contexts — exactly what you want when switching between different codebases with different conventions.
When you switch between projects, each Claude Code session reads only the CLAUDE.md in its working directory. Your SaaS app's Claude knows about Next.js and Prisma. Your CLI tool's Claude knows about Node.js and Commander. Your open source contribution's Claude knows about the upstream conventions and contribution guidelines. There's no cross-contamination between contexts.
If you use Beam's workspace feature, this maps perfectly. Each workspace points to a different project directory, and each workspace's Claude Code sessions automatically load the right memory file. Switch from your frontend workspace to your backend workspace, and Claude's context switches with you. No manual re-explaining required.
For monorepos or multi-package projects, you can place a CLAUDE.md at the root level with shared conventions, and additional CLAUDE.md files in subdirectories for package-specific context. Claude reads the nearest one to its working directory.
Beyond CLAUDE.md: Interoperable Memory
CLAUDE.md works with Claude Code, but the underlying concept — giving AI agents persistent project context through a file — works with any AI coding agent. The idea is universal even if the file name differs.
OpenAI's Codex CLI reads a file called .codex-instructions at the project root. Google's Jules looks for similar configuration files. Other agents have their own conventions. The content is almost identical across all of them — it's the same project context, just read by different tools.
You can maintain a single source of truth by using a shared file like project-memory.md that all agents can read, or you can create agent-specific files that reference common content. Some teams keep a CLAUDE.md for Claude Code and a .codex-instructions for Codex, with both files containing the same information.
Beam's memory management works across all agents. The "Install Project Memory" button creates a memory file that any agent can read, and the "Save Project Memory" button updates it universally. One button, one file, every agent gets the same context. Whether you're using Claude Code, Codex CLI, or switching between them, your AI assistants share the same understanding of your project.
Give Your AI Agent a Memory
Download Beam and use Install Project Memory to create your first CLAUDE.md in one click.
Download Beam for macOSSummary
A well-crafted CLAUDE.md file eliminates the amnesia problem and makes every Claude Code session productive from the first prompt. Here's what to include:
- Project Overview — name, purpose, and complete tech stack
- Architecture — directory structure, layers, and data flow
- Coding Conventions — naming, error handling, API shapes, and test patterns
- Key Decisions — choices you've already made that Claude should respect
- Known Gotchas — quirks, non-obvious defaults, and common pitfalls
Keep it concise, keep it current, and keep it in your project root. That single file is the difference between an AI assistant that knows your project and one that's guessing.