Beads: Nâng cấp bộ nhớ dài hạn cho AI agent bằng git-backed issue tracker
Tóm tắt nhanh (Key Takeaways)
- Beads giải quyết vấn đề “mất trí nhớ” của AI agent giữa các phiên làm việc bằng cơ sở dữ liệu có cấu trúc, có thể truy vấn được, thay vì file markdown dễ bị mất ngữ cảnh.
- Dữ liệu được lưu trữ qua Dolt – cơ sở dữ liệu SQL có version control, đồng bộ với Git thông qua file
issues.jsonl, hoàn toàn cục bộ và không phụ thuộc cloud.- Khác với RAG truyền thống, Beads cho phép agent truy vấn đúng thông tin cần thiết (task sẵn sàng, quan hệ blocking) mà không cần nạp toàn bộ lịch sử vào context window.
- Hỗ trợ MCP server để tích hợp trực tiếp với Claude, Cursor và các AI client tương thích MCP.
- Mã nguồn mở, cài đặt trên macOS, Linux, Windows, FreeBSD; miễn phí hoàn toàn.
AI agent và bài toán “mất trí nhớ”
Bất kỳ ai đã làm việc với AI coding agent trong thời gian dài đều nhận ra một điểm yếu cố hữu: mỗi phiên mới bắt đầu, agent gần như không nhớ gì từ phiên trước. Kế hoạch nằm rải rác trong các file markdown, context bị cắt xén sau mỗi lần compaction, và agent phát hiện lại chính xác những lỗi nó đã tìm thấy ba ngày trước.
Vấn đề cốt lõi không phải là agent không đủ thông minh. Vấn đề là nó thiếu một kho lưu trữ bộ nhớ ngoài (external memory) có cấu trúc, bền vững giữa các phiên, và có thể truy vấn hiệu quả. File markdown là giải pháp phổ biến nhất, nhưng đây cũng là giải pháp kém nhất: không có dependency graph, không có truy vấn có điều kiện, không có version control ở cấp độ từng thay đổi.
Beads, được xây dựng bởi Steve Yegge, tiếp cận bài toán này theo một hướng hoàn toàn khác.
Beads là gì và nó hoạt động như thế nào
Beads (lệnh CLI: bd) là một git-backed graph issue tracker được thiết kế đặc biệt cho AI agent. Thay vì lưu task trong todo list hay file văn bản, Beads dùng Dolt – một cơ sở dữ liệu SQL với đầy đủ version control theo từng commit, hỗ trợ branching và merging như Git.
Về mặt lưu trữ, hệ thống hoạt động theo kiến trúc kép: Dolt database đóng vai trò engine truy vấn cục bộ tốc độ cao, còn file issues.jsonl trong thư mục .beads/ đóng vai trò bản sao text-based để commit lên Git. Mỗi khi agent ghi dữ liệu, thay đổi tự động được commit vào lịch sử Dolt. Khi thực hiện git pull, hệ thống tự động nhập issue mới nhất từ file JSONL.
Điểm khiến Beads nổi bật là thiết kế dependency-aware từ gốc: mỗi issue có thể khai báo quan hệ blocks, relates_to, duplicates, supersedes, hoặc replies_to với các issue khác. Lệnh bd ready trả về danh sách các task không còn blocker nào – thứ duy nhất mà agent cần biết để quyết định bước tiếp theo.
Beads khác RAG truyền thống ở điểm nào
Retrieval-Augmented Generation (RAG) thường được nhắc đến khi nói về bộ nhớ ngoài cho AI. Tuy nhiên, RAG và Beads giải quyết hai bài toán khác nhau.
RAG tìm kiếm tài liệu liên quan theo độ tương đồng ngữ nghĩa (semantic similarity) và đưa vào context. Cách tiếp cận này tốt cho việc trả lời câu hỏi dựa trên tài liệu, nhưng không phù hợp để quản lý luồng công việc có thứ tự thực thi, có trạng thái, và có quan hệ phụ thuộc rõ ràng.
Beads, ngược lại, cung cấp một cơ sở dữ liệu truy vấn có cấu trúc: agent không tìm kiếm bằng từ khóa mà gọi bd ready --json để lấy đúng danh sách task khả thi, hoặc bd show bd-42 --json để lấy chi tiết một issue cụ thể. Điều này giảm thiểu lượng dữ liệu đưa vào context window và loại bỏ sự mơ hồ về thứ tự thực thi.
Yêu cầu hệ thống (Prerequisites)
Trước khi cài đặt, cần đảm bảo các điều kiện sau:
- macOS / Linux:
curl,bashđể dùng quick install script. Nếu cài qua Homebrew, cần Homebrew 3.x trở lên. - Windows 11: Go 1.24+ (thêm
%USERPROFILE%\go\binvàoPATH) và Git for Windows. - Cài từ source (tùy chọn): Cần thêm thư viện CGO theo hệ điều hành:
- macOS:
brew install icu4c zstd - Debian/Ubuntu:
sudo apt-get install -y libicu-dev libzstd-dev - Fedora/RHEL:
sudo dnf install -y libicu-devel libzstd-devel
Hướng dẫn cài đặt Beads
Cài đặt trên macOS
Homebrew là cách đơn giản và được khuyến nghị:
brew install beadsKiểm tra cài đặt thành công:
bd --versionNgoài ra, có thể dùng Go hoặc npm:
# Via Go
go install github.com/steveyegge/beads/cmd/bd@latest
# Via npm
npm install -g @beads/bdCài đặt trên Linux
Homebrew on Linux hoặc script tự động:
# Homebrew
brew install beads
# Arch Linux (AUR)
yay -S beads-git
# Quick install script (cũng dùng được cho macOS)
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bashSau khi cài, xác minh:
bd --versionCài đặt trên Windows
Mở PowerShell với quyền Administrator và chạy:
irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iexBeads hỗ trợ Windows native, không cần MSYS hay MinGW. Nếu muốn build từ source trên Windows, cần thêm flag đặc biệt:
go build -tags gms_pure_go -o bd.exe ./cmd/bdSử dụng Beads trong thực tế
Khởi tạo và tạo issue đầu tiên
Sau khi cài CLI, khởi tạo Beads trong thư mục dự án:
cd your-project
bd initLệnh này tạo thư mục .beads/ với cơ sở dữ liệu Dolt bên trong. Thêm một dòng vào AGENTS.md để agent biết dùng bd cho task tracking:
echo "Use 'bd' for task tracking. Run 'bd ready' to find next task." >> AGENTS.mdTạo issue đầu tiên:
bd create "Refactor authentication module" -t task -p 1 --description="Replace JWT library with newer alternative"Các lệnh cốt lõi cần nắm
| Lệnh | Mục đích |
|---|---|
bd ready | Liệt kê task không còn blocker nào |
bd create "Tiêu đề" -p 0 | Tạo task mới với priority P0 |
bd update <id> --claim | Nhận task (gán assignee + in_progress) |
bd dep add <child> <parent> | Liên kết quan hệ phụ thuộc |
bd show <id> | Xem chi tiết và audit trail |
bd close <id> --reason "Done" | Đóng task hoàn thành |
bd tree | Xem cây phân cấp epic/task |
bd compact | Nén bộ nhớ — tóm tắt task cũ đã đóng |
Quản lý epic và phân cấp
Beads hỗ trợ ID phân cấp tự nhiên:
# Tạo epic
bd create "Authentication overhaul" -t epic -p 1
# -> Tạo ra: bd-a3f8
# Tạo task thuộc epic bằng dependency
bd create "Write unit tests" -t task -p 2 --deps parent:bd-a3f8
# -> Tạo ra: bd-a3f8.1Stealth mode và chế độ contributor
Khi làm việc trên project của người khác mà không muốn commit .beads/ vào nhánh chính:
# Dùng cục bộ, không commit vào repo
bd init --stealth
# Dùng cho contributor - route issue sang repo riêng
bd init --contributorTích hợp Beads với AI agent
Luồng làm việc chuẩn cho agent
Một phiên làm việc điển hình của AI agent với Beads:
# 1. Kiểm tra task sẵn sàng (không có blocker)
bd ready --json
# 2. Nhận task ưu tiên cao nhất
bd update bd-42 --claim --json
# 3. Làm việc... phát hiện issue mới trong quá trình thực thi
bd create "Found memory leak in auth module" -p 1 \
--deps discovered-from:bd-42 --json
# 4. Hoàn thành
bd close bd-42 --reason "Refactoring complete, tests passing" --jsonCờ --json đảm bảo output luôn có cấu trúc machine-readable, tránh việc agent phải parse text tự do.
Tích hợp qua MCP server
Beads cung cấp một MCP (Model Context Protocol) server tùy chọn, cho phép các AI client như Claude và Cursor gọi bd trực tiếp thông qua giao thức chuẩn. MCP server là stateless – nó không lưu cache hay dữ liệu riêng, chỉ đóng vai trò protocol adapter, dịch lệnh MCP thành lời gọi CLI tương ứng và định tuyến đến đúng workspace .beads/.
Cài đặt Git hooks để tự động đồng bộ
bd hooks installSau khi cài hook, mỗi lần thực hiện git pull hoặc git push, Beads tự động đồng bộ dữ liệu Dolt mà không cần thao tác thủ công.
Đánh giá: tại sao Beads là bản nâng cấp đáng giá
Ưu điểm rõ ràng. Beads lấp đúng khoảng trống mà file markdown và cloud issue tracker không thể lấp: bộ nhớ có cấu trúc, có dependency graph, có version history, hoạt động offline hoàn toàn, và được thiết kế từ đầu để agent tương tác lập trình được. Lệnh bd compact giải quyết vấn đề database phình to theo thời gian bằng cách dùng LLM tóm tắt các task cũ đã đóng – một cơ chế “quên có chọn lọc” giúp giữ context window luôn gọn gàng. Hash-based ID (bd-a1b2) ngăn xung đột khi nhiều agent chạy song song trên cùng một database.
Hạn chế cần lưu ý. Beads đòi hỏi agent phải được cấu hình để thực sự dùng bd thay vì tự tạo markdown TODO – điều này phụ thuộc vào nội dung AGENTS.md và system prompt. Với nhóm lớn cần tích hợp với GitHub PR, Slack hay dashboard web, Beads không có sẵn connector; điểm mở rộng chủ yếu là bd CLI kết hợp shell script tùy chỉnh.
Beads không phải là một issue tracker thông thường được điều chỉnh để dùng với AI. Nó là một công cụ được xây dựng từ gốc rễ với AI agent là đối tượng sử dụng chính: JSON output mặc định, dependency graph là first-class citizen, và cơ chế compaction để quản lý vòng đời bộ nhớ. Đối với developer đang vận hành nhiều AI coding agent song song, hoặc đơn giản là muốn một luồng làm việc có cấu trúc và bền vững hơn, Beads là nâng cấp thực chất so với bất kỳ tập hợp file markdown nào.
