Agent memory files

You have just started Claude Code in a project you have been working on for three months. The agent has no idea what the project does. It does not know your preferred test framework, your naming conventions, the commands that build and run the project, or the patterns you have decided to avoid. It will ask you. Or worse, it will guess.

This is not a bug — it is how language model inference works. Each session processes a fresh context window. Nothing from the previous session survives unless you explicitly put it there.

Memory files are how you put it there.

What a memory file is

A memory file is a plain Markdown file that the agent reads automatically at the start of every session, before you type your first message. It is your chance to front-load all the context the agent would otherwise have to ask about or infer incorrectly.

Different tools look for memory files in different places:

The format is the same across all of them: plain Markdown that the model reads as natural language. There is no special syntax to learn.

What to put in a memory file

A good memory file answers the questions an agent would otherwise have to ask you or guess at:

What is this project?

## Project overview
A command-line tool that parses CSV files and generates summary reports.
Written in Python 3.11. No web framework — pure stdlib plus the `rich` library
for terminal output.

How do I build and run it?

## Running and testing
- Run the CLI: `python -m reporter --help`
- Run tests: `pytest tests/ -v`
- Lint: `ruff check .`
- All three should pass clean before any commit.

What are the coding conventions?

## Conventions
- Functions are small — if a function exceeds 30 lines, split it.
- All public functions have docstrings.
- Use `pathlib.Path` everywhere; never `os.path`.
- Error messages go to stderr, output goes to stdout.

What patterns should the agent avoid?

## Do not do
- Do not use `print()` for debugging — use the `logging` module.
- Do not add new dependencies without asking first.
- Do not modify `tests/fixtures/` — those files are reference data.

What to leave out

A memory file that is too long or contradicts itself is worse than a short one. The model reads the whole file and tries to reconcile everything — if you have written fifty rules, some of which conflict, it will do its best and get it approximately right, which is not the same as getting it right.

Leave out secrets. API keys, passwords, database connection strings — none of these belong in a file that is likely to be committed to your repository. Use environment variables, .env files (gitignored), and secrets managers. A memory file is often checked in to source control.

Leave out obvious things. "Write correct code" is not a useful instruction. Neither is "be helpful." Document the non-obvious: the unusual constraint, the historical decision, the footgun you have already stepped on.

Leave out aspirational rules you don't actually enforce. If your codebase does not consistently follow a rule, writing it in the memory file creates a contradiction the agent will encounter as soon as it reads a file that violates the rule. Document what is true, not what you wish were true.

A minimal starter template

Here is a starter CLAUDE.md you can adapt for any project:

# CLAUDE.md

## Project overview
[One paragraph: what this project does, the language/runtime, and its purpose.]

## How to run
- Install dependencies: [command]
- Run the project: [command]
- Run tests: [command]
- Lint: [command]

## Conventions
- [Language version or runtime version]
- [Key style rules: naming, function size, commenting]
- [Libraries in use that the agent should know about]

## Do not
- [Patterns to avoid]
- [Files not to modify]
- [Operations that require explicit human approval]

Fill this in once at project start. Update it when you make architectural decisions that change the project's structure or constraints. Think of it as a living onboarding document — the one you wish you had when you joined someone else's project.

The compounding effect

The return on a good memory file is high and gets higher over time. Every agent session that does not have to re-discover your test command, re-infer your naming convention, or re-learn which files are off-limits is a session that can spend its context window on the actual task. The investment of thirty minutes writing a thorough CLAUDE.md pays off across every session for the life of the project.

Where to go next

Your agent now knows your project before it starts. The next lesson moves to the core skill of the module: directing agents effectively — how to scope tasks, give instructions that produce the right behaviour, and course-correct when the agent goes off track.