01
BEADS: CONTINUITY
Agent-native task tracking.
Memory that persists.
02
The Problem
Every session, context resets.
- What was I working on?
- What's blocked by what?
- What did I discover yesterday?
Humans remember. Agents forget.
03
"Understanding is always already moving in a circle."— Martin Heidegger, "Being and Time"
Memory bridges the gap between sessions.
04
┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ BEADS ARCHITECTURE │ │ Dual storage for speed and sync │ │ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ .beads/ │ │ │ ├───────────────────────┬─────────────────────────────────────────┤ │ │ │ beads.db │ SQLite cache (gitignored) │ │ │ │ (fast queries) │ Local speed │ │ │ ├───────────────────────┼─────────────────────────────────────────┤ │ │ │ issues.jsonl │ Source of truth (git-synced) │ │ │ │ (append-only log) │ Cross-session memory │ │ │ ├───────────────────────┼─────────────────────────────────────────┤ │ │ │ config.yaml │ Repository configuration │ │ │ └───────────────────────┴─────────────────────────────────────────┘ │ │ │ │ SQLite for speed. JSONL for sync. Git for memory. │ │ │ └─────────────────────────────────────────────────────────────────────────┘
Fast locally. Persistent globally.
05
bd create
# Create an issue
bd create "Implement user dashboard"
# With priority (P0-P4)
bd create "Fix login bug" --priority P0
# With labels
bd create "Add dark mode" --label feature --label spaceCapture work as it emerges. Don't lose discovered tasks.
06
bd ready
# Show unblocked work
bd ready
# What CAN you start right now?
# - No pending dependencies
# - Status is 'open' or 'in_progress'
# - Ranked by priority
# Start your session here
bv --robot-priority # AI-optimized outputDon't ask "what should I do?" Ask Beads.
07
bd close
# Mark work complete
bd close cs-abc
# Close with reason
bd close cs-abc --reason "Commit abc123"
# Close multiple at once
bd close cs-abc cs-def cs-ghiWork without closure is work forgotten.
08
bd sync
# Sync with Git
bd sync
# Pull from main (ephemeral branches)
bd sync --from-main
# Check sync status
bd sync --statusSync before session ends. Memory persists through Git.
09
┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ SESSION WORKFLOW │ │ Three phases of continuity │ │ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ SESSION START │ │ │ │ ───────────── │ │ │ │ bv --robot-priority # What's highest impact? │ │ │ │ bd show <id> # Review the issue │ │ │ │ bd update <id> --status in_progress │ │ │ └──────────────────────────────────────────────────────────────────┘ │ │ ↓ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ DURING WORK │ │ │ │ ─────────── │ │ │ │ bd create "Discovered task" # Capture emergent work │ │ │ │ bd dep add <id> blocks <other> # Record dependencies │ │ │ └──────────────────────────────────────────────────────────────────┘ │ │ ↓ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ SESSION END │ │ │ │ ─────────── │ │ │ │ bd close <id> # Mark complete │ │ │ │ bd sync --from-main # Pull updates │ │ │ │ git commit # Commit your work │ │ │ └──────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘
Start with context. End with closure.
10
Dependencies
# X blocks Y (Y cannot start until X completes)
bd dep add cs-auth blocks cs-dashboard
# Parent-child (hierarchical)
bd dep add cs-subtask parent cs-epic
# Related (informational)
bd dep add cs-login related cs-auth
# Discovered-from (audit trail)
bd dep add cs-bugfix discovered-from cs-featureDependencies are relationships. Relationships are memory.
11
┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ ROBOT MODE │ │ Machine-readable output for agents │ │ │ │ ┌─────────────────────────┬───────────────────────────────────────┐ │ │ │ Flag │ Output │ │ │ ├─────────────────────────┼───────────────────────────────────────┤ │ │ │ --robot-priority │ PageRank + Critical Path ranking │ │ │ │ --robot-insights │ Bottleneck and keystone detection │ │ │ │ --robot-plan │ Suggested execution sequence │ │ │ └─────────────────────────┴───────────────────────────────────────┘ │ │ │ │ bv --robot-priority │ │ # Returns JSON that agents can parse │ │ │ │ Beads was designed for AI agents. Not adapted—designed. │ │ │ └─────────────────────────────────────────────────────────────────────────┘
Agent-native from the start.
12
┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ LABEL CONVENTIONS │ │ Two dimensions: scope and type │ │ │ │ PROPERTIES (where) │ TYPES (what) │ │ ─────────────────────────── │ ──────────────────────────────────── │ │ agency → Client work │ feature → New capability │ │ io → Research, docs │ bug → Something broken │ │ space → Practice, learn │ research → Investigation │ │ ltd → Canon, philosophy │ refactor → Structural improvement │ │ │ │ PRIORITY │ │ ────────────────────────────────────────────────────────────────── │ │ P0: Drop everything P1: This week P2: This month │ │ P3: Someday P4: Maybe never │ │ │ └─────────────────────────────────────────────────────────────────────────┘
Scope + Type + Priority = Complete context.
13
┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ MOLECULES & CHEMISTRY │ │ Work templates using phase metaphor │ │ │ │ ┌────────────┬────────────┬───────────────┬───────────────────────┐ │ │ │ Phase │ Type │ Persistence │ Use Case │ │ │ ├────────────┼────────────┼───────────────┼───────────────────────┤ │ │ │ SOLID │ Proto │ Template │ Reusable workflows │ │ │ │ LIQUID │ Mol │ Git-synced │ Feature work │ │ │ │ VAPOR │ Wisp │ Gitignored │ Scratch, experiments │ │ │ └────────────┴────────────┴───────────────┴───────────────────────┘ │ │ │ │ bd pour <proto> --var name=auth # Solid → Liquid │ │ bd wisp create <proto> # Solid → Vapor │ │ bd mol squash <wisp> # Vapor → Permanent │ │ bd mol burn <wisp> # Vapor → Gone │ │ │ └─────────────────────────────────────────────────────────────────────────┘
Protos are templates. Mols persist. Wisps evaporate.
14
Hermeneutic Continuity
Memory bridges sessions.
Understanding accumulates.
bv --robot-priority — Start every session here.