Beads: A Dolt-Backed Issue Graph That Gives Coding Agents a Real Memory

What Beads Actually Solves

Coding agents like Codex or Claude Code often start a task, lose context, and then drift. Markdown plans and TODO lists are flat, so an agent cannot see which tasks block others or what work is ready to claim. Beads gives those agents a persistent, structured memory: a graph of issues where every task has dependencies, a status, and an audit trail. The README frames it directly: it replaces messy markdown plans with a dependency-aware graph, so agents can handle long-horizon tasks without losing context. The target user is a developer who runs an AI agent on a real project and wants that agent to remember what it was doing, what is blocked, and what to pick up next. It is not a general-purpose issue tracker for humans, though the CLI works fine for that too. The core insight is that agents need machine-readable state, not prose.

The Dolt-Backed Graph: How State Moves

Beads stores everything in Dolt, a version-controlled SQL database with cell-level merge and native branching. That choice is what makes the graph distributed. Each issue is a row, each dependency is an edge, and the whole graph is a database you can push and pull with `bd dolt push` and `bd dolt pull`. The README's flowchart shows the lifecycle: `bd create` makes a bead, it enters the dependency graph, `bd ready` lists claimable work, `bd update --claim` assigns it, and `bd close` marks it done, which releases blockers and makes new work ready. Hash-based IDs like `bd-a1b2` prevent merge collisions when multiple agents or branches write to the same graph. That is a real design win: you do not need a central server to coordinate agents, you just need a shared Dolt remote. The graph also supports hierarchical IDs for epics (`bd-a3f8`), tasks (`bd-a3f8.1`), and sub-tasks (`bd-a3f8.1.1`), which gives structure to large plans without forcing a separate tool.

Getting Started: Install, Init, and Agent Setup

Installation is deliberately simple. The README recommends `brew install beads` on macOS or Linux, or `npm install -g @beads/bd` for Node.js users. There is also a curl install script that verifies release checksums before install, which is a good security habit. You do not clone the Beads repo into your project; you install the CLI once and run `bd init` in each project. That command creates or updates `AGENTS.md` so agents can discover the workflow, and it installs integrations for Codex, Claude Code, and others. You can skip those with `--skip-agents` or `--stealth`. For agents not covered by `bd setup`, the README gives a minimal `AGENTS.md` snippet: run `bd prime` for workflow context, use `bd ready`, `bd show <id>`, `bd update <id> --claim`, `bd close <id>`, and `bd remember` for persistent memory. A key command is `bd remember "insight"`, which stores a memory that `bd prime` injects later, so the agent's context window is not cluttered with stale notes.

Storage Modes and Concurrency Trade-offs

Beads has two storage modes, and the choice matters. The default is embedded mode: Dolt runs in-process, data lives in `.beads/embeddeddolt/`, and it is single-writer. That is fine for one agent on one machine, but it means two agents cannot write to the same embedded database at the same time. The alternative is server mode, `bd init --server`, which connects to an external `dolt sql-server` for multiple concurrent writers. The README recommends embedded for most users, which is honest but also a hint that concurrency is not the default. If you run multiple agents in parallel on the same repository, you need server mode or you need to rely on push/pull sync with a remote. The single-writer constraint is a real limitation for teams that expect simultaneous edits, and the README does not hide it. The trade-off is between simplicity and scale, and for a single-agent workflow, embedded is probably the right call.

Stealth Mode and Contributor Workflows

Two workflow flags show Beads is designed for real-world collaboration. `bd init --stealth` runs Beads locally without committing files to the main repo, which is useful for personal use on shared projects where you do not want to pollute the repository with your planning data. The README calls this "git-free usage," and it points to a dedicated section in the docs. For open-source contributors, `bd init --contributor` routes planning issues to a separate repo, for example `~/.beads-planning`, so your experimental work stays out of pull requests. Maintainers get auto-detection via SSH URLs or HTTPS with credentials, or they can set `git config beads.role maintainer` manually. This is a thoughtful split: contributors and maintainers have different write permissions, and Beads adapts without forcing a single workflow. The stealth mode is particularly useful if you want to keep your agent's planning memory private while still tracking issues in the shared repo.

Upgrade and Maintenance: Not Just a Binary Swap

The README is explicit that upgrading Beads is not always a simple binary replacement. The short version: sync remote-backed databases with your current `bd`, back up with `bd export --all`, upgrade the binary, then run `bd info --whats-new`, `bd hooks install`, and `bd version`. If the upgrade crosses a schema migration on a remote-backed database, exactly one designated clone runs `bd migrate` and `bd dolt push`, while other clones install the new binary and run `bd bootstrap`. That is a multi-step process that requires planning, especially if you have multiple clones. The good news is the README points to a full upgrade guide, so the steps are documented. The maintenance cost is not zero: you need to keep your Dolt remotes in sync, handle schema migrations, and reinstall hooks after upgrades. This is a tool that expects you to understand its data layer, not a fire-and-forget SaaS.

Limitations and Wrong Use Cases

Beads is not a fit for every scenario. The single-writer embedded mode is a bottleneck if you have multiple agents or humans writing to the same project simultaneously. The CLI is text-based, so there is no visual board or web UI; if your team needs a graphical issue tracker, Beads will feel bare. The dependency graph is powerful, but it requires agents to actually use the commands; if your agent ignores `AGENTS.md` and falls back to markdown TODOs, you get no benefit. The README warns agents not to create `MEMORY.md` files, but that is a behavioral rule, not a technical enforcement. Also, the project is young (recent releases are v1.2.x), so the API and storage format may change between versions, and the upgrade process is more involved than a typical CLI. For a solo developer with one agent, those limitations are minor; for a team with concurrent agents, they are deal-breakers unless you adopt server mode.

Alternatives and How Beads Differs

The obvious alternative is a plain markdown file or a TODO list in the repository, which is what Beads explicitly replaces. The difference is structural: markdown is flat and has no dependency edges, so an agent cannot tell what is blocked or ready. Another alternative is a traditional issue tracker like GitHub Issues, which has a web UI and API but is not designed for agent memory or local sync. Beads differs by storing state in Dolt, which gives you versioning, branching, and cell-level merge, so you can sync across machines without a central service. A third alternative is a dedicated agent memory tool like Mem0 or Zep, but those focus on conversational memory, not task graphs. Beads is closer to a task database with memory injection (`bd prime`), which is a different niche. If you already use GitHub Issues, Beads adds a local, graph-based layer that can sync back to the remote via Dolt, but it does not integrate with GitHub's API directly.

Editorial conclusion

Adopt Beads if you run an AI coding agent (Codex, Claude Code, Factory) on projects with long-horizon tasks and you want to replace markdown plans with a structured, dependency-aware graph that syncs across machines. Skip it if you need a traditional human-facing issue tracker with rich UI, or if you cannot accept a single-writer embedded database or the extra Dolt sync steps. Before adopting, verify the upgrade path for your remote-backed databases, confirm the Dolt server mode fits your concurrency needs, and check the checksums for your platform. Beads is a young tool, so test it on a non-critical project first.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes