Beads：AI智能体持久化任务记忆工具 - 基于图的多会话工作流管理

beads by steveyegge/beads

425 周安装量

19,700 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/steveyegge/beads --skill beads

AI/机器学习项目管理自动化

🇨🇳中文介绍

Beads - AI 智能体的持久化任务记忆

基于图的问题跟踪器，可在对话压缩后持久保存。为具有复杂依赖关系的多会话工作提供持久化记忆。

bd 与 TodoWrite 对比

决策测试："我两周后还需要这个上下文吗？" 是 = bd，否 = TodoWrite。

bd (持久化)	TodoWrite (临时性)
多会话、依赖关系、压缩后存活	单会话线性任务
基于 Dolt 的团队同步	会话作用域

详细对比请参阅 BOUNDARIES.md。

先决条件

bd --version  # 需要 v0.60.0+

bd CLI 已安装并在 PATH 中
Git 仓库 (可选 — 使用 BEADS_DIR + --stealth 实现无需 Git 的操作)
初始化：运行一次 (由人类执行，非智能体)

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

749,400 周安装

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

103,800 周安装

AI Elements：基于shadcn/ui的AI原生应用组件库，快速构建对话界面

53,500 周安装

基本命令：bd ready、bd create、bd show、bd update、bd close、bd dolt push

bd ready — 查找未阻塞的工作
bd show <id> — 获取完整上下文
bd update <id> --claim — 原子性地认领并开始工作
工作时添加笔记 (对压缩后存活至关重要)
bd close <id> --reason "..." — 完成任务
bd dolt push — 推送到 Dolt 远程仓库 (如果已配置)

在任何命令后附加 --json 以获取结构化输出。使用 bd show <id> --long 获取扩展元数据。状态图标：○ 开放 ◐ 进行中 ● 已阻塞 ✓ 已关闭 ❄ 已延期。

错误	修复方法
`database not found`	在项目根目录运行 `bd init <prefix>`
`not in a git repository`	先运行 `git init`
`disk I/O error (522)`	将 `.beads/` 移出云同步文件系统
状态更新延迟	使用服务器模式：`bd dolt start`

功能	CLI	资源
分子 (模板)	`bd mol --help`	MOLECULES.md
化学 (pour/wisp)	`bd pour`, `bd wisp`	CHEMISTRY_PATTERNS.md
智能体珠子	`bd agent --help`	AGENTS.md
异步门	`bd gate --help`	ASYNC_GATES.md
工作树	`bd worktree --help`	WORKTREES.md

类别	文件
入门指南	BOUNDARIES.md, CLI_REFERENCE.md, WORKFLOWS.md
核心概念	DEPENDENCIES.md, ISSUE_CREATION.md, PATTERNS.md
恢复能力	RESUMABILITY.md, TROUBLESHOOTING.md
高级功能	MOLECULES.md, CHEMISTRY_PATTERNS.md, AGENTS.md, ASYNC_GATES.md, WORKTREES.md
参考	STATIC_DATA.md, INTEGRATION_PATTERNS.md

🇺🇸English

Beads - Persistent Task Memory for AI Agents

Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.

bd vs TodoWrite

Decision test : "Will I need this context in 2 weeks?" YES = bd, NO = TodoWrite.

bd (persistent)	TodoWrite (ephemeral)
Multi-session, dependencies, compaction survival	Single-session linear tasks
Dolt-backed team sync	Conversation-scoped

See BOUNDARIES.md for detailed comparison.

Prerequisites

bd --version  # Requires v0.60.0+

bd CLI installed and in PATH
Git repository (optional — use BEADS_DIR + --stealth for git-free operation)
Initialization : bd init run once (humans do this, not agents)

CLI Reference

Runbd prime for AI-optimized workflow context (auto-loaded by hooks). Runbd <command> --help for specific command usage.

Essential commands: bd ready, bd create, bd show, bd update, bd close, bd dolt push

Session Protocol

bd ready — Find unblocked work
bd show <id> — Get full context
bd update <id> --claim — Claim and start work atomically
Add notes as you work (critical for compaction survival)
bd close <id> --reason "..." — Complete task
bd dolt push — Push to Dolt remote (if configured)

Output

Append --json to any command for structured output. Use bd show <id> --long for extended metadata. Status icons: ○ open ◐ in_progress ● blocked ✓ closed ❄ deferred.

Error Handling

Error	Fix
`database not found`	`bd init <prefix>` in project root
`not in a git repository`	`git init` first
`disk I/O error (522)`	Move `.beads/` off cloud-synced filesystem
Status updates lag	Use server mode: `bd dolt start`

See TROUBLESHOOTING.md for full details.

Examples

Track a multi-session feature:

bd create "OAuth integration" -t epic -p 1 --json
bd create "Token storage" -t task --deps blocks:oauth-id --json
bd ready --json                    # Shows unblocked work
bd update <id> --claim --json      # Claim and start
bd close <id> --reason "Implemented with refresh tokens" --json

Recover after compaction: bd list --status in_progress --json then bd show <id> --long

Discover work mid-task: bd create "Found bug" -t bug -p 1 --deps discovered-from:<current-id> --json

Advanced Features

Feature	CLI	Resource
Molecules (templates)	`bd mol --help`	MOLECULES.md
Chemistry (pour/wisp)	`bd pour`, `bd wisp`	CHEMISTRY_PATTERNS.md
Agent beads	`bd agent --help`	AGENTS.md
Async gates

Resources

Category	Files
Getting Started	BOUNDARIES.md, CLI_REFERENCE.md, WORKFLOWS.md
Core Concepts	DEPENDENCIES.md, ISSUE_CREATION.md, PATTERNS.md
Resilience	RESUMABILITY.md, TROUBLESHOOTING.md
Advanced	, , , ,

Validation

If bd --version reports newer than 0.60.0, this skill may be stale. Run bd prime for current CLI guidance — it auto-updates with each bd release and is the canonical source of truth (ADR-0001).

Weekly Installs

425

Repository

steveyegge/beads

GitHub Stars

19.7K

First Seen

Jan 30, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode413

codex410

github-copilot407

gemini-cli406

amp400

kimi-cli398