Beads: The Agent Memory System That Inspired Claude Code Tasks

The 50 First Dates Problem

Coding agent sessions last about ten minutes. When the session ends, everything the agent learned disappears. The next session starts from scratch. You re-explain the project structure, re-describe the bug, re-establish which files matter. Steve Yegge, ex-Amazon, ex-Google, and ex-Sourcegraph, spent a year dealing with this before building Beads.

The standard workaround is a markdown plan file. Write a TODO.md, point the agent at it, and hope for the best. Yegge found this breaks fast: "All they know is what's on disk. If you got competing documents, obsolete documents, conflicting documents... they get dementia."

Markdown plans have no dependencies, no priority ordering, no machine-readable structure, and no compaction strategy. An agent reading a 2,000-line plan file wastes context on closed items and stale notes. The plan file becomes the problem it was supposed to solve.

What Beads Is

Beads (bd) is a dependency-aware issue tracker that stores structured tasks in your git repository. Each task has a hash-based ID (like bd-a3f2), a priority level, a status, and typed dependency links to other tasks. The agent queries Beads at session start, gets back the highest-priority unblocked work, and begins.

Yegge describes it as "orchestration for what you're working on today and this week." It is not a project management tool. It is not Jira. It is a machine-readable memory layer that tells an agent: here is what to do next, here is what blocks it, and here is what you did yesterday.

Architecture: SQLite + JSONL + Git

Beads uses a dual-storage model. SQLite (.beads/beads.db) handles fast local queries. JSONL (.beads/issues.jsonl) is the git-tracked source of truth that syncs across machines. A background daemon synchronizes the two with a 5-second debounce on JSONL exports.

Hash-based IDs prevent merge collisions when multiple agents or branches touch the same Beads database. This is the key architectural bet: treating git as the distributed database protocol means Beads gets branching, merging, and conflict resolution for free.

The project is migrating to a Dolt backend for version-controlled SQL with cell-level merge and native branching. This would replace the SQLite+JSONL dual model with a single storage layer that has git-like semantics built into the database itself.

Key Commands

Beads is CLI-first. Every command supports --json for machine consumption. Agents interact through the CLI; humans can use the CLI or one of the community-built UIs.

# Initialize Beads in a project
bd init
bd setup claude    # Configure for Claude Code

# Create work items
bd create "Refactor auth module" -t epic -p 1 --description="Split monolith"
bd create "Extract JWT validation" -p 2 --parent bd-a3f2

# Session start: find what to work on
bd ready           # Shows open issues with no unmet dependencies

# During work
bd update bd-a3f2 --status in_progress
bd show bd-a3f2    # Full issue details + dependencies

# Session end
bd close bd-a3f2 --reason "JWT extraction complete"
bd compact         # Summarize old closed issues to save context
bd sync            # Export to JSONL for git

# Inspect the dependency graph
bd dep tree bd-a3f2 --direction=both
bd stats           # Total issues, open, closed

The bd ready command is the critical one. It resolves the dependency graph and returns only issues that are unblocked and ready for work. An agent starting a new session runs bd ready, picks the top result, and has full context without any human re-explanation.

The Land the Plane Protocol

Session handoffs are where most agent workflows break. The agent does good work, hits the context limit, and the next session has no idea what happened. Beads defines a formal "Land the Plane" protocol for session ends:

One developer using this protocol reported refactoring 315 frontend files in a single 12-hour session while doing other things on the side. The agent worked through compaction cycles, checked Beads for context after each one, and maintained coherence across the full run.

Beads vs Claude Code Tasks

An Anthropic engineer explicitly credited Beads as inspiration for Claude Code's Tasks system. The paddo.dev analysis frames this as the "pattern-to-product cycle": community project solves a real problem, platform vendor productizes it.

But Tasks and Beads are not competitors. They operate at different layers.

Where Beads Fits in the Agent Memory Hierarchy

Production coding agents now implement a recognizable memory hierarchy that mirrors CPU cache design. Beads occupies L2: persistent project state that loads on demand.

L1 is tiny but always present. L2 (Beads) is larger and queried at session boundaries. L3 is the live context window, where context rot becomes the primary challenge. L4 is the full codebase, accessed through search tools.

The key insight from this hierarchy: L2 memory (Beads/Tasks) only works if L3 operations are reliable. If the agent loses accuracy when applying edits within a session, the session state it writes back to Beads is corrupted. Memory systems need accurate execution underneath them.

Honest Limitations

Beads is not magic. Yegge himself calls it "a crummy architecture (by pre-AI standards) that requires AI in order to work around all its edge cases." The community has identified several real limitations:

The 29-contributor community is actively building around these edges. VS Code extensions, Emacs modes, Neovim plugins, web dashboards, and multi-agent orchestration layers all exist. The protocol-first design (stable CLI with --json output, JSONL source of truth) makes this possible.

Where Morph Fits: Reliable Edits for Long-Running Workflows

Beads solves the memory problem. It does not solve the execution problem. When an agent picks up a task from Beads and applies a code change, that edit needs to land correctly. A misapplied diff corrupts not just the file but the session state the agent writes back to Beads.

This is where fast apply models become critical infrastructure. Morph processes file edits at 10,500 tokens per second with sub-200ms latency. When an agent is working through a Beads queue of 20 tasks across 12 hours, each edit needs to be fast enough to not bottleneck the workflow and accurate enough to not corrupt the chain.

The combination works like this: Beads tells the agent what to do. The reasoning model (Claude, GPT) figures out the change. Morph applies it to the file. The agent verifies, updates Beads, and moves to the next task. Each layer does one thing.

Getting Started with Beads

# Install (requires Go)
git clone https://github.com/steveyegge/beads.git
cd beads
go install ./cmd/bd

# Initialize in your project
cd /path/to/your/project
bd init

# Configure for your agent
bd setup claude    # Adds Beads instructions to CLAUDE.md
bd onboard         # Interactive setup wizard

# Verify it works
bd stats
bd ready

After setup, add session bookend instructions to your CLAUDE.md or agent config:

## Beads Workflow

At session start:
1. Run `bd ready` to find highest-priority unblocked work
2. Run `bd show <id>` for full context on the chosen task
3. Update status: `bd update <id> --status in_progress`

At session end (Land the Plane):
1. Run quality gates (lint, test, typecheck)
2. Create new issues for discovered work
3. Close completed issues with `bd close <id> --reason "..."`
4. Run `bd sync` to export state
5. Commit and push

The GitHub repo has detailed quickstart docs, FAQ, and agent-specific configuration guides. The community maintains web UIs (npx beads-ui), TUI interfaces (lazybeads), and editor integrations for VS Code, Emacs, and Neovim.

FAQ

What is Beads for coding agents?

Beads is a git-backed issue tracker built for AI coding agents by Steve Yegge. It stores tasks, dependencies, and agent memory as JSONL files in a .beads/ directory committed to git. When a new session starts, the agent queries Beads to find unblocked work and resumes without re-explanation. It has 17.9K GitHub stars and inspired Claude Code's Tasks system.

How is Beads different from Claude Code Tasks?

Beads operates at project scope and stores memory in git, making it agent-agnostic and persistent across weeks. Claude Code Tasks operates at session scope and stores data in ~/.claude/tasks/. Tasks handles immediate coordination; Beads handles long-term project memory. You can use both without conflict.

Does Beads work with agents other than Claude Code?

Yes. Beads works with Claude Code, OpenAI Codex, Sourcegraph AMP, Cursor, and any agent that reads files. The CLI outputs JSON, and the JSONL format is universal. This agent-agnostic design is one of its main advantages over platform-specific memory systems.

What is the Land the Plane protocol?

A session-end protocol where the agent runs quality gates, files discovered work as new issues, closes finished items, syncs state with bd sync, and generates a handoff prompt for the next session. It prevents context loss between sessions.

Is Beads production-ready?

It is in active use by thousands of developers. Yegge honestly calls it "a crummy architecture (by pre-AI standards) that requires AI in order to work around all its edge cases." The 29-contributor community is building tooling fast: web UIs, editor integrations, and multi-agent orchestration layers. The core is stable; the ecosystem is still maturing.

Do I need Beads if I already use Claude Code Tasks?

Tasks handles within-session coordination. If your work fits inside a single Claude Code session or a few coordinated terminals, Tasks is sufficient. If you need memory that survives across weeks, works with multiple agents, or lives in the git repo alongside your code, add Beads.