-
Notifications
You must be signed in to change notification settings - Fork 1.7k
Home
persistent, structured memory for coding agents
Beads is a distributed graph issue tracker for AI agents, powered by Dolt. It replaces messy markdown plans with a dependency-aware task graph, giving agents the persistent memory they need to handle long-horizon work without losing context.
# Install the Beads CLI (system-wide — don't clone this repo into your project)
brew install beads
# Initialize in YOUR project
cd your-project
bd init
# Optional: set up richer agent integration
bd setup codex # Codex CLI
bd setup claude # Claude Code
bd setup factory # Factory.ai DroidBeads is a CLI tool you install once and use everywhere. bd init creates or updates AGENTS.md so agents can discover the Beads workflow automatically.
See the Docs site and README for the full installation guide.
| Feature | Description |
|---|---|
| Dolt-Powered | Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes |
| Agent-Optimized | JSON output, dependency tracking, and auto-ready task detection |
| Zero Conflict | Hash-based IDs (e.g. bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows |
| Compaction | Semantic "memory decay" summarizes old closed tasks to save context window |
| Messaging | Message issue type with threading, ephemeral lifecycle, and mail delegation |
| Graph Links |
relates_to, duplicates, supersedes, and replies_to for knowledge graphs |
| Command | Action |
|---|---|
bd ready |
List tasks with no open blockers |
bd create "Title" -p 0 |
Create a P0 task |
bd update <id> --claim |
Atomically claim a task (sets assignee + in_progress) |
bd dep add <child> <parent> |
Link tasks (blocks, related, parent-child) |
bd show <id> |
View task details and audit trail |
bd prime |
Print agent workflow context and persistent memories |
bd remember "insight" |
Store project memory that bd prime injects later |
Embedded Mode (default): Dolt runs in-process — no external server needed. Data lives in .beads/embeddeddolt/. Single-writer only. Recommended for most users.
Server Mode: Connects to an external dolt sql-server. Supports multiple concurrent writers. Initialize with bd init --server.
🗺️ Roadmap
The forward-looking plan for Beads' evolution. Current focus areas include server v2 implementation, CI coverage improvements, schema redesign, and a stable Beads v2.0.0 release. All aspirational — community input welcomed!
We'd love your help! Read CONTRIBUTING.md before opening a PR.
Issues, feature requests, and discussion are all welcome. Join us on Discord to connect with the community.
Beads is MIT licensed. Built with ☕ by gastownhall and contributors.