Skip to main content
Beads provides a persistent memory system for AI agents that survives context compaction, session resets, and account rotations. Use bd remember, bd recall, bd forget, and bd memories to store knowledge that should persist across conversations.

​
Why Agent Memory?

AI agents face a fundamental challenge: context doesn’t persist.

The Problem

  • Context compaction loses history
  • Session resets forget decisions
  • Account rotations start from scratch
  • Manual notes in conversation are lost

The Solution

  • Knowledge stored in database
  • Auto-injected at session start
  • Survives all resets
  • Searchable and queryable

​
Core Commands

​
Store a Memory

Save knowledge that should persist: 
bd remember "always run tests with -race flag"
# Remembered [always-run-tests-with-race-flag]: always run tests...
Keys are auto-generated from content using the first ~8 words, lowercased, with non-alphanumeric chars replaced by hyphens.

​
List All Memories

View stored memories: 
bd memories

​
Retrieve a Memory

Recall full content by key: 
bd recall auth-design
# Auth module architecture:
# - JWT tokens not sessions
# - Refresh token rotation every 7 days
# - PKCE flow for public clients

​
Delete a Memory

Remove outdated knowledge: 
bd forget dolt-phantoms
# Forgot [dolt-phantoms]: Dolt phantom DBs hide...

​
How Memory Works

Memories are stored in the Dolt database using the key-value store:
1

Store

bd remember writes to kv.memory.* namespace in Dolt
2

Persist

Memory survives context compaction and session resets
3

Auto-inject

bd prime includes memories in workflow context
4

Available

Agent has access to memories in every session

​
Integration with bd prime

Memories are automatically injected when running bd prime: 
bd prime
Output includes:
  • Essential workflow rules
  • Command reference
  • All stored memories (auto-included)
# Beads Workflow

[standard workflow content...]

## Persistent Memories

always-run-tests-with-race-flag:
  always run tests with -race flag

auth-design:
  Auth module architecture:
  - JWT tokens not sessions
  - Refresh token rotation every 7 days
  - PKCE flow for public clients

dolt-phantoms:
  Dolt phantom DBs hide in three places:
  1. ~/.dolt/
  2. /tmp/dolt-*
  3. .beads/dolt/

​
Claude Code Integration

Designed for Claude Code hooks: 
# .claude-project.json
{
  "hooks": {
    "sessionStart": "bd prime",
    "preCompact": "bd prime"
  }
}
This ensures memories are injected:
  • At session start
  • Before context compaction
  • After account rotation

​
Memory Patterns

​
Architecture Decisions

Store key architectural choices: 
bd remember "Database: Dolt for version control, SQLite deprecated as of v0.50" --key db-architecture

bd remember "Auth: JWT with refresh token rotation, PKCE for mobile clients" --key auth-pattern

bd remember "Error handling: wrap errors with context, log at boundary, never panic in production" --key error-pattern

​
Testing Requirements

bd remember "Always run 'make test-full-cgo' for complete validation, 'make test' for quick checks" --key test-commands

bd remember "CGO tests require ICU flags on macOS, use scripts/test-cgo.sh" --key cgo-testing

​
Configuration Quirks

bd remember "Dolt auto-commit defaults: ON for embedded, OFF for server mode" --key dolt-autocommit

bd remember "Server mode port 3307 to avoid MySQL conflict on 3306" --key dolt-port

​
Deployment Details

bd remember "Staging: deploy via 'make deploy-staging', requires VPN and kubectl config" --key deploy-staging

bd remember "Production deploys need approval gate from @alice and CI green on main" --key deploy-prod

​
Debugging Techniques

bd remember "Phantom database issues: check ~/.dolt/, /tmp/dolt-*, and .beads/dolt/" --key debug-phantoms

bd remember "Lock contention: use 'bd doctor' to detect, switch to server mode if persistent" --key debug-locks

​
Best Practices

Keys should be memorable and meaningful:
# Good
bd remember "..." --key auth-jwt-rotation

# Bad
bd remember "..." --key tmp123
One concept per memory for easy recall:
# Good - focused
bd remember "Test command: make test-full-cgo" --key test-cmd
bd remember "CI requires both unit and integration tests" --key ci-requirements

# Bad - too broad
bd remember "Testing: use make test-full-cgo for CI which requires unit and integration tests and coverage" --key testing
Use the same key to update existing memories:
bd remember "Old info" --key topic
# Later...
bd remember "Updated info" --key topic
# Updated [topic]: Updated info
Avoid duplicates by searching first:
bd memories dolt  # Check existing memories
bd remember "New Dolt insight" --key dolt-insight
Remove outdated knowledge:
bd memories  # Review all
bd forget old-pattern  # Remove obsolete

​
Memory vs Issues

Understand when to use each:
Use Memory ForUse Issues For
Architecture decisionsTasks to complete
Configuration detailsBugs to fix
Testing proceduresFeatures to build
Debugging techniquesWork to track
Deployment stepsDependencies to manage
Common pitfallsStatus to monitor
Rule of thumb: If it’s knowledge, use memory. If it’s work, use an issue.

​
Storage Details

Memories are stored in the key-value store with the prefix kv.memory.*: 
-- Internal storage
SELECT * FROM config WHERE key LIKE 'kv.memory.%';

-- Returns:
-- key: kv.memory.auth-design
-- value: Auth module architecture...
Direct database manipulation is not recommended. Always use bd remember, bd memories, bd recall, and bd forget commands.

​
Backup and Migration

Memories are included in Dolt commits: 
# Backup
bd dolt push  # Memories included

# Restore
bd dolt pull  # Memories restored

# Export
bd export > backup.jsonl  # Includes memories

# Import
bd import backup.jsonl  # Restores memories

​
JSON API

All memory commands support --json for programmatic use: 
bd remember "insight" --key test --json
# {"key": "test", "value": "insight", "action": "remembered"}

​
Example: Multi-Session Workflow

See how memory helps across sessions:
1

Session 1: Discovery

# Working on auth, discover important detail
bd remember "Auth tokens expire after 24h, refresh at 23h mark" --key auth-expiry

# Session ends (context compacted)
2

Session 2: Different task

# New session, different work
bd ready  # Work on something else

# bd prime auto-injected the auth-expiry memory
# Agent knows about 24h expiry without being told
3

Session 3: Account rotation

# Account rotated, fresh start
# But memories persist in database!

bd prime  # Includes auth-expiry
bd recall auth-expiry  # Full details available

​
Troubleshooting

Verify storage:
bd memories  # Should list your memory
bd recall <key>  # Verify content
Check database access:
bd doctor  # Verify database health
Memory commands require direct database access (not RPC mode).
Update with same key:
bd remember "new content" --key existing-key
# Updated [existing-key]: new content
Search is case-insensitive and matches keys or values:
bd memories auth  # Matches "auth-design" key
bd memories JWT   # Matches "JWT" in value

Architecture

Understand the Dolt storage backend

Workflows

Learn about agent session protocols

Prime Command

Deep dive into bd prime integration

Key-Value Store

Advanced key-value store usage

Build docs developers (and LLMs) love

Get started for freeTalk to us