Agent Memory & Context Management

Here is a scene you have almost certainly lived through. You built a feature on Tuesday — a user dashboard with filters, a clean API endpoint, everything tested and working. On Wednesday you open a fresh session to add a CSV export to that dashboard. You type your prompt, Claude Code starts writing code, and within three minutes you notice it is doing something completely wrong: it is building a new dashboard from scratch instead of extending the one you built yesterday. It does not know the dashboard exists because it does not remember Tuesday.

This is the most common failure mode in vibe coding, and it has nothing to do with the model being bad at code. It happens because every session starts with amnesia. The model does not know your project unless you tell it about your project, and if you forget to tell it about the dashboard, it invents one.

The fix is not a better prompt. The fix is a single file that makes your project self-describing — a file the agent reads automatically before it writes a single line of code, so it walks into every session knowing what you built, how you built it, and what decisions you already made.

What you'll learn

• CLAUDE.md is the agent's memory — a single file at your project root that describes your stack, conventions, architecture, and decisions
• Everything the agent needs to know before writing code belongs in CLAUDE.md; everything specific to a single task belongs in the prompt
• Memory rots when you don't update it — the file must grow as your project grows, or the agent starts making decisions based on stale information
• A CLAUDE.md that works is short enough to read in one pass, specific enough that the agent never guesses, and current enough that it reflects what is actually in the codebase today

The problem: your agent has no memory

When you open a new Claude Code session, the agent sees your prompt, your project files, and whatever context you feed it. It does not see your chat history from Tuesday. It does not see the decisions you made at 11 PM when you chose SQLite over PostgreSQL after debating it for an hour. It does not see the naming convention you settled on after three rounds of iteration.

What happens next is predictable: the agent makes different decisions. It uses camelCase when the rest of your codebase uses snake_case. It imports from a path that doesn't exist. It suggests PostgreSQL when the project already has SQLite wired up. You spend the first ten minutes of every session correcting the agent instead of building.

This is not the model being careless. It is the model doing exactly what it was told: solve this problem, given these constraints. If you do not give it the constraints — the existing decisions, the conventions, the architecture — it picks reasonable defaults. And reasonable defaults almost never match what you actually built.

One solution is to include all of this in every prompt: "Remember, this project uses SQLite, snake_case naming, FastAPI with Pydantic v2, and the dashboard lives in app/dashboard/routes.py." That works for about three prompts. By the fourth prompt you are sick of typing it. By the tenth you have forgotten one of the constraints, and the agent drifts.

The other solution is CLAUDE.md.

Options & when to use each

Approach	What it is good for	What it costs you	When to pick it
Everything in the prompt	Quick one-off tasks, no setup	Retyping context every session; forgetting constraints; inconsistent agent behavior over time	You are building a throwaway script, not a project
CLAUDE.md at project root	Persistent project memory that loads automatically every session	Requires discipline to maintain; stale data is worse than no data	Any project that spans more than one session — which is every real project
Multiple context files (CLAUDE.md + ARCHITECTURE.md + CONVENTIONS.md)	Large projects where one file gets unwieldy	Fragmentation: the agent might not read all files unless you reference them; more maintenance surface area	Teams or projects with 50+ source files where a single CLAUDE.md would exceed a few hundred lines
Embedded context in source files (header comments explaining conventions)	File-level conventions that rarely change	Hidden from the agent unless it opens the file; duplicates need to be kept in sync	Supplementary to CLAUDE.md, never a replacement

For a solo project or a small team, CLAUDE.md at the project root is the right call. One file, read automatically, updated as the project grows. For very large projects, CLAUDE.md remains the entry point, but you can reference additional files from it: "See ARCHITECTURE.md for the module diagram."

Build it: a CLAUDE.md that actually works

Step 1: create the file

cd ~/projects/my-app
touch CLAUDE.md

Place it at your project root. Claude Code reads it from the current working directory upward, so no special configuration is needed.

Step 2: write the minimum viable CLAUDE.md

A working CLAUDE.md has four sections. You can add more later, but these four are the ones that prevent the most common failures:

# My App

## Stack
- Python 3.12 with uv for package management
- FastAPI web framework
- SQLite database (file: data/app.db)
- Jinja2 templates in templates/
- Tailwind CSS via CDN

## Conventions
- snake_case for all Python identifiers
- Pydantic v2 models in app/schemas.py
- Route handlers in app/routes/ -- one file per domain
- Database queries use raw SQL, not an ORM
- Error responses: {"error": "message"} with appropriate HTTP status code
- Never use TODO placeholders -- write real implementations or mark with # FIXME

## Architecture
- app/main.py -- FastAPI app creation and middleware
- app/routes/ -- one file per domain (dashboard.py, users.py, api.py)
- app/templates/ -- Jinja2 templates mirroring route structure
- app/static/ -- CSS, JS, images
- data/ -- SQLite database and migration scripts

## Key Decisions
- SQLite chosen over PostgreSQL for zero-config deployment (2026-07-15)
- Raw SQL instead of SQLAlchemy to keep the stack simple (2026-07-16)
- User auth uses session cookies, not JWT (2026-07-20)

This is about 40 lines. It takes five minutes to write. It covers everything the agent needs to write code that fits into your project without you re-explaining it.

Step 3: the "prompt vs CLAUDE.md" test

After writing CLAUDE.md, run this mental test on every new prompt:

Does this information apply to the whole project, or just this task?

Whole project → CLAUDE.md. The stack, the conventions, the architecture, the decisions you made that the agent should never contradict. This is the background the agent needs for every session.

This task → the prompt. "Add a CSV export to the dashboard." "Fix the 500 error in the notification pipeline." "Add a date filter to the user list." This is the specific work you want done right now.

Here are two examples to make it concrete:

Example 1: adding a new feature

CLAUDE.md says: Python 3.12, uv, FastAPI, SQLite, snake_case, routes in app/routes/

Prompt: Add a monthly report page to the dashboard. It should show revenue by category for the selected month. Use the existing database schema from data/schema.sql. The report route goes in app/routes/reports.py.

The prompt does not repeat the stack or conventions because CLAUDE.md already covers them. The prompt tells the agent what to build and where to put it. That is enough.

Example 2: fixing a bug

CLAUDE.md says: raw SQL, error responses use {"error": "message"}, no ORM

Prompt: The dashboard filter for Q3 2026 returns an empty table but data exists. Trace the query in app/routes/dashboard.py and fix it.

Again, the prompt focuses on the specific task. All the background — the database approach, the error format, the route structure — comes from CLAUDE.md.

Step 4: maintain it as your project grows

The most important habit with CLAUDE.md is not writing it. It is updating it.

After every significant session, ask yourself: "Did I make a decision the agent would need to know about next time?" If yes, add it to CLAUDE.md before you close the session. Here are the most common triggers:

• You added a new dependency → add it to the Stack section
• You introduced a new directory or module → update the Architecture section
• You settled on a new pattern (e.g., "all forms use HTMX, not fetch") → add it to Conventions
• You made a decision that could go either way (e.g., "use server-side sessions instead of JWTs") → add it to Key Decisions with a date

A stale CLAUDE.md is worse than no CLAUDE.md. A stale file tells the agent to do things that are no longer true. If your CLAUDE.md says "PostgreSQL" but you switched to SQLite last week, the agent will generate PostgreSQL connection strings and wonder why nothing works.

Maintenance is not heavy. It is usually a one-line addition. "Added HTMX for form submissions (2026-08-01)." Done. Five seconds, and the next session starts with full context.

Step 5: when CLAUDE.md gets large

For a project of 10-20 source files, a 40-line CLAUDE.md is plenty. As the project grows past 50 files, you will feel the pull to add more and more detail. Resist that pull, but also recognize when a single file is genuinely not enough.

The rule of thumb: if CLAUDE.md passes 200 lines, it is time to split. But do not split into a dozen tiny files. Create at most two additional files — ARCHITECTURE.md for the module diagram and inter-component relationships, and CONVENTIONS.md for the style guide and patterns — and reference them from CLAUDE.md:

## Architecture (detailed)
See ARCHITECTURE.md for the full module dependency diagram.

## Conventions (detailed)
See CONVENTIONS.md for the complete code style guide.

The agent reads CLAUDE.md automatically. It does not automatically read ARCHITECTURE.md. If you reference external files, your prompts should also reference them when the agent needs those details: "Read ARCHITECTURE.md first, then add the new module."

What goes wrong

Mistake	How you notice it	The fix
Writing CLAUDE.md once and never updating it	The agent imports a library you removed, uses a pattern you deprecated, or references a module that was renamed three sessions ago	After every session, add one line if anything changed. Make it a habit, not a chore
Putting task-specific instructions in CLAUDE.md	Your CLAUDE.md reads like a to-do list: "Add CSV export, fix the filter bug, implement dark mode"	Move task instructions to individual prompts. CLAUDE.md is for permanent context, not the current sprint
Making CLAUDE.md too long	The agent starts missing conventions because they are buried in 400 lines of prose. You stop reading it yourself	Keep it under 200 lines. Be specific, not exhaustive. Every line should tell the agent something it cannot discover by reading the codebase
Making CLAUDE.md too vague	"Write clean code." "Follow best practices." "Use good patterns." The agent hears these and does whatever it was going to do anyway	Every line must be falsifiable. "Use snake_case for all Python identifiers" can be checked. "Write clean code" cannot
Not dating decisions	Three months later, you look at "Use JWT for auth" and do not know if that was a deliberate choice or an early assumption you later reversed	Add dates to key decisions: "Use JWT for auth (2026-07-01 -- reconsidered 2026-07-20, switched to session cookies)"
Forgetting to put environment setup in CLAUDE.md	Every session starts with "what Python version?" or "where is the virtual environment?"	The Stack section exists for exactly this. Python version, package manager, database location, env file path — these are the first things the agent should know

Confirm it worked

Open a fresh Claude Code session. Do not tell it anything about your project. Ask: "What stack does this project use?" If the answer matches your CLAUDE.md, the file is loading correctly.

Now give it a real task that depends on conventions from the file: "Add a new route that returns a list of users from the database." The agent should use the correct database approach (raw SQL if that is your convention, ORM if that is yours), put the file in the right directory (app/routes/ if you specified that), and use the right naming convention (snake_case). If it does all three without you specifying any of them in the prompt, your CLAUDE.md is doing its job.

The final test: check the file length. If your CLAUDE.md is under 200 lines, contains concrete, falsifiable instructions, and the agent follows them without prompting, you have built working agent memory. If it is over 200 lines and you dread opening it, split it and reference the sub-files.

Next: Custom Commands for Project Management