How to Pin Your Conventions File Into Every Aider Session (2026 Guide)

Aider's conventions documentation describes the mechanism plainly. You write a small markdown file, and then:

"It's best to load the conventions file with /read CONVENTIONS.md or aider --read CONVENTIONS.md. This way it is marked as read-only, and cached if prompt caching is enabled."

Two properties are packed into that sentence, and both are deliberate. Marking the file read-only means the agent will not try to edit it — a conventions file is an input, not a work product. Caching it means the tokens are not re-paid on every turn when prompt caching is available.

The catch is the verb. You load it. Aider's documented mechanism for conventions is a file you read in explicitly, not a filename it looks for. There is no CONVENTIONS.md discovery step that fires because the file happens to exist.

That is worth stating precisely, because it is easy to over-read — and it is a different failure from the one where a tool does discover your file and then ignores it. Why agents ignore your instruction files covers that case; this one is simpler, because nothing was loaded to ignore.

Aider is not indifferent to your codebase. It automatically builds and sends a repository map with every request:

"Aider uses a concise map of your whole git repository that includes the most important classes and functions along with their types and call signatures."

"Aider sends a repo map to the LLM along with each change request from the user."

So the model arrives with a real picture of your code's structure. What it does not arrive with is your conventions — and the reason is structural rather than an oversight. The repo map is derived from the code. It can show that a module exists and what its call signatures are. It cannot show that you rejected an alternative library eight months ago, because the rejected library is not in the repository to be mapped. That distinction is the whole reason a conventions file exists.

The documentation includes a side-by-side example that makes the effect concrete: with the conventions file read in, the generated function used the preferred HTTP client and included type hints. Without it, the same request produced code using the other library and no types — described in the docs as "perhaps more typical in small python scripts." Same model, same prompt, different result, entirely because of one file.

Typing /read CONVENTIONS.md at the start of every session. This works and it is the right first move. It is also a habit, and habits fail on the days you are in a hurry — which are exactly the days a convention gets violated and merged.

Pasting the conventions into the prompt. It works for one turn. It is not read-only, so the file can be edited by the agent; it is not cached, so you pay for it repeatedly; and it will be a different paste next week.

Adding the conventions file with /add instead of /read. Subtly worse than it looks. /add puts a file in the chat as an editable file. The documentation's advice is specific about the read-only path, and there is a related tip worth internalizing: don't /drop read-only files added at launch. A conventions file that the agent can edit is a conventions file that will eventually get edited.

Writing the conventions into a comment block at the top of the main source file. Now the rule lives inside the code it governs, it only travels with that one file, and the repo map will happily include the comment while your other twelve modules never see it.

Putting everything in the conventions file. The opposite failure, and the more common one after a few months. A conventions file that has grown to hold every architectural decision, every incident postmortem, and every rejected option is loaded in full on every session. It is read-only and cached, so the cost is manageable — but you are now spending a large, fixed block of context on material that applies to a small fraction of your requests.

Three steps. The first one is the two-line change; the other two are what stop you needing to do this again.

Step 1: Put read in the project's config file

Aider documents a way to make this automatic:

"You can also configure aider to always load your conventions file in the .aider.conf.yml config file"

The field is read, and it takes either a single filename or a list of them. One entry for a single conventions file; a list when you have a conventions file plus, say, a schema reference you always want available.

Where you put the config file matters, because Aider searches three locations:

"Aider will look for a this file in these locations: Your home directory. The root of your git repo. The current directory. If the files above exist, they will be loaded in that order. Files loaded last will take priority."

Put the read entry in the config at the root of your git repo, not in your home directory. Two reasons. First, it is the only location that travels with the project, so teammates and CI get the same behavior without anyone configuring anything. Second, a read entry in your home directory config points at a filename that may not exist in every repository you open — a global setting referring to a project-local file is a trap waiting for the next repository you clone.

Because files loaded last take priority, a repo-root config also cleanly overrides whatever you have set globally, which is usually what you want.

Step 2: Decide what belongs in the file, and move the rest out

Now that the file loads unconditionally on every session, its size is a permanent cost. That changes what should be in it.

Keep the things that are true on every request and short enough to state as a rule: the libraries to prefer, the type-hint expectation, the naming convention, the test command. These are commands, and a conventions file is a good container for commands.

Move out anything that is history. The paragraph explaining the incident that led to the library choice is valuable — it is the reason the rule survives review — but it does not need to be in the prompt on every turn. The same goes for the long explanation of the data model, the release checklist, and the notes on why three modules are structured oddly.

The test is simple: if a sentence answers "what should I do," it belongs in the conventions file. If it answers "why," it belongs somewhere the agent can look it up when asked. What coding agents actually read is a useful cross-check here, because the same split applies to every tool with an always-loaded instruction file.

Aider's own advice for the file, from the community conventions the docs point to, is in the same spirit — short, specific statements about preferences.

Step 3: Give the "why" a home the agent can query

This is the step that stops the conventions file from re-growing. A rule with no recorded reason is a rule nobody will delete and nobody will defend, so the file only ever gets longer.

The reasoning needs to be retrievable rather than always-loaded, and it needs to survive the next tool. Aider is a terminal-native tool with a distinctive mechanism, and plenty of teams run it alongside an IDE assistant. If the reasoning lives in a CONVENTIONS.md that only Aider reads in, the other half of your toolchain never sees it — and neither will you, next year, when you are using something else. Turning project docs into AI memory covers how to get existing written material into that shape without rewriting it from scratch.

MemoryLake holds the reasoning behind your conventions outside any single tool and serves it to whichever agent asks, over MCP or the API. Your CONVENTIONS.md stays exactly where it is, and Aider goes on loading it the way its own documentation describes; the shared layer holds only what would otherwise bloat that file.

Step 1: Create an API key

Generate a key and make your first request in about thirty seconds. Do this before Step 2 above, so you have somewhere to put each reason as you trim the file.

Step 2: Upload your first memories

Work through the conventions file line by line. For each rule, write down why it exists — the alternative you rejected, the incident behind it, the constraint that forced it. Those paragraphs come out of the conventions file and go here. Supporting documents and files go in the same place.

Step 3: Connect your AI & agents

Give Claude, Codex, OpenClaw, and your other agents access over MCP or the API. When someone asks why the convention is what it is, the answer arrives with its reason attached rather than as a restatement of the rule.

The first change is that the Monday-morning failure stops. The conventions file is loaded before your first message, every session, on every machine that has the repository, without anyone remembering anything.

The second is that read-only and cached become defaults rather than something you have to type correctly. Both properties come from the documented read path, and both matter more once the file loads every time.

The third change is that the conventions file can get smaller instead of larger. Every rule whose rationale moved into a queryable store is a rule that can be stated in one line. A short always-loaded file plus a queryable reason store is strictly better than a long always-loaded file, and it is the same total information.

The fourth shows up when someone on the team is not using Aider. The rules stay in the repository where Aider reads them. The reasoning is in a place every agent can reach. Neither half is trapped in one tool's format.

Use read, not add. Read-only is the correct posture for an input file, and it is what the documentation recommends. It also means the agent will not quietly rewrite your rules.

Put the config at the git root. It travels with the project and it takes priority over your home-directory config, since files loaded last win.

Use a list when you have more than one always-on input. The read field accepts a list, so a conventions file plus a schema reference is one entry each rather than a merged mega-file.

Do not /drop read-only files added at launch. Aider's tips call this out directly, and it is an easy accident during a long session when you are clearing the chat of files.

Keep commands in the file and reasons out of it. The file is loaded on every request. Anything that answers "why" is being paid for on turns where nobody asked.

Do not expect the repo map to carry your conventions. It is built from your code and sent with every request, which is genuinely useful — and it can only reflect what the repository contains. A rejected library leaves no trace to map.

Check the conventions file into git. Obvious, and still worth saying: a conventions file that lives only on one laptop is a personal preference wearing a team's clothes.

Expect to do this again in every other tool you use. The mechanism differs — making an agent stick to your coding style covers a different tool's version of the same job, and memory solutions for autonomous coding agents covers the layer underneath all of them.

Aider's conventions mechanism is an explicitly loaded read-only file rather than a filename discovered by convention, and that single difference is why the file that works in testing stops working in daily use. The fix is documented and small: a read entry in .aider.conf.yml at the root of your git repo, which makes the file load on every session, read-only and cached, for everyone who has the repository.

The part that takes judgment is what goes in it. Because the file is now loaded unconditionally, every line is a permanent cost — which is the right pressure to keep it to standing commands and move the reasoning somewhere an agent can query on demand. Aider's repo map will keep telling the model what your code contains. Only you can tell it what your code deliberately does not.