CLI Reference

bm status
bm status --verbose
bm status --json
bm status --project research
bm status --wait --timeout 60

bm doctor

# Default: stdio transport (for Claude Desktop, Claude Code, etc.)
bm mcp

# Lock to a single project
bm mcp --project main

# HTTP transport for web deployments
bm mcp --transport streamable-http --port 8000

# SSE transport for compatibility with existing clients
bm mcp --transport sse

# Rebuild everything (search + embeddings)
bm reindex

# Rebuild only full-text search index
bm reindex --search
bm reindex -s

# Rebuild only vector embeddings
bm reindex --embeddings
bm reindex -e

# Reindex a specific project
bm reindex -p main

bm reset
bm reset --reindex

bm orphans
bm orphans --json
bm orphans --project research

# Check for updates and install if available
bm update

# Check only — report without installing
bm update --check

bm format                         # Format all files in current project
bm format --project research      # Format files in specific project
bm format notes/meeting.md        # Format a specific file
bm format notes/                  # Format all files in a directory

bm inspect chunks "coffee-brewing-methods"
bm inspect chunks "Coffee Brewing Methods" --project research
bm inspect chunks coffee-brewing-methods --json

bm inspect query "how do we handle auth"
bm inspect query "auth" --mode vector --show-misses
bm inspect query "auth" --mode hybrid --page 1 --page-size 10 --json

bm config list
bm config list --json

bm config get reranker_enabled
bm config get milvus_uri

bm config set reranker_enabled true
bm config set cli_output_style plain

bm config unset reranker_enabled

# Inspect shared inbox and harness settings health
bm hook status --harness codex --project-dir /path/to/repository
bm hook status --harness claude --project-dir /path/to/repository

# Archive local lifecycle envelopes
bm hook flush
bm hook flush --older-than-days 30

# Wire or remove user-level hooks without a plugin
bm hook install --harness codex
bm hook remove --harness codex
bm hook install --harness claude
bm hook remove --harness claude

bm project list
bm project list --json
bm project list --workspace my-workspace

bm project info main
bm project info main --json

# Local project
bm project add research ~/Documents/research

# Cloud project (no local sync)
bm project add research --cloud

# Cloud project with local sync path
bm project add research --cloud --local-path ~/docs

# Cloud project in a specific team workspace, visible to all members
bm project add team-wiki --cloud --workspace acme --visibility workspace

# Cloud project restricted to specific people you grant access to
bm project add hiring --cloud --workspace acme --visibility shared

# Add and set as default
bm project add research ~/Documents/research --default

# Stop tracking a project while retaining its files
bm project remove research

# Delete a local project's files
bm project remove research --delete-notes

# Purge cloud storage and remove any configured local sync directory
bm project remove research --cloud --delete-notes

bm project default main

bm project move research /new/path/to/research

bm project ls --name research
bm project ls --name research subfolder
bm project ls --name research --local
bm project ls --name research --cloud

bm project set-cloud research
bm project set-local research

bm cloud login
bm cloud status
bm cloud logout

bm cloud api-key save bmc_...
bm cloud api-key create "my-laptop"

bm cloud setup   # provision the rclone remote (Personal workspaces; Team push/pull needs no setup)
bm cloud upload ~/my-notes --project research --create-project

# Fetch cloud changes additively (Personal + Team workspaces)
bm cloud pull --name research

# Upload local changes additively (Personal + Team workspaces)
bm cloud push --name research

# Choose conflict resolution: fail (default) | keep-local | keep-cloud | keep-both
bm cloud pull --name research --on-conflict keep-cloud

# One-way mirror: local → cloud (Personal workspaces only)
bm cloud sync --name research

# Preview and delete cloud files matching ~/.basic-memory/.bmignore (Personal only)
bm cloud prune --name research --dry-run
bm cloud prune --name research

# Verify file integrity between local and cloud (Personal only)
bm cloud check --name research

# Configure local sync for an existing cloud project
bm cloud sync-setup research ~/Documents/research

bm cloud share create research notes/my-idea
bm cloud share create research notes/my-idea --expires-at 2099-12-31
bm cloud share list
bm cloud share list --project research
bm cloud share update SHARE_TOKEN --disable
bm cloud share update SHARE_TOKEN --enable
bm cloud share update SHARE_TOKEN --expires-at none
bm cloud share revoke SHARE_TOKEN
bm cloud share revoke SHARE_TOKEN --force

bm cloud snapshot create "Before migration"
bm cloud snapshot list
bm cloud snapshot show <snapshot-id>
bm cloud snapshot browse <snapshot-id>
bm cloud snapshot delete <snapshot-id>

bm cloud restore <path> --snapshot <snapshot-id>

# List cloud workspaces available to the current session
bm cloud workspace list

# Set the default workspace for CLI and MCP routing
bm cloud workspace set-default acme

bm cloud promo --off
bm cloud promo --on

# Validate all notes with schemas
bm schema validate

# Validate all notes of a type
bm schema validate person

# Validate one specific note
bm schema validate people/ada-lovelace.md

# Strict mode — exit 1 if any validation errors are found
bm schema validate person --strict

# Machine-readable output
bm schema validate person --json

# Target a specific project
bm schema validate person --project research

# Infer schema for a note type
bm schema infer person

# Lower the threshold to include less common fields
bm schema infer person --threshold 0.1

# Machine-readable output
bm schema infer person --json

# Target a specific project
bm schema infer person --project research

# Check drift for a note type
bm schema diff person

# Machine-readable output
bm schema diff person --json

# Target a specific project
bm schema diff person --project research

# Create a note with inline content
bm tool write-note --title "API Notes" --folder specs --content "# API Notes"

# Pipe content from stdin
echo "# My Note" | bm tool write-note --title "My Note" --folder notes

# Set the note type at creation time
bm tool write-note --title "Standup" --folder meetings --type meeting

# Replace an existing note (past the overwrite guard)
bm tool write-note --title "API Notes" --folder specs --content "..." --overwrite

bm tool read-note "specs/api-notes"
bm tool read-note my-note --include-frontmatter

bm tool edit-note my-note --operation append --content "new content"
bm tool edit-note my-note --operation find_replace --find-text "old" --content "new"
bm tool edit-note my-note --operation replace_section --section "## Notes" --content "updated"
bm tool edit-note my-note --operation replace_section --section "## Notes" --content "updated" --no-replace-subsections

bm tool delete-note notes/old-draft
bm tool delete-note docs/archive --is-directory

# Text search (query is a positional argument)
bm tool search-notes "authentication"

# Tag and metadata filters (query is optional)
bm tool search-notes --tag python --tag async
bm tool search-notes --meta status=draft
bm tool search-notes --type person --type meeting

# Search observations by category
bm tool search-notes "auth" --entity-type observation --category decision

# Search modes
bm tool search-notes "how to speed up the app" --hybrid
bm tool search-notes "how to speed up the app" --vector
bm tool search-notes --permalink "specs/*"
bm tool search-notes --title "API Design"

# Advanced metadata filter (JSON)
bm tool search-notes --filter '{"priority": {"$in": ["high", "critical"]}}'

# Pagination
bm tool search-notes "api" --page 2 --page-size 20

bm tool build-context memory://specs/search
bm tool build-context specs/search --depth 2 --timeframe 30d

bm tool recent-activity
bm tool recent-activity --timeframe 30d --page-size 20
bm tool recent-activity --type entity --type observation

bm tool schema-validate person
bm tool schema-infer person
bm tool schema-diff person
bm tool list-projects
bm tool list-workspaces

bm import claude conversations
bm import claude projects
bm import chatgpt
bm import memory-json /path/to/export.json