I Gave My AI Agents a Single Markdown File — It Cut Recurring Mistakes to Zero

Jeremy Mandile — Mon, 11 May 2026 15:28:35 +0000

Agent "invoice-bot" generated a PDF invoice with a € sign. DejaVu Sans didn't support it — the symbol rendered as a blank square in the customer email. I fixed invoice-bot and moved on.

Two days later, "report-gen" produced a quarterly PDF with the same broken character. No connection between the two agents. Same mistake, different day.

That was the moment I realized agents don't share a brain. They share a codebase, a tool set, and a prompt — but they have no persistent lessons‑learned memory.

The Fix: A Single File Called LESSONS.md

Instead of building a vector database, a reinforcement‑learning pipeline, or a complex critique‑agent system, I did the simplest thing that could possibly work:

I gave them a LESSONS.md file.

A single Markdown file, checked into the repo, that any agent can read before acting and write to after a mistake. It has three sections:

DO NOT — hard blocks. Agents abort immediately and substitute the safe alternative.
PITFALLS — context‑dependent gotchas to watch for.
SUCCESS PATTERNS — techniques that actually worked.

Here's what the invoice‑bot entry looks like:

### DO NOT use DejaVu Sans for currency symbols

- **Why:** Missing glyph for €, £, ¥.

- **Use instead:** Noto Sans or Liberation Sans.

- **First seen:** 2025-06-10 (agent: invoice‑bot)

- **Tags:** #pdf #fonts #unicode #currency

The PR auto‑merges. Report‑gen's next PDF job hits the lesson-guard plugin, sees the #pdf tag, and automatically switches fonts. The error never appears again.

How It Works

1. Pre‑Action Guard — Before any non‑trivial task, agents read LESSONS.md. A matching DO NOT entry? Stop and substitute. No human needed.

2. Post‑Failure Write‑Back — When a mistake happens, the agent formats a new entry and submits a PR. Auto‑merge, and every agent in the fleet learns from it within minutes.

3. Retrieval Is Just Grep — Tag matching via ripgrep. No vector DB, no embeddings, no RAG pipeline. A grep call is faster than any API round‑trip.

Why It Works (When Fancy Systems Fail)

Zero latency memory. No embedding API call, no slow vector store. LESSONS.md is sitting in the file system.
Human‑auditable. Open the file and immediately understand what agents are avoiding and why. No hidden latent space.
Agent‑actionable. Every DO NOT pairs with a concrete Use instead. Agents self‑correct without asking a human.
No prompt rot. The main system prompt stays clean. All the urgent "don't do X because Y broke last Tuesday" lives in LESSONS.md, which ages out naturally.

The Results

After six months, my OpenClaw agent swarm went from ~12 recurring mistake classes per month to zero of those same classes repeating. New mistakes still happen — but each one only happens once.

Beyond Agents: The LESSON.md Spec

While building this, I realized the same philosophy — Markdown + YAML front matter = actionable knowledge — could solve a different problem: portability of programming lessons across platforms.

So I built LESSON.md, a universal lesson container. Write a programming tutorial once, and any LMS, IDE, or LLM can ingest it. The spec covers title, language, difficulty, topics, prerequisites, and objectives in YAML front matter, plus standard body sections.

Both specs are part of the md-knowledge-format family — open‑source, MIT‑licensed, and framework‑agnostic.

The Repo

Everything is live at github.com/jeremymandile/md-knowledge-format:

Formal specs for both formats (v1.0)
A single Python 3.6+ CLI — scaffold, validate, export (zero mandatory dependencies)
Docker wrapper for containerized use
OpenClaw plugins (npm install @jeremymandile/openclaw-lessons)
Worked examples + LMS integration guide

The best systems are often just a file. A sticky note on a monitor. A logbook entry. An after‑action review. LESSONS.md is that pattern — made machine‑readable.

What would make this more useful for your stack? I'd love feedback — especially from anyone running multi‑agent systems or building LMS tooling.