LLM-Maintained Markdown Knowledge Bases

Overview

An LLM-maintained Markdown knowledge base is a file-first memory architecture where an agent incrementally turns raw source material into a structured, interlinked wiki. Instead of treating knowledge as opaque embeddings in a vector database, the system stores durable Markdown pages that humans and agents can both read, review, diff, edit, and version-control.

The pattern is useful for personal research libraries, coding-agent workspaces, departmental knowledge bases, and long-running analysis projects where the corpus is large enough to exceed a chat context but small enough that curated structure matters more than web-scale retrieval. The agent acts less like a search engine and more like a librarian: ingest sources, write synthesis pages, create backlinks, lint for contradictions, and keep indexes current.

This does not make vector search obsolete. Dense retrieval remains the right tool for massive, frequently changing corpora and low-latency recall. The Markdown-wiki pattern is strongest when auditability, compounding synthesis, source traceability, and human ownership matter more than indexing millions of documents.

Core Concepts

Raw Sources as Immutable Input

The system begins with a raw input area containing clipped articles, papers, repository writeups, datasets, images, transcripts, or manual records. These files are treated as evidence, not as the polished knowledge base. Keeping raw material separate prevents synthesized pages from becoming the only source of truth.

Compiled Wiki as Maintained Output

The agent reads raw inputs and writes organized pages: concept explainers, source summaries, entity pages, project records, indexes, and relationship maps. The output is plain Markdown so it can be inspected in any editor, rendered by static-site tooling, or committed to Git.

Linting and Health Checks

A maintenance pass scans for broken links, orphan pages, stale statements, missing citations, duplicate concepts, and contradictions. This is the step that turns a one-time summary dump into a living memory system.

How It Works

Organize the File Tree

A practical layout separates raw evidence, generated wiki pages, schemas, and maintenance logs. The schema file gives the agent stable rules for naming, citation, page ownership, and when to update versus create.

knowledge-base/
  AGENTS.md              # Rules for agent edits and quality gates
  raw/
    papers/
    clippings/
    repos/
    images/
  wiki/
    index.md
    concepts/
    sources/
    projects/
    entities/
  logs/
    ingest-log.md
    lint-log.md

Run an Ingest Pass

An ingest pass reads one or more raw files, extracts durable facts, writes source summaries, updates concept pages, and adds backlinks. The agent should preserve citations to raw files or source URLs so claims can be traced and corrected later.

def ingest(source_path, wiki):
    source = read_raw_source(source_path)
    summary = llm_extract_source_summary(source)
    concepts = llm_extract_concepts(source)

    wiki.write(f"wiki/sources/{slug(source_path)}.md", summary)

    for concept in concepts:
        page = wiki.read_or_new(f"wiki/concepts/{concept.slug}.md")
        updated = llm_merge_concept_page(page, concept, citation=source_path)
        wiki.write(page.path, updated)

    wiki.update_index()
    wiki.append_log("logs/ingest-log.md", source_path)

Query by Navigation

At query time, the agent reads indexes, follows links, opens concept pages, and pulls raw evidence only when needed. The retrieval trace is visible: which files were opened, which links were followed, and which raw sources support the answer.

Practical Applications

Long-Running Research Projects

A research agent can ingest papers and web articles into source pages, maintain concept summaries, and keep a project index updated. The next session starts with the already-compiled map rather than re-reading dozens of PDFs from scratch.

Coding-Agent Project Memory

For software projects, the wiki can hold architecture decisions, module maps, integration records, debugging history, and runbook fragments. Agents can update these files after major implementation steps so future sessions avoid repeated repository rediscovery.

Team Knowledge Bases

Small teams can use the pattern to convert scattered documents into an auditable internal wiki. Human review remains important: agents can propose updates, but owners should approve pages that affect policy, customer commitments, security, or operational practice.

Implementation Patterns

Use Git as the Audit Layer

Commit every ingest and lint pass. Git diffs make agent edits inspectable, rollbackable, and attributable. Branches are useful when a large ingest touches many pages or when source quality is uncertain.

git checkout -b kb/ingest-openxla-pjrt
python tools/ingest.py raw/clippings/pjrt.md
python tools/lint_wiki.py --changed
git diff -- wiki/
git commit -am "Ingest PJRT source records into ML infrastructure wiki"

Separate Generated and Human-Owned Zones

Mark which directories the agent may edit freely and which require approval. A common split is raw evidence as append-only, generated source summaries as agent-owned, and policy or decision pages as human-reviewed.

Make Linting Concrete

Lint passes should produce actionable findings rather than vague quality comments. Examples include missing citation, broken local link, duplicate heading, stale date, contradiction with source page, orphan concept, and uncited claim.

Performance Considerations

• Corpus size: The pattern works best for hundreds to low-thousands of high-signal documents. At web scale, use search or vector retrieval as a first-stage candidate selector.
• Token budget: Compilation spends tokens upfront so future sessions spend fewer tokens rebuilding context. Track ingest cost separately from query cost.
• Latency: Querying a Markdown wiki may involve multiple file reads and reasoning steps. Cache indexes and summaries for frequently used sections.
• Source freshness: If raw sources change often, schedule incremental re-ingest and mark pages with last-source-check metadata.
• Review bandwidth: The knowledge base can grow faster than humans can review. Use confidence levels, ownership metadata, and approval queues for sensitive pages.

Common Pitfalls

• Letting summaries become ground truth: Generated wiki pages are derived artifacts. Important claims should point back to raw sources or citations.
• No contamination boundary: If the agent repeatedly ingests its own generated pages as raw evidence, errors can compound. Keep raw inputs and compiled outputs separate.
• Writing pages without schemas: Without naming, citation, and ownership rules, the wiki becomes a pile of inconsistent records that is hard for future agents to navigate.
• Skipping lint passes: Initial synthesis is easy; maintenance is the hard part. Broken links, contradictions, and duplicate concepts accumulate unless checked deliberately.
• Using it where RAG is better: For millions of small, access-controlled, frequently changing records, a retrieval system with metadata filtering and embeddings is usually more appropriate.