This one didn't start in my head. The idea came from a thread I read on X. It stuck, because of what happened when I pointed an AI agent at a big internal wiki and asked it to find things. The agent could read every page perfectly. It could not find the right pages. I ended up walking it through the space by hand, which is not what anyone means by automation.
The easy diagnosis is "search is bad." I don't think that's it. The agent could open anything. It just had no idea what existed. That's a discoverability problem, not a search problem. A city where every street sign is readable but no map exists is still a city you get lost in. And yes, wikis have sidebars, which are technically indexes. A tree of bare titles is a hallway of unlabeled doors.
The hypothesis, and this is the borrowed part: wikis and PDFs are built for human navigation. Click, scroll, skim, search by gut. Markdown is built for traversal. Plain text, grep-able, linkable, readable in one pass. So moving a knowledge base from wiki pages to markdown isn't a tooling preference. It changes the information architecture into something an agent can actually move around in.
I run my own notes this way. One markdown repo, an index at the top, a one-line description on every file, explicit links between related notes, and small convention files that say what goes where. Sample size of one, and the one is me, so take it accordingly. But I do move faster in that system, mostly because the agent stops needing a tour guide.
"Document everything" isn't the answer either. Noise buries things about as well as absence does. So the better question isn't markdown versus wiki. It's what makes a pile of documents navigable by an agent at all. My current list has four things on it. A map: one index that says what exists. Scent, to borrow the information-foraging term: a one-line description on everything, so relevance can be judged without opening the file. Edges: real links between related things. Boundaries: written rules about what lives where. None of the four is "markdown." The structure does the work. The format is just what it's written on.
The part I can't settle: when the agent failed in that wiki, was the content bad or was the map bad? Export the whole space to markdown, keep the structure, add no index. Does the agent suddenly do fine? The answer changes what the actual problem is, and I don't have it yet.
If you have run that experiment, I would like to know what happened. If you think the four are wrong, that works too. sachindewangan2000@gmail.com
How this page got made: The AI reviewers have opinions; I have a veto.