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 memories command lists all stored memories or searches them by keyword. It helps you discover what knowledge has been saved and find specific insights quickly. Added in: v0.58.0

​
Syntax

bd memories
bd memories [search-term]

​
Arguments

​
search-term
string
Optional keyword or phrase to filter memories. Searches both memory keys and content (case-insensitive).

​
How It Works

The command queries the key-value store for all entries with the kv.memory. prefix. When a search term is provided, it filters memories where either:
  • The memory key contains the search term
  • The memory content contains the search term
Matching is case-insensitive for better usability.

​
Output Format

Memories are displayed in alphabetical order by key with:
  • Key - The memory identifier (shown on its own line)
  • Content - The stored insight (indented, truncated at 120 characters)
The output includes a count of total memories found.

​
Examples

​
List All Memories

View everything you’ve stored: 
bd memories
Output: 
Memories (4):

  api-test-setup
    This repo's API tests require STAGING_API_KEY env var

  auth-jwt
    Auth module uses JWT not sessions. Token expiry is 24h. Refresh tokens stored in Redis.

  docker-version
    Deploy script needs Docker 24+ for BuildKit features

  dolt-phantoms
    Dolt phantom DBs hide in three places: ~/.dolt, .dolt-data, and server catalog

​
Search by Keyword

Find memories about a specific topic: 
bd memories dolt
Output: 
Memories matching "dolt":

  dolt-phantoms
    Dolt phantom DBs hide in three places: ~/.dolt, .dolt-data, and server catalog

​
Search by Phrase

Use quotes for multi-word searches: 
bd memories "race flag"
Output: 
Memories matching "race flag":

  test-race-detector
    always run tests with -race flag to catch concurrency bugs

​
Search Matches Content

Search finds matches in both keys and content: 
bd memories JWT
Output: 
Memories matching "JWT":

  auth-jwt
    Auth module uses JWT not sessions. Token expiry is 24h.
Note: The key doesn’t contain “JWT” (lowercase), but the content does, so it matches.

​
No Results

When no memories match: 
bd memories kubernetes
Output: 
No memories matching "kubernetes"
When no memories exist at all: 
bd memories
Output: 
No memories stored. Use 'bd remember "insight"' to add one.

​
JSON Output

For programmatic access, add the --json flag: 
bd memories --json
Output: 
{
  "api-test-setup": "This repo's API tests require STAGING_API_KEY env var",
  "auth-jwt": "Auth module uses JWT not sessions. Token expiry is 24h.",
  "docker-version": "Deploy script needs Docker 24+ for BuildKit features",
  "dolt-phantoms": "Dolt phantom DBs hide in three places: ~/.dolt, .dolt-data, and server catalog"
}
With search: 
bd memories dolt --json
Output: 
{
  "dolt-phantoms": "Dolt phantom DBs hide in three places: ~/.dolt, .dolt-data, and server catalog"
}
Empty results: 
bd memories nonexistent --json
Output: 
{}

​
Use Cases

​
Quick Reference

Find that configuration detail you stored weeks ago: 
bd memories staging
# Shows all staging-related memories

​
Knowledge Discovery

Browse all stored knowledge before starting work: 
bd memories
# Review everything before making changes

​
Preventing Duplicates

Check if you’ve already stored similar knowledge: 
bd memories "docker version"
# See if docker requirements are already documented

​
Agent Context Building

AI agents can use this to gather project-specific knowledge: 
# Agent workflow:
# 1. Check for relevant memories
bd memories api
bd memories test

# 2. Use insights to inform implementation
# 3. Store new learnings
bd remember "API rate limit is 1000 req/min" --key api-rate-limit

​
Audit Trail

Review what knowledge has been accumulated: 
bd memories --json | jq 'keys'
# Get list of all memory keys

bd memories --json | jq 'to_entries | length'
# Count total memories

​
Agent Workflow

AI agents should use bd memories to:
  1. Check existing knowledge before asking questions
  2. Avoid duplicate storage by searching first
  3. Build context for unfamiliar projects
  4. Validate assumptions against stored insights
Example agent pattern: 
# Before working on auth code:
bd memories auth
# Oh! JWT tokens with 24h expiry - good to know

# Before deploying:
bd memories deploy
# Reminder: Docker 24+ required

​
Sorting and Display

Memories are always sorted alphabetically by key for consistency. The content is truncated at 120 characters to keep the list readable. To see full content, use: 
bd recall <key>  # See full content of specific memory
  • bd remember - Store a new memory
  • bd recall - Retrieve full content of a specific memory
  • bd forget - Delete a memory
  • bd prime - Inject all memories into AI context (auto-called by hooks)

​
Tips

Run bd memories at the start of each session to refresh your knowledge of project-specific details.
Use broad search terms first, then narrow down:
bd memories test    # See all test-related memories
bd memories "race"  # Narrow to race detector
Memories are sorted alphabetically by key, not by creation date. Use descriptive key prefixes to group related memories:
  • test-* for testing insights
  • deploy-* for deployment notes
  • api-* for API details
Search is case-insensitive but matches substrings. Searching for “test” will match “test-race”, “latest-build”, and “contest-winner”.

Build docs developers (and LLMs) love

Get started for freeTalk to us