Beads by Steve Yegge: Git-Backed Persistent Memory for AI Coding Agents – Installation and Usage Guide

Beads revolutionizes AI agent persistence by transforming a simple git-backed graph issue tracker into an infinite-context memory upgrade, enabling reliable long-horizon task management without context loss.

Introduction

Modern large language model-based coding agents operate within strict context windows, typically limited to a few thousand tokens. Once a session ends or the window fills with code and history, critical task state vanishes. Agents forget dependencies, duplicate work, or abandon long-running initiatives entirely. This “context window problem” turns sophisticated autonomous workflows into brittle, short-horizon scripts.

Beads, created by Steve Yegge, addresses this architectural limitation directly. It functions as a distributed, git-backed graph issue tracker that lives inside every project repository. Rather than relying on ephemeral markdown files or external databases, Beads stores tasks, dependencies, status transitions, and audit history inside a version-controlled SQL database powered by Dolt. The result is persistent, queryable memory that survives restarts, branch switches, and even multi-agent collaboration.

For software engineers, AI researchers, and developers building with Cursor, Windsurf, GitHub Copilot, or custom LLM agents, Beads represents a fundamental shift from stateless prompting to stateful, long-horizon execution. This guide delivers a complete technical walkthrough: philosophy, installation, core workflow, advanced integrations, and the implications for the next generation of AI coding systems.

The Philosophy

Steve Yegge’s design philosophy for Beads stems from decades of experience building developer tools at Google and Amazon. Traditional issue trackers and markdown plans fail agents for three structural reasons. First, markdown becomes write-only memory; agents generate plans but cannot query or traverse them reliably. Second, centralized databases introduce single points of failure and merge conflicts in distributed or branched workflows. Third, session-based context windows enforce amnesia between interactions.

Beads replaces these with a decentralized, local-first model. Every project contains its own .beads directory holding a Dolt database — a Git-compatible SQL engine that supports time travel, branching, and cell-level three-way merges. Tasks form a directed acyclic graph with first-class relations such as blocks, depends_on, discovered_from, supersedes, and replies_to. Hash-based identifiers (for example bd-a3f8.1) eliminate collision risks during concurrent edits.

The superiority over database-backed solutions is architectural. Git provides free versioning, conflict resolution semantics agents already understand, and zero-cost distribution via ordinary git push. Dolt adds SQL querying on top without sacrificing merge safety. Developers gain the query power of PostgreSQL combined with the resilience of Git, all without network round-trips or managed service costs. This local-first approach aligns perfectly with developer workflows: the memory travels with the code, forks cleanly, and survives repository clones.

Yegge describes the system as “external memory for agents, with dependency tracking and query capabilities that make it feel like I have a reliable extension of my working memory across sessions.” The cognitive upgrade is immediate. Agents no longer panic when the context window resets; they simply run bd ready --json and continue exactly where they left off.

Installation Guide

Prerequisites

Beads runs on macOS, Linux, Windows, and FreeBSD. The only hard requirement is a working Git installation, because the .beads directory is committed to the repository. Dolt is bundled and managed automatically. Go 1.24 or later is needed only if building from source; binary installations require no Go toolchain.

Step-by-Step Installation

The recommended method uses the official bootstrap script for a system-wide installation:

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

This places the bd binary in ~/.local/bin and updates your PATH.

Alternative methods include:

• npm: npm install -g @beads/bd
• Homebrew: brew install beads
• Go: go install github.com/steveyegge/beads/cmd/bd@latest

Verify success with:

bd --version

No project-specific cloning is required. The CLI installs once and works everywhere.

Post-Installation Configuration

Optionally install Git hooks for automatic Dolt synchronization:

bd hooks install

These hooks commit database changes on every git commit and pull remote updates after merges, eliminating manual bd dolt push calls in most workflows.

Operational Workflow

Initializing a Beads Store

Navigate to any project root and run:

bd init

This creates the .beads directory containing the Dolt database (beads.db), configuration, and Git-tracked metadata. For local-only experimentation use bd init --stealth. Contributors on forks should run bd init --contributor to isolate planning data in ~/.beads-planning.

The initialization process also registers the repository with Git hooks if installed, ensuring seamless synchronization.

Creating, Updating, and Querying Tasks for an AI Agent

Task creation follows a simple, scriptable pattern:

bd create "Implement user authentication API" \  
  --type task \  
  --priority 1 \  
  --description "Add JWT middleware and protected routes" \  
  --json  

Atomic claiming prevents race conditions in multi-agent environments:

bd update bd-a3f8 --claim --json  

Dependencies are first-class:

bd dep add bd-a3f8.2 bd-a3f8.1   # child blocked by parent  

Querying uses SQL under the hood but exposes human- and machine-friendly commands:

• bd ready — lists unblocked, unclaimed tasks
• bd show bd-a3f8 — full audit trail and relations
• bd dep tree bd-a3f8 — visual dependency graph

All commands support --json output for programmatic consumption by agents.

How an Agent Interacts with the .beads Directory to Maintain State

Agents interact exclusively through the bd CLI executed via shell tools or Model Context Protocol servers. The recommended pattern is to embed the following instructions in AGENTS.md, .claude.md, or .github/copilot-instructions.md:

“Always use the bd CLI for task tracking. Never create markdown TODO files. Before starting work, run bd ready --json and claim the highest-priority unblocked task with bd update <id> --claim --json. When discovering new work, create linked issues using --deps discovered-from:<parent-id>. At session end, close completed tasks and ensure git push succeeds.”

The .beads directory structure is deliberately minimal:

• beads.db — Dolt SQL database holding the entire task graph
• Configuration files for remotes and hooks
• Git-tracked metadata enabling ordinary git pull and git push

Every write operation produces an atomic Dolt commit, preserving full history. Agents therefore inherit Git’s branching model: work on feature branches carries its own memory, and merges reconcile state safely.

Advanced Use Cases

Integrating Beads with Popular AI Agents or Custom IDE Extensions

GitHub Copilot users install the companion beads-mcp package:

uv tool install beads-mcp  

A single .vscode/mcp.json entry exposes bd commands as native tools. Copilot then responds to natural-language requests such as “What issues are ready?” by calling the underlying CLI and returning structured results. Similar MCP or shell-tool integrations exist for Cursor, Claude Code, Aider, and Windsurf.

For custom IDE extensions, community projects provide web viewers, VS Code sidebars, and lightweight desktop clients that read the same .beads database. These tools allow human oversight without breaking the agent-native workflow.

Multi-Agent Swarms and Protected Branch Workflows

In swarm scenarios, multiple agents on different machines or branches share the same repository. Hash-based IDs and Dolt’s merge semantics prevent collisions. Maintainers configure protected branches via bd init --branch beads-metadata so planning data lives on a dedicated branch, avoiding pollution of main.

Memory Compaction and Long-Term Retention

Beads automatically compacts closed tasks by summarizing outcomes into concise notes, preventing unbounded growth inside the context window. Developers can also run bd doctor to detect orphaned issues and bd vc log to time-travel through historical task states. These capabilities turn Beads into true long-term project memory rather than a temporary to-do list.

Conclusion

The future of AI coding agents is stateful. Stateless prompting will remain useful for quick scripts, but any serious software engineering effort requires persistent memory that survives context resets, branch switches, and team handoffs. Beads delivers exactly that memory layer using tools developers already trust — Git and a lightweight SQL engine — without introducing new infrastructure or vendor lock-in.

By adopting Beads today, teams gain agents that plan across weeks, coordinate across machines, and evolve project state with the same rigor as human engineers. The installation takes minutes, the cognitive upgrade is immediate, and the architectural advantage compounds over time. For any developer serious about scaling LLM-based coding beyond toy examples, Beads is no longer optional — it is the foundation.

The repository at https://github.com/steveyegge/beads contains the latest binaries, community tools, and integration guides. Install bd, initialize your first store, and watch your agents remember what they are building.