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.

That habit is what makes repository memory durable. AGENTS.md 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.

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

Map updates help, but the deeper shift is psychological. I was inspired by NetworkChuck's framing: you're not programming a bot, you're training an employee. You teach the agent by continuously updating its context.

That only pays off if the lessons stick. 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

Navigation gets the agent to the right room; norms tell them how to behave once they are there. The bullets below are the sort of correction I got tired of saying out loud.

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.

Examples worth spelling out

Norms work best when they read like instructions the agent can execute without guessing. What follows are four patterns I have actually written into agent memory. They all sit in the "local rules" bucket above, not in the map.

Markdown: lint what you touch

When the project lives in Markdown, I add an explicit documentation workflow: after editing any .md file, run markdownlint on that file and fix issues before the change is "done." In Pixi-heavy repos, markdownlint is often installed globally. Tell the agent to use markdownlint path/to/file.md, not pixi run markdownlint ..., and to run pixi global install markdownlint when the tool is missing.

Tests: steer toward pytest

Most models default to unittest classes because that pattern is overrepresented in training data. Stating a preference for pytest-style functions in AGENTS.md is usually enough; you stop getting class TestThing(unittest.TestCase) unless the project truly wants it. When you have a real test runner story, add a short line about how CI runs tests (markers, coverage, directories) so the agent does not invent a different incantation every session.

Verification: skip throwaway probe scripts

Agents like to drop quick_check.py or test_something_random.py on disk. Those files are not under CI and they do not guard regressions; they only add noise. I teach the agent to add a proper test in the suite instead, or to run the project's existing test command. The point matches the other norms here: encode the workflow you want repeated.

Tooling: document the `pixi run` contract

The same literalism helps with how commands are run. When Python and tools only exist inside Pixi, bare python or pytest will fail or use the wrong environment. I spell that out with explicit right and wrong examples so there is no improvisation:

All project commands must use: pixi run <task-or-tool>

Right:
  pixi run pytest tests/test_api.py
  pixi run python -m mypkg

Wrong:
  pytest tests/test_api.py
  python -m mypkg

That pattern generalizes to any toolchain that is newer than the model's training set, not only Pixi.

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

This chapter ties together a few threads the book keeps returning to.

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.

For a long-form example of package management, tests, and style rules in one place, see the Llamabot AGENTS.md.

Building repository memory with AGENTS.md

What is AGENTS.md?