beads

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Beads - Persistent Task Memory for AI Agents

Beads - AI Agent的持久化任务记忆工具

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

基于图结构的问题追踪工具，可在对话压缩后保留数据。为存在复杂依赖的跨会话工作提供持久化记忆支持。

bd vs TodoWrite

bd (persistent)	TodoWrite (ephemeral)
Multi-session work	Single-session tasks
Complex dependencies	Linear execution
Survives compaction	Conversation-scoped
Git-backed, team sync	Local to session

Decision test: "Will I need this context in 2 weeks?" → YES = bd

When to use bd:

Work spans multiple sessions or days
Tasks have dependencies or blockers
Need to survive conversation compaction
Exploratory/research work with fuzzy boundaries
Collaboration with team (git sync)

When to use TodoWrite:

Single-session linear tasks
Simple checklist for immediate work
All context is in current conversation
Will complete within current session

bd（持久化）	TodoWrite（临时）
跨会话工作	单会话任务
复杂依赖管理	线性执行
可在对话压缩后保留数据	会话范围内有效
基于Git，支持团队同步	仅会话本地有效

决策测试：“两周后我还需要这个上下文吗？” → 是 = 使用bd

何时使用bd:

工作跨多个会话或多天
任务存在依赖项或阻塞项
需要在对话压缩后保留数据
边界模糊的探索性/研究工作
团队协作（Git同步）

何时使用TodoWrite:

单会话线性任务
用于即时工作的简单清单
所有上下文都在当前对话中
可在当前会话内完成

Prerequisites

前置条件

bash

bd --version  # Requires v0.47.0+

bd CLI installed and in PATH
Git repository (bd requires git for sync)
Initialization:
```
bd init
```
run once (humans do this, not agents)

bash

bd --version  # Requires v0.47.0+

bd CLI 已安装并添加至PATH
Git仓库（bd需要git进行同步）
初始化：运行一次
```
bd init
```
（由人工操作，而非Agent）

CLI Reference

CLI参考

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

Essential commands:

bd ready

bd create

bd show

bd update

bd close

bd sync

**运行

bd prime

**获取AI优化的工作流上下文（由钩子自动加载）。 **运行

bd <command> --help

**查看特定命令的使用方法。

核心命令：

bd ready

bd create

bd show

bd update

bd close

bd sync

Session Protocol

会话流程

```
bd ready
```
— Find unblocked work
```
bd show <id>
```
— Get full context
```
bd update <id> --status in_progress
```
— Start work
Add notes as you work (critical for compaction survival)
```
bd close <id> --reason "..."
```
— Complete task
```
bd sync
```
— Persist to git (always run at session end)

```
bd ready
```
— 查找未被阻塞的工作任务
```
bd show <id>
```
— 获取完整上下文
```
bd update <id> --status in_progress
```
— 开始工作
工作过程中添加笔记（这对在对话压缩后保留数据至关重要）
```
bd close <id> --reason "..."
```
— 完成任务
```
bd sync
```
— 将数据持久化到Git（会话结束时务必运行）

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	`bd gate --help`	ASYNC_GATES.md
Worktrees	`bd worktree --help`	WORKTREES.md

功能	CLI指令	资源文档
Molecules（模板）	`bd mol --help`	MOLECULES.md
Chemistry（pour/wisp模式）	`bd pour` , `bd wisp`	CHEMISTRY_PATTERNS.md
Agent beads	`bd agent --help`	AGENTS.md
Async gates（异步闸门）	`bd gate --help`	ASYNC_GATES.md
Worktrees（工作树）	`bd worktree --help`	WORKTREES.md

Resources

资源文档

Resource	Content
BOUNDARIES.md	bd vs TodoWrite detailed comparison
CLI_REFERENCE.md	Complete command syntax
DEPENDENCIES.md	Dependency system deep dive
INTEGRATION_PATTERNS.md	TodoWrite and tool integration
ISSUE_CREATION.md	When and how to create issues
MOLECULES.md	Proto definitions, component labels
PATTERNS.md	Common usage patterns
RESUMABILITY.md	Compaction survival guide
STATIC_DATA.md	Database schema reference
TROUBLESHOOTING.md	Error handling and fixes
WORKFLOWS.md	Step-by-step workflow patterns
AGENTS.md	Agent bead tracking (v0.40+)
ASYNC_GATES.md	Human-in-the-loop gates
CHEMISTRY_PATTERNS.md	Mol vs Wisp decision tree
WORKTREES.md	Parallel development patterns

资源文档	内容
BOUNDARIES.md	bd与TodoWrite的详细对比
CLI_REFERENCE.md	完整命令语法
DEPENDENCIES.md	依赖系统深度解析
INTEGRATION_PATTERNS.md	TodoWrite与其他工具的集成方式
ISSUE_CREATION.md	问题的创建时机与方法
MOLECULES.md	原型定义、组件标签
PATTERNS.md	常见使用模式
RESUMABILITY.md	对话压缩后的数据恢复指南
STATIC_DATA.md	数据库架构参考
TROUBLESHOOTING.md	错误处理与修复方法
WORKFLOWS.md	分步工作流模式
AGENTS.md	Agent bead追踪（v0.40+）
ASYNC_GATES.md	人工介入闸门
CHEMISTRY_PATTERNS.md	Mol与Wisp模式决策树
WORKTREES.md	并行开发模式

Full Documentation

完整文档

bd prime: AI-optimized workflow context
GitHub: github.com/steveyegge/beads

bd prime：AI优化的工作流上下文
GitHub：github.com/steveyegge/beads