gastownhall

beads

AI#AI Agents#Dolt#CLI#Task Tracking#Database

// summary

Beads is a distributed, Dolt-powered issue tracking system designed specifically to provide persistent memory for AI coding agents. It utilizes a dependency-aware graph structure to manage complex, long-horizon tasks while preventing merge conflicts through hash-based identifiers. The tool offers flexible storage modes and integrates seamlessly into development workflows without requiring repository-level git operations.

// technical analysis

Beads (bd) is a distributed graph-based issue tracker designed specifically to provide persistent, structured memory for AI coding agents. By leveraging Dolt as its underlying version-controlled SQL database, it enables dependency-aware task management that allows agents to maintain context over long-horizon projects. The architecture prioritizes agent-friendly interactions, such as JSON output and hash-based task identification, effectively replacing unstructured markdown plans with a robust, mergeable data structure.

// key highlights

Utilizes Dolt as a version-controlled SQL backend to provide cell-level merging and native branching capabilities.

Implements hash-based task IDs to ensure zero-conflict workflows across multiple agents and branches.

Features semantic memory compaction that summarizes closed tasks to optimize the context window for AI agents.

Supports a hierarchical task structure, allowing for the organization of epics, tasks, and sub-tasks.

Offers a stealth mode for local-only usage, enabling task tracking without modifying the host repository's file structure.

Provides flexible storage modes, including an embedded single-writer mode and a server mode for concurrent multi-writer access.

// use cases

Persistent, dependency-aware task tracking for AI coding agents

Conflict-free issue management in multi-agent or multi-branch workflows

Semantic memory compaction to optimize context window usage

// getting started

To begin, install the Beads CLI using the provided install script or via Homebrew/npm. Once installed, navigate to your project directory and run 'bd init' to initialize the local database. You can then start managing tasks using commands like 'bd create' and 'bd ready', or configure your agent to interact with the system by updating your project's AGENTS.md file.