Project Memory File

Also known as: CLAUDE.md, AGENTS.md, agent instructions file, repo memory

A CLAUDE.md or AGENTS.md file holds conventions, commands and decisions that build up over time.

TrackBuilding with coding agents FamilyWorking agreements Maturity Established ChangesContext

Problem

Every new session with a coding agent starts from zero. The agent doesn’t know how to run the tests, which libraries the team chose, which folders not to touch, or the mistake it made last week. Developers repeat the same instructions every session, and the agent still breaks conventions it was told about yesterday.

Each session starts without memory of earlier ones.
The same instructions get repeated across sessions and developers.
A file loaded into every session costs context, so it has to stay short.
Notes that nobody maintains become wrong and mislead the agent.

Solution

Keep a memory file at the root of the repo, named CLAUDE.md, AGENTS.md or whatever your agent reads automatically. It holds what stays true across milestones: how to build, test and run the project; architecture in a few lines; conventions; folders and files the agent must not change; and decisions with a one-line reason. When the agent makes a mistake worth preventing, add a rule. Keep it short and specific, review changes to it like code, and link out to longer docs instead of pasting them in. Subfolders can have their own smaller memory files for local rules.

Diagram

The memory file is loaded into every session. Lessons from each session flow back into it as short, reviewed rules.

When to use

Use it when

Any repo where coding agents work more than once
Several developers or agents work on the same codebase
The project has conventions or commands that aren't obvious
You keep correcting the agent on the same thing

Avoid it when

One-off scripts that won't be touched again
Using it as a dumping ground for long docs; link to them instead
Storing secrets or credentials, which never belong in it

Trade-offs

Latency

Loaded automatically at session start

Cost

A few hundred to a few thousand tokens per session

Complexity

One Markdown file, reviewed like code

Reliability

Fewer repeated mistakes; only as good as its upkeep

Gains

Every session starts with the team's conventions and commands
Mistakes get fixed once, as a rule, instead of every session
New developers benefit from the same file

Costs

Needs ongoing pruning so it stays short and true
Long files dilute the important rules
Conflicting rules confuse the agent

Worked example

Scenario
The Linkwatch repo after MVP1, with a CLAUDE.md the developer and agent maintain together.

Commandsmake test runs all tests in about 8 seconds. make dev starts the app. Always run make test before saying a task is done.
Architecture3 lines: a checker worker, a SQLite store and a small web UI. Check results are append-only.
DecisionsSQLite, not Postgres, until there’s more than one user (decided during MVP1). The check interval lives in config, never hard-coded.
Rules from mistakesIn MVP2 the agent edited a generated migration file. A rule is added: “Never edit files in /migrations; create a new migration.” It hasn’t happened since.
UpkeepEach milestone, the developer prunes the file. It stays at about 60 lines, and every change to it is part of a reviewed PR.

Failure modes

Failure	Symptom	Mitigation
Bloated file	Hundreds of lines; the agent misses the important rules	Keep only what applies broadly; link to detailed docs
Stale rules	File describes commands or structure that changed	Update it in the same PR as the change; prune every milestone
Vague rules	"Write clean code" changes nothing	Write specific, checkable rules with the command or path
Secrets in memory	API keys or passwords committed in the file	Never; point to the secrets manager instead