Introducing Beads

Most "agent memory" pitches reach for vector databases and clever retrieval. Yegge's move is more mundane and more convincing: give the agent a real issue tracker — dependency graph, git history, JSON queries — and let it manage its own work the way a disciplined engineer would.

The amnesia problem

The whole essay hangs on one uncomfortable fact about how agents actually run. A coding agent doesn't carry a project in its head; it carries a context window, and that window collapses every few minutes. Every compaction is a small stroke.

"The problem we all face with coding agents is that they have no memory between sessions — sessions that only last about ten minutes. It's the movie Memento in real life, or Fifty First Dates."— Introducing Beads

Any task worth doing outlasts a single window. Tests, reviews, and cleanup drag a "small feature" across many sessions — and somewhere in the middle the agent forgets the plan, skips the follow-through, and cheerfully announces the system is done.

Why markdown plans don't scale

The community's first answer was to write the plan down: hand the agent a plan.md, let it check off steps, resume from the file next session. Yegge went all-in on this — a whole directory of plans under git — and watched it rot. Prose plans decay, contradict each other, and force the agent to re-read and mentally parse them every time just to figure out what's still blocked.

"By the time I finally found a solution that works — Beads — I discovered I had six hundred and five markdown plan files in varying stages of decay in my plans/ folder."— Introducing Beads

605 files is the punchline, but the real diagnosis is underneath it: a plan written as prose is not a data structure. You can't query it, you can't reliably diff it, and an agent can't ask it "what's ready?" without re-reading the whole pile.

What Beads actually is

Beads is not a framework or an orchestrator — Yegge scrapped a heavyweight one on the way here. It's a small command-line issue tracker, bd, that stores issues as plain JSONL versioned in git (with Dolt underneath for real version-controlled sync). No server to run, no vector store to tend; it rides along in the repo the agent is already working in.

"Beads is an incredibly small-footprint, drop-in upgrade for your favorite coding agent."— Introducing Beads

Because the store is JSONL in git, it inherits everything git already gives you: history, branching, review, and sync across machines and across parallel agent sessions. The memory isn't bolted onto the agent — it lives with the code.

Memory you can query

The difference between a plan and a tracker is that a tracker knows its own shape. Beads models issues with explicit parent/child and blocking relationships, so "what can I work on right now" is a query, not a reading-comprehension exercise. The agent asks bd ready --json and gets a definitive list of unblocked work back — machine-readable, no prose to parse.

"Dependencies are first-class, not prose."— Introducing Beads

The second-order effect is the interesting one. When an agent notices something broken mid-task, it doesn't have to choose between derailing and forgetting — it files an issue, links it as discovered work, and keeps going. Work that used to evaporate at the next compaction now persists as a row someone (human or agent) will pick up later. It also makes shortcuts harder to hide: skipped steps become open issues, not silent gaps.

Does it actually work — and one caveat

Yegge's claim is blunt: the thing he'd been fighting for months mostly dissolved once the agent had a queryable external memory to plan against.

"Long-term planning — the dementia/amnesia problem we discussed — has been one their primary struggles, and this little specialized issue tracker solved it in seemingly the snap of a finger."— Introducing Beads

Read it with the enthusiasm discounted. Beads is young, largely agent-built, and grew fast enough that hype outran hard data — "snap of a finger" is a testimonial, not a benchmark. The durable idea survives the hype anyway: agents don't need smarter recall so much as an external, structured, versioned place to put state — and an issue tracker with a real dependency graph is a remarkably boring, remarkably good place to put it.