Your Agent’s Markdown File Is Becoming a Database With No Query Language
Markdown is your agent’s config layer. It is not its memory layer.
I have a CLAUDE.md that started as a clean page of house rules. It is not clean anymore. A third of it now reads like a dispatch table. “Read this other file, but only when the task touches X.” “If two rules disagree, the later one wins.” A note near the bottom reminds me that a rule three paragraphs up was superseded last week and I should trust the new one.
That is not configuration anymore. That is a router I am maintaining by hand, in prose, with no tests.
The emerging habit treats the markdown file as the new control layer for agents. CLAUDE.md, AGENTS.md, SKILL.md, one file per concern, version-controlled, written once instead of repeated in every prompt. For stable rules that is correct, and I am not here to argue against it. House style, naming conventions, the three commands you always run before a commit. Put them in a file, stop retyping them. Good.
The part that gets skipped is what happens after the fourth file. Markdown is a fine substrate for rules that hold still. It has no answer for three things that show up the moment your setup grows, and all three are load-bearing.
Loading
A markdown file on its own has no retrieval. So you get one of two failure modes, and you get to pick.
Either everything loads every turn, and the one rule that actually governs this task sits diluted among forty that do not. The model reads all of it and weights none of it. Or you start hand-gating what loads, “read the deploy rules only when deploying,” and now you are writing routing logic in English and hoping the agent honors it. That is the part of my CLAUDE.md that embarrasses me. It is a lookup table pretending to be documentation.
“Separate concerns into more files” is sold as the fix. It is the thing that creates the problem. More files means more to load, or more gates to maintain. The advice scales the wrong direction.
Precedence
Put a rule in CLAUDE.md and a quietly conflicting one in AGENTS.md and nothing resolves the conflict. Say your personal CLAUDE.md permits a quick hotfix straight to main when production is down, and the repo’s AGENTS.md forbids any direct push to main, ever. Both are real rules. Both are reasonable. Nothing decides which one governs the 2 a.m. incident.
Markdown has no notion of precedence. The agent picks one. It does not tell you which, and it does not tell you there was a choice.
You find out later, when it does the thing you were sure you had ruled out. Then you go diffing two files trying to reconstruct which instruction won and why, which is a debugging session with no stack trace. The information you need, “these two rules collide, here is the winner, here is the reason,” does not exist anywhere. It was never written down, because a file has no place to write it. An index would record exactly that: which rule won, where each one came from, when, and on what grounds.
Staleness
A file is a snapshot. It cannot tell you it went stale. It cannot tell you that you decided the opposite on Tuesday, or that the API it references shipped a breaking change, or that the rule was a workaround for a bug you already fixed. The deploy note that says “always run the migration by hand” sits in the file for months after you automated it, and the agent dutifully keeps running it by hand.
Files remember. They do not know when they are wrong. So the rot is invisible. The instruction reads as authoritative long after it stopped being true, and authority is the one thing a stale file never loses.
The line that actually matters
None of this kills the idea. It sharpens it. Markdown is the config layer. It is not the memory layer, and most agent setups break because they are asked to be both.
The split is clean once you see it. Stable, low-churn, human-authored rules belong in files. They change rarely, a person edits them on purpose, and there are few enough that loading all of them is fine. That is config, and files are good at config.
Everything else is memory, and memory has properties files do not. It needs retrieval, so the relevant rule loads and the other forty stay out of the context. It needs conflict resolution with provenance, so when two facts collide you get the winner and the reason, not a silent coin flip. It needs a sense of time, so a decision carries a date, a supersession can point at what it replaced, and staleness is detectable instead of just suffered.
You can feel where the boundary sits by asking one question of any line in your CLAUDE.md: would I rather query this than read it? The day you start wishing you could ask “what is the current rule about deploys, and when did it last change,” you have left config and walked into memory. No amount of additional files takes you back.
What this means in practice
I am not telling you to throw out CLAUDE.md. I keep mine. I am telling you to stop letting it grow into a database with no query language. When a file starts containing routing logic, conflict-resolution rules, or supersession notes, those three things are signals that the content underneath wants to be indexed, not appended.
I built a small index over my own files for exactly this reason, after the dispatch-table embarrassment got bad enough to fix. Not a full memory system, not a vector database for everything. Just enough structure to answer the three questions the files could not: what applies here, what wins when two rules collide, and what changed since I last looked. Each rule carries where it lives, when it was last confirmed, and what it supersedes. The files stay simple. The hard part moves up a layer.
The rule of thumb I use now: config is stable and loaded whole; memory is retrieved, dated, and aware of where it came from. The first belongs in markdown. The second outgrew it the day you wrote your first “read this other file only when.” Config is loaded. Memory is queried.
The next time your CLAUDE.md crosses that line, notice what just happened. You did not need a better file. You needed an index over the files, not a fifth file.