Beads (Yegge) — Summary

Beads (bd) is a distributed graph issue tracker for AI agents powered by Dolt (version-controlled SQL database). With 24,000+ GitHub stars, it reframes "memory" as a task-graph: instead of storing facts or decisions in flat files or vector indexes, it stores issues with dependency edges, hierarchical IDs (bd-a3f8, bd-a3f8.1, bd-a3f8.1.1), typed relationships (relates_to, duplicates, supersedes, replies_to), and compaction semantics. The bd prime command outputs AI-optimized workflow context (including persistent memories stored via bd remember) that agents inject at session start. Compaction is explicit: bd compact --analyze exports candidates, bd compact --apply accepts agent-generated summaries — "graceful decay" that reduces old closed issues to semantic summaries. The system is a Go binary distributed via brew, npm, and install script; it integrates with Claude Code, Codex, Cursor, Factory.ai, and other agents via bd setup <agent>. Compared to seeds, Beads is unique in this corpus — it is neither a memory layer over a coding session nor a methodology doc, but a persistent external issue-tracking database that survives across agents, machines, and compaction events.

Beads (Yegge) — Overview

Origin

Created by steveyegge (Steve Yegge, author of the "Stevey's Blog Rants" essays, previously at Google and Grab). Published under the gastownhall GitHub organization. Active development with significant community adoption (24K stars, 1600 forks).

Philosophy

The README captures the core claim: "Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context."

The key insight is that markdown task lists fail for multi-session, multi-agent work because they have no structure — no dependencies, no atomic claiming, no conflict-free merging. Beads replaces them with Dolt (git-for-data), making the task graph version-controlled, branchable, and mergeable.

Dolt as the Core

Beads uses Dolt as its primary storage engine:

• Version-controlled SQL with cell-level merge
• Native branching on data
• Built-in sync via Dolt remotes (bd dolt push / bd dolt pull)
• Hash-based issue IDs prevent merge collisions (bd-a1b2 format)

Compaction Philosophy

Compaction reduces database size by summarizing closed issues that are no longer
actively referenced. This is permanent graceful decay — original content is discarded.

Tiers:
  - Tier 1: Semantic compression (30 days closed, 70% reduction)
  - Tier 2: Ultra compression (90 days closed, 95% reduction)

Memory vs Issue Tracking

Beads has two memory primitives:

1. Issues — tasks with dependencies, assignees, priorities, statuses
2. Memories — persistent free-text insights stored via bd remember "insight", injected at bd prime time

The bd prime command is the key session-start injection mechanism: it outputs AI-optimized workflow context including both issue workflow guidance and all stored memories.

Multi-Agent Design

Zero Conflict: Hash-based IDs (bd-a1b2) prevent merge collisions in
multi-agent/multi-branch workflows.

The system is explicitly designed for multi-agent, multi-branch, multi-machine use with a real distributed database as the coordination layer.

Beads (Yegge) — Architecture

Distribution

Go binary (bd). Multiple install methods.

Install

brew install beads                       # macOS / Linux (recommended)
npm install -g @beads/bd                 # Node.js users
curl -fsSL <install-script> | bash       # All platforms
go install github.com/steveyegge/beads/cmd/bd@latest  # From source

Project Setup

cd your-project
bd init                                   # Init Beads in project
bd setup claude                          # Install Claude Code hooks
bd setup codex                           # Install Codex AGENTS.md
bd setup factory                         # Factory.ai AGENTS.md
bd prime                                  # Print workflow context for agent injection

Directory Structure

.beads/
├── embeddeddolt/   # Embedded Dolt database (default mode)
│   └── (Dolt SQL files)
├── issues.jsonl    # Export for viewers/interchange (NOT source of truth)
└── config          # Beads config

(optional, server mode):
.beads/dolt/        # External Dolt server connection

Storage Modes

Claude Code Integration

bd setup claude installs:

• .claude/settings.json hooks (PreToolUse matchers for blocking interactive commands)
• CLAUDE.md or AGENTS.md with bd workflow instructions

Required Runtime

Go 1.26+ (at build time). Binary has no runtime dependencies.

Platform Support

macOS, Linux, Windows, FreeBSD.

Beads (Yegge) — Components

CLI Commands (extensive — ~80+ command files in cmd/bd/)

Core Issue Operations

Memory & Context

Database Operations

Project Setup

Diagnostics

Multi-agent / Federation

Claude Code Hooks (2)

From .claude/settings.json:

These are safety hooks for the Beads development repo itself, not part of the general user setup.

Issue Data Model

type BeadIssue struct {
    id           string        // "bd-a1b2" or "bd-a1b2.1" (hierarchical)
    title        string
    description  string
    status       BeadStatus    // open|in_progress|blocked|deferred|closed|pinned|hooked
    priority     int           // 0-4
    issue_type   string        // bug|feature|task|epic|chore
    labels       []string
    assignee     string
    dependencies []Dependency  // relates_to|duplicates|supersedes|replies_to
    // ...
}

Memory Data Model

Memories are stored as key-value entries in the Dolt database, with the slugify key generated from the first ~8 words. Injected at bd prime time.

Beads (Yegge) — Uniqueness

Differs From Seeds

Beads has no close analog in the 11 seeds. The closest is taskmaster-ai (seed), which also uses a structured task store (JSON) with dependency tracking. But Beads goes much further: Dolt (version-controlled SQL with cell-level merge and remote sync) vs taskmaster's flat JSON file; hierarchical IDs with dependency graphs vs taskmaster's numeric ID + flat dependencies; multi-agent atomic claiming (bd update --claim) vs taskmaster's sequential single-agent model; explicit compaction with graceful decay vs taskmaster's unlimited growth. Beads also resembles ccmemory (seed) in storing memories in a persistent external store accessible across sessions, but ccmemory focuses on episodic memory (decisions, corrections) while Beads focuses on work-to-do (task graph).

Distinctive Features

1. Dolt as storage engine: The only framework in this corpus that uses a version-controlled SQL database as the state store. This enables branching, merging, and distributed sync for issue state.
2. Task graph with hierarchical IDs: bd-a3f8.1.2 format supports epic/task/subtask without a separate concept; dependency edges are first-class.
3. Graceful decay compaction: Explicit tiered compaction (30 days/70%, 90 days/95%) with agent-driven or AI-driven summarization. Issues permanently reduced — not archived.
4. Multi-agent atomic claiming: bd update --claim is an atomic operation preventing race conditions in multi-agent scenarios.
5. bd prime + bd remember: The combination of workflow context injection and free-text memory storage is the simplest possible session-handoff mechanism — one command, no hooks required.
6. "Landing the plane" protocol: The explicit "the plane is not landed until git push succeeds" iron law in AGENT_INSTRUCTIONS.md is one of the most detailed agent workflow contracts in this batch.
7. Cross-tool by design: bd setup supports Claude Code, Codex, Cursor, Factory.ai, Warp, Mux, and more — widest agent integration surface outside claude-mem.

Observable Failure Modes

1. Dolt binary dependency: Beads embeds Dolt; first-run or updates require downloading the Dolt binary, which may fail in restricted environments.
2. issues.jsonl confusion: Many users mistake .beads/issues.jsonl for a backup; it is only an export and does not capture full Dolt state.
3. No automatic session injection: Unlike claude-mem or ccmemory, there is no SessionStart hook that automatically runs bd prime. The agent must be instructed to run it.
4. Complex setup for contributors: bd init --contributor mode routes to ~/.beads-planning — multi-repo setup can confuse agents.
5. Compaction is permanent: "Graceful decay" cannot be reversed — if summaries are poor quality, original content is gone.