Beads: Persistent Memory for Coding Agents

Beads is a CLI that gives coding agents a persistent, structured memory. Instead of markdown plans that get ignored after compaction, it stores tasks in a dependency-aware graph backed by Dolt, the version-controlled SQL database. The memory survives compaction, handles multi-agent edits without conflicts, and works with Claude Code, Copilot, Cursor, and anything that can run a shell command.

Repo: github.com/gastownhall/beads

The Problem Nobody Talks About

Coding agents forget. You give Claude Code a 10-step plan, it executes steps 1 through 3, you run /compact because the context is getting long, and now the agent has no idea what steps 4 through 10 were. So you re-explain. Or worse, it invents its own next steps and drifts off course.

The standard fix is a markdown plan file. Write the steps to PLAN.md, tell the agent to check it. This works until you have two agents on the same project, or the plan gets complex enough to need dependencies between tasks. Markdown has no structure. No dependency tracking. No way to know which task is actually unblocked and ready to work.

Beads replaces the markdown file with a real database. Tasks have IDs, priorities, dependencies, status flags, and audit trails. The agent queries bd ready to get the next unblocked task. No re-explanation needed. No drift.

Why This Matters

Survives compaction. The memory lives in a database, not in the context window. Compact all you want. The tasks are still there when the agent checks.

Dependency-aware. Tasks can block other tasks. bd ready only returns tasks whose dependencies are all closed. The agent never works on something out of order.

Multi-agent safe. Hash-based IDs (bd-a1b2) instead of sequential numbers. Two agents creating tasks at the same time never collide. Dolt's cell-level merge handles the rest.

Works without git. Dolt is the storage backend. Git integration is optional. Works in monorepos, non-git VCS, CI/CD, ephemeral environments.

Step 1: Install Beads

Pick your install method:

brew install beads

Or via npm:

npm install -g @beads/bd

Or via the install script (all platforms):

curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

Beads is a system-wide CLI. You install it once and use it in every project. Don't clone the repo into your project directory.

Step 2: Initialize in Your Project

Navigate to your project and run:

cd your-project
bd init

This creates a .beads/ directory with an embedded Dolt database. No external server needed. Single-writer, file-locked, zero config.

Then tell your agent it exists:

echo "Use 'bd' for task tracking" >> CLAUDE.md