Linear and Beads: How to prevent your AI from getting Alzheimer's

The robot’s amnesia

Imagine you hire a brilliant programmer. They solve complex problems, write clean code, understand your architecture. But they have one small flaw: every few hours their memory gets wiped. They start from scratch. They don’t remember what they were doing, what you decided together, or why the code is the way it is.

Well, that’s exactly what happens with Claude Code and other AI agents.

When the context fills up (and it fills up fast if you’re working on a real project), the system does a “compaction.” In plain English: it summarizes the conversation and throws everything else away. The problem is that summary loses nuances, decisions, and especially the state of ongoing tasks.

The solution? Two tools that complement each other: Linear for you and Beads for your AI.

Linear: Your product view

Linear is a modern issue tracker. If you’ve used Jira, imagine the opposite: fast, clean, and doesn’t make you want to tear your eyes out.

What I use it for

• Product backlog: Features, bugs, epics. Everything that needs to be done at the business level
• Roadmap: What goes first, what comes after
• Communication: The rest of the team (if there is one) can see the status

Real example

QIN-500: Add dark mode to the application
QIN-501: Optimize image loading
QIN-502: Integrate payment gateway

These are product tasks. They’re the “what needs to be done.” They don’t say anything about how to do it. That’s the developer’s job… or your AI agent’s.

Beads: Your AI’s memory

This is where Beads comes in, created by Steve Yegge (the same guy from the famous Google and Amazon rants).

Beads is an issue tracker that lives inside your repository. But it’s not for you, it’s for your AI agent. It’s their persistent memory.

The problem it solves

When I work with Claude Code on a complex task, things like this happen:

1. I read issue QIN-500 from Linear
2. I investigate the current architecture
3. I create a mental plan of 5 steps
4. I start implementing…
5. 💥 COMPACTION 💥
6. “Hi, I’m Claude. How can I help you?”

All the context, the plan, the progress… evaporated. It’s like the movie Memento, but less cinematic and more frustrating.

The solution

With Beads, before compacting, the state is persisted in .beads/ inside the repo:

1
2
3

bd create --title "Research current theme system" --priority P2
bd create --title "Create ThemeContext" --priority P2
bd create --title "Add toggle in Settings" --priority P2

After compaction, the first thing I do is:

1

bd ready

And boom: I know exactly where I was.

📋 Ready work (2 issues with no blockers):

1. [P2] qinqin-a3f2: Create ThemeContext
2. [P2] qinqin-b4c5: Add toggle in Settings

How it works

Beads saves everything in your repo:

your-project/
└── .beads/
    ├── beads.db       # SQLite database
    ├── issues.jsonl   # Issues in versionable format
    └── config.yaml    # Configuration

Since it’s in git, it’s versioned with your code. You can see the history, branch, merge… It’s code, not an external service.

The coexistence: Linear + Beads

Here’s the trick: they don’t compete, they complement each other.

The flow in practice

YOU (in Linear):
  QIN-500: Add dark mode

CLAUDE (in Beads, during the session):
  qinqin-a1b2: Research theme system [DONE]
  qinqin-c3d4: Create ThemeContext [IN PROGRESS]
  qinqin-e5f6: Add toggle in Settings [BLOCKED by c3d4]
  qinqin-g7h8: Tests for dark mode [BLOCKED by e5f6]

COMMIT (when done):
  feat(web): add dark mode toggle (QIN-500)

Linear has the what. Beads has the how.

Quick installation

Beads

Important: the bd CLI is installed once on your system. But .beads/ is initialized per project. It’s like git: you install git once, but you do git init in each repo.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 1. Install CLI (once only, global)
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# 2. Add to PATH (if it didn't do it automatically)
# In fish:
fish_add_path ~/.local/bin
# In bash/zsh:
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc

# 3. Configure integration with Claude Code (once only)
bd setup claude

# 4. Initialize in EACH project where you want to use it
cd your-project
bd init

After bd init, you’ll see a .beads/ directory in your project. Decide: do you commit it to the repo (shared with the team) or add it to .gitignore (private memory for your AI)?

I commit it. That way if someone else works with Claude on the same repo, they have the context.

Linear

Linear is a web service. Create an account at linear.app and you’re set. If you use Claude Code, install the Linear MCP so it can read and create issues directly.

Essential Beads commands

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# See tasks with no blockers
bd ready

# Create task
bd create --title "Implement feature X" --priority P2

# See details
bd show qinqin-a1b2

# Close task
bd close qinqin-a1b2 --reason "Committed in abc123"

# List all
bd list --all

# See dependency graph
bd graph

Is it worth it?

Look, if you use Claude Code for small, isolated tasks, you probably don’t need Beads. An ephemeral TodoWrite will suffice.

But if you work on real projects, with long sessions that inevitably get compacted, with context that matters… then Beads is the difference between having a useful assistant and one with Alzheimer’s.

And the best part: since it lives in the repo, you don’t depend on any external service. If Beads disappears tomorrow, you have your data in JSON. Another good thing is there are community UIs if the CLI isn’t your thing: beads-ui gives you a local kanban.

Warning

Beads is new. There are reports that it doesn’t work perfectly with Opus 4.5. It’s worked for me, but your experience may vary.

As a sensible engineer would say: test it on a side project before marrying it.

TL;DR: Linear is for you (what to do). Beads is for your AI (how it’s doing it). Together, they prevent every compaction from being a restart from scratch.

Now if you’ll excuse me, I have to go close some beads.