gastownhall/beads

Beads - A memory upgrade for your coding agent

What it solves

Beads provides a persistent, structured memory and issue tracking system specifically designed for AI agents. It replaces unstructured markdown-based plans with a dependency-aware graph, preventing agents from losing context during long-horizon tasks and eliminating the need for messy TODO lists.

How it works

Beads uses a version-controlled SQL database (powered by Dolt) to store tasks and memories. It operates as a CLI tool that agents can use to create, claim, and close tasks while tracking dependencies (e.g., blocks, relates-to). It integrates with various AI agents (like Claude Code, Codex, and Factory.ai) by providing structured JSON output and a bd prime command that injects necessary workflow context and persistent memories into the agent's prompt.

Who it’s for

Developers and AI agent orchestrators who want to move beyond simple text files for task management and provide their agents with a reliable, version-controlled knowledge graph of project progress.

Highlights

  • Dolt-Powered Storage: Uses a version-controlled SQL database with cell-level merge and native branching for zero-conflict multi-agent workflows.
  • Agent-Optimized: Features JSON output and auto-detection of "ready" tasks (those with no open blockers).
  • Semantic Memory Decay: Includes a compaction feature that summarizes old closed tasks to save context window space.
  • Flexible Deployment: Supports both embedded and server-based storage modes and can operate entirely without Git.
  • Hierarchical Tasking: Supports epics and sub-tasks via hierarchical IDs (e.g., bd-a3f8.1.1).