Skip to content

Building repository memory with AGENTS.md

Here's the one meta tip that changes everything: if there's anything you want your LLM coding agent to remember for future sessions, just tell it to "Please update AGENTS.md with..." and then specify what you want it to remember.

AGENTS.md serves as durable repository memory. It automates the repetitive task of teaching your agent the same preferences over and over.

What is AGENTS.md?

AGENTS.md is an emerging open standard for providing context to AI coding agents. Think of it as a README for your AI teammates. It's a predictable location where you provide navigation hints, local norms, and constraints that the agent needs to work effectively.

While your README.md is optimized for humans, AGENTS.md is optimized for agents. It should be the single source of truth for how work happens in your repo.

The two jobs of repository memory

To be effective, AGENTS.md needs to do two things for the agent.

First, it needs to make the agent fast at navigating the repo. A code map is a straightforward way to do that. It gets the agent to the right files in 2 seconds instead of 40 seconds of wandering through grep results.

Second, it needs to encode local ways of working so the agent stops repeating the same mistakes. This is where your specific preferences and norms live.

Fast navigation to the right files

In the ideal state, the agent gets to the right files quickly. A code map is the simplest way I know to make that happen. It does not have to be perfect; it can be slightly stale and still be useful.

The difference lies in the feel of the collaboration. The agent spends less time exploring neighborhood by neighborhood, and you spend less time steering them toward obvious entry points.

Close the loop when the map is stale

The code map is not a static artifact; it is part of a feedback loop. When the agent notices that the map looks stale (e.g., a file moved or a new module was added), it should update the map immediately.

You can encode this as an explicit instruction inside AGENTS.md. This "on-demand" update is what makes the loop feel alive and prevents documentation rot.

Training an employee, not programming a bot

I was inspired by NetworkChuck's approach: you're not programming a bot, you're training an employee. You teach the agent by continuously updating its context.

The beauty is that these instructions persist across sessions. Your agent doesn't forget; it gets smarter as your project evolves. This is the Automation philosophy in action.

Durable norms and corrections

The second job of AGENTS.md is to hold repo-specific corrections. These are the things you find yourself saying out loud to the agent.

Two examples from my own work:

  • Run Python in the pixi context: Use pixi run python .... This prevents the agent from trying to use a global Python that may not exist or has the wrong dependencies.
  • Do not cheat by modifying tests: The agent must modify the implementation to make tests pass, never the tests themselves.

Once these rules are written down, the agent stops making you restate them.

Bootstrap your AGENTS.md

I have found it useful to bootstrap AGENTS.md with a one-time deep dive. Here is a prompt you can use to generate your first version:

You are a coding agent. Read through this repository and create an `AGENTS.md` file at the repo root.

Requirements:
- Include a short codebase map that helps an agent find files quickly.
- Focus on entry points, directory roles, naming conventions, configuration wiring, and test locations.
- Add a section called "Local norms" with repo-specific rules you infer from the code and tooling.
- Add a section called "Self-correction" with two explicit instructions:
  - If the code map is discovered to be stale, update it.
  - If the user gives a correction about how work should be done in this repo, add it to "Local norms" so future sessions inherit it.

Process:
- Use search and targeted file reads; do not read every file.
- Prefer high-signal files: `README`, `pyproject.toml`, `package.json`, `pixi.toml`, `.github/workflows`.

See this in action

The Single source of truth philosophy emphasizes having one authoritative version of everything. AGENTS.md is exactly that for agent behavior.

It also connects to Project configuration. Just as you consolidate tool settings in pyproject.toml, you consolidate agent instructions in AGENTS.md.

For more on how to expand these instructions into reusable playbooks, see the next chapter on Skills.