# I Built a Durable AI Knowledge Base with Markdown and Git > Source: > Published: 2026-07-25 03:32:01+00:00 *Why search alone does not create memory—and how source layers, agent rules, and deterministic checks keep a knowledge base useful over time* My AI knowledge base starts with a directory tree, not a search box: ``` 10-inbox rough, unverified capture 20-sources evidence that cannot be silently rewritten 30-knowledge synthesis that can change with new evidence 40-projects goals, constraints, and current execution state 50-research questions, competing explanations, and evidence gaps 60-writing drafts and publication records 70-investing observations, theses, and capital decisions 80-logs append-only changes, decisions, and handoffs 90-archive inactive material retained for history ``` The point of these folders is not tidiness. Each one defines a different change contract. A captured conversation may be incomplete. A source record should preserve what was actually found. A synthesis page must remain editable because better evidence may overturn it. A project decision needs a date and an owner. A log should not be rewritten simply because the outcome later became inconvenient. That distinction turned out to matter more than the choice of model, embedding database, or note-taking app. Most AI document tools follow a retrieval-augmented generation pattern: upload files, retrieve relevant chunks at query time, and ask a model to assemble an answer. This is useful. It is also easy to mistake for long-term memory. If a question requires five documents, a retrieval system may locate and combine five fragments each time the question is asked. The answer can be excellent, yet the synthesis usually disappears into chat history. A contradiction discovered today may have to be rediscovered next month. A corrected interpretation may never update the next answer. In April 2026, Andrej Karpathy described a different pattern in his [LLM Wiki proposal](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f): put a persistent, interlinked Markdown wiki between raw sources and the user. When a new source arrives, an agent does more than index it. The agent updates topic pages, adds cross-references, records contradictions, and revises the existing synthesis. Karpathy's document is a design proposal, not a benchmark proving that a wiki beats RAG at every scale. I treat the two as complementary: The maintained wiki stores conclusions, relationships, and unresolved disagreements that have already been developed. Retrieval helps an agent find the right sources and pages as the collection grows. Raw evidence remains available when a conclusion needs to be audited or rebuilt. Search is the navigation layer. It should not quietly become the truth layer. The simplest useful architecture has three layers: ``` php raw sources -> maintained knowledge -> agent schema ``` Each layer answers a different question. The source layer stores provenance: the exact URL or file, author, publication date when available, access date, and any capture limitations. It may also include a faithful excerpt or source note. Its job is not to be elegant. Its job is to make later verification possible. The knowledge layer contains concept pages, comparisons, summaries, and evolving conclusions. These pages are expected to change. If new evidence weakens an old claim, the synthesis should say so. This is where accumulated knowledge lives. It is not raw evidence, and it should never pretend to be. The schema or repository protocol tells an agent how to name files, check for duplicates, cite claims, update indexes, and validate its work. In my setup, these rules live in `AGENTS.md` and in the frontmatter schema used by each page. Without this layer, every new agent session has to guess the rules again. The result is predictable: duplicate pages, drifting names, missing links, and confident summaries with weak provenance. The three-layer model explains how documents become maintained knowledge. My repository also has to support execution: projects, research questions, writing, and investment decisions. Those objects do not age in the same way. An early draft used a generic structure: ``` raw/ wiki/ daily/ memory/ projects/ ``` It looked simple until real material arrived. Should an unverified chat transcript go into `wiki` or `memory` ? Should a research conclusion and a project decision use the same status fields? If a source later proves inaccurate, may the original record be edited? Adding more vaguely named folders would not solve those questions. Defining mutation rules did. That led to the numbered directory structure at the beginning of this article. The important move was separating *evidence that should not be silently changed* from *conclusions that must remain revisable*. Both rules are necessary. Immutable conclusions become dogma. Mutable evidence destroys the audit trail. I am not claiming that Markdown files automatically survive for decades, or that Git makes a repository truthful. I chose them for narrower reasons. The [CommonMark specification](https://spec.commonmark.org/0.31.2/) defines Markdown as a plain-text format for structured documents and emphasizes that the source remains readable. A person can inspect it without a proprietary application. So can Codex, Claude Code, Cursor, Gemini CLI, OpenCode, or a future tool that does not exist yet. [Pro Git](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) describes version control as recording changes to files over time so that earlier versions can be recovered. In practice, Git gives this knowledge base reviewable diffs, history, branches, and portable clones. Together, Markdown and Git provide four properties I care about: **Inspectability.** The content, sources, and operating rules are readable without a dedicated product. **Comparability.** When an agent changes a conclusion, a diff shows what changed. **Portability.** Changing editors, models, or retrieval systems does not require exporting the core knowledge first. **Rebuildability.** Search indexes, graph caches, and visual interfaces can be regenerated from the files. There are limits. Git is not a backup policy. Markdown does not verify claims. Private repositories still need access control and remote copies. Sensitive material still needs an explicit visibility model. The tools make governance possible; they do not perform it. “Organize my notes” is not an operating model. Before making a substantive change, an agent in my setup is expected to read the current priorities, the relevant indexes, the directory rules, and the schema. It must search for an existing page on the same subject before creating another one. A minimal page uses frontmatter like this: ``` --- schema: v1 id: note-llm-compiled-knowledge type: note title: "LLM-compiled knowledge" status: stable visibility: shareable created: 2026-07-24 updated: 2026-07-24 tags: - ai-agents - knowledge-management confidence: high --- ``` The schema is not an attempt to turn Markdown into a database. It establishes the minimum shared vocabulary required for several agents to work on the same repository without constantly renegotiating identity and lifecycle. The protocol also distinguishes different kinds of statements: **Fact:** directly supported by a source. **Inference:** a conclusion drawn from one or more facts. **Hypothesis:** a claim that still needs evidence. **Opinion:** an explicit judgment. **Decision:** a chosen action, including its context and date. One of the more dangerous model errors is not an obvious fabrication. It is a compression error: an author's opinion is summarized as a verified fact, or a tentative hypothesis loses its uncertainty label after three rewrites. Statement types make that drift easier to notice. An early draft of my source material cited Karpathy's work with a link to his general Gist page. Technically, there was a reference. Practically, it was not auditable. A reader could not tell which Gist supported the claim, when it was created, or whether I had accurately represented it. I replaced the profile-level link with the exact [LLM Wiki Gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) and created a separate source record containing its author, creation date, access date, capture method, and limitations. The mistake was small, but the lesson was not: a references section is not the same thing as evidence provenance. Search-result snippets, homepages, and model paraphrases are leads. They are not substitutes for the source itself. Natural-language instructions are good at expressing editorial judgment: Is this source credible enough for the claim? Did a summary erase a disagreement? Is a conclusion now stale? Has an inference been presented as a fact? They are an inefficient way to catch mechanical errors that ordinary code can find reliably: missing required fields duplicate IDs broken relative links files stored under the wrong content type pages omitted from an index My implementation uses a small Python tool, built only with the standard library, to perform those structural checks. The repository's verification command runs both unit tests and a health check: ``` make verify ``` This does not prove the knowledge is correct. It proves that a defined set of structural invariants holds. Semantic review and deterministic validation are complementary, not interchangeable. You do not need my full directory structure. Start with: ``` sources/ knowledge/ projects/ logs/ AGENTS.md INDEX.md ``` Then add five constraints. Treat Markdown files and local assets as the source of record. Note apps, vector databases, and graph views can be useful interfaces, but they should not be the only copy of the knowledge. Preserve the origin of a claim in `sources/` . Put revisable summaries and concept pages in `knowledge/` . Never promote an AI-generated summary into the source layer. Your `AGENTS.md` should answer: What must an agent read before editing? How are files named and deduplicated? Which records may be edited, and which are append-only? How are facts cited and inferences labeled? Which checks must pass before the task is complete? Start with `id` , `type` , `status` , `created` , `updated` , and `tags` . Add a field only when it solves an observed retrieval, review, or collaboration problem. A large ontology created on day one is usually a maintenance bill disguised as preparation. Check required fields, unique IDs, links, file locations, and index coverage with deterministic code. Reserve model judgment for source quality, contradictions, uncertainty, and synthesis. Not on the first day. At a modest scale, an index file plus full-text search may be enough. Add BM25, embeddings, reranking, or a graph database when you can name the recurring failure: known information is repeatedly hard to find the index is too large to navigate vocabulary mismatch defeats keyword search near-duplicate pages keep appearing relationship queries have become central to the work This is an engineering threshold, not a universal rule. Retrieval infrastructure can become necessary as the corpus, query patterns, and number of collaborators grow. It should remain a rebuildable acceleration layer wherever possible. It is a knowledge system that preserves source provenance, maintains revisable synthesis, records changes, and gives humans and agents explicit rules for updating the collection. Its value comes from accumulated, auditable work—not merely from answering the current query. No. A maintained wiki stores conclusions and relationships that should persist between questions. RAG or other retrieval methods help find relevant material at query time. Many systems benefit from both. Git makes file changes reviewable and recoverable. It can show when an agent changed a claim, compare competing edits, and preserve repository history across clones. It does not replace backups, access controls, or fact-checking. They can collaborate more reliably when the repository defines naming, evidence, mutation, indexing, and validation rules. Concurrency still requires ordinary Git discipline and human review for consequential changes. Automate structural invariants: required metadata, unique IDs, valid links, correct locations, and index coverage. Do not treat a passing linter as proof that a conclusion is true. My current implementation shows that clear layers, a repository protocol, and standard-library checks can let multiple AI coding agents work on the same Markdown assets while leaving reviewable file history. It has not proved that the structure will remain sufficient across thousands of pages, years of use, or heavy multi-user concurrency. Vector retrieval may become necessary. The directory tree may need to be split. The schema may grow heavier. Those changes should be triggered by observed failures. The useful measure of an AI knowledge base is not how many pages it generated on day one. It is whether the system can preserve evidence, correct a conclusion, and let the next conversation continue from work that can still be inspected. [Andrej Karpathy, “LLM Wiki”](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f), created April 4, 2026; accessed July 25, 2026. [CommonMark Spec 0.31.2](https://spec.commonmark.org/0.31.2/), January 28, 2024; accessed July 25, 2026. [Pro Git, “About Version Control”](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control), accessed July 25, 2026.