INTERACTIVE ESSAY

The Context Bottleneck

How 'Beads' gives AI Agents long-term memory by transforming flat files into intelligent graphs.

SCROLL TO BEGIN ↓

1. The "Amnesia" of Flat Files

When you give an AI Agent a `TODO.md` file, it consumes "Context Tokens". As the project grows, the file gets too big. The AI forgets early instructions to make room for new ones.

AI CONTEXT WINDOW (RAM) 10%

MEMORY USAGE

EDITOR: TODO.md

- Initialize Repo - Setup Environment

2. The Structure: JSONL Log

Beads treats tasks as database entries, not text. It uses an append-only issues.jsonl file. This is git-friendly and machine-readable.

CREATE NEW BEAD

FILE: issues.jsonl

3. The Core Logic: Dependency Graph

A list is flat. A project is a graph. If "Update CSS" is blocked by "Fix Header", the AI shouldn't see "Update CSS" yet.

Instructions: 1. Click "Fix Header" then "Update CSS" to create a dependency link. 2. Notice the AI view shrinks. 3. Click "Fix Header" again to Complete it.

DEPENDENCY GRAPH

State: Select a node to link...

WHAT THE AI SEES Tokens: High

4. The Ecosystem: Automated Ingestion

Since tasks are structured data, we can automate them. Watch how a Sentry error becomes a ready-to-code Bead automatically.

PRODUCTION LOGS

[INFO] Server started port 8080
[INFO] User 123 logged in
[INFO] Dashboard rendered

BEADS INBOX

5. Landing the Plane

By moving from Markdown to Beads, we turn ephemeral chat context into a persistent, shared database that lives inside your Git repo.

📄 → ☁️

Synced issues.jsonl to remote origin/main