Project instructions (`AGENTS.md`) — explanation

What is this about?

An agent's configuration says what the agent is: its name, its tools, how it edits files. It cannot say how each project it works in is built, tested or organised — one agent.yaml serves many projects. AGENTS.md (https://agents.md) is the convention coding agents share for that: a plain Markdown file at the root of a repository, written for agents. mm reads it from the directory a conversation works in and adds it to the system prompt (ticket 81).

Why it is appended to the system prompt

The file follows the configuration's system prompt, under a heading naming where it came from — PROJECT INSTRUCTIONS (from <path>) — and never replaces it: the two answer different questions, and the agent needs both. The heading tells the model the rules belong to the project, not to its role, which helps when they disagree (an agent told to answer in English, a project whose comments are in French).

A first user message ("here are the project's instructions") was rejected: small local models weigh the system message more, and some chat templates (Gemma, Mistral) refuse two user turns in a row. The same mechanism already carries structuredOutput's OUTPUT FORMAT paragraph.

Why it is read per conversation, not per question

The file is read when a conversation starts — at start-up, on /new, on /resume, for a new or reloaded editor session — and not again until the next one. Reading it before every question would pick an edit up sooner, but a system message that changes mid-conversation forces the server to re-read the whole history: llama.cpp keeps the already-processed prefix of the prompt in a cache, and the system message is the first thing in it (the same cache ticket 53 protects by keeping the tools in a stable order). On a long local conversation that is minutes per question. One version per conversation keeps the cache; /new is the way to take an edit into account.

/resume follows the rule mm already applied to the system prompt: a resumed conversation continues under the agent's prompt as it is now, so it gets the current file too. A resumed session is re-read whole by the server anyway, so this costs nothing.

Why the working directory, and only it

The working directory is the project: the directory mm runs in, or the cwd an editor gives each session. Each ACP session therefore reads its own project's file, and a relative agentsMd.path is resolved there, never next to the configuration file — otherwise one agent.yaml would read the same file in every project.

The convention also allows nested files in a monorepo, closest one winning. mm does not walk up to the repository root nor concatenate files: one file, one place, predictable.

Why a warning rather than a cut

The system message is sent with every request and occupies the context window for the whole conversation. A few pages of AGENTS.md are nothing to a cloud model and half the window of a 4B model served with 16k tokens. mm measures it — the same estimate as the context compression, characters divided by 3.5 — and warns from 20 % of a known window. It does not cut it: truncation keeps the beginning and silently drops the end, which may hold the one rule that mattered, while the model believes it read everything. agentsMd.maxChars exists for those who want a hard limit; above it, the file is left out whole and the banner says so — a missing file is a state the user sees, a half-read one is not.

Agents that do not read it

JSON agents (structuredOutput): prose instructions ("end every answer with a signature") would fight the JSON constraint, and a signature appended to the JSON would break every script reading it. The banner mentions the ignored file neutrally, since it is intended.
Agents called by another one (/ask, ask_agent, mm --ask): they run as their own mm process with their own configuration, and read the file of the working directory they are given only when their own agentsMd.enabled says so. A reviewer with no tools can turn it off; a coding helper keeps it and follows the same rules as the agent that called it.

How it relates to the rest

Structured output — the other paragraph mm appends to the system prompt.
Asking another agent — the working directory an asked agent is given.
How to give the agent your project's instructions and the agentsMd reference.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


# Project instructions (`AGENTS.md`) — explanation

## What is this about?

An agent's configuration says what the agent is: its name, its tools, how it edits files. It cannot say how each project it works in is built, tested or organised — one `agent.yaml` serves many projects. `AGENTS.md` (https://agents.md) is the convention coding agents share for that: a plain Markdown file at the root of a repository, written for agents. mm reads it from the directory a conversation works in and adds it to the system prompt (ticket 81).

## Why it is appended to the system prompt

The file follows the configuration's `system` prompt, under a heading naming where it came from — `PROJECT INSTRUCTIONS (from <path>)` — and never replaces it: the two answer different questions, and the agent needs both. The heading tells the model the rules belong to the project, not to its role, which helps when they disagree (an agent told to answer in English, a project whose comments are in French).

A first user message ("here are the project's instructions") was rejected: small local models weigh the system message more, and some chat templates (Gemma, Mistral) refuse two user turns in a row. The same mechanism already carries `structuredOutput`'s `OUTPUT FORMAT` paragraph.

## Why it is read per conversation, not per question

The file is read when a conversation starts — at start-up, on `/new`, on `/resume`, for a new or reloaded editor session — and not again until the next one. Reading it before every question would pick an edit up sooner, but a system message that changes mid-conversation forces the server to re-read the whole history: llama.cpp keeps the already-processed prefix of the prompt in a cache, and the system message is the first thing in it (the same cache ticket 53 protects by keeping the tools in a stable order). On a long local conversation that is minutes per question. One version per conversation keeps the cache; `/new` is the way to take an edit into account.

`/resume` follows the rule mm already applied to the `system` prompt: a resumed conversation continues under the agent's prompt as it is now, so it gets the current file too. A resumed session is re-read whole by the server anyway, so this costs nothing.

## Why the working directory, and only it

The working directory is the project: the directory `mm` runs in, or the `cwd` an editor gives each session. Each ACP session therefore reads its own project's file, and a relative `agentsMd.path` is resolved there, never next to the configuration file — otherwise one `agent.yaml` would read the same file in every project.

The convention also allows nested files in a monorepo, closest one winning. mm does not walk up to the repository root nor concatenate files: one file, one place, predictable.

## Why a warning rather than a cut

The system message is sent with every request and occupies the context window for the whole conversation. A few pages of `AGENTS.md` are nothing to a cloud model and half the window of a 4B model served with 16k tokens. mm measures it — the same estimate as the context compression, characters divided by 3.5 — and warns from 20 % of a known window. It does not cut it: truncation keeps the beginning and silently drops the end, which may hold the one rule that mattered, while the model believes it read everything. `agentsMd.maxChars` exists for those who want a hard limit; above it, the file is left out whole and the banner says so — a missing file is a state the user sees, a half-read one is not.

## Agents that do not read it

- **JSON agents** (`structuredOutput`): prose instructions ("end every answer with a signature") would fight the JSON constraint, and a signature appended to the JSON would break every script reading it. The banner mentions the ignored file neutrally, since it is intended.
- **Agents called by another one** (`/ask`, `ask_agent`, `mm --ask`): they run as their own `mm` process with their own configuration, and read the file of the working directory they are given only when their own `agentsMd.enabled` says so. A reviewer with no tools can turn it off; a coding helper keeps it and follows the same rules as the agent that called it.

## How it relates to the rest

- [Structured output](structured-output.md) — the other paragraph mm appends to the system prompt.
- [Asking another agent](asking-another-agent.md) — the working directory an asked agent is given.
- [How to give the agent your project's instructions](../how-to/give-project-instructions.md) and the [`agentsMd` reference](../reference/configuration.md#agentsmd-keys).

Project instructions (AGENTS.md) — explanation