Linear, Beads, and Tasks: Three Memory Layers for Claude Code

The Memory Problem

Claude Code has a problem: it forgets everything. You close the session, open another one, and it’s like talking to someone who doesn’t know you. You can load context with CLAUDE.md, sure, but what about half-finished tasks? Bugs you found but didn’t fix? The plan you had for tomorrow?

There are three complementary solutions: Linear (or your product tool), Beads (git-backed plugin), and Tasks (integrated in Claude Code). Each one for a different time horizon.

Tasks: Working Memory

Tasks is Claude Code’s internal system for tracking what it’s doing right now. When you ask for something complex, Claude automatically creates a task list.

Press Ctrl+T to see them:

┌─────────────────────────────────────────────────┐
│ Tasks                                           │
├─────────────────────────────────────────────────┤
│ ✓ Read project structure                        │
│ ● Implement authentication endpoint             │
│ ○ Write tests                                   │
│ ○ Update documentation                          │
└─────────────────────────────────────────────────┘

Features

• Automatic: Claude creates them when work has multiple steps
• Persistent through compaction: Survive when context gets compacted
• Visible with Ctrl+T: Quick toggle view
• Limited to 10: Only shows the first 10 (ask “show me all tasks” to see more)

Sharing Between Sessions

By default, Tasks die with the session. But you can make them persistent:

1

CLAUDE_CODE_TASK_LIST_ID=qualitra claude

This saves tasks in ~/.claude/tasks/qualitra/. Next time you start with the same ID, you recover the list.

When to Use Tasks

Tasks is for execution. You know what needs to be done, you just need tracking.

Beads: Project Memory

Beads is a plugin that adds a complete issue tracker, stored in git. Think of it as “Linear but local and free.”

1

bd list --status open

ID          TYPE    PRI  STATUS       TITLE
qua-1       epic    P2   open         Scoring Raven
qua-2       task    P1   in_progress  Implement scoring module
qua-3       bug     P0   blocked      Stack overflow in acquireStartLock

Features

• Git-backed: Issues live in .beads/ and get committed with your code
• Dependencies: One issue can block another
• Priorities and types: Epics, tasks, bugs, features, chores
• Multi-session: Context persists between sessions (and people)
• Hooks: Syncs automatically with bd sync

The Workflow

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

# Find available work
bd ready

# See details
bd show qua-2

# Start working
bd update qua-2 --status in_progress

# Create sub-tasks
bd create --title="Write PBT tests" --type=task
bd dep add qua-5 qua-2  # qua-5 depends on qua-2

# Finish
bd close qua-2

# Synchronize
bd sync

When to Use Beads

Beads is for planning. You don’t know exactly what you’ll do, but you know what problems need solving.

The Key Difference

Tasks: “I’m doing X, which has steps A, B, C”

Beads: “Need to solve X, Y, Z. Now working on X.”

Tasks is the shopping list while you’re cooking. Beads is the week’s menu.

Using Them Together

The ideal flow combines both:

1. Beads to capture work (issues, bugs, ideas)
2. Tasks to execute that work step by step

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

# 1. Session start: what's pending?
bd ready

# 2. Choose an issue
bd show qua-42
bd update qua-42 --status in_progress

# 3. Claude creates Tasks for the steps
# (automatic when I ask to implement qua-42)

# 4. During session, I find a bug
bd create --title="Race condition in cache" --type=bug --priority=1

# 5. Finish original work
bd close qua-42

# 6. Bug remains for another session
bd sync
git push

Mental Migration

If you’re coming from other systems:

Quick Setup

Tasks

Already included. Just remember:

• Ctrl+T for view toggle
• CLAUDE_CODE_TASK_LIST_ID=name for persistence
• “clear all tasks” to clean up

Beads

1
2
3
4
5
6
7
8

# Install plugin
claude mcp add beads-marketplace -- npx -y @anthropics/beads-mcp

# In your project
bd init

# See commands
bd help

Useful Commands

Tasks

Beads

The Common Mistake

Don’t use Beads as Tasks. I’ve seen this:

1
2
3
4

# BAD: Beads for session micro-tasks
bd create --title="Read file X"
bd create --title="Modify function Y"
bd create --title="Run tests"

That’s Tasks’ job, not Beads’. Beads is for things that matter tomorrow:

1
2
3
4

# GOOD: Beads for meaningful work
bd create --title="Implement OAuth authentication" --type=feature
bd create --title="Memory leak in worker" --type=bug
bd create --title="Migrate DB to PostgreSQL" --type=epic

The Three-Layer System

If you work with Claude Code on serious projects, you probably already use something like Linear, Jira, or GitHub Projects for product vision. Where does that fit?

The answer is a three-layer system by time horizon and audience:

Why It Works

Linear (or your product tool) has what Beads can’t offer:

• Visual roadmaps
• Cycles and sprints
• Integrations (Slack, GitHub, etc.)
• UI for thinking big
• Stakeholder collaboration

Beads has what Linear can’t offer:

• Lives in the repo (LLM sees it without configuration)
• Zero latency (local)
• Dependencies the LLM understands natively
• Git history of decisions
• Works offline

Tasks has what neither of the others offers:

• Automatic creation
• Real-time visualization
• Zero friction

The Natural Flow

Linear (roadmap)
    ↓ you manually break down
Beads (sprint/week)
    ↓ Claude automatically breaks down
Tasks (session)

Avoiding Duplication

Don’t copy issues from Linear to Beads literally. Beads should have the concrete work, not the product description.

# Linear (what you want)
"Implement OAuth authentication with Google and GitHub"

# Beads (what needs to be done)
qua-12: Configure OAuth provider in Supabase
qua-13: Endpoint /auth/callback
qua-14: Refresh token rotation
qua-15: E2E tests for login flow

# Tasks (what I'm doing now)
✓ Read Supabase Auth documentation
● Create migration for oauth_tokens table
○ Implement callback handler

Linear says what you want. Beads says what needs to be done. Tasks says what I’m doing.

Summary

TL;DR: Three memory layers for working with AI: Linear for product vision (weeks), Beads for tactical work (days), Tasks for execution (hours). Linear says what you want, Beads says what needs to be done, Tasks says what I’m doing. Don’t duplicate between layers.

More info:

• Tasks - Claude Code Docs
• Beads - GitHub
• Linear