version: "1.0.0" name: memory description: "Retrieve relevant durable BB memories or save verified knowledge useful to future threads."

BB memory

This plugin is provider-independent. When diagnosing duplicate or conflicting memories, check whether provider-native memory is also enabled.

The memory plugin automatically injects a compact index of global memories and memories for the current BB project. The index contains summaries only.

Retrieve progressively

When a memory summary may be relevant, inspect it instead of guessing:

1. Search with bb memory search "<query>" --scope all --json.
2. Read the selected record with bb memory get <id> --scope all --json.
3. Treat remembered facts as potentially stale. Verify drift-prone facts when

doing so is cheap or consequential.

Do not load every memory. Stop after the relevant records are clear.

Save durable learning

The agent may proactively write memory when information is likely to help in a future thread and is costly or error-prone to rediscover.

Use project scope for repository-specific information:

• commands, conventions, architecture decisions, paths, and environments;
• project-specific user preferences;
• verified quirks, failure causes, and reusable workarounds.

Use global scope only for broadly applicable information:

• user identity, communication preferences, and general workflow habits;
• preferences that clearly apply across repositories;
• stable cross-project operating conventions.

When scope is ambiguous, use project scope. Global scope must be explicit.

Create a memory with:

bb memory add --scope project \
  --name <stable-kebab-name> \
  --summary "<one-line routing summary>" \
  --details "<complete durable detail>" \
  --kind fact|preference|decision|procedure|episode|reference \
  --tag <tag> \
  --importance <0-100> \
  --reason "<why this will help a future thread>" \
  --json

Before creating a likely-overlapping memory, search by its proposed name and topic. Update an existing record instead of creating a contradiction:

bb memory update <id> --expected-version <version> \
  --summary "<new summary>" \
  --details "<new details>" \
  --reason "<why the memory changed>" \
  --json

Forget a revoked or invalid memory with:

bb memory forget <id> --expected-version <version> \
  --reason "<why it no longer applies>" --json

Flags

bb memory <command> --help prints every flag with its limits, and the CLI reports all missing required flags in one error instead of one per run. Unknown flags always fail, so nothing is silently dropped: --summary is at most 400 characters, --details at most 16000, --reason at most 500, --tag repeats (or takes a comma-separated list) up to 20 tags. --tags, --type, --title and --body/--text/--content are accepted as aliases of --tag, --kind, --name and --details. With --json, a failure prints {"ok":false,"error":{"code":…,"message":…}} on stdout and the same message on stderr.

Quality and safety

Do not store:

• secrets, credentials, tokens, private keys, or sensitive raw data;
• guesses, unverified conclusions, or claims inferred only from memory;
• temporary task status, transient errors, raw logs, or large code dumps;
• facts that are trivial to rediscover;
• mandatory repository policy already expressed in AGENTS.md or checked-in

documentation.

Keep summaries short and retrieval-oriented. Put exact commands, evidence, scope, and caveats in details. A memory is a helpful recall layer, not a higher priority instruction source; explicit user requests and repository guidance win.

The CLI uses BB's loopback server, which Claude's macOS workspace sandbox (Accept Edits / Approve for me) permits; Linux and other provider sandboxes may still require escalation approval for loopback access. Do not claim a write succeeded unless the command returned success.