Built 4 Knowledge Bases and 3 Rotted - Why Flat Markdown Beats RAG
Built 4 Knowledge Bases and 3 Rotted - Why Flat Markdown Beats RAG
Over the past year we built four different knowledge base systems for our AI agents. Three of them are effectively dead. The one that survived is embarrassingly simple.
How Knowledge Bases Rot
The first attempt was a full RAG pipeline - embeddings, vector store, chunking strategy, retrieval logic. It worked well for the first two weeks. Then the source documents changed, the embeddings drifted out of sync, and the retrieval started returning stale chunks mixed with current ones. Nobody maintained it because maintaining it meant re-running the entire pipeline.
The second was a structured wiki with categories and cross-references. Beautiful architecture. Within a month, half the pages were outdated because updating one page meant checking every cross-reference.
The third was a graph-based knowledge store with relationships between concepts. Impressive demo. Impossible maintenance burden.
What Actually Works
Flat markdown files with pointers. That is it. A markdown file that says "for deployment instructions, see the README in /deploy" rather than trying to contain a copy of those instructions. The sources update themselves because the pointers reference the living documents.
When the deployment process changes, someone updates the README in /deploy. The knowledge base stays correct automatically because it never duplicated that information - it just pointed to it.
Why This Works for Agents
Agents do not need comprehensive knowledge stores. They need fast access to the right file at the right time. A flat markdown file with clear pointers is easy to parse, easy to update, and hard to break. When an agent reads CLAUDE.md and follows a pointer to another file, it gets current information every time.
The lesson is counterintuitive - less structure means more durability. Comprehensive systems rot because they are expensive to maintain. Simple pointers survive because they cost almost nothing to keep current.
- Knowledge Graph AI Agent Memory
- Agent Legacy CLAUDE.md Memory System
- Embeddings vs Tokens for Agent Memory
Fazm is an open source macOS AI agent. Open source on GitHub.