"Knowledge base" gets used loosely. Sometimes it means a single onboarding document. Sometimes it means a product's entire internal wiki. The version this article is about sits in between: a folder — or a whole tree of folders — of Markdown notes that someone actively maintains, that grows week by week, and that outlives any single project or conversation.
That's a different problem from the one solved by a one-off context file, and it's worth being precise about the difference before going further.
A knowledge base is not a context file
A context file — the kind covered in Markdown as RAG — is written once, for one purpose: giving an AI agent the background it needs for a session. It's a single document. You write it, you inject it, you occasionally correct it. Its job is done the moment the session that needed it is over.
A knowledge base is the opposite shape. It's not one document but many — meeting notes, decisions, how-to guides, reference material, project histories — added to continuously, by one person or a whole team, over a timescale measured in months and years rather than sessions. Nobody reads all of it at once. The core challenge isn't "how do I get this into the context window" — it's "how do I find the three notes that matter, out of the three hundred that exist."
A context file answers one question well. A knowledge base has to answer questions nobody asked yet, from someone who wasn't there when the notes were written.
Markdown is still the right building material for this — the reasons it beats Word or PDF for a single context file (plain text, no format bloat, easy to diff and version) apply just as much here. What changes is everything around the files: naming, structure, metadata, and linking all start to matter, because the collection has to remain navigable as it grows.
Why markdown holds up over years, not just one session
Three properties matter specifically because a knowledge base is long-lived, not because it's read by an AI at all:
Software you use to browse or edit your notes today may not exist in five years. Plain text does not depend on any of it. A folder of .md files opens in whatever comes next — a text editor, a new note-taking app, an AI tool that doesn't exist yet — with nothing lost in translation.
Put the folder under Git and every change to every note has a history: who changed what, and when. A decision that got revised six months later is still visible in the log. Try that with a wiki page's edit history exported from some SaaS tool, or a stack of Word documents named "final," "final_v2," "final_v2_reviewed."
Headings, lists, tables, and links are enough to represent almost anything worth writing down, and they cost nothing to type. There's no dialog box between having a thought and capturing it — which is exactly the friction that determines whether a knowledge base actually gets maintained, or quietly stops growing after the first month.
Structure that scales — folders, frontmatter, and links
A single context file needs no organizing principle beyond "write it clearly." A hundred notes need three things a single file doesn't: a place, a label, and a way to point at each other.
A place — folders with a consistent shape
The exact taxonomy matters less than having one at all, and sticking to it. A common, low-friction split is by kind rather than by project: /decisions/, /reference/, /people/, /areas/ — so a new note has an obvious home, and an old one has a predictable address.
A label — frontmatter as metadata
YAML frontmatter at the top of a file turns a plain note into a queryable record, without leaving Markdown:
--- title: Switch to usage-based pricing for the API tier status: decided date: 2026-09-01 tags: [pricing, api, decision] related: [2026-06-14-tier-structure, 2026-08-20-competitor-review] --- ## Decision ...
None of this is exotic — it's the same pattern markdownizer and markdownword already lean on for document metadata. The payoff is that "show me every open decision tagged pricing from the last quarter" becomes a grep or a simple script, not an afternoon of manual searching.
A way to point at each other — links between notes
A note that references another note should link to it — a plain relative Markdown link ([tier structure](2026-06-14-tier-structure.md)) works everywhere, including on GitHub and in any tool that renders Markdown natively. The value compounds: after a year, the links themselves become a map of how ideas in the knowledge base actually connect, which is often more useful than the folder structure it sits in.
How AI tools actually use a knowledge base like this
There are two realistic ways an AI tool interacts with a knowledge base of this size, and which one applies depends on scale:
If the collection is a few dozen to a few hundred notes, an agent with file access can simply search and read — grep for a term, follow the frontmatter tags, open the linked notes. This is the same access pattern described in Markdown as RAG, just pointed at a folder that keeps growing instead of one static file. No extra infrastructure required.
Once a knowledge base runs into the thousands of notes, or many people are querying it concurrently, a proper retrieval pipeline — embeddings, a vector store, ranked search — starts to earn its complexity. The good news is that well-structured Markdown is also the best possible input to that pipeline: clean chunks, meaningful headings, and frontmatter metadata all make retrieval more accurate. Structure your knowledge base well early, and it stays useful whichever approach you eventually need.
Prior art: Obsidian and friends
This pattern isn't new — it's the whole premise behind personal knowledge management tools like Obsidian, which is built entirely on a folder of linked Markdown files (wikilinks, backlinks, tags, and all). If you already keep a vault there, you already have most of what's described above — the frontmatter, the links, the plain-text files on disk that any AI tool can read directly. Obsidian's specific syntax additions — wikilinks, callouts, tags — get their own look in Obsidian and Markdown, but the underlying idea is exactly this one: Markdown notes, linked together, growing over time.
Getting existing material in — and out
Most knowledge bases don't start from a blank folder — they start from years of Word documents, PDFs, and scattered notes that predate the decision to organize anything. Converting that material into clean Markdown is the actual first step, and doing it by hand for a few hundred documents isn't realistic. markdownizer batch-converts Word, PDF, Excel, and PowerPoint files into Markdown, which is what turns "we have a shared drive full of documents" into "we have a knowledge base."
The reverse trip matters too — a decision or reference note frequently needs to leave the knowledge base as a polished document for someone who isn't going to read raw Markdown. markdownword converts the other way, turning a Markdown note into a formatted Word document without you leaving the format your knowledge base already lives in.
The pattern
One file solves a session. A folder, kept tidy, solves years.
Pick a small set of folders and stick to them. Add frontmatter — even just title, date, and tags — to every note from day one, because retrofitting metadata onto hundreds of files later is exactly the kind of chore that never happens. Link notes to each other as you write, not as a cleanup pass afterward.
Do that, and the collection stays useful to the same degree whether it's a person reading it at 2am, a colleague six months from now, or an AI agent given access to the folder. That's the actual test of a knowledge base: not whether it looks organized today, but whether it's still worth searching in three years.
For the narrower question — how to hand an AI agent exactly the context it needs for one task, right now — see Markdown as RAG. The two patterns aren't competing; a good context file is often just a well-chosen excerpt from a knowledge base like this one.
Further reading: Obsidian and Markdown — the syntax it adds, and what stays portable · Markdown as RAG — your own lightweight context layer · Spec-driven development — this is where Markdown really shines · Plain text, formatted — what AI-ready really means