The first issue tracker I’ve liked is the one I don’t need to use myself. Beads is an AI-native issue tracker that helps my agents on long-horizon tasks.
You need a solution for AI memory across long-horizon tasks. Before Beads, I was using Markdown files to keep track of todos and findings from previous work.
The problem with that? Agents will just add and add. The documentation sprawl confused the other agents reading those files.
Switching to Beads has been a big productivity boost. Let’s talk about the problems of agent memory and issue tracking and why Beads addresses them
Managing your CLAUDE.md or AGENTS.md
Your CLAUDE.md or AGENTS.md file is read into every chat session. This file tells the agent the important things to know about the project and your preferences. Anthropic recommends this file stays under 200 lines.
You can go over this amount, but it uses up your context window faster and the agent is less likely to adhere to instructions if you overburden it with too much to remember.
Depending on the folder or codebase you’re working in, the agent may only find a fraction of your AGENTS.md instructions relevant to its task. If this happens a lot, you have an area of opportunity.
You likely would want to split the relevant content into another file, or use memories.
Using Claude or Codex memory feature
Claude, Codex, Cursor, and other tools allow you to save memories. This is helpful for anyone who’s had to remind an agent that it’s making the same mistake across sessions.
One immediate downside: these are not portable to other agents out of the box. If you like to alternate or switch between agents, this is annoying. Even if you prefer one agent, you are locking yourself in more.
Markdown sprawl with shared files
While working on DataRoles.dev, I tried to create an agent-agnostic system to keep track of agent context. Files included frontend.md, backend.md, todo.md, and findings.md.
This went poorly.
The frontend and backend files were supposed to reflect key design and architecture choices but they went stale quickly, and were hundreds of lines long.
The todo file gave conflicting directions to agents, and got me stuck in a loop where agents created new problems and strayed completely off the roadmap.
The findings file was recording things that didn’t matter, and was often incorrect when future agents referred to it.
I ran a one-time cleanup process and updated my CLAUDE.md instructions for handling documentation. It worked okay for a day, then it only took one bad chat session to open the floodgates back up.
Agents want to add. It’s what they do. Unless you have very-dialed in guardrails, this just isn’t the way.
Beads issue tracking and memory
Beads is an issue tracker designed for AI agents, from noteworthy software engineer Steve Yegge.
You can think of Beads as like Jira for your AI agents, in a CLI. That includes an easy install process — you can just hand your agent the GitHub repo link and ask it to install it. Your agent then handles the setup and adds instructions on how to use Beads to your CLAUDE.md file.
Beads stopped my DataRoles.dev problem at the root. Dozens of lines of handoff notes became issue comments. Findings became searchable memories. My agents get what they need without the clutter, and performance is noticeably better. If you’re running agents in parallel, you can add dependencies so it knows ready vs. blocked issues.
When you’re doing long-horizon work that spans several chat sessions (and especially if you have multiple agents running), it’s crucial to stay organized. That’s what makes Beads powerful.
Plus, everything from Beads is portable across model providers and IDEs, rather than locking you in.