Beads - Persistent Task Memory for AI Agents

Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.

Overview

bd (beads) replaces markdown task lists with a dependency-aware graph stored in git. Unlike TodoWrite (session-scoped), bd persists across compactions and tracks complex dependencies.

Key Distinction:

• bd: Multi-session work, dependencies, survives compaction, git-backed
• TodoWrite: Single-session tasks, linear execution, conversation-scoped

Core Capabilities:

• 📊 Dependency Graphs: Track what blocks what (blocks, parent-child, discovered-from, related)
• 💾 Compaction Survival: Tasks persist when conversation history is compacted
• 🐙 Git Integration: Issues versioned in .beads/issues.jsonl, sync with bd sync
• 🔍 Smart Discovery: Auto-finds ready work (bd ready), blocked work (bd blocked)
• 📝 Audit Trails: Complete history of status changes, notes, and decisions
• 🏷️ Rich Metadata: Priority (P0-P4), types (bug/feature/task/epic), labels, assignees

When to Use bd vs TodoWrite:

• ❓ "Will I need this context in 2 weeks?" → YES = bd
• ❓ "Could conversation history get compacted?" → YES = bd
• ❓ "Does this have blockers/dependencies?" → YES = bd
• ❓ "Is this fuzzy/exploratory work?" → YES = bd
• ❓ "Will this be done in this session?" → YES = TodoWrite
• ❓ "Is this just a task list for me right now?" → YES = TodoWrite

Decision Rule: If resuming in 2 weeks would be hard without bd, use bd.

Prerequisites

Required:

• bd CLI: Version 0.34.0 or later installed and in PATH
• Git Repository: Current directory must be a git repo
• Initialization: bd init must be run once (humans do this, not agents)

Verify Installation:

bd --version  # Should return 0.34.0 or later