Beads AI Memory: A Structured Memory System to Solve Agent Amnesia

The Problem: When AI Forgets the Plan

Picture this: We’re three weeks into a Flutter app rebuild. Our AI coding assistant has been phenomenal, refactoring authentication, rebuilding the navigation system, migrating state management. But today, when we check in on progress, something’s wrong.

The AI proudly announces the project is complete. We look at the codebase. The navigation is only half-migrated. The new state management exists alongside the old one. Tests that were passing last week are now disabled. What happened?

Our AI experienced what we call agent amnesia.

Unlike human developers who maintain context across days, weeks, and months, AI coding assistants effectively reset with each session. They see only what’s in the codebase at that moment. The comprehensive six-phase plan we created together? Unless it’s in the current context window, it might as well not exist.

The Impact of Agent Amnesia: When Projects Lack Beads AI Memory

Three critical failure patterns emerge when working on complex projects:

Lost context leads to premature completion.

An agent working on phase 3 of 6 forgets the broader plan. It creates a new multi-step plan for just that subtask, completes it, and declares victory. We discover that 70% of the planned work was never touched.

Valuable insights disappear.

While refactoring our Flutter widget tree, the agent notices a memory leak in an image loading service. But with context running low, it notes it’s “pre-existing” and moves on. The insight is never recorded. Six weeks later, users report app crashes. The same leak, rediscovered.

Quality degrades under pressure.

As the context limit approaches, the agent begins making poor decisions: skipping test updates, commenting out failing assertions, or implementing incomplete error handling just to mark the task “done” before memory runs out.

Common Solutions: Why Markdown Fails in AI Context Management

The standard response is simple: write it down. Have our AI create a markdown plan.

# Project Plan: Flutter App Refactor

## Phase 1: Authentication ✓
- [x] Migrate to Firebase Auth
- [x] Update login flow

## Phase 2: Navigation
- [ ] Replace Navigator 1.0 with GoRouter
- [ ] Update deep linking
- [ ] Test on iOS and Android

## Phase 3: State Management
...

This works for the first session. By session three, the cracks appear.

The Markdown Trap

Projects can quickly accumulate dozens of markdown files: PLAN.md, TODO.md, PROJECT_PHASES.md, DETAILED_PLAN_v2.md, IMPLEMENTATION_STEPS.md. Each file partially obsolete, partially contradictory, completely unmanageable.

The problem isn’t markdown itself. It’s that markdown creates unstructured text, not structured data.

From an AI’s perspective:

• It must read and interpret prose on every query
• It cannot programmatically determine “what tasks are ready to work on?”
• It cannot track dependencies between tasks
• It rarely updates plans during execution, causing rapid decay

We end up with what we call a “plan jungle” . Disconnected files that confuse rather than guide.

How the Beads AI Memory System Works: Structured Memory for Agents

Beads is a specialized issue tracker that functions as an external memory system for AI coding assistants. Instead of adapting human tools for AI use, it was designed specifically for how AI agents think and work.

The core architectural shift: from prose to queryable graph.

Rather than asking an AI to parse “TODO: implement payment flow (blocked by auth migration)” from markdown, Beads stores this as structured data with explicit dependencies. The AI can query directly: “What work is unblocked and ready?” The answer is definitive, not interpreted.

Three Design Principles

1. Git-Native Storage

All tasks are stored as JSON lines in .beads/beads.jsonl within our repository. Our task graph is versioned, branched, and merged alongside our code. Check out a commit from last month, and we see the exact task state at that moment. A complete time-travel capability that traditional issue trackers can’t provide.

2.  Dependency-Aware

Dependencies are first-class entities, not prose. Task A blocks Task B is data, not text. The AI runs bd ready and gets a structured list of actionable work. No interpretation and guessing.

3. Agent-First Interface

Beads provides JSON output and a command-line interface designed for programmatic access. The AI doesn’t read documentation and interpret meaning. It queries structured data and receives structured responses.

Setup: Getting Started with Beads

Installation

# via npm
npm install -g @beads/bd

# via Homebrew
brew install beads

Initialize Our Project

cd our-project
bd init

This creates a .beads/ directory in our repository. If we’re working on a shared project but want to keep Beads personal:

bd init --stealth

This keeps .beads/ in our .git/info/exclude, making it invisible to other developers

Verify Installation

bd version
bd ready  # Should return empty list initially

We’re ready to go.

Real-World Workflow: Flutter App Migration

Let’s take a look at a complete example: migrating a Flutter e-commerce app from Provider to Riverpod state management.

Phase 1: Create the Project Plan

Start by discussing the high-level approach with our AI assistant:

Prompt: “We need to migrate this Flutter app from Provider to Riverpod. It’s about 15,000 lines across 47 widgets. Let’s plan this migration carefully.”

AI: Discusses approach, identifies phases: setup, core state migration, widget updates, testing, cleanup

Prompt: “Great. Now import this plan into Beads. Create epics for each major phase, break them into concrete tasks, and set up dependencies carefully.”

The AI creates the structure:

# Epic: Setup and Dependencies
bd create "Setup Riverpod dependencies and project structure" -p 0
# Returns: Created bd-a3f8

# Tasks under Setup
bd create "Add riverpod and flutter_riverpod to pubspec.yaml" -p 0 --parent bd-a3f8
# Returns: Created bd-a3f8.1

bd create "Create providers/ directory structure" -p 0 --parent bd-a3f8
# Returns: Created bd-a3f8.2

bd create "Set up ProviderScope in main.dart" -p 0 --parent bd-a3f8
# Returns: Created bd-a3f8.3

# Epic: Core State Migration
bd create "Migrate core state management to Riverpod" -p 0
# Returns: Created bd-b2k9

bd create "Migrate AuthProvider to Riverpod" -p 1 --parent bd-b2k9
# Returns: Created bd-b2k9.1

bd create "Migrate CartProvider to Riverpod" -p 1 --parent bd-b2k9
# Returns: Created bd-b2k9.2

# Set dependency
bd dep add bd-b2k9 bd-a3f8

Phase 2: Initial Review and Refinement

Prompt: “Please review the beads you just created. Make sure the tasks are sufficiently small, the dependencies make sense, and nothing important is missing.”

The AI audits its own work:

bd list --all
bd show bd-a3f8
bd show bd-b2k9

AI: “I notice bd-b2k9.2 (CartProvider migration) should be blocked by bd-b2k9.1 (AuthProvider) since Cart depends on Auth state. Also, we should add a task for updating tests after each provider migration.”

The AI self-corrects:

bd dep add bd-b2k9.2 bd-b2k9.1
bd create "Update auth tests for Riverpod" -p 1 --parent bd-b2k9.1
bd create "Update cart tests for Riverpod" -p 1 --parent bd-b2k9.2

We can ask for multiple refinement passes, typically 2-3 iterations work well for complex projects.

Phase 3: Daily Execution Loop

This is where Beads transforms the workflow.

Monday Morning – Session 1:

Prompt: What work is ready?”

bd ready

Output:

bd-a3f8.1: Add riverpod and flutter_riverpod to pubspec.yaml [P0]
bd-a3f8.2: Create providers/ directory structure [P0]
bd-a3f8.3: Set up ProviderScope in main.dart [P0]

Prompt: “Work on bd-a3f8.1.”

The AI completes the task, runs tests, commits the code.

bd close bd-a3f8.1 -m "Added riverpod 2.4.9 and flutter_riverpod 2.4.9 to dependencies"

Prompt: “Great. What’s ready now?”

bd ready

Now bd-a3f8.2 and bd-a3f8.3 are still available. The AI tackles the next one.

Monday Afternoon – Session 2:

We start a fresh conversation (saving tokens and improving focus).

bd ready

The AI immediately sees the current state. No need to re-explain the project or copy-paste plans. The memory persists.

Phase 4: Capturing Discovered Work

Tuesday – During Migration:

While migrating AuthProvider, the AI notices something:

AI: “I’m seeing that the logout functionality doesn’t properly clear secure storage. This is pre-existing but should be fixed. I’ll file a bead for it.”

bd create "Fix: Clear secure storage on logout" -p 1 --tag bug

Instead of the insight disappearing, it’s captured. Later, we can query:

bd list --tag bug  # See all discovered bugs

Phase 5: Handling Blockers

Wednesday:

The AI starts work on widget updates but encounters an issue:

AI: “I can’t update ProductListWidget yet—the ProductProvider it depends on hasn’t been migrated to Riverpod. This should have been done first.”

bd create "Migrate ProductProvider to Riverpod" -p 0 --parent bd-b2k9
bd dep add bd-d4m2 bd-b2k9.4

The dependency graph self-corrects. Next time we run bd ready, bd-b2k9.4 appears in the work queue while bd-d4m2correctly shows as blocked.

Phase 6: Multi-Session Continuity

Thursday – After Multiple Sessions:

We’ve restarted the AI five times this week. Each time:

bd ready

The AI immediately knows: the current state, what’s blocked, what’s complete, what needs attention. No context loss, no re-explanation, no confusion.

Friday – Project Status:

bd stats

Output:
Total beads: 34
Closed: 28
Open: 6
Ready: 3
Blocked: 3

We can see exactly where we stand. Three tasks ready to work, three blocked (likely by those ready tasks), 82% completion.

Phase 7: Final Review

Prompt : “List all open beads.”

bd list --status open

The AI sees the remaining work, tackles each task methodically, and the migration completes successfully, no forgotten phases, no lost insights, no premature declarations of victory.

Essential Maintenance Commands

# Daily: Check for issues and auto-fix
bd doctor

# Every few days: Archive closed tasks (critical for performance)
bd cleanup

# Weekly: Update to latest version
bd upgrade

Performance note: Keep our active database under ~500 tasks. Beads queries can slow significantly with larger files. Use bd cleanup to archive completed work regularly.

Bottom Line

While AI is exceptionally capable at handling individual tasks, it struggles with long-term memory. Beads AI Memory bridges this gap by providing a consistent structure.

The difference is tangible. Complex, multi-week projects that previously stalled at partial completion can now progress methodically to finish. The rate of forgotten work, disabled tests, and incomplete implementations drops significantly when the AI has reliable external memory.

 The difference between markdown plans and Beads is the difference between asking someone to remember everything we told them versus giving them a reliable notebook. For developers doing serious work with AI-assisted development, structured memory isn’t optional anymore, it’s foundational.

As a company at the forefront of technological innovation, LOGIQUE Digital Indonesia understands the importance of efficient AI integration—such as utilizing Beads AI Memory—to accelerate the application development process. If you are looking to optimize your company’s digital transformation with scalable and professional AI-driven software development solutions, LOGIQUE is ready to be your strategic partner. Contact us today to start your consultation!