Beads: A Memory Upgrade for Your Coding Agent

The Memory Problem

AI coding agents are powerful, but they have a fundamental flaw: they forget. Every time you restart Claude Code, OpenCode, or Aider, the agent starts with a blank slate. It has no memory of what it was working on, what’s blocked, or what comes next.

Most teams use flat issue lists — GitHub Issues, Jira boards, or markdown TODO files — to track work. But these are designed for humans, not agents. A flat list doesn’t tell an agent which tasks are unblocked, which depend on each other, or what the priority order is. The agent either picks the wrong task and stalls, or you spend your session hand-holding it through the backlog.

Beads, created by Steve Yegge, solves this by replacing flat lists with a dependency-aware graph database purpose-built for AI coding agents.

What Is Beads

Beads is a distributed graph issue tracker written in Go. It ships as a single static binary called bd and stores everything in a .beads/ directory inside your project. The storage backend is Dolt — a version-controlled SQL database that supports cell-level merging, native branching, and built-in sync via Dolt remotes.

The core idea is simple: instead of a flat list of tasks, Beads maintains a graph where tasks have edges like blocks, related, parent-child, and discovered-from. When an agent asks “what should I work on?”, Beads traverses the graph and returns only the tasks that are unblocked — the bd ready command.

1
# Install once, use everywhere
2
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
3

4
# Initialize in your project
5
cd your-project
6
bd init
7

8
# Create a task with priority
9
bd create "Fix auth middleware timeout" -p 0 -t bug
10

11
# Add a dependency
12
bd dep add bd-c3d7 bd-a1b2
13

14
# Ask: what's ready to work on?
15
bd ready
16

17
# Claim a task atomically
18
bd update bd-a1b2 --claim

How It Works

Hash-Based IDs

Every task gets a hash-based ID like bd-a1b2. These are collision-resistant, which means multiple agents on multiple branches can create tasks independently without conflicts. When branches merge, Dolt handles the database merge at the cell level — two agents can update different tasks on different branches and everything reconciles cleanly.

Hierarchical Epics

Tasks can be nested into epics using dotted IDs:

1
bd-a3f8              → Epic
2
bd-a3f8.1            → Task
3
bd-a3f8.1.1          → Sub-task

This lets agents decompose complex features into manageable pieces while maintaining the parent-child relationship.

Compaction (Memory Decay)

As tasks accumulate, old closed tasks waste context window. Beads solves this with compaction — a semantic “memory decay” system that summarizes old closed tasks. Instead of loading 50 historical task descriptions, the agent sees a compressed summary. This is critical for long-running projects where the task history grows faster than the context window.

Agent-Optimized Output

Every bd command supports --json output. This isn’t an afterthought — it’s a design principle. JSON output is deterministic, token-efficient, and parseable by LLMs. Agents don’t need to parse markdown tables or guess at formatting.

Stealth Mode

Not everyone wants to commit .beads/ to their repository. Run bd init --stealth to use Beads locally without any git hooks or committed files. Or set BEADS_DIR=/path/to/.beads to point the database anywhere — useful for monorepos, non-git VCS, or CI/CD environments.

Real Use Cases

1. Solo Developer with Context Loss

You’re building a feature across multiple sessions. Each time you start Claude Code, you paste a summary of what you were doing. With Beads, the agent reads bd ready and picks up exactly where it left off. Closed tasks are compacted, open tasks show their current state, and dependencies are respected.

1
# Session 1: Agent discovers subtasks
2
bd create "Implement OAuth2 flow" -p 0
3
bd create "Add PKCE support" -p 1
4
bd dep add bd-b4e2 bd-a1f3  # PKCE blocks OAuth2
5

6
# Session 2 (next day): Agent picks up
7
bd ready  # Returns only unblocked tasks

2. Multi-Agent Coordination

Multiple AI agents (or multiple instances of the same agent) work on different branches simultaneously. Without coordination, they might work on the same task or create conflicting changes. With Beads, bd update <id> --claim atomically assigns a task to an agent. Other agents see it’s claimed and move on.

The BeadHub coordination server takes this further — it adds work claiming, file reservation, presence awareness, and inter-agent messaging on top of Beads.

3. Long-Horizon Feature Development

Large features decompose into epics with dozens of subtasks. A flat issue list forces you to manually track which subtasks are done and what’s next. Beads maintains the dependency graph, so bd ready always returns the correct next task. The agent never picks a blocked task and stalls.

4. CI/CD Task Tracking

Use BEADS_DIR=/tmp/ci-beads bd init --stealth to create an ephemeral task database for CI pipelines. Track build steps, test results, and deployment tasks without any repo-level side effects.

The Ecosystem

What makes Beads remarkable isn’t just the core tool — it’s the ecosystem that has grown around it. In a short time, the community has built:

Agent Orchestration Frameworks

Editor Plugins

UIs

From terminal UIs (Mardi Gras, perles) to web UIs (beads-ui, BeadBoard) to native apps (Beadbox for macOS, Beads Task-Issue Tracker for cross-platform) — there’s a visualization layer for every workflow.

SDK

@herbcaudill/beads-sdk provides a typed TypeScript client with zero runtime dependencies for programmatic access.

How It Compares

Getting Started

Install Beads, initialize it in your project, and tell your agent to use it:

1
# Install
2
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
3

4
# Or via npm, homebrew, or go install
5
npm install -g @beads/bd
6
brew install beads
7
go install github.com/steveyegge/beads/cmd/bd@latest
8

9
# Initialize
10
cd your-project
11
bd init
12

13
# Tell your agent
14
echo "Use 'bd' for task tracking. Run 'bd ready' to see what's available." >> AGENTS.md

The agent will read bd ready --json at the start of each session, pick an unblocked task, claim it with bd update <id> --claim, work on it, and close it with bd close <id> "description". When it discovers new subtasks, it creates them and links dependencies. When the session ends, all state persists in the Dolt database — ready for the next session.

Sources

• Beads GitHub Repository
• Introducing Beads: A Coding Agent Memory System — Steve Yegge (Medium)
• Beads Community Tools
• Beads FAQ
• Beads Quickstart Guide
• Beads Architecture

Related Articles

Qwen Code Setup: Free AI Coding with Extensions, PDCA Workflows, and Context Engineering

Apr 1, 2026

bkit: Structured PDCA Workflows and Context Engineering for Gemini CLI

Mar 31, 2026

My Opencode Setup: Guardrails, Intelligence, and Skill-Driven AI Workflows

Mar 28, 2026