How Beads Handles Persistent Memory for AI Agents: A Dolt‑Backed Key‑Value Implementation

Beads implements persistent memory for AI agents by storing key‑value pairs under a namespaced prefix in a Dolt‑backed repository configuration, enabling durable, version‑controlled memories that survive clones and branch switches.

Beads, the open‑source project housed at gastownhall/beads, provides AI agents with durable memory capabilities by leveraging Dolt’s relational database engine as a key‑value store. This architecture ensures that agent insights persist across sessions and machines without requiring external databases, making persistent memory for AI agents a native feature of the repository itself.

Memory Namespace and Storage Architecture

Isolated Memory Prefix

All agent memories are stored under the key prefix kvPrefix + "memory." defined in cmd/bd/memory.go. This isolation prevents collision with other configuration entries while keeping memories queryable within the repository’s Dolt instance.

Dolt‑Backed Persistence

The storage layer uses store.SetConfig to stage changes and store.CommitPending to persist them to the Dolt database. This transaction‑like approach ensures that every memory write becomes a committed database change, providing ACID properties and version history for agent memories.

CRUD Operations for Agent Memories

Storing Insights with Automatic Key Generation

The bd remember command, implemented in the rememberCmd function at cmd/bd/memory.go (lines 44‑98), accepts an insight string and optional key. When no --key is provided, the slugify function (lines 19‑41) automatically generates a key by lower‑casing the text, replacing non‑alphanumeric characters with hyphens, truncating to the first eight words, and limiting the result to 60 characters.

# Store a memory (auto‑generated key)

$ bd remember "always run tests with -race flag"

# Store with an explicit key

$ bd remember "auth module uses JWT not sessions" --key auth-jwt

Retrieving and Searching Memories

Agents retrieve specific memories via bd recall <key>, which calls store.GetConfig in the recallCmd function (lines 170‑194). For discovery, bd memories [search] executes memoriesCmd (lines 110‑158), fetching all configuration entries via store.GetAllConfig, filtering for the memory prefix, and applying optional case‑insensitive substring matching on both keys and values.

# Retrieve a specific memory

$ bd recall auth-jwt
auth module uses JWT not sessions

# List all memories

$ bd memories

Deleting Memories

The bd forget <key> command, defined in forgetCmd at lines 94‑146 of cmd/bd/memory.go, removes entries and commits the deletion, emitting JSON‑aware errors if the key does not exist.

Concurrency and Durability Guarantees

Beads handles concurrent access through Dolt’s file‑level flocking mechanism. The test suite in cmd/bd/memory_embedded_test.go (lines 9‑51) validates that concurrent remember, recall, and forget operations remain safe, though the tests note a race condition in the underlying engine that you can mitigate by disabling automatic export during high‑volume parallel writes.

Because memories reside in the repository’s Dolt configuration, they automatically load during the Beads "prime" phase. This design gives AI agents access to consistent memories regardless of execution environment, machine, or account, and survives repository clones and branch switches.

Programmatic Integration Example

The following Go snippet demonstrates how to implement memory storage programmatically using the same patterns as the CLI:

// Programmatic use inside a Go command
func addMemory(ctx context.Context, store Store, insight, key string) error {
    if key == "" {
        key = slugify(insight) // same algorithm as the CLI
    }
    storageKey := kvPrefix + memoryPrefix + key
    if err := store.SetConfig(ctx, storageKey, insight); err != nil {
        return err
    }
    _, err := store.CommitPending(ctx, "beads-agent")
    return err
}

Summary

• Beads stores AI agent memories under the isolated prefix memory. in a Dolt‑backed key‑value store defined in cmd/bd/memory.go.
• The slugify function automatically generates URL‑safe keys from insight text when users omit the --key flag.
• All write operations (remember, forget) use store.CommitPending to persist changes as Dolt commits, ensuring durability.
• Memories survive repository clones and branch switches because they live in the repository configuration itself.
• Concurrent access is safe under Dolt’s file‑level flocking, though high‑parallel writes should disable automatic export to avoid race conditions.

Frequently Asked Questions

How does Beads isolate agent memories from other configuration data?

Beads prepends the constant memory. prefix (combined with kvPrefix) to all memory keys in cmd/bd/memory.go, ensuring these entries remain logically separated from other repository configuration values while still being accessible through the standard store.GetConfig API.

What happens if two AI agents write memories simultaneously?

Dolt’s file‑level flocking prevents corruption during concurrent writes, as demonstrated in cmd/bd/memory_embedded_test.go. However, the test suite notes a race condition in the underlying engine that you can mitigate by disabling automatic export during high‑volume parallel operations.

How are memory keys generated if I don't specify a --key flag?

The slugify function in cmd/bd/memory.go automatically converts the insight text to lowercase, replaces non‑alphanumeric characters with hyphens, keeps only the first eight words, and truncates the result to 60 characters maximum.

Can memories survive repository cloning and branch switches?

Yes. Because memories are stored directly in the repository’s Dolt configuration database, they persist across git clone operations, branch switches, and account rotations, loading automatically when Beads enters the "prime" phase.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}