Beads: The Complete Guide to the Memory Upgrade for Your Coding Agent
Beads (bd) is a memory upgrade for your coding agent — a Dolt-powered, version-controlled task tracking system designed for AI coding agents. Hash-based IDs for zero-conflict multi-agent workflows, semantic memory decay for context window management, graph links for knowledge graphs, hierarchical epics. By Steve Yegge. 18,600+ stars, Go, MIT.
What Is Beads?
Coding agents lose track of what they're doing. Beads gives them a structured memory system — a version-controlled database where agents track tasks, dependencies, and knowledge across sessions and branches. Built on Dolt (Git for data), it brings real version control to agent memory.
- Stars: 18,600+ ⭐
- Forks: 1,182
- Releases: 81
- Contributors: 283
- Language: Go
- License: MIT
- Author: Steve Yegge
- CLI:
bd - Topics: agents, claude-code, coding
Quick Start
# Install (system-wide)
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
# Initialize in your project
cd your-project
bd init
# Tell your agent
echo "Use 'bd' for task tracking" >> AGENTS.md
6 Key Features
🗄️ Dolt-Powered Database
Built on Dolt — version-controlled SQL with cell-level merge, native branching, and built-in sync via Dolt remotes. Your agent's memory is a real database with full git-like history.
🤖 Agent-Optimized
JSON output, dependency tracking, and auto-ready task detection. Designed for machines first, humans second.
🔀 Zero Conflict
Hash-based IDs (bd-a1b2) prevent merge collisions in multi-agent and multi-branch workflows. Multiple agents can work simultaneously without conflicts.
🧠 Compaction (Memory Decay)
Semantic "memory decay" that summarizes old closed tasks to save context window. The killer feature — as tasks age, they're compressed into summaries, keeping the agent's memory manageable.
💬 Messaging System
Message issue type with threading (--thread), ephemeral lifecycle, and mail delegation. Agents can communicate asynchronously.
🔗 Graph Links
relates_to, duplicates, supersedes, and replies_to for building knowledge graphs. Tasks become interconnected knowledge, not just a flat list.
Essential Commands
| Command | Purpose |
|---|---|
bd ready | Show tasks ready for work |
bd create "Title" -p 0 | Create high-priority task |
bd update <id> --claim | Claim a task |
bd dep add <child> <parent> | Add dependency |
bd show <id> | Show task details |
Hierarchical Epics
bd-a3f8 (Epic)
bd-a3f8.1 (Task)
bd-a3f8.1.1 (Sub-task)
Break complex work into tree structures that agents can navigate.
Modes & Roles
Stealth Mode
bd init --stealth
Use Beads locally without committing files. Perfect for personal use on shared projects.
Contributor vs Maintainer
- Contributors (forked repos):
bd init --contributorroutes planning to~/.beads-planning - Maintainers (write access): Auto-detected via SSH URLs
Installation
# npm
npm install -g @beads/bd
# Homebrew
brew install beads
# Go
go install github.com/steveyegge/beads/cmd/bd@latest
All platforms: Linux, FreeBSD, macOS, Windows.
Beads vs Alternatives
Category: This is a structured memory/task system for AI coding agents.
| Feature | Beads | Claude-Mem | CLAUDE.md | Linear/Jira |
|---|---|---|---|---|
| Focus | Agent task memory | Session memory | Project notes | Human project mgmt |
| Stars | 18.6K ⭐ | 33.7K ⭐ | Built-in | N/A (SaaS) |
| Version Control | ✅ Dolt (Git for DB) | SQLite | ❌ | ❌ |
| Hash-Based IDs | ✅ Zero conflict | ❌ | ❌ | ❌ |
| Memory Decay | ✅ Compaction | ❌ | ❌ | ❌ |
| Graph Links | ✅ Knowledge graph | ❌ | ❌ | Limited |
| Hierarchical Epics | ✅ | ❌ | ❌ | ✅ |
| Multi-Agent | ✅ Safe | Single agent | N/A | N/A |
| Messaging/Threading | ✅ | ❌ | ❌ | ✅ |
| Stealth Mode | ✅ | ❌ | ❌ | ❌ |
| Agent-First Design | ✅ JSON output | ✅ | ❌ | ❌ |
When to choose Beads: You want structured, version-controlled task memory for coding agents — with multi-agent safety, memory decay, and knowledge graphs.
When to choose Claude-Mem: You want automatic session-level memory capture without explicit task tracking.
When to choose CLAUDE.md: You want simple manual project documentation.
Conclusion
Beads reimagines what agent memory should look like. It's not just session logs — it's a version-controlled, graph-linked task database with semantic compaction, designed by Steve Yegge for how AI agents actually work. Hash-based IDs solve the multi-agent coordination problem, while memory decay keeps context windows manageable. 18.6K stars and 283 contributors.