27,616 颗星的 Beads：Steve Yegge 给 Coding Agent 装上的「金鱼记忆」解药

27,616 颗星的 Beads：Steve Yegge 给 Coding Agent 装上的「金鱼记忆」解药

你有没有这种体验：让 Claude Code 或 Cursor 修一个稍微大点的 bug，开头十分钟它思路清晰、改得稳；聊到第五十条消息，它开始忘——刚才修过什么、下一步该做什么、谁依赖谁，最后干脆把任务标成”完成”再 hallucinate 一个 PR 出来。VirtusLab 把这种症状叫”AI 金鱼记忆”。

gastownhall/beads 这个仓库干的就是这件事：给 Coding Agent 装一套持久化、结构化、带依赖图的工作记忆。它在 27,616 颗星、4,293 个 Fork 的体量下，已经从最初的 JSONL + SQLite 一路演化到今天的 v1.3.1（2026-09-30 发布），由 Dolt 这个”Git for Data”做底座。它的作者是 Steve Yegge——前 Google、Amazon 工程师，Sourcegraph 现任——所以你可以把它看成”老炮儿程序员对 Coding Agent 工业级缺陷的一次正面回应”。

它到底是什么

官方一句话定义：”Distributed graph issue tracker for AI agents, powered by Dolt”。不要被”issue tracker”骗了——它不是给人类用的 Jira，也不是给团队的 Linear。它是给 LLM 当外部记忆体的依赖图数据库：

• 持久化：记忆跨 session、跨崩溃、跨模型切换都能续上
• 图结构：任务之间有依赖（blocks / parent-child / relates-to），下游任务在前置未 close 时不会出现在 ready 列表
• Agent UX：JSON 输出、hash ID（bd-a1b2）、hash 抗冲突、JSONL 增量追加——所有设计都让 LLM 少烧 token、少走弯路

核心命令只有六七个：

bd create "fix auth bug" -p 1 -t bug
bd ready                                # 看现在能做的（依赖已解开）
bd update bd-a1b2 --claim               # 原子认领，assignee + in_progress
bd dep add <child> <parent>             # 建依赖
bd show bd-a1b2
bd close bd-a1b2 "fixed"
bd prime                                # 注入 Agent 工作流上下文

bd prime 这条特别关键：它把项目的事实、agent 工作流、AGENTS.md 上下文一次性打印出来，相当于给 Agent 喂了份”项目记忆 manifest”。

为什么不是又一个 Markdown TODO 列表

VirtusLab 在 GitHub All-Stars #12 里拆得非常到位：Markdown 是自由文本，Agent 改它的时候会把计划删一半；两个 Agent 并行改同一个 TODO.md，Git merge 直接冲突。Beads 的解法是”把任务当成数据库行”：

• 存储：从 JSONL（v0.x）演化到 Dolt SQL（v1.x），数据落在 .beads/embeddeddolt/ 或 .beads/dolt/，git 远程走 refs/dolt/data 分支
• 冲突解决：每个 bead 有 hash ID，两个并行 branch 创建的同名任务不会撞车，merge 自然 friendly
• 崩溃恢复：append-only 日志，中途崩了最多丢最后一行，文件不损坏；SQLite/Dolt 缓存可以随时从日志重建

到 v1.3.x，又多了一个”proxied-server”模式：默认起一个 Dolt sql-server，多个 Agent 多端写不打架；这解决了单进程内嵌 Dolt 写并发卡顿的痛点。补丁清单里还顺手修了 fan-in stall——两个 blocker 同时 close 时，被依赖的任务以前可能停在 is_blocked=1 不进 ready。

和 GasTown 的边界

Beeds 是从 GasTown 拆出来的”组件”。GasTown 是 Yegge 那个”管理 AI Agent 群”的宏大 IDE 环境；Beads 是它底下那层”任务账本”。换句话说——

• 想要 Agent 协同编排（多 Agent 角色、Convoy、Mayor）：用 GasTown
• 只想要”任务持久化 + 依赖图”这一件事：用 Beads 即可，不必上 GasTown

Okhlopkov 的 Beads vs Gastown 里更直接：framework 是”别人心智模型的轨道”，与其全套 install 不如 cherry-pick。而且据他说 Anthropic 已经受 Beads 启发把 Claude Code 自己的 todo 升级成了完整 task tracker——这部分功能会逐步被收编回 first-party。

上手门槛

真实安装时间：5 分钟。

brew install beads            # macOS / Linux 推荐
# 或
npm install -g @beads/bd     # Node 党
# 或一行脚本：curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

cd your-project
bd init                       # 初始化 .beads/，自动写一份 AGENTS.md
bd setup claude               # 装 Claude Code hooks
# 或 bd setup codex / factory / cursor / mux

跑 bd init 后，Agent 启动时会自动读到 AGENTS.md 里的提示，然后自己 bd prime 拉上下文。不需要手动粘 prompt。

但要清醒：Beads 不是灵丹。它有真实门槛——

• 你得在用 AI Agent（Cursor / Claude Code / Codex / Factory.ai / Mux），纯手写代码用不到
• 你得接受命令行；终端恐惧症别碰
• 它存状态靠 Dolt，跨机器同步走 git remote，多人协作需要约定 bd dolt push/pull 时机
• Windows 装得动但生态偏 Linux/Mac
• v1.3 跨大版本升级要按 bd info --whats-new + bd hooks install + bd version 三步走，不要裸换 binary

适合谁：每天和 Claude Code 较劲、个人/小团队想给 Agent 装”长期记忆”的工程师。

不适合谁：纯前端可视化爱好者（社区工具有但还在追）、只想找 ToDo app 的人、用不上 AI Agent 的项目。

下一步建议

1. 先在一个真实项目里 brew install beads && bd init，跑半小时 bd ready → bd claim → bd close 循环，看依赖图对不对得上你的开发直觉
2. 把 bd remember "项目里的重要约定" 用起来——这是把”AI 重复犯同一个错”治掉的最快路径
3. 如果已经在用 Claude Code，跑 bd setup claude 装 hooks，让 Agent 启动即拉 bd prime，别手动提示
4. 跨机器协作时再读 v1.3 升级指南 和 Dolt backend 文档，别一上来就开 server 模式

仓库：https://github.com/gastownhall/beads
文档：https://beads.gascity.com/
讨论与评测：https://virtuslab.com/blog/ai/beads-give-ai-memory、https://okhlopkov.com/en-beads-gastown-framework-ai-agents
v1.3.1 Release Notes：https://github.com/gastownhall/beads/releases