Markdown as Memory: A First Experiment

The convention file I had been maintaining started as a two-page document. By month four it had grown into something more ambitious — and the growth was telling me something about what I actually needed from an AI-assisted workflow.

The markdown-as-memory pattern wasn't a design decision I made deliberately. It emerged from necessity. And studying why it worked — and where it started to strain — pointed directly at the architecture question I would spend the next year trying to answer.

How the Pattern Evolved

The starting point was simple: a file called CONTEXT.md in the project root. It described naming conventions, config shapes, and agreed-upon patterns. Keep it open in the editor, and Copilot's suggestions drift toward your conventions instead of generic ones.

That worked. But once I had that file, I kept adding to it. First the naming conventions, then the domain vocabulary, then the non-obvious business rules, then the known gotchas, then decisions that had been made and the reasoning behind them. Each addition made the AI tools more useful. Each addition also made the file larger and harder to maintain.

Within two months, CONTEXT.md had sections: Project Overview, Domain Model, Data Sources, Agreed Patterns, Known Issues, Decision Log. It was starting to look less like a context file and more like a living specification document.

What It Enabled

The practical effect was significant. When I opened ChatGPT to reason through a domain-specific problem, I could paste the relevant section of CONTEXT.md and get a response that engaged with my actual project instead of the generic version of my problem. The quality of the reasoning improved immediately.

For Copilot, having domain vocabulary and data model notes visible in the editor produced suggestions that used the right names — FiscalPeriod instead of Quarter, AccountStatus instead of a bare integer. Small thing. Adds up across a long day.

More interesting was what happened to my own thinking. The act of writing domain knowledge into a structured document forced clarification I hadn't done consciously. When I went to write "the orders.amount field contains..." I had to decide: pre-tax or post-tax? At what version did that change? I would go check, find out the field actually had three different behaviors depending on order date, and document all three. The context file was becoming a decision forcing function.

What It Cost

Maintenance. That's the entire cost, and it compounds.

Every new gotcha needs to be added. Every superseded decision needs to be updated so the old one doesn't contradict the new one. Every source system change that invalidates a documented assumption needs a corresponding update. If you don't do the maintenance, the context file drifts from reality — and a context file that's partially wrong is worse than no context file, because now your AI tools are confidently applying stale facts.

By month four I was spending fifteen to twenty minutes per week just maintaining CONTEXT.md. That's not a lot. But it was time I hadn't budgeted, and it scaled with project complexity. On a larger project with more moving parts, that estimate would multiply.

There was also the structural problem. Markdown is flat. It doesn't have a schema. When I wanted to find everything documented about a specific data source, I searched by keyword and hoped the relevant entries were in the same section. When I wanted to understand which decisions had been made in the last month, I scrolled. The document was organized for human reading, not for retrieval.

The Retrieval Problem

This is where the pattern started to show its ceiling. A flat markdown file is essentially a key-value store where both the keys and the values are prose. Retrieval is keyword search or manual scanning. For a small file, that's fine. For a large one, it's friction.

What I wanted — what became increasingly clear I wanted — was a way to surface the relevant context for a given task automatically, without having to decide which section of the document to paste. If I was working on the orders pipeline, the relevant context included the amount field behavior, the fiscal calendar definition, the agreed transformation sequence, and the known issue with the v1 API rate limiter. I wanted those facts to appear without me manually assembling them.

That's a retrieval problem. And retrieval on unstructured text, at scale, with semantic matching rather than keyword matching, is not a problem you solve with a markdown file.

I knew what I needed. I didn't yet know how to build it. That question would occupy a significant amount of the next year's engineering work.

If you've built something similar — a structured context system for AI-assisted development — I'd like to hear what you chose and why. The approaches I've seen vary widely, and the tradeoffs are not obvious. As always, I'm here to help.