beads란 ― AI 코딩 에이전트에게 「의존 관계를 이해한 영속 메모리」를 부여하는 분산 그래프형 이슈 트래커

AI 코딩 에이전트를 실무에서 운용하다 보면 반드시 부딪히는 벽이 있습니다. **「세션을 넘나드는 태스크의 기억과, 태스크 간의 의존 관계를 어떻게 관리할 것인가」**라는 벽입니다.

Claude Code / Codex / Cursor 등의 에이전트는 1회 세션에서는 놀라운 작업을 수행하지만, 장시간의 작업을 맡기려 하면 다음과 같은 문제가 발생합니다.

• 마크다운 (Markdown) TODO 리스트는 세션 간에 동기화가 깨진다
• 「이 태스크가 먼저な」「저것은 이것을 끝내기 전에 완료해줘」와 같은 의존 관계를 매번 다시 설명해야 한다
• 병렬 에이전트 운용 시, 동일한 번호의 티켓이 다른 의미로 작성되어 충돌한다
• 오래된 완료 태스크가 컨텍스트 (Context) 영역을 계속 차지한다

이러한 문제들을 해결하기 위해 등장한 것이 beads (bd) 입니다. 리포지토리(Repository)의 설명을 그대로 인용하자면 「Distributed graph issue tracker for AI agents, powered by Dolt」――AI 에이전트용 분산 그래프형 이슈 트래커 (Distributed graph issue tracker) 로, 버전 관리 기능이 있는 SQL 데이터베이스인 Dolt를 스토리지 기반으로 채택하고 있습니다.

GitHub 리포지토리의 설명(description)에는 「A memory upgrade for your coding agent」라고 덧붙여져 있습니다. 어지러운 마크다운 작업 계획을 의존 관계를 이해하는 그래프로 대체하여, 장기적인 태스크를 컨텍스트를 잃지 않고 다룰 수 있게 하는 것이 beads의 존재 의의입니다.

이 기사에서 얻을 수 있는 것:

• 🪞 마크다운 TODO가 안고 있는 한계와, beads가 해결하는 과제
• 🏗️ Dolt를 스토리지로 사용하는 「2층 아키텍처 (Two-layer architecture)」와 쓰기·읽기 흐름
• 🛠️ 기본 커맨드 (bd init / bd ready / bd update --claim / bd close) 사용법과 「ready 검출」 로직
• 🕸️ 4종류의 의존 관계 (blocks / parent-child / related / discovered-from)의 구분 사용
• 🧠 bd prime과 bd remember, 그리고 Compaction에 의한 「영속 메모리 (Persistent memory)」 설계
• 👥 병렬 멀티 에이전트 운용 시의 충돌 회피 (Hash-based ID)

beads의 존재 의의를 파악하려면, 먼저 **「에이전트에게 마크다운 TODO를 쓰게 하면 어떤 일이 일어나는가」**를 살펴보는 것이 빠릅니다.

에이전트에게 작업을 지시할 때, 무심코 다음과 같이 작성하곤 합니다.

# TODO
- [ ] 데이터베이스를 셋업
- [ ] API를 구현
...

이는 1개 세션 안에서는 기능하지만, 다음 세션에서 에이전트를 기동하면 「어디까지 끝났는지」, 「다음에 착수해야 할 것이 무엇인지」가 모호해집니다. 또한 다음과 같은 문제가 있습니다.

• 의존 관계를 표현할 수 없음: 「인증 기능은 API 이후에」라는 관계를 매번 구두로 설명해야 함
• 병렬 실행을 상정하지 않음: 여러 에이전트가 동일한 파일에 쓰면 TODO가 깨짐
• 영속적인 메모리가 되지 않음: 완료된 태스크를 언제 지워야 할지 에이전트는 판단할 수 없음

beads는 동일한 작업을 의존 관계가 포함된 그래프 (Graph) 로 표현합니다.

이 도표의 포인트는, beads가 「다음에 무엇을 해야 하는지」를 기계적으로 결정할 수 있다는 점입니다. bd ready라는 커맨드는 블로킹(Blocking) 의존 관계가 없는 태스크만을 반환해 줍니다. 에이전트는 「다음은 뭐지?」라고 매번 생각할 필요 없이, bd ready의 결과를 가져와 bd update --claim으로 착수하면 의존 관계에 따른 올바른 순서로 작업이 진행됩니다.

💡 마크다운 TODO와 이슈 트래커의 가장 큰 차이는 「의존 관계를 계산할 수 있는가」입니다. beads는 이 계산 결과 (ready 큐)를 에이전트가 다루기 쉬운 JSON 형식으로 반환해 줍니다.

beads의 핵심은 Dolt (버전 관리 기능이 있는 SQL 데이터베이스) 를 스토리지로 사용하는 2층 아키텍처입니다. 공식 문서 docs/ARCHITECTURE.md에서는 이를 「The Two-Layer Data Model」이라고 부르고 있습니다.

이 그림의 핵심은 Dolt가 「로컬 SQL 데이터베이스」와 「분산 동기화가 가능한 리모트」를 하나의 실체로 겸하고 있다는 점입니다. 일반적인 이슈 트래커(GitHub Issues 등)는 중앙 서버에 항상 연결되어 있어야 하지만, beads는 오프라인에서 완결되며, 필요할 때 bd dolt push/pull로 동기화하는 Git 라이크(Git-like)한 운용이 가능합니다.

Dolt는 버전 관리가 포함된 SQL 데이터베이스로, 다음과 같은 점들이 beads에 있어 유리한 특징입니다.

Dolt의 특징	beads에 있어서의 가치
밀리초(ms) 단위의 쿼리 성능과 SQL 호환성	에이전트가 대량의 이슈를 순식간에 검색할 수 있음
자동 커밋 (쓰기 작업마다 버전 이력 생성)	완전한 감사 추적 (audit trail)을 기본적으로 확보
Cell-level merge	병렬 브랜치에서 이슈를 편집해도 필드 단위로 자동 머지
Dolt remotes (DoltHub / S3 / GCS)	전용 동기화 서버를 구축할 필요가 없음
네이티브 push / pull	코드와 동일한 Git 방식의 운용 감각

beads의 모든 커맨드는 로컬의 Dolt 데이터베이스를 직접 읽고 씁니다.

이 그림의 핵심은 읽기/쓰기가 항상 로컬에서 완결되어 네트워크 지연(latency)의 영향을 받지 않는다는 점입니다. bd dolt push/pull을 명시적으로 실행했을 때만 리모트와 동기화하므로, 네트워크 단절이나 CI 환경에서도 문제없이 작동합니다.

beads는 시스템 전체에 한 번 설치하면 모든 프로젝트에서 사용할 수 있는 CLI 도구입니다. 프로젝트마다 beads 리포지토리를 클론할 필요는 없습니다.

# 권장: Homebrew (macOS / Linux)
brew install beads
# Node.js 사용자
...

Windows / Arch / Go install 등 다른 수단은 docs/INSTALLING.md를 참조하십시오. 설치 후, bd --help로 연결 확인을 할 수 있습니다.

프로젝트 디렉토리에서 bd init을 실행하면, .beads/ 디렉토리와 임베디드(embedded) Dolt 데이터베이스가 생성됩니다. 동시에 AGENTS.md가 자동으로 생성되거나 업데이트되어, 에이전트가 beads의 워크플로우를 발견할 수 있게 됩니다.

cd your-project
bd init

bd init에는 여러 가지 플래이버(flavor)가 있습니다. 상황에 맞춰 선택하십시오.

커맨드	용도
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>를 통해 각 에이전트용 상세 지시사항이나 훅(hook)을 도입할 수 있습니다.

bd setup codex # Codex CLI를 위해 AGENTS.md를 강화
bd setup claude # Claude Code를 위한 훅 / 설정 설치
bd setup factory # Factory.ai Droid용
...

지원되는 에이전트 전체 리스트는 bd setup --list로 확인할 수 있습니다. 지원 대상이 아닌 에이전트를 사용하는 경우에는 bd onboard를 실행하고, 표시된 스니펫을 에이전트의 지시 파일에 수동으로 붙여넣으십시오.

이 그림의 핵심은 「설치 → init → setup」의 3단계로 주요 에이전트에 대응할 수 있다는 점입니다. bd init 단계에서 AGENTS.md가 준비되므로, 최소 구성이라면 그 시점에서 바로 작동하기 시작합니다.

beads의 사용법은 몇 가지 간단한 명령어로 집약됩니다. 에이전트가 일상적으로 호출하는 명령어는 다음과 같습니다.

명령어	동작
bd ready	차단(blocking) 의존 관계가 없는 태스크를 목록으로 표시
bd create "Title" -p 0	P0 (critical) 우선순위로 태스크 생성
bd update <id> --claim	태스크를 원자적(atomic)으로 claim (assignee 설정 + in_progress화)
bd dep add <child> <parent>	의존 관계 (blocks / related / parent-child) 추가
bd show <id>	태스크의 상세 정보와 감사 로그 (audit log) 표시
bd close <id> "reason"	태스크 종료
bd prime	에이전트용 워크플로우 컨텍스트 (workflow context)와 영속 메모리 (persistent memory) 출력
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
...

이슈의 상태 전이 (status transition) 는 다음과 같습니다.

이 도표의 핵심은 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가지 타입으로 구분하여 사용할 수 있다는 점에 있습니다.

타입	의미	bd ready에 미치는 영향
blocks	X가 close될 때까지 Y는 시작할 수 없음	있음 (가장 강력한 제약)
parent-child	Epic ↔ Sub-task 간의 계층 관계	있음 (부모가 차단되면 자식도 차단됨)
related	참고 링크 정도의 느슨한 연관성	없음
discovered-from	작업 중 파생되어 발견됨	없음

이 도표의 핵심은 blocks와 parent-child만이 ready 계산에 영향을 미치며, related와 discovered-from은 "정보 링크"로 취급된다는 것입니다. 후자의 두 가지는 "지식 그래프 (knowledge graph)"를 구축하기 위한 약한 연관성으로, ready 큐를 어지럽히지 않습니다.

beads는 계층적 ID도 지원합니다.

• bd-a3f8 ― Epic
• bd-a3f8.1 ― Task (Epic의 자식)
• bd-a3f8.1.1 ― Sub-task (Task의 자식)

ID만 보고도 계층 구조를 알 수 있어 에이전트에 대한 설명 비용이 낮아집니다.

💡 "분석 중에 발견했다"는 케이스에 discovered-from을 사용하면, ready 큐에 혼입시키지 않고 지식(knowledge)으로서 남길 수 있습니다. 구현 중에 탈선하여 발견한 버그나 개선점을 가볍게 수집하기에 편리합니다.

beads가 스스로 "memory upgrade"라고 자칭하듯, 영속 메모리 (persistent memory) 기능은 핵심 기능 중 하나입니다. 세 가지 메커니즘이 연동됩니다.

bd prime

는, 에이전트가 새로운 세션을 시작할 때 가장 먼저 실행해야 하는 명령어입니다. 이것을 실행하면 다음 내용이 출력됩니다.

• 현재 프로젝트의 beads 워크플로우 context
• 사용 가능한 명령어 가이드
• 과거에 bd remember로 저장한 영속 메모리

에이전트는 이를 읽어 들임으로써, 지난 세션에서 얻은 지식을 계승한 상태로 작업을 시작할 수 있습니다.

bd remember "FastAPI의 버전은 0.115입니다. 3.13에서는 asyncio의 동작 방식이 바뀝니다" 

세션 중에 얻은 통찰을 bd remember로 저장하면, 그것이 Dolt 데이터베이스에 영속화되고 다음번 bd prime에서 자동으로 재주입됩니다.

💡 공식 설정 절차에서는 'MEMORY.md 파일을 만들지 마라'고 명시되어 있습니다. beads가 메모리 관리를 담당하기 때문에 이중 관리가 되는 것을 피하도록 설계되었습니다.

장기간 운영할 경우, 과거에 닫힌 태스크가 방대해져 에이전트의 컨텍스트 창을 압박합니다. beads는 이에 대해 **Compaction(압축)**이라고 부르는 메커니즘으로, 오래된 종료된 태스크를 의미적으로 요약하여 보관합니다.

이 다이어그램의 핵심은 **'오래된 태스크를 완전히 버리는 것이 아니라, 요약 형태로 남긴다'**는 설계 사상입니다. 완전한 이력은 Dolt의 버전 관리에 남아있기 때문에 필요하다면 되돌아갈 수 있습니다. 가장 최근 작업의 컨텍스트만 가볍게 유지하면서도 과거의 지식도 잃지 않는 균형을 맞추고 있습니다.

여러 에이전트, 여러 브랜치에서 동시에 태스크를 작성하면 일반적인 시퀀셜 ID로는 충돌이 발생합니다. beads는 이를 Hash-based ID로 구조적으로 방지하고 있습니다.

시퀀셜 ID의 문제는 이렇습니다.

beads는 이를 무작위 UUID 기반의 짧은 해시 ID로 대체했습니다.

ID 길이는 초기에는 4글자(예: bd-a1b2)에서 시작하여, 데이터베이스가 커짐에 따라 5글자, 6글자로 점진적으로 늘어나는 메커니즘입니다. 충돌 확률의 수학적 근거는 docs/COLLISION_MATH.md에 '생일의 역설(Birthday Paradox)' 계산으로 기재되어 있습니다.

같은 ID를 가진 이슈가 다른 브랜치에서 수정되었을 때도, Dolt의 cell-level merge로 필드 단위로 병합됩니다. 게다가 각 이슈에는 **콘텐츠 해시(Content Hash)**가 부여되어 있어, 병합 로직은 다음과 같이 작동합니다.

같은 ID + 같은 해시 → 스킵 (이미 동일)

• 같은 ID + 다른 해시 → 업데이트 (새로운 버전으로 가져오기)
• 새로운 ID → 생성

중앙 서버를 거치지 않고 모든 참여자가 동일한 최종 상태로 수렴하는 설계입니다.

멀티 에이전트 운영에서 유용한 두 가지 모드를 소개합니다.

: git에 커밋하지 않고 로컬에 bd init --stealth만 가진 운영. 공유 프로젝트에서 개인적으로 사용하고 싶을 때 편리 -

• : OSS 기여자가 planning issue를 다른 리포지토리(예: bd init --contributor ~/.beads-planning)로 라우팅하여 PR에 섞이지 않게 하는 방식

💡 관리자/기여자 자동 판별은 SSH URL 또는 HTTPS 인증 정보의 유무로 결정됩니다. HTTPS로 쓰기 권한이 있는데도 자동 판별되지 않을 때는 git config beads.role maintainer를 명시적으로 설정합니다.

beads의 스토리지에는 두 가지 모드가 있습니다.

bd init

Dolt을 프로세스 내에서 구동하는 단일 쓰기(single-write) 모드입니다. 데이터는 .beads/embeddeddolt/에 보관됩니다. 대부분의 사용자는 이 모드로 충분하다고 문서에서는 권장합니다.

bd init --server

외부의 dolt sql-server에 연결하여 다중 쓰기(multiple-write)를 허용하는 모드입니다. 데이터는 .beads/dolt/에 저장됩니다. 연결은 CLI 플래그 또는 환경 변수로 지정합니다.

플래그 (Flag)	환경 변수 (Env Var)	기본값 (Default)
--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 도메인 소켓 (Unix Domain Socket)도 --server-socket으로 지정 가능하며, 포트 충돌을 피하고 싶을 때나 Claude Code와 같은 샌드박스 (Sandbox) 환경에서 유효합니다.

# 백업 대상을 설정하고 push
bd backup init /path/to/backup
bd backup sync
...

bd backup은 Dolt 네이티브 백업 기능으로, 커밋 히스토리 (Commit history)를 포함하여 저장 및 복원이 가능합니다. bd export를 사용하면 JSONL 형식으로 내보낼 수도 있어, 타 시스템으로의 이관이나 호환성 확보에도 사용할 수 있습니다.

beads는 Notion과의 동기화도 제공합니다.

bd config set notion.token <token>
bd notion init --parent <page-id>
bd notion sync --dry-run # 프리뷰
...

에이전트 (Agent)는 beads에서 기계적으로 작업하고, 인간은 Notion에서 전체를 조망하는 하이브리드 (Hybrid) 운용이 용이해집니다.

beads의 본질을 3가지로 압축합니다.

#	핵심 메시지
①	의존 관계를 이해한 그래프 (Graph)를 통해, AI 에이전트는 '다음에 무엇을 해야 할지'를 기계적으로 판단할 수 있다. 마크다운 (Markdown) TODO의 한계를 넘기 위한 토대
②	Dolt를 스토리지 (Storage)로 사용함으로써 버전 관리, 셀 레벨 머지 (Cell-level merge), 분산 동기화를 모두 하나의 실체로 얻을 수 있다. 중앙 서버가 필요 없다
③	해시 기반 ID (Hash-based ID)와 컴팩션 (Compaction)이 멀티 에이전트 (Multi-agent) 병렬 운용과 장기 메모리 (Long-term memory) 관리를 동시에 해결한다

첫걸음은 다음과 같이 진행하는 것을 권장합니다.

• 설치: 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 ― 공식 리포지토리 (Official Repository)
• Beads Documentation Site ― 공식 문서 사이트
• Quick Start ― 공식 퀵 스타트
• docs/ARCHITECTURE.md ― 2계층 아키텍처 (2-layer architecture) 상세
• Dolt ― 스토리지 기반이 되는 버전 관리 기능이 포함된 SQL 데이터베이스