The current era of AI-assisted coding is often criticized for being “vibe-based”—agents guess what to do next based on a messy, sprawling README or a long chat history. Beads is the “adult in the room” for AI agents.
The core innovation here is Structured Persistent Memory. By replacing messy markdown plans with a dependency-aware graph, Beads prevents “long-horizon amnesia.” It even features Semantic Compaction—effectively “memory decay” that summarizes closed tasks so they don’t clog up the LLM’s context window. It’s a specialized, local alternative to heavy-duty Jira-like systems, optimized specifically for the speed and token-constraints of autonomous agents.
The AI Engineer’s View: The “State Machine” for Agentic Loops
From an agentic engineering standpoint, the biggest bottleneck isn’t the LLM’s reasoning; it’s the Reliability of State. When an agent enters a loop, it needs a source of truth that is:
- Observable:
bd show <id>provides a structured JSON/text output the LLM can parse easily. - Transactional: Powered by Dolt, every task update is a database transaction. We move from “I think I finished this” to “The graph state is updated.”
- Context-Efficient: The
bd primecommand acts as a system prompt injector, giving the agent exactly the workflow context it needs without manual copy-pasting.
By using bd remember, we stop the “memory leak” where insights discovered during a 2:00 AM debugging session are lost once the chat history is cleared. It’s essentially a Distributed Long-Term Memory (LTM) module for any agent (Claude Code, Codex, or custom Droids) operating on a codebase.
Quick Summary of Commands for your AGENTS.md:
bd prime: Syncs the agent with the current project state.bd ready: Filters the graph for tasks that have all dependencies met.bd remember: Commits an “insight” to the database to prevent losing context.bd close: Moves the task to the archive and triggers potential compaction.
Features
- Dolt-Powered: Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes.
- Agent-Optimized: JSON output, dependency tracking, and auto-ready task detection.
- Zero Conflict: Hash-based IDs (
bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows. - Compaction: Semantic “memory decay” summarizes old closed tasks to save context window.
- Messaging: Message issue type with threading (
--thread), ephemeral lifecycle, and mail delegation. - Graph Links:
relates_to,duplicates,supersedes, andreplies_tofor knowledge graphs.
Platforms
Beads works seamlessly on all systems such as macOS, Linux and Windows.
License
MIT License
