# Beads — Memory Upgrade Layer for Coding Agents

> Beads adds persistent, structured memory for coding agents via a dependency-aware graph and a CLI, keeping long-horizon tasks on track across runs.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

1. Install / run:
   ```bash
   curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
   ```
2. Start / smoke test:
   ```bash
   cd your-project && bd init && bd prime
   ```
3. Verify:
   - Create one issue node, claim it, update it once, then close it; confirm state persists across a new terminal session.

## Intro

Beads adds persistent, structured memory for coding agents via a dependency-aware graph and a CLI, keeping long-horizon tasks on track across runs.

- **Best for:** Coding agents that need durable task state (issues, dependencies, claims) instead of losing context between runs
- **Works with:** CLI-first workflow; integrates with multiple agent/IDE setups (see README)
- **Setup time:** 12 minutes

## How to Use It Well

- Setup time ~12 minutes (install CLI + `bd init` in one repo)
- Persistent graph beats markdown plans for long-horizon work (dependencies, status, claims)
- GitHub stars + forks (verified): see Source & Thanks

Treat memory as a data structure, not prose. If an agent can query a graph (what’s blocked, what’s claimed, what changed), it can plan more reliably and avoid re-deriving the same context every run.

### FAQ

**Q: Do I need to clone the repo into my project?**
A: No. The README recommends installing the CLI system-wide and using it across repos.

**Q: What’s the first command to learn?**
A: `bd prime` (or equivalent) to get workflow context, then `bd show/update/close` for issue lifecycle.

**Q: Is it tied to one agent?**
A: No. The README mentions multiple integrations (Codex, Claude, Cursor, etc.); use the setup that matches your tool.

## Source & Thanks

> Source: https://github.com/gastownhall/beads
> License: MIT
> GitHub stars: 23,532 · forks: 1,554

---

<!-- ZH -->

## 快速使用

1. 安装 / 运行：
   ```bash
   curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
   ```
2. 启动 / 冒烟测试：
   ```bash
   cd your-project && bd init && bd prime
   ```
3. 验证：
   - Create one issue node, claim it, update it once, then close it; confirm state persists across a new terminal session.

## 简介

Beads 用依赖图+持久存储替代松散的 markdown 计划，为 coding agent 提供结构化 issue/上下文记忆；配套 CLI 与多种 agent/IDE 集成，适合长周期任务。

- **适合谁：** 需要“可持续的任务状态”（工单、依赖、认领）而不是每次 run 重新丢上下文的 coding agent
- **可搭配：** CLI 优先工作流；可与多种 agent/IDE 集成（见 README）
- **准备时间：** 12 分钟

## 实战建议

- 上手约 12 分钟（安装 CLI + 在一个仓库里 `bd init`）
- 依赖图+状态比 markdown 计划更适合长周期任务（依赖/状态/认领可追踪）
- GitHub stars + forks（已核验）：见「来源与感谢」

把记忆当数据结构而不是散文。如果 agent 能查询一张图（阻塞点、认领状态、变更历史），规划会更可靠，也能避免每次 run 都重新推导同一份上下文。

### FAQ

**需要把仓库 clone 到项目里吗？**
A: 不需要。README 建议系统级安装 CLI，然后在多个仓库复用。

**最该先学哪个命令？**
A: 先用 `bd prime` 获取工作流上下文，再用 `bd show/update/close` 走完整生命周期。

**只能配某一种 agent 吗？**
A: 不是。README 提到多种集成（Codex/Claude/Cursor 等）；按你的工具选择对应 setup。

## 来源与感谢

> Source: https://github.com/gastownhall/beads
> License: MIT
> GitHub stars: 23,532 · forks: 1,554


---
Source: https://tokrepo.com/en/workflows/beads-memory-upgrade-layer-for-coding-agents
Author: Script Depot