2026-09-13 · Markdown workflows

Markdown as agent memory 2026: the editing rules

On September 10, 2026, Wes Sander published a post titled Markdown Is All You Need on the Practical Systems blog with a claim that sounds like a joke and then stops being one. He had spent the week running a break-it test on a memory runtime with 382 dependencies — the kind of product that sells reliability as something you install. He fed it three versions of a single project decision across eight months: REST in January, GraphQL in April, tRPC in August, each tagged with the meeting it came from. Then he asked it what the current public API decision was.

It said GraphQL. GraphQL is the superseded one.

The reason is more interesting than the failure. All three versions came back tied at a relevance score of 1.000, because nothing in the retrieval path actually read the temporal fields the pitch was built on. The supersession columns existed in the schema. Nothing wrote to them and nothing ranked by them. Three versions of a decision became three equal facts, and an agent asking for the best answer got a coin flip weighted toward wrong. He then asked his own agent the same class of question against its memory, which is a folder of Markdown files in a Git repository. It returned the current decision, dated, with the superseded versions preserved above it as struck-through history, each line carrying where it came from. Twelve days later, the design is worth reading closely — not because Markdown is a magic format, but because of what it makes impossible.

The claim underneath the headline

The post's abstract states the argument precisely: a folder of Markdown files, one routing index, and a small set of editing rules outperforms an installed runtime on the property that matters for a long-running agent — returning the current truth with its source while preserving what used to be true. The architecture needs zero dependencies, is auditable by a human with a text editor, and, per the author, has run seven months in daily production across three frontier models from two vendors.

The conclusion he draws is the part that generalizes beyond his own setup: the hard part of agent memory was never storage or retrieval. It is editorial policy, which no memory product ships.

That is a testable assertion, and the post tests it. He is explicit that the runtime is not a strawman — it is a serious open-source project with a genuinely correct data model on paper, with validity windows, append-only corrections, and supersession edges. He then says he has now looked closely at a hosted context server, a Go memory CLI that was two hours old, and this runtime, and that all three share the same gap: the schema knows about time; the write path and the read path do not. Supersession only happens if you call an internal API by hand or run an LLM consolidation job and trust it. Which means the property you installed the tool for is not a property of the tool — it is a property of how disciplined the writes are.

Follow that to its end and the database underneath becomes interchangeable. If the reliability comes from write discipline anyway, you should pick the store a human can read, grep, diff, and fix. That store is a text file.

The architecture, in numbers

The system is open source at github.com/ucsandman/markdown-agent-memory under MIT, created in February 2026 and describing itself as markdown-only hierarchical memory for long-running agents. The repository's README reports 125 stars and 14 forks as of mid-September 2026, with the last push on September 11. The measured contents of the agent's memory at the time of writing:

• An identity layer read on every boot — who it is, who the operator is, the rules it operates under, current standing decisions.
• One routing index, MEMORY.md, at 10,079 characters against a hard cap of 15,000. It holds no facts, only pointers: which file owns which person, project, and decision, and what triggers reading each one.
• 34 files for people and projects, one file per thing that has a history.
• 5 decision records for choices that changed default behavior.
• 345 dated daily notes, raw logs written the day things happened.
• A SQLite index and semantic search over all of it, for lookup only. The index is rebuilt from the files.

That last line is the sharpest single sentence in the design. The files are the truth. If the index and a file disagree, the index is wrong by definition. The layering follows from it: boot reads only identity and the index, everything else is retrieved when a task asks for it, narrowest file first. The agent does not preload project history to answer a question about dinner. The README puts the saving at roughly 70% off a typical session start, because boot loads a ~1.5k-token index instead of a 5–10k flat file.

He is honest that the shape is not the innovation. Folders, entities, and an index is roughly what every memory tool looks like now. The shape was never the hard part.

The four write rules

All the reliability comes from four constraints on writing. They are short enough to paste into any agent's instructions file, which is exactly the point.

1. Every fact carries a provenance tag

Each line in a people, project, or decision file gets one of four tags, and the set is deliberately small:

[stated]    the operator said it directly
[observed]  you saw it in a tool result, file, or log
[inferred]  your conclusion
[suggested] your idea the operator never committed to

The rule that gives it teeth: never record that the operator decided something unless a human turn actually states it. The failure mode it kills is the agent laundering its own proposals into decisions. A proposal plus "sounds good" files the shape of what was approved as one decision, not ten separate facts nobody ever stated.

This is also a prompt-injection defense, and an unusually clean one. When lessons are stored as tagged data rather than as instructions, a hostile input can suggest a rule once — but once is never enough.

2. Inferred lessons pass a recurrence gate

A pattern the agent notices needs at least three independent signals across at least two distinct sessions before it can become standing behavior. Signals older than thirty days count half, so old one-offs decay out instead of accumulating. Explicit operator corrections skip the gate and take effect immediately.

The asymmetry is the design. Corrections are cheap and immediate; self-derived rules are expensive and slow. Failure lessons get stored as data in the form "when X broke, Y fixed it" — never as a command, so even a poisoned lesson cannot become an instruction the agent executes.

3. Supersession is an edit, not an append

When a decision changes, the old line gets struck through with a date and the new line lands next to it with its own provenance tag. The current truth and the full history live in the same place, in reading order, and both come back on any retrieval of that file. There is no query-time ranking step left to get wrong, because there is nothing to rank.

This is where the design buys its strongest property. The runtime's supersession edges lived in valid_from and valid_until columns that nothing populated. Git gives the folder those same semantics for free, as the author points out: log is the validity window, blame is per-line provenance, diff is the supersession edge, and revert is the restore path.

4. Store only what is not re-derivable

Fetched data, generated plans, and anything Git already records stays out. Current state gets verified live, never asserted from memory. Durable phrasing beats figures that go stale; where a figure matters, it carries an observed date. A file containing only things that cannot be recomputed stays small enough to stay honest.

The read path is a bounded evidence step

Before answering anything about prior work, decisions, dates, people, or preferences, the agent must search memory. It returns a compact bundle capped at five sources by default, and each retained fact carries its file path and line, its provenance type, and its freshness. If freshness cannot be established, the claim gets labeled stale or unknown rather than silently promoted to current. If two sources conflict, the agent states the conflict and then fixes the canonical file, in that order.

Note what the semantic index does in this design: it finds the file. It does not answer the question. Answers come from reading the canonical lines, and the tags and dates travel with those lines. That is the difference the break-it test exposed. The runtime stored the source URIs faithfully and then stripped them from the search output and from the context block handed to the model. Provenance that survives in storage but never reaches the agent might as well not exist. In the folder, that failure is unrepresentable — the source tag is in the line, so if you read the line you got the source.

Tiers, because rules alone still drift

Every file sits in one of four tiers, and the tier decides how it may change. The README credits the ROM / RAM / disk / tape framing to a Reddit commenter on r/ClaudeCode, which is itself a nice detail: the design is being edited in public.

The admission buried in that table is the one worth taking seriously: rules an LLM is only asked to follow drift. So the design ships a machine check for the mechanical half. scripts/memory-lint.mjs runs on Node 20+ with zero dependencies and fails on an over-cap boot file, an untagged new fact line, a deleted struck line, an edited archive file, or a dead path in the routing index. It runs as a pre-commit hook and in the agent's recurring health check.

node scripts/memory-lint.mjs --root path/to/workspace --staged

# FAIL on any of:
#   - boot file over its cap
#   - new fact line without a provenance tag
#   - a struck line was deleted
#   - an archive file was edited
#   - MEMORY.md points at a path that no longer exists

The lint checks the mechanical failures. Whether a tag is honest is still on the writer, and the README says so rather than pretending otherwise. That boundary — automate what can be checked, name what cannot — is the part most memory products skip.

What the author admits does not work yet

The limitations section is unusually direct, and it is the reason this is worth citing at all. It only works if the writer follows the policy, and the writer is an LLM. If your agent will not consistently apply editing discipline, a Markdown folder degrades just like every other store — only more legibly, and legibility is the safety net. It is single-agent and single-operator; a fifty-seat team needs real locking and merge discipline, which Git was arguably built for but this repository does not solve for you. There is a scale ceiling somewhere past a few hundred daily notes; he has not hit it, and states plainly that this is not a claim it does not exist. And it is n=1: seven months, one agent, one operator who cares.

His own framing of the evidence standard is the line to keep: that is weaker evidence than a benchmark suite and stronger evidence than a benchmark suite the vendor scored themselves — which, he notes, is what the memory tools ship.

What this means if you publish or write in Markdown

Strip away the agent framing and the design is a set of rules about documents that accumulate: tag where each claim came from, require evidence before a pattern becomes policy, edit the line instead of appending a second version of the truth, and keep only what you cannot recompute. Those are the same rules that separate a notes folder you trust from one you open once and abandon.

Which is the reason this connects to publishing rather than only to agents. Agent memory and human publishing are two ends of the same document's life, and both fail for the same reason — a store that keeps everything and ranks nothing. A knowledge base that holds three un-struck versions of a decision is the same failure as a draft that has been pasted into four platforms with four different bodies. The fix in both cases is the same: keep one canonical source, keep the history visibly as history, and make the current version the one that travels.

Here is the shape of the problem in the form most writers hit first. You keep a canonical Markdown file with a struck-through decision, exactly as the system prescribes, and you want to publish the current version:

# API decision record

~~REST, chosen 2026-01-14, from the platform kickoff~~

~~GraphQL, chosen 2026-04-22, from the client meeting~~

**tRPC, chosen 2026-08-19, from the architecture review** [stated]

## Consequences

- One typed client, no schema drift
- Streaming default for long jobs

Paste the current line, not the record. The
struck lines are history for the repo, not
for the post.

Paste that into LinkedIn or a newsletter editor and the strikethrough usually survives, the bold current line survives, and the code fence frequently does not — it arrives as a paragraph of literal backticks and dashes. The distinction the memory system draws between the canonical file and what gets read is the same distinction you need between the Markdown source and the platform-facing version of it.

md2rich handles that last step and runs entirely in your browser — no upload, no server-side rendering, nothing sent anywhere. For agent memory that property is merely nice. For a decision record, a postmortem, or an internal migration write-up, it is the whole argument: the document you are converting is usually the most internal prose you have, full of customer context and system names, and a converter that uploads it to format it is a bad trade. Convert it with md2rich and paste it into LinkedIn, X Articles, Medium, or Notion with the structure intact, having never left your machine.

Bottom line

The honest read is that the headline oversells and the argument undersells. Markdown is not sufficient for agent memory in any sense a benchmark would recognize: it is n=1, single-operator, and past a few hundred daily notes the author himself will not claim it holds. What the September 2026 test actually demonstrates is narrower and more useful. A memory system fails the one question that matters — what changed, and how do you know — when its write path does not enforce supersession and its read path does not carry provenance, and the impressive schema is irrelevant if nothing populates it. A folder of files that enforces both, with a lint and a pre-commit hook, beats it on that question today.

The transferable part is not the format. It is that reliability in a store of accumulated prose is a property of the editing policy, not of the storage engine — and that you should therefore pick the storage a human can read, diff, and correct. That reasoning holds whether the reader at the end is an agent retrieving a decision or a person reading your post.