Durable Memory for Coding Agents

Durable memory for a coding agent is the work state it can recover without replaying the conversation: what changed, what was decided, what was found, and what is ready next.

A larger context window postpones forgetting. Durable memory begins when the useful state leaves the session, before compaction, restart, or a handoff can erase its shape.

Four durable work artifacts remain intact as one workstation fails and another waits to continue.

Before compaction, an agent records a decision, discovered bug, status, and dependency in Beads so the next session can read those objects directly.

Context is working memory

Context is where the agent reasons. It contains the user’s request, source code, tool results, discussion, failed approaches, and whatever else the model needs at that moment. Large context makes complex work possible.

It is also transient. Old material may be summarized during compaction. A new session may start with only project instructions. A replacement agent may see the repository but none of the choices that produced its current state.

Transcripts help humans inspect what happened, and summaries can orient an agent. Neither gives the agent a clean answer to operational questions:

Which work is still open?
What is already in progress?
What decision did we make?
What new bug did we find?
Does that bug block the original feature?
What can another agent do now?

Those answers belong in structured work state.

What needs to survive

Imagine an agent implementing passkey login. Halfway through, it finds that the session-expiry code also drops a security flag. The bug is real but does not block the passkey endpoint. The agent also decides to preserve the old cookie name for backward compatibility.

Before compaction, durable memory should hold:

the passkey implementation bead and its in_progress status;
a note recording the cookie compatibility decision;
a new session-expiry bug bead;
a discovered-from edge back to the implementation;
any dependency that changes what is ready next.

The source code still carries implementation details. Git carries commits. Beads carries the work’s meaning.

After compaction, the next session can skip the impossible hunt for a perfect conversation summary. It inspects the in-progress bead, reads the decision, sees the discovered bug, and queries ready work.

Beads externalizes the job

Beads gives agents durable, structured memory for work that survives across sessions, so they can pick up where they left off instead of reconstructing context.

The memory has several forms:

Beads record the work definition, status, priority, ownership, and history.
Typed relationships preserve hierarchy, ordering, and provenance.
Notes and comments keep the reasoning another agent will need.
bd remember stores durable project memories that do not belong to one task.
bd ready derives the actionable frontier from current work state.

These are complementary. A project-wide convention such as “all timestamps are UTC” belongs in memory. A newly discovered auth bug belongs in a bead. “The auth bug blocks release” belongs in the graph.

Beads stores that state in Dolt, a version-controlled SQL database. The database sits outside the model’s context and keeps versioned work-state history. Claim leases and heartbeats are intentionally node-local and ephemeral. How Beads works covers the storage and work loop.

The test is resumption

Good memory is not measured by how much text it stores. It is measured by how quickly a competent replacement can continue correctly.

Start a clean agent session and ask:

What work is in progress?
What changed since it began?
What decisions constrain the implementation?
What was discovered?
What is blocked, and by what?
What can be claimed now?

If the answers require reading a long transcript and inferring state, the system preserved history but not operational memory. If the answers come from explicit objects and relationships, the handoff is much safer.

This is also why a single MEMORY.md file eventually strains. Prose can explain conventions beautifully. Concurrent status, typed relationships, claims, and ready-work calculation want structured state.

The record only contains what reached it

Durability starts at the moment an agent records something.

A material decision left in hidden reasoning disappears with the session. Unsaved code remains a source-control and workspace problem. A useful command result needs a note if the next agent will depend on it.

The right discipline is a minimum useful record, updated as the work changes. Record facts that change execution rather than logging every thought:

a decision another agent must respect;
a discovery worth separate work;
a status change;
a newly introduced blocker;
a verification result that closes the loop.

The discipline resembles a good engineering handoff, except the agent writes it continuously.

How context comes back after compaction

Beads uses each coding agent’s native instruction and lifecycle surfaces to restore current operating context. bd prime supplies the workflow and project memory at session start and around compaction where the host supports reinjection; the durable issue graph supplies the current work.

The agent-recognition guide covers the host-specific setup paths for Claude Code, Codex, Gemini CLI, and other tools. The memory point here is narrower: restored instructions tell the agent how to work, while durable objects tell it what the job is now.

Use each record for its own purpose

Durable agent memory, source control, transcripts, and organizational audit records answer different questions:

Record	Best answer
Git	What changed in the code?
Transcript	What did this session say and do?
Beads	What work exists, how is it related, and what is ready?
Shared organizational Run	What happened across an operated team workflow?

Open source Gas City materializes a graph-workflow run as a root bead and child step beads. Its dashboard and API project the local run from retained bead lifecycle events and add live or linked execution detail; that view is not a separately governed team record. The Beads Team Server preview captures capitalized Runs in the organization’s shared location and stores them for the retention period the organization chooses. Durable agent memory and audit trails keeps those boundaries straight.

Beads is a memory upgrade for coding agents because it preserves the part of memory that drives the next action.

Give your agent durable memory.

Beads: Read the complete product and memory-upgrade narrative.
Why coding agents need a work graph: Learn how durable memory becomes relationship-aware work.
Recover agent work after a crash: Follow the operational handoff to a replacement session.
Durable agent memory and audit trails: Separate individual work memory from local visibility and retained team records.