Memory

Persistent agent knowledge that survives sessions and account rotations

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:

Auto-generated key

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:

List all

bd memories

Retrieve a Memory

Recall full content by key:

Recall

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)

Example prime output with memories

# 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

Use descriptive keys

Keys should be memorable and meaningful:

# Good
bd remember "..." --key auth-jwt-rotation

# Bad
bd remember "..." --key tmp123

Keep memories focused

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

Update, don't duplicate

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

Search before creating

Avoid duplicates by searching first:

bd memories dolt  # Check existing memories
bd remember "New Dolt insight" --key dolt-insight

Clean up stale memories

Remove outdated knowledge:

bd memories  # Review all
bd forget old-pattern  # Remove obsolete

Memory vs Issues

Understand when to use each:

Use Memory For	Use Issues For
Architecture decisions	Tasks to complete
Configuration details	Bugs to fix
Testing procedures	Features to build
Debugging techniques	Work to track
Deployment steps	Dependencies to manage
Common pitfalls	Status 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:

Remember

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

Memory not showing in bd prime

Verify storage:

bd memories  # Should list your memory
bd recall <key>  # Verify content

Can't remember (write error)

Check database access:

bd doctor  # Verify database health

Memory commands require direct database access (not RPC mode).

Key collision

Update with same key:

bd remember "new content" --key existing-key
# Updated [existing-key]: new content

Search not finding memory

Search is case-insensitive and matches keys or values:

bd memories auth  # Matches "auth-design" key
bd memories JWT   # Matches "JWT" in value

Related Documentation

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