A brain is a markdown architecture. Dylan Engelbrecht has built and refined one so agents can hold a lot of context, and still pick only the information that is relevant to the task.
It acts like a map. The agent does not memorize the whole library. It gets its bearings, then opens one path.
That idea has a name: progressive disclosure (Nielsen Norman Group). It is similar to how humans think. You start at the beginning with a map. You get your bearings. You do not read every street name in the city first.
Chat is not that map. Chat is the current conversation. AGENTS.md is also not that map. It tells the agent how to work in the repo — build, test, do not break the house. The brain is memory of the world the agent is acting in: people, services, decisions, vocabulary, what happened last week.
Folder names are not the protocol. The protocol is the shape: an index, a one-line description next to each entry, and knowledge that stays in one place.
A walkthrough (simplified)
A really simplified example, but bear with me.
The task is: “What is my favorite food?”
The agent does not load every file. It starts at the index. The index lists first-class paths. Each line is short enough that the agent can decide “open this” or “skip this.”
Take the tree below with a grain of salt. Adapt the names to your world. What matters is the index, the one-line descriptions, and that the knowledge is cohesive.
A grain-of-salt tree — adapt the names
AGENTS.md — mentions that the user's name is x
INDEX.md — the map
Wiki/
People/
x.md — a page about the user
y.mdThe agent already saw in AGENTS.md that the user’s name is x. It looks at the index. It sees Wiki/People/. It sees a file named x. That might be relevant, so it opens that file. It does not open y.md. It does not dump the whole wiki.
Inside x.md it might find a note: favorite food is a lime. The note is marked unverified. Maybe an earlier agent inferred it. It is not confirmed.
So the agent should not say “Your favorite food is lime.” It should say something like: “I think your favorite food is a lime, but that’s not confirmed. Am I correct?”
That is the protocol in miniature. Map first. One match. One file. Unconfirmed facts get a question, not a guess.
What the index has to do
If the agent has to open the file to find out whether the file was relevant, the index failed.
A good index line is a routing hint: topic, path, when to open. Nested indexes (people, services, incidents) are more map, not more boot files. One fact lives in one place. If you need it somewhere else, point at it. Do not copy it. Copies drift.
The same rule applies to instructions. The closest AGENTS.md to the files being edited wins. Defaults at the root. Exceptions next to the subtree. See The AGENTS.md standard for AI coding agents.
After the toy example: three lifespans
Once you have seen a lookup, the layers are easier.
Some notes are for this week. This incident. This launch. Archive or delete them when they go stale.
Some pages stay true across weeks: people, services, vocabulary, architecture decisions. Version those.
Some records already happened and must not be rewritten in place: incident write-ups, shipped milestones, audit notes. Link out for entity facts. Do not duplicate them.
Facts can move when they stabilize. A guess that gets confirmed becomes a verified line on the person page. A chat instruction that appears twice becomes a playbook line. A name that keeps recurring becomes a wiki entity. Do not invent extra folders until agents keep asking the same question, or keep making the same mistake.
Write down how you know
Markdown is easy for humans to read. Agents also need a stop sign.
On each fact or file, say:
status — verified, needs-verification, or deprecated.
source — a URL, a person, a ticket, a document.
last-verified — a date.
Treat needs-verification the way the lime example did. Ask or cite. Do not invent. Unknown stays unknown.
That is provenance. It answers: is this true, according to whom, as of when?
Access control is a different job. It asks who may see the file. Some brains need labels such as internal, restricted, or secret. Do not fold that into the verification fields.
Rules live next to the layer they govern
Pair each layer with its own AGENTS.md. The root file sets global boundaries and the read order. The wiki file explains when to write a person or a service page. The hot-context file says when to archive. Agents discover rules in the closest directory. Same precedence model as a code repo.
Same walkthrough, work context
Imagine a team shipping a billing API. The task is: “What is the billing failover?”
The agent starts at the index, not at the public homepage. The index says: for billing failover, open wiki/runbooks/billing-failover.md. It opens that runbook. It does not load every service page.
A sketch of that map:
INDEX.md — a map, not a dump
# INDEX.md — Agent brain
## Read order
1. working-memory/current.md
2. wiki/INDEX.md
3. governance.md
## Layers
| Layer | Path | Lifespan |
| Hot context | working-memory/ | This week |
| Wiki | wiki/ | Stays true |
| Incidents | incidents/ | Already happened |
## Open when
| Signal | Path |
| On-call or Sev | working-memory/current.md, then incidents/ |
| What is service X? | wiki/services/INDEX.md |
| Billing failover | wiki/runbooks/billing-failover.md |Hot context might look like this — notice the source and the date:
working-memory/current.md — this week, with provenance
---
title: Current focus
status: verified
last-verified: 2026-08-29
source: #inc-1842 retro notes
---
## This week
- Billing retry storm after the card-network timeout change.
- Cut over invoice PDF rendering to the new worker.
## Open threads
- Confirm whether legacy accounts still hit /v1/invoices:finalize.And the wiki folder can carry its own rules, discovered only when the agent is in that folder:
wiki/AGENTS.md — rules at the closest directory
# AGENTS.md — Wiki
## Purpose
Durable entities: services, customers, concepts, runbooks.
## When to write here
- Stable facts with a source (ticket, spec, or named owner).
- One file per service or concept.
## Never
- Duplicate SLOs or owner names that live on the service page — link.
- Treat chat summaries as canonical.This is still a sketch. A research lab might keep papers/ and experiments/. An ops team might skip incidents/ until the second repeat. The folder names are not the protocol.
Start small
One index. One hot-context file. One entity template. One page that says “if you do not know, ask.”
Add a layer when repetition proves the gap. A brain is not a wiki dump. It is a map, plus files you open on purpose, plus a habit of not inventing the lime.
Summary
Do not dump the corpus. Start with a map and get your bearings. Follow one index line. Open one file. Give every store a lifespan. Give every claim a source. One canonical location. Rules next to the layer they govern. If it is not confirmed, ask.
Dylan Engelbrecht updates this knowledge hub as agent practice evolves. Treat these articles as living reference — current practice, not a frozen snapshot.