bd forget

Remove a persistent memory by its key

Overview

The bd forget command permanently deletes a stored memory from the key-value store. Use this to remove outdated, incorrect, or no longer relevant knowledge.

Added in: v0.58.0

Syntax

bd forget <key>

Arguments

key · string · required

The exact key of the memory to delete. Keys are case-sensitive.

How It Works

The command:

1. Looks up the memory by key (kv.memory.<key>)
2. Verifies it exists (fails if not found)
3. Deletes it from the database
4. Confirms deletion with the deleted content (truncated)

The deletion is permanent and syncs via Dolt push/pull like all database changes.

Examples

Basic Deletion

Remove a single memory:

bd forget test-race

Output:

Forgot [test-race]: always run tests with -race flag to catch concurrency bugs

Long Content Confirmation

When forgetting a long memory:

bd forget deployment-checklist

Output (truncated at 80 chars):

Forgot [deployment-checklist]: Pre-deployment checklist: 1. Run full test suite wi...

Key Not Found

Attempting to delete a non-existent memory:

bd forget nonexistent-key

Output (stderr):

No memory with key "nonexistent-key"

Exit code: 1

JSON Output

For programmatic use:

bd forget test-race --json

Success output:

{
  "key": "test-race",
  "deleted": "true"
}

Not found output:

{
  "key": "nonexistent-key",
  "found": "false"
}

Exit code: 1 when not found.

Use Cases

Remove Outdated Information

Clean up memories that are no longer accurate:

# Old info
bd remember "API rate limit is 100 req/min" --key api-rate-limit

# Rate limit changed
bd forget api-rate-limit
bd remember "API rate limit is 1000 req/min" --key api-rate-limit

Note: You can also just update by running bd remember with the same key. Use forget when you want to completely remove the memory, not replace it.

Cleanup Test Data

Remove memories created during testing:

bd forget test-memory-1
bd forget test-memory-2
bd forget temp-note

Remove Sensitive Info

If you accidentally stored something sensitive:

bd forget api-key  # Delete immediately

This only deletes from the current database. If you’ve already pushed to a Dolt remote, the memory exists in git history. Use dolt sql to rewrite history if needed, or rotate the credential.

Bulk Deletion Script

Delete multiple memories at once:

#!/bin/bash
for key in $(bd memories temp --json | jq -r 'keys[]'); do
  bd forget "$key"
done

Or delete all memories matching a pattern:

# Delete all test-* memories
bd memories --json | jq -r 'keys[] | select(startswith("test-"))' | while read key; do
  bd forget "$key"
done

Safe Deletion with Confirmation

Verify before deleting:

# 1. Check what you're about to delete
bd recall auth-old

# 2. Confirm it's the right one
echo "Delete this? (y/n)"
read answer

# 3. Delete if confirmed
if [ "$answer" = "y" ]; then
  bd forget auth-old
fi

Agent Cleanup

AI agents can clean up after themselves:

# Agent stores temporary context
bd remember "Working on feature X, needs Y" --key agent-context

# Work is done, clean up
bd forget agent-context

Exit Codes

• 0: Memory deleted successfully
• 1: Memory key not found (nothing to delete)

Use in scripts:

if bd forget old-config 2>/dev/null; then
  echo "Cleaned up old config"
else
  echo "No old config to clean"
fi

Finding Keys to Delete

If you don’t remember the exact key:

# 1. Search for it
bd memories staging
# Shows: staging-api, staging-db, staging-old

# 2. Delete the right one
bd forget staging-old

Or list all keys:

bd memories --json | jq 'keys[]'

Undo Deletion

There’s no built-in undo for bd forget, but if you have Dolt history:

# 1. Find the commit before deletion
bd dolt log --oneline | head

# 2. Check the old value
bd dolt show <commit-hash>

# 3. Re-create the memory
bd remember "original content" --key original-key

Or query historical data:

bd sql "SELECT value FROM beads_config AS OF '<commit-hash>' WHERE key = 'kv.memory.old-key'"

Related Commands

• bd memories - List all memories to find keys to delete
• bd recall - View full content before deleting
• bd remember - Store or update a memory (alternative to delete + recreate)

Tips

Before deleting, recall the content to verify it’s what you think:

bd recall suspicious-key  # Check content first
bd forget suspicious-key  # Then delete

Use descriptive keys with prefixes so you can bulk-delete by category:

# All temp-* keys can be cleaned up together
bd forget temp-note-1
bd forget temp-note-2

Deletion is permanent in your local database. However, Dolt tracks all changes. If you need to recover a deleted memory, you can query historical commits.

If you’re using bd forget to remove sensitive data, remember that:

1. The data remains in Dolt history
2. If pushed to a remote, it’s in the shared history
3. Use Dolt’s history rewriting features if true deletion is required
4. Rotate compromised credentials regardless

Common Patterns

Replace Instead of Delete

Often you want to update, not delete:

# Don't do this:
bd forget api-config
bd remember "new config" --key api-config

# Do this instead:
bd remember "new config" --key api-config  # Automatically updates

Safe Batch Deletion

Delete multiple memories with confirmation:

for key in $(bd memories deprecated --json | jq -r 'keys[]'); do
  echo "Delete $key?"
  bd recall "$key"
  read -p "Confirm (y/n): " answer
  if [ "$answer" = "y" ]; then
    bd forget "$key"
  fi
done

Audit Before Delete

Log deletions for audit trail:

#!/bin/bash
KEY=$1
CONTENT=$(bd recall "$KEY" 2>/dev/null)
if [ $? -eq 0 ]; then
  echo "[$(date)] Deleting $KEY: $CONTENT" >> /tmp/bd-forget.log
  bd forget "$KEY"
fi