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

Step 3: essential commands

Everything you need for day-to-day usage:

bd ready: List tasks with no open blockers, the agent's "what do I work on next"
bd create "Title" -p 0: Create a P0 (highest priority) task
bd update <id> --claim: Atomically claim a task (sets assignee + in_progress)
bd dep add <child> <parent>: Link tasks: child is blocked until parent closes
bd show <id>: View task details, dependencies, and full audit trail
bd close <id> "Done": Close a task with a summary
bd prime: Generate a context summary for the agent (compaction-safe)

The workflow in practice: agent runs bd ready, picks the top task, runs bd update <id> --claim, does the work, runs bd close <id> "summary", then checks bd ready again. No human intervention needed between tasks.

Step 4: hierarchical tasks and epics

Beads supports hierarchical IDs for breaking big work into smaller pieces:

bd-a3f8 is the epic
bd-a3f8.1 is a task under that epic
bd-a3f8.1.1 is a sub-task under that task

This matters when you're planning a multi-day feature. The epic holds the overall goal. Tasks break it into shippable chunks. Sub-tasks break those into individual steps. The agent navigates the hierarchy the same way it navigates a file tree.

Step 5: multi-agent and stealth workflows

Three modes depending on your situation:

Stealth mode. Run bd init --stealth to use Beads locally without committing anything to the repo. The .beads/directory stays local. Good for personal use on shared projects where you don't want to push Beads files to the team.

Contributor mode. Run bd init --contributor on forked repos. Routes planning issues to a separate directory (~/.beads-planning) so your experimental task tracking doesn't show up in PRs.

Server mode. Run bd init --server to connect to an external Dolt server instead of the embedded database. Supports multiple concurrent writers. Useful when you have 3+ agents working the same project and need true concurrent access, not just merge-safe writes.

The embedded mode (default) handles most cases. You only need server mode when you're running parallel agents that write frequently enough to hit file-lock contention.

Step 6: messaging

Beads has a message issue type with threading. Create a message with --threadto start a conversation thread. Messages have an ephemeral lifecycle. They're designed for coordination between agents, not permanent records.

Mail delegation lets one agent hand off work to another by assigning a message. The receiving agent sees it in bd ready alongside regular tasks.

This is how multi-agent coordination works without a separate orchestration layer. Agent A creates a message for Agent B, Agent B picks it up on its next bd ready cycle, does the work, and closes the message.

Step 7: graph links

Tasks can link to each other with semantic relationship types:

relates_to: loose connection, for context
duplicates: this task is a duplicate of another (auto-close candidate)
supersedes: this task replaces an older one
replies_to: threaded message response

These links turn your task list into a knowledge graph. When the agent runs bd show <id>, it sees not just the task but its full context: what it relates to, what it replaced, what depends on it. The agent makes better decisions because it has the full picture, not an isolated task description.

Storage: embedded vs server

Embedded (default). Dolt runs in-process. Data lives in .beads/embeddeddolt/. Single-writer with file locking. Zero config. This is what you should use unless you have a specific reason not to.

Server. Connects to an external dolt sql-server. Supports multiple concurrent writers. Configure with environment variables:

BEADS_DOLT_SERVER_HOST=127.0.0.1
BEADS_DOLT_SERVER_PORT=3307
BEADS_DOLT_SERVER_USER=root
BEADS_DOLT_PASSWORD=

Unix domain sockets are supported via --server-socket for sandboxed environments where file-level access control is simpler than network allowlists.

Backup and migration. Back up your database with bd backup:

bd backup init /path/to/backup
bd backup sync

Restore into a new project (any mode):

bd init
bd backup restore --force /path/to/backup

You can migrate between embedded and server mode using backup/restore.

The gotcha: when Beads is worth it vs overkill

Beads adds a tool to your agent's workflow. Every bd ready and bd updateis a command the agent runs instead of doing actual work. On a 20-minute task, that overhead is noise. On a 3-hour multi-step refactor, it's the difference between finishing and going in circles.

Worth it when:

The task has 5+ steps with dependencies between them
You're running multiple agents on the same project
You're doing multi-session work that spans compactions
You keep re-explaining the plan after /compact

Overkill when:

Single-step tasks ("fix this bug", "add this endpoint")
Short sessions that won't hit compaction
Solo agent, simple plan, no dependencies

If you're not sure, try it on your next multi-step feature. If the agent stops drifting after compaction, it paid for itself.