bd memories

List or search persistent memories across your project

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

Related Commands

• 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”.