Beads Cross-Session Memory Patterns

AI agents forget everything when a session ends. Each new conversation starts blank—developers re-explain problems, re-provide context, re-iterate findings. This wastes time and limits AI to simple, single-session tasks.

Human developers carry context naturally: yesterday's debugging session informs today's fix. AI needs the same capability. Beads provides it by storing issues in .beads/issues.jsonl, a Git-committed file that any session can read. Work survives restarts, context limits, even crashes.

AI sessions end. Browser tabs close. Context windows fill. Servers timeout. When they do, everything disappears: partial solutions, debugging progress, the thread of investigation you were following.

This creates concrete problems:

• Repetitive Context Setting: Developers must repeatedly provide the same background information, code snippets, or problem descriptions to the AI.
• Fragmented Problem Solving: Complex issues that require multiple steps or days to resolve become unmanageable, as the AI cannot track progress or remember previous attempts.
• Reduced Efficiency: Time is wasted on re-establishing context rather than advancing the task, leading to slower development cycles.
• Lack of Cumulative Learning: The AI cannot build upon past interactions or learn from previous mistakes within the scope of a larger project.

Beads stores issues in a local directory (.beads/) using a single file: issues.jsonl. Each line is a JSON object representing one issue. This file is the source of truth for what AI is tracking.

The file is Git-committed alongside your code. This gives you:

• Version Control: Every change to an issue, every new piece of context, is tracked and auditable through Git history.
• Collaboration: Teams can share AI context and progress by simply pushing and pulling the .beads directory.
• Durability: The AI's memory is as persistent as the codebase itself, surviving system reboots, environment changes, and developer handovers.

The Beads Workflow

The interaction with Beads follows a clear, command-line driven workflow, enabling developers to manage AI's memory explicitly:

# 1. Initiate a new issue or task
bd create "Implement user authentication via OAuth2"

# This creates a new entry in .beads/issues.jsonl
# The AI can now be prompted with context related to this issue.

# 2. Update an existing issue with new information or progress
bd update <issue_id> "Discovered a dependency conflict with 'passport-oauth2'. Investigating alternatives."

# The AI processes this update, adding it to the issue's history and context.
# This can be done across multiple sessions.

# 3. Close an issue once it's resolved
bd close <issue_id> "OAuth2 authentication successfully implemented and tested."

# Marks the issue as complete, but retains its history for future reference.

# 4. Synchronize the AI's memory with the team via Git
bd sync

# This command typically stages and commits changes to .beads/issues.jsonl
# and pushes them to the remote repository, making AI context shareable.

issues.jsonl Structure

Beads enables two patterns: context that survives sessions, and work extraction during sessions.

A. Context Survival Across Sessions

When a developer resumes work, AI loads open issues from issues.jsonl. It knows what it was working on, what problems exist, and what was already tried. This enables:

• Session handoffs: AI picks up where it left off, even after days.
• Project-specific knowledge: AI accumulates understanding of your codebase over time.
• Less re-explaining: Developers stop repeating context; AI already knows.

B. Work Extraction and Granular Tracking

AI doesn't just track what you tell it—it discovers work while processing code. It identifies sub-tasks, potential improvements, or refactoring needs. These become new entries in issues.jsonl, building a dynamic backlog.

This enables:

• Automated Issue Identification: AI can flag code smells, security vulnerabilities, or performance bottlenecks as new issues.
• Dependency Mapping: Tracking how issues relate to specific files or modules.
• Progress Monitoring: Updating issue statuses as code changes resolve them.

What Works

• No more re-explaining: Developers stop repeating context. AI reads issues.jsonl and knows what's happening.
• Multi-session tasks become possible: Problems that span days or weeks can be tracked continuously.
• Project-specific knowledge accumulates: The file becomes a record of what was tried, what worked, what failed.
• Team sharing via Git: Push .beads/ to share AI context across developers.
• Audit trail: Every decision is version-controlled.

What Doesn't Work Yet

• issues.jsonl Bloat: For very long-running projects with numerous issues, the issues.jsonl file could grow large. Strategies for archiving or summarizing closed issues might be necessary.
• Granularity Management: Determining the optimal granularity for issues (e.g., should a minor refactoring be a new issue or an update to an existing one?) requires careful consideration.
• AI Interpretation: The effectiveness of Beads heavily relies on the AI's ability to correctly parse and interpret the structured information in issues.jsonl and integrate it into its reasoning.
• Automated Context Pruning: Developing intelligent mechanisms for the AI to automatically prioritize and prune less relevant historical context to optimize prompt length and focus.

Future Work

Automatic issue creation, intelligent summarization of long histories, and smarter context retrieval to keep prompts focused.