はじめに 🎯
AI コーディングエージェントを実務で運用していくと、必ずぶつかる壁があります。「セッションをまたいだタスクの記憶と、タスク同士の依存関係をどう管理するか」 という壁です。
Claude Code / Codex / Cursor などのエージェントは、1回のセッションでは驚くほどの作業をこなしますが、長時間の作業を任せようとすると以下のような問題が起きます。
- マークダウンの TODO リストはセッション間で同期が壊れる
- 「このタスクが先」「あれはこれの前に終わらせて」という依存関係を毎回説明し直す必要がある
- 並列エージェント運用では、同じ番号のチケットが別の意味で書き込まれて衝突する
- 古い完了タスクがコンテキスト枠を食い続ける
これらを解決するために登場したのが beads（bd） です。リポジトリの説明そのままに引用すれば「Distributed graph issue tracker for AI agents, powered by Dolt」――AI エージェント向けの 分散グラフ型イシュートラッカー で、バージョン管理付き SQL データベースの Dolt をストレージ基盤に採用しています。
GitHub リポジトリの description には「A memory upgrade for your coding agent」と添えられています。マークダウンの散らかった作業計画を、依存関係を理解したグラフに置き換え、長期的なタスクをコンテキストを失わずに扱えるようにする、というのが beads の存在意義です。
この記事で得られること:
- 🪞 マークダウン TODO が抱える限界と、beads が解決する課題
- 🏗️ Dolt をストレージにした「2層アーキテクチャ」と書き込み・読み取りの流れ
- 🛠️ 基本コマンド（
bd init/bd ready/bd update --claim/bd close）の使い方と「ready 検出」のロジック - 🕸️ 4種類の依存関係（blocks / parent-child / related / discovered-from）の使い分け
- 🧠
bd primeとbd rememberと Compaction による「永続メモリ」の設計 - 👥 並列マルチエージェント運用での衝突回避（Hash-based ID）
なぜ beads が必要か 🪞
beads の存在意義を掴むには、まず 「エージェントにマークダウン TODO を書かせると何が起きるか」 を見ておくのが早いです。
マークダウン TODO の限界
エージェントに作業を指示するとき、つい以下のような書き方をします。
# TODO
- [ ] データベースをセットアップ
- [ ] API を実装
- [ ] 認証機能を追加
これは1セッションの中では機能しますが、次のセッションでエージェントを起動すると 「どこまで終わったのか」「次に着手すべきはどれか」が曖昧 になります。さらに以下の問題があります。
- 依存関係が表現できない: 「認証機能はAPIの後」という関係を毎回口頭で説明する必要がある
- 並列実行を想定していない: 複数エージェントが同じファイルに書き込むと TODO が壊れる
- 永続的なメモリにならない: 完了タスクをいつ消すべきか、エージェントは判断できない
beads が提示する解
beads は同じ作業を 依存関係付きのグラフ として表現します。
この図のポイントは、beads が「次に何をやるべきか」を機械的に決められる ことです。bd ready というコマンドは、ブロッキング依存関係のないタスク だけを返してくれます。エージェントは「次は何？」と毎回考えなくてよく、bd ready の結果を取って bd update --claim で着手すれば、依存関係に沿った正しい順番で作業が進みます。
💡 マークダウン TODO とイシュートラッカーの最大の差は「依存関係を計算できるか」です。beads はこの計算結果（ready キュー）を、エージェントが扱いやすい JSON 形式で返してくれます。
アーキテクチャ概観 🏗️
beads の中核は、Dolt（バージョン管理付き SQL データベース） をストレージとした2層アーキテクチャです。公式ドキュメント docs/ARCHITECTURE.md ではこれを「The Two-Layer Data Model」と呼んでいます。
この図のポイントは、Dolt が「ローカル SQL データベース」と「分散同期可能なリモート」の両方を1つの実体で兼ねている ことです。普通のイシュートラッカー（GitHub Issues 等）は中央のサーバに常時接続する必要がありますが、beads は オフラインで完結し、必要なときに bd dolt push/pull で同期 という Git ライクな運用ができます。
Dolt を選んだ理由
Dolt はバージョン管理付きの SQL データベースで、以下が beads にとって都合がよい特徴です。
| Dolt の特徴 | beads にとっての価値 |
|---|---|
| ミリ秒のクエリ性能と SQL 互換 | エージェントが大量のイシューを瞬時に検索できる |
| 自動コミット（書き込みごとにバージョン履歴） | 完全な監査証跡（audit trail）が標準で得られる |
| Cell-level merge | 並列ブランチでイシューを編集しても、フィールド単位で自動マージ |
| Dolt remotes（DoltHub / S3 / GCS） | 専用同期サーバを立てる必要がない |
| ネイティブの push / pull | コードと同じ Git 的な運用感覚 |
書き込みと読み取りのパス
beads のすべてのコマンドは、ローカルの Dolt データベースを直接読み書きします。
この図のポイントは、読み書きが常にローカルで完結し、ネットワーク遅延の影響を受けない ことです。bd dolt push/pull を明示的に叩いたときだけリモートと同期するため、ネットワーク断や CI 環境でも問題なく動きます。
インストールと初期化 ⚙️
beads は システムワイドに1度インストールすれば、全プロジェクトで使える CLI ツールです。プロジェクトごとに beads リポジトリをクローンする必要はありません。
インストール方法
# 推奨: Homebrew（macOS / Linux）
brew install beads
# Node.js ユーザー
npm install -g @beads/bd
# 公式インストールスクリプト
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
Windows / Arch / Go install など他の手段は docs/INSTALLING.md を参照してください。インストール後、bd --help で疎通確認できます。
プロジェクトの初期化
プロジェクトディレクトリで bd init を実行すると、.beads/ ディレクトリと埋め込み Dolt データベースが作成されます。同時に AGENTS.md が自動生成または更新され、エージェントが beads のワークフローを発見できるようになります。
cd your-project
bd init
bd init には複数のフレーバーがあります。状況に合わせて選択してください。
| コマンド | 用途 |
|---|---|
bd init |
通常の初期化。AGENTS.md を作成・更新 |
bd init --quiet |
AI エージェント向け（対話を抑制） |
bd init --contributor |
OSS コントリビューター向け（planning を別リポジトリに分離） |
bd init --stealth |
git にコミットせずローカル利用（個人用） |
bd init --server |
Dolt サーバモード（複数書き込み可） |
bd init --skip-agents |
AGENTS.md を作らない |
エージェント別の追加セットアップ
bd setup <agent> で、各エージェント向けの詳細な指示やフックを導入できます。
bd setup codex # Codex CLI 向けに AGENTS.md を強化
bd setup claude # Claude Code 向けのフック / 設定をインストール
bd setup factory # Factory.ai Droid 向け
bd setup cursor # Cursor IDE
bd setup mux # mux 向け
対応エージェントの全リストは bd setup --list で確認できます。サポート対象外のエージェントを使う場合は bd onboard を実行し、表示されたスニペットを手動でエージェントの指示ファイルにペーストします。
この図のポイントは、「インストール → init → setup」の3ステップで主要エージェントに対応できる ことです。bd init の段階で AGENTS.md が用意されるので、最小構成ならその時点で動き始めます。
基本コマンドと「ready」フロー 🛠️
beads の使い方は、シンプルな数個のコマンドに集約されます。エージェントが日常的に叩くコマンドはこれです。
Essential Commands
| コマンド | 動作 |
|---|---|
bd ready |
ブロッキング依存関係のないタスクを一覧表示 |
bd create "Title" -p 0 |
P0（critical）優先度でタスクを作成 |
bd update <id> --claim |
タスクをアトミックに claim（assignee 設定 + in_progress化） |
bd dep add <child> <parent> |
依存関係（blocks / related / parent-child）を追加 |
bd show <id> |
タスクの詳細と監査ログを表示 |
bd close <id> "reason" |
タスクを閉じる |
bd prime |
エージェント向けのワークフロー context と永続メモリを出力 |
bd remember "insight" |
プロジェクトメモリとして永続保存（次回の bd prime で注入される） |
典型的なフロー
たとえば「DB セットアップ → API 実装 → 認証機能追加」という3タスクを並べる場合、こうなります。
# 1. タスク作成
bd create "Set up database" -p 1 -t task
bd create "Create API" -p 2 -t feature
bd create "Add authentication" -p 2 -t feature
# 2. 依存関係を貼る（bd-2 は bd-1 に blocked、bd-3 は bd-2 に blocked）
bd dep add bd-2 bd-1
bd dep add bd-3 bd-2
# 3. ready なタスクを確認
bd ready
# → bd-1 のみが返る（bd-2 と bd-3 はブロックされている）
# 4. 着手
bd update bd-1 --claim
# 5. 完了
bd close bd-1 --reason "Database setup complete"
# 6. もう一度 ready 確認
bd ready
# → bd-2 が ready になる
ステータスとプライオリティ
イシューの ステータス遷移 は次のとおりです。
この図のポイントは、open in_progress closed の基本3状態に加えて、blocked / deferred / tombstone / pinned / hooked といった補助ステータスが揃っている ことです。blocked は依存関係の計算結果として自動で付与されるため、エージェントは「これは今やれるか」を考えずに bd ready の結果だけ見れば判断できます。
優先度（priority）は 0〜4 の整数値 で、0 が critical / 4 が backlog です。Issue type も豊富で、bug / feature / task / epic / chore / message / merge-request / molecule / gate / agent / role / convoy から選べます。
💡
bd ready --explainを使うと、なぜそのタスクが ready なのか／なぜ他のタスクが ready でないのかを表示してくれます。デバッグ用に便利です。
依存関係グラフ 🕸️
beads の真価は 依存関係を4種類のタイプで使い分けられる ところにあります。
4種類の依存タイプ
| タイプ | 意味 |
bd ready への影響 |
|---|---|---|
blocks |
X が close するまで Y は始められない | あり（最も強い縛り） |
parent-child |
エピック↔サブタスクの階層関係 | あり（親がブロックなら子もブロック） |
related |
参考リンク程度のソフトな関連 | なし |
discovered-from |
作業中に派生して見つかった | なし |
この図のポイントは、blocks と parent-child だけが ready 計算に影響を与え、related と discovered-from は「情報リンク」として扱われる ことです。後者の2つは「ナレッジグラフ」を構築するための弱い関連で、ready キューを汚しません。
階層 ID（hierarchical IDs）
beads は階層的な ID もサポートしています。
-
bd-a3f8― Epic -
bd-a3f8.1― Task（Epic の子） -
bd-a3f8.1.1― Sub-task（Task の子）
ID を見ただけで階層構造が分かるので、エージェントへの説明コストが下がります。
💡 「分析中に見つけた」というケースに
discovered-fromを使うと、ready キューに混入させずにナレッジとして残せます。実装中に脱線して見つけたバグや改善点を雑に拾うのに便利です。
メモリの仕組み 🧠
beads が「memory upgrade」と自称しているとおり、永続メモリ機能は中核機能の1つです。3つの仕組みが連携します。
bd prime ― エージェントへの context 注入
bd prime は、エージェントが新しいセッションを始めるときに 最初に叩くべきコマンド です。これを実行すると以下が出力されます。
- 現在のプロジェクトの beads ワークフロー context
- 使えるコマンドのガイダンス
- 過去に
bd rememberで保存した永続メモリ
エージェントはこれを読み込むことで、前回のセッションで得た知見を引き継いだ状態 で作業を始められます。
bd remember ― 永続メモリの保存
bd remember "FastAPI のバージョンは 0.115。3.13 では asyncio の挙動が変わる"
セッション中に得た洞察を bd remember で保存すると、それが Dolt データベースに永続化され、次回以降の bd prime で自動的に再注入されます。
💡 公式のセットアップ手順では「MEMORY.md ファイルを作るな」と明示されています。beads がメモリ管理を担うため、二重管理になるのを避ける設計です。
Compaction ― 「semantic memory decay」
長期間運用していると、過去に閉じたタスクが膨大になり、エージェントのコンテキスト枠を圧迫します。beads はこれに対し Compaction（圧縮） と呼ぶ仕組みで、古いクローズ済みタスクを 意味的に要約 して保持します。
この図のポイントは、「古いタスクを完全に捨てるのではなく、要約として残す」 という設計思想です。完全な履歴は Dolt のバージョン管理に残っているため、必要なら遡れます。直近の作業のコンテキストだけを軽く保ちながら、過去のナレッジも失わない、というバランスを取っています。
マルチエージェント運用 👥
複数のエージェント、複数のブランチで同時にタスクを書き込むと、普通のシーケンシャル ID では衝突が起きます。beads はこれを Hash-based ID で構造的に防いでいます。
Hash-based ID による衝突回避
シーケンシャル ID の問題はこうです。
beads はこれを ランダム UUID 由来の短いハッシュ ID に置き換えています。
ID 長は当初4文字（例: bd-a1b2）から始まり、データベースが大きくなるにつれ 5文字・6文字へ段階的に伸びる 仕組みです。衝突確率の数学的根拠は docs/COLLISION_MATH.md に「誕生日のパラドックス」計算として記載されています。
Cell-level merge とコンテンツハッシュ
同じ ID のイシューが別ブランチで編集されたときも、Dolt の cell-level merge で フィールド単位 にマージされます。さらに各イシューには コンテンツハッシュ が振られており、マージロジックはこう動きます。
- 同じ ID + 同じハッシュ → スキップ（既に同一）
- 同じ ID + 異なるハッシュ → 更新（新しいバージョンとして取り込み）
- 新しい ID → 作成
中央サーバを介さずに、すべての参加者が同じ最終状態に収束する設計です。
Stealth Mode と Contributor Mode
マルチエージェント運用で便利な2つのモードを紹介します。
-
bd init --stealth: git にコミットせず、ローカルに.beads/だけ持つ運用。共有プロジェクトで個人的に使いたいときに便利 -
bd init --contributor: OSS コントリビューターが planning issue を別リポジトリ（例:~/.beads-planning）にルーティングし、PR に混入させない
💡 メンテナー / コントリビューターの自動判定は、SSH URL か HTTPS の認証情報の有無で決まります。HTTPS で書き込み権限があるのに自動判定されないときは
git config beads.role maintainerを明示的に設定します。
ストレージモードと同期 💾
beads のストレージは2モードあります。
Embedded Mode（デフォルト）
bd init
Dolt をプロセス内で動かす単一書き込みモード。データは .beads/embeddeddolt/ に保持されます。ほとんどのユーザーはこのモードでよい とドキュメントは推奨しています。
Server Mode
bd init --server
外部の dolt sql-server に接続して 複数書き込みを許容 するモード。データは .beads/dolt/ に格納されます。接続は CLI フラグまたは環境変数で指定します。
| Flag | Env Var | デフォルト |
|---|---|---|
--server-host |
BEADS_DOLT_SERVER_HOST |
127.0.0.1 |
--server-port |
BEADS_DOLT_SERVER_PORT |
3307 |
--server-socket |
BEADS_DOLT_SERVER_SOCKET |
（なし、TCP 使用） |
--server-user |
BEADS_DOLT_SERVER_USER |
root |
Unix ドメインソケットも --server-socket で指定可能で、ポート競合を避けたいときや Claude Code のようなサンドボックス環境で有効です。
バックアップとマイグレーション
# バックアップ先を設定して push
bd backup init /path/to/backup
bd backup sync
# 新規プロジェクトに復元
bd init # または bd init --server
bd backup restore --force /path/to/backup
bd backup は Dolt ネイティブのバックアップ機能で、コミット履歴も含めて保存・復元できます。bd export を使うと JSONL 形式での書き出しもできるため、他システムへの移行や互換性確保にも使えます。
Notion 連携
beads は Notion との同期も提供しています。
bd config set notion.token <token>
bd notion init --parent <page-id>
bd notion sync --dry-run # プレビュー
bd notion sync # 実際の同期
エージェントは beads で機械的に作業し、人間は Notion で全体を眺める、というハイブリッド運用がやりやすくなります。
まとめ 🏁
beads の本質を3つに絞ります。
| # | キーメッセージ |
|---|---|
| ① | 依存関係を理解したグラフ で、AI エージェントは「次に何をすべきか」を機械的に判断できる。マークダウン TODO の限界を超えるための土台 |
| ② | Dolt をストレージにすることで、バージョン管理・cell-level merge・分散同期がすべて1つの実体で得られる。中央サーバ不要 |
| ③ | Hash-based ID と Compaction が、マルチエージェント並列運用と長期メモリ管理の両方を同時に解決する |
明日から試すなら
最初の一歩は、こう進めるのを推奨します。
-
インストール:
brew install beads（またはnpm install -g @beads/bd） -
小さなプロジェクトで初期化:
cd your-project && bd init -
エージェント連携を設定:
bd setup claude/bd setup codexなど、使っているエージェントに合わせて -
タスクを3個ほど作って依存関係を貼る:
bd create→bd dep add→bd readyで挙動を確認 -
bd rememberで永続メモリを試す: セッションを再起動してbd primeで再注入されることを体感する
おわりに
AI エージェントを「ぶっつけ本番のチャット」から「組織で運用できるシステム」へ引き上げるには、永続メモリ × 依存関係グラフ という土台がいります。beads はその土台を、インストール1回・コマンド数個 という低い摩擦で提供してくれます。
完璧なツールではありません。Notion との同期、Dolt のリモート選択、Stealth/Contributor の使い分けなど、運用には学習コストがそれなりにあります。それでも、長時間の自律作業や複数エージェント並列運用を本気でやろうとするなら、検討する価値のある選択肢 だと感じています。
参考
- gastownhall/beads ― 公式リポジトリ
- Beads Documentation Site ― 公式ドキュメントサイト
- Quick Start ― 公式クイックスタート
- docs/ARCHITECTURE.md ― 2層アーキテクチャの詳細
- Dolt ― ストレージ基盤となるバージョン管理付き SQL データベース