Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/steveyegge/beads/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The bd remember command stores knowledge permanently in a key-value store. Memories are automatically injected at bd prime time, making them available in every session without manual loading. Added in: v0.58.0

​
Syntax

bd remember "<insight>"
bd remember "<insight>" --key <custom-key>

​
Arguments

​
insight
string
required
The knowledge or insight to store permanently. Must not be empty.

​
Options

​
--key
string
Explicit key for the memory. If not provided, a key is auto-generated from the first ~8 words of the content using slugification (lowercase, hyphenated, max 60 chars).

​
How It Works

​
Storage

Memories are stored in the Dolt-backed key-value configuration store with the prefix kv.memory.. This ensures they:
  • Persist across CLI sessions
  • Survive account rotations
  • Sync via Dolt push/pull
  • Are versioned with your project

​
Auto-Injection

When you run bd prime (typically called automatically by AI tool hooks), all stored memories are injected into the context. This happens:
  • At session start (via SessionStart hooks)
  • After context compaction (via PreCompact hooks)
  • Whenever you manually run bd prime
The memories appear in the output under a “Persistent Memories” section, making them available to AI agents automatically.

​
Key Generation

If you don’t specify --key, the system generates one by:
  1. Converting to lowercase
  2. Replacing non-alphanumeric characters with hyphens
  3. Taking the first ~8 words (hyphen-separated segments)
  4. Capping total length at 60 characters
  5. Trimming trailing hyphens

​
Examples

​
Basic Usage

Store a simple insight: 
bd remember "always run tests with -race flag"
Output: 
Remembered [always-run-tests-with-race-flag]: always run tests with -race flag

​
Custom Key

Use a memorable key for easier retrieval: 
bd remember "Dolt phantom DBs hide in three places: ~/.dolt, .dolt-data, and server catalog" --key dolt-phantoms
Output: 
Remembered [dolt-phantoms]: Dolt phantom DBs hide in three places: ~/.dolt, .dolt-data, and...

​
Multi-line Memories

Store detailed information: 
bd remember "Auth module uses JWT not sessions.
Token expiry is 24h.
Refresh tokens stored in Redis."

​
Project-Specific Knowledge

bd remember "This repo's API tests require STAGING_API_KEY env var" --key api-test-setup
bd remember "Deploy script needs Docker 24+ for BuildKit features" --key docker-version
bd remember "Customer X prefers MySQL 8.0 compatibility mode" --key customer-x-db

​
Updating Existing Memories

If you store a memory with a key that already exists, it updates the existing value: 
# First time
bd remember "Run tests before deploy" --key deploy-checklist
# Output: Remembered [deploy-checklist]: Run tests before deploy

# Update it
bd remember "Run tests and linter before deploy" --key deploy-checklist
# Output: Updated [deploy-checklist]: Run tests and linter before deploy

​
Use Cases for Agents

​
Configuration Details

bd remember "S3 bucket for staging: beads-staging-us-west-2" --key s3-staging
bd remember "Production DB requires VPN connection" --key prod-db-access

​
Gotchas and Edge Cases

bd remember "Zero-value timestamps mean 'never set' not 'epoch time'" --key timestamp-gotcha
bd remember "Race detector catches the flaky TestParallel issue" --key test-race

​
Team Conventions

bd remember "PRs need 2 approvals for main branch" --key pr-policy
bd remember "Use bd create before coding, not after" --key workflow-rule

​
Tool Quirks

bd remember "Dolt embedded mode deadlocks in git hooks - use server mode" --key dolt-hook-deadlock
bd remember "ICU flags required for CGO tests on macOS" --key macos-test-cgo

​
Agent Workflow

AI agents should use bd remember to store knowledge that:
  1. Persists across sessions - Don’t lose hard-won insights
  2. Applies project-wide - Not specific to one file or task
  3. Prevents repeated mistakes - Learn from bugs and gotchas
  4. Documents decisions - Why certain patterns exist
Anti-pattern: Creating MEMORY.md files that fragment across accounts and get lost. Best practice: Use bd remember so memories sync with your Dolt database and inject automatically.

​
JSON Output

Add --json flag for programmatic use: 
bd remember "insight" --key test --json
Output: 
{
  "key": "test",
  "value": "insight",
  "action": "remembered"
}
For updates: 
{
  "key": "test",
  "value": "new insight",
  "action": "updated"
}
  • bd memories - List or search all stored memories
  • bd recall - Retrieve a specific memory by key
  • bd forget - Delete a memory
  • bd prime - Output context including all memories (auto-called by hooks)

​
Error Handling

​
Empty Content

bd remember ""
# Error: memory content cannot be empty

​
Key Generation Failure

bd remember "!!!" 
# Error: could not generate key from content; use --key to specify one
In this case, provide an explicit key: 
bd remember "!!!" --key special-marker

​
Tips

Use descriptive keys that you’ll remember. Keys like auth-jwt, dolt-phantoms, and api-staging are better than auto-generated dolt-phantom-dbs-hide-in.
Search your memories before creating new ones: bd memories <keyword> to avoid duplicates.
Memories are stored in the database. Don’t store secrets or credentials. Use environment variables or secret managers for sensitive data.
Memories automatically sync when you push to your Dolt remote, making them available to team members and other machines.

Build docs developers (and LLMs) love

Get started for freeTalk to us