title: "Project Memory" last_updated: 2026-03-21 status: proven difficulty: beginner prerequisites: [01-your-first-hour]

Project Memory

The Core Question: How Do Agents Understand Your Project?

Every time you start a new session with an AI coding agent, you face the same problem: the agent knows nothing about your project. It does not know your directory structure. It does not know that your team uses Zustand instead of Redux, that your API responses always follow a specific envelope format, or that there is a legacy module in src/billing/ that must never be refactored without a product manager's sign-off.

The agent starts cold. Every single session.

This is the fundamental challenge of agentic development: your AI collaborator has powerful general knowledge of programming, but zero specific knowledge of your codebase. Without help, it will guess at your conventions, produce code that works but does not fit, and force you into repetitive corrections.

Project memory solves this. It is the collective set of configuration files — CLAUDE.md, AGENTS.md, and their supporting directories — that give an agent persistent context about your project. Think of it as the onboarding document you would write for a new team member who is brilliant but has never seen your codebase.

Project Memory as Compound Interest

A well-crafted project memory file is the single highest-leverage investment in agentic development. Here is why: every configuration line you write pays off not once, but across every session, every task, and every team member who uses an agent on your project.

Consider the math. Suppose you spend 30 minutes writing a CLAUDE.md that saves you 2 minutes of corrections per session. If you run 10 sessions per day, that is 20 minutes saved daily — and your initial investment pays for itself in under two days. Over a month, you have saved roughly 7 hours. Over a year, you have saved weeks.

Now multiply that across your team. A shared project memory file means every developer gets those savings from day one, without each person independently discovering the same conventions through trial and error.

The compounding goes deeper. As your project memory improves, the agent produces better code on the first attempt. Better first attempts mean you trust the agent with larger tasks. Larger tasks mean greater productivity gains. The virtuous cycle accelerates.

What Goes in Project Memory

Effective project memory answers five questions an agent would ask on its first day:

1. What is this project? A one-to-two sentence overview. Not a marketing pitch — a technical summary. "This is a Next.js 14 e-commerce platform using App Router, Postgres via Drizzle ORM, and Stripe for payments."

2. How is the code organized? Key directories and their purpose. The agent needs a mental map of where things live. You do not need to list every folder — just the ones that matter for navigation.

3. What conventions should I follow? Naming patterns, formatting rules, preferred libraries, architectural patterns. These are the instructions that prevent the agent from writing technically correct code that looks nothing like the rest of your codebase.

4. How do I run things? Build commands, test commands, deploy steps, common development tasks. Agents frequently need to verify their work, and they cannot do that if they do not know how to run your test suite.

5. What should I avoid? Anti-patterns specific to your project. Legacy modules that should not be touched. Libraries that look like good fits but cause problems. Patterns that have been tried and rejected. This section prevents the agent from repeating your team's past mistakes.

The Hierarchy: Repo, Directory, File

Project memory is not a single flat file. It operates as a hierarchy:

• Repo-level instructions (project root) apply everywhere. This is where your project overview, global conventions, and common tasks live.
• Directory-level instructions (subdirectories) override or extend repo-level guidance for specific parts of the codebase. Your api/ directory might have different conventions than your frontend/ directory.
• File-level instructions come from inline comments within your code — these are the most specific and the most rare.

This hierarchy means you can keep your root configuration concise while adding specific guidance exactly where it is needed. A monorepo with a Python backend and a React frontend does not need to cram both sets of conventions into a single file.

What NOT to Put in Project Memory

The most common mistake is writing too much. Project memory is loaded into the agent's context window at the start of every session. Every line consumes tokens — the limited resource that determines how much the agent can process in a single session.

Do not duplicate your README. Your README is for humans browsing GitHub. Project memory is for agents working in your code. There is overlap, but they serve different audiences.

Do not write a novel. A 500-line configuration file means the agent has 500 fewer lines of capacity for your actual task. Be ruthless about conciseness.

Do not document obvious things. You do not need to tell the agent to "write clean code" or "handle errors properly." It already knows these things. Focus on what is specific to your project.

Do not include temporary instructions. "Fix the bug in auth.ts" is a task, not a convention. Keep project memory focused on durable knowledge that will be true next month.

The 80/20 Rule

Eighty percent of the value from project memory comes from twenty percent of the content. Specifically:

1. A clear project overview (1-2 sentences) — this anchors everything else
2. Three to four key conventions — the ones you would correct most often without them
3. A build/test command reference — so the agent can verify its own work

If you write nothing else, write these. A 10-line file covering these basics will outperform a 200-line file that tries to document everything but buries the important bits in noise.

Evolving Your Config Over Time

Do not try to write the perfect project memory file upfront. You cannot anticipate what the agent will get wrong. Instead:

1. Start minimal. Write a 5-10 line file with your project overview and the conventions you care about most.
2. Use the agent. Give it real tasks on your project.
3. Notice the corrections. When you find yourself telling the agent the same thing twice, that is a signal to add it to your config.
4. Add one thing at a time. After each session, add the single most impactful instruction you wish the agent had known.
5. Prune ruthlessly. If an instruction is not earning its token cost, remove it.

This iterative approach produces a config that reflects your actual needs rather than your assumptions about what an agent might need.

The Aspirational Trap

A subtle but damaging mistake is writing instructions that describe how you wish your project worked rather than how it actually works. If your codebase is full of class components but you write "Always use functional components with hooks," the agent will produce code that is stylistically inconsistent with everything around it.

Write instructions for the project you have, not the project you want. If you are migrating from one pattern to another, say so explicitly: "New components should use functional components with hooks. Existing class components in src/legacy/ should not be refactored without explicit instruction."

Context Windows and Token Budgets

Project memory is always loaded — it consumes context window space whether or not it is relevant to the current task. This is by design: the agent needs your conventions for every task. But it means that a bloated configuration file directly reduces the agent's capacity for complex work.

A rough guideline: keep your root-level project memory file under 100 lines. If you need more than that, use the directory-level hierarchy to put specialized instructions closer to where they are needed. This way, the agent only loads the subset of instructions relevant to the part of the codebase it is working in.

Key Takeaways

• Every agent session starts cold. Project memory is how you give the agent persistent knowledge about your codebase.
• Start with 5-10 lines, not 200. A concise file that covers your project overview and top conventions delivers most of the value.
• Add instructions reactively. When you correct the agent twice for the same thing, add it to your config.
• Use the hierarchy. Repo-level for global conventions, directory-level for local overrides.
• Keep it honest. Document what your project actually does, not what you wish it did.