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

> Learn how Beads implements persistent memory for AI agents using a Dolt-backed key-value store. Discover durable, version-controlled memories that persist across clones and branches.

- Repository: [Gas Town Hall/beads](https://github.com/gastownhall/beads)
- Tags: deep-dive
- Published: 2026-04-27

---

**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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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.

```bash

# 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.

```bash

# 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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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:

```go
// 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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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.