CLI Reference

Use bm (short) or basic-memory (full). Examples below use bm.

Every command also has a manual page: bm man list lists them and bm man <page> prints one (see Manual commands).

Core commands

bm status

Show the current project-index observation and readiness: how many project files were seen, with file details under --verbose. Use --json for automation.

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

In v0.24, --json reports readiness per stage. readiness.stages covers file indexing, relation resolution, and embeddings separately, and readiness.phase tells a project that was never indexed apart from one that is indexed and idle. --wait now blocks until every stage settles, embeddings included, not just until file changes are processed.

bm doctor

Run local consistency checks to verify file/database sync. Defaults to local routing since it scans the local filesystem.

bm doctor

bm mcp

Run the MCP server with configurable transport options. The server handles initialization, file sync, and cleanup automatically.

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

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

# HTTP transport (binds 127.0.0.1 by default)
bm mcp --transport streamable-http --port 8000

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

# Accept connections from other machines (no authentication; trusted networks only)
bm mcp --transport streamable-http --host 0.0.0.0

bm reindex

Rebuild search indexes and/or vector embeddings without dropping the database.

# 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

When neither --search nor --embeddings is specified, both are rebuilt. To index a single project by name, bm project index NAME does the same as bm reindex --project NAME.

bm reindex --embeddings exits nonzero if any embedding fails and reports the configured vector index. Changing semantic_vector_index requires this command; until it succeeds, vector search returns no results and hybrid search serves full-text results only.

In v0.24, semantic search is always on, so --embeddings never refuses. It also finishes oversized notes before reporting success. Vector sync embeds at most 256 chunks of one note per pass, and the reindex now repeats passes until no deferred chunks remain. With --full, vectors are cleared only once. If a pass stops making progress, the command reports how many notes still have pending chunks and exits nonzero.

bm prune

Remove index entries for files that your current .bmignore or .gitignore patterns now exclude. Indexing skips ignored files, but entries indexed before a pattern was added stay in the index because the files are still on disk. Like git rm --cached, prune removes the index entries (entity, relations, search rows, vectors) and leaves the files untouched.

bm prune --dry-run
bm prune
bm prune --project research --yes

prune lists the entries before removing them. For cloud projects, use bm cloud prune instead.

bm reset

Reset database — drops all tables and recreates them. Files are never deleted.

bm reset
bm reset --reindex

bm orphans

List entities that have no relations — no incoming or outgoing connections in the knowledge graph. Useful for finding notes that aren't yet linked to anything, or notes that had their relations removed.

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

bm update

Check for a newer Basic Memory release and install it when supported. Basic Memory also checks for updates automatically in the background for Homebrew and uv tool installs (uvx environments are skipped — uvx resolves its own cache); MCP server processes check silently and never block.

# Check for updates and install if available
bm update

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

bm format

Format files using configured formatters. Uses the formatter_command or formatters settings from your config. By default, formats all .md, .json, and .canvas files in the current project.

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

Shell-style read commands

New in v0.24. These read-only verbs mirror the familiar Unix tools and share one translation layer with the MCP cat, grep, ls, find, and tail tools. All of them accept --project, --project-id, --local, and --cloud, plus --json and --plain for output. They follow the same output rules as bm tool: Rich on a TTY, JSON when piped.

Projects act as mount points. bm ls / lists your projects as top-level directories, and a path whose first segment names a project routes to that project (bm ls /research/specs). The paths these commands return can be passed straight back in.

bm cat

Print a note, resolved exactly by title, permalink, or memory:// URL. Notes are indexed by heading, so you can read one section, a line range, or a token budget instead of the whole note.

bm cat specs/search
bm cat specs/search --lines 20-40
bm cat specs/search --section Decisions
bm cat specs/search --section "Auth/Decisions"
bm cat specs/search --max-tokens 500 --plain

--lines and --section cannot be combined. A section response includes start_line and end_line for follow-up --lines reads. With --plain, the raw content goes to stdout and slice details go to stderr.

bm head

Print the first lines of a note (head(1) over bm cat).

bm head specs/search
bm head specs/search -n 3 --plain

bm grep

Search note content by keyword. A pattern found in no note returns no results. The pattern is tokenized like a full-text query, not treated as a regex. Pass --semantic to rank by meaning instead; semantic results are nearest neighbours, so they can include notes that do not contain the pattern.

bm grep "BASIC_MEMORY_FORCE_LOCAL"
bm grep "retry" -C 3 --plain
bm grep --semantic "auth token rotation"
bm grep "deploy checklist" --page-size 20 --json

With -C N, the full-text index selects candidate notes, and their current content is checked for case-insensitive literal matches. Overlapping windows merge. Line numbers include frontmatter, so you can pass them straight to bm cat NOTE --lines N-M or bm tool read-note NOTE --start-line N --end-line M. Pagination and totals count candidate notes, not matching lines.

bm ls

List the immediate contents of one directory. Directories print with a trailing slash. With no path, bm ls lists /, where each project appears as a directory.

bm ls
bm ls /research
bm ls /research/specs
bm ls /main/notes --page 2 --plain

--plain prints one path per line, ls -1 style. When more pages exist, --plain reports that on stderr so stdout stays clean for pipes.

bm find

Recursively list files by name glob, or query notes by frontmatter metadata.

# List files
bm find --name "*.md"
bm find /specs --depth 3
bm find /notes --name "auth*" --plain

# Query notes by frontmatter
bm find /specs --meta "status=active" --meta "confidence>0.6"
bm find --meta "priority in high,critical" --fields title,priority,owner
bm find --meta "tags has security" --meta "owner=null"

Predicates use one key per --meta flag:

Values are inferred as JSON scalars, so true, false, null, and numbers are typed. Quote a value to force a literal string, for example status="true". Keys accept dot-paths into nested frontmatter (review.approved). PATH still scopes a --meta query, by file path. --name and --depth are refused alongside --meta.

--fields works like a SELECT clause. Each hit returns the note's identity (title, permalink, file path, external ID, last updated) plus a fields object with the named values, instead of the note body. --plain reports further pages on stderr.

bm tail

Show the most recently changed notes in a project, newest first. This is the tail of the change log, not of one file.

bm tail
bm tail -n 20 --timeframe 1d
bm tail --plain

Each row shows the last-change time (updated_at), type, title, permalink, and file path.

bm tree

Show a directory hierarchy (tree(1) over bm find).

bm tree
bm tree /specs --depth 2
bm tree --name "*.md" --plain

Manual commands

New in v0.24. The manual ships inside the package. Section 1 covers the shell commands (cat(1), grep(1), okf-export(1), ...), and section 3 has one page per MCP tool (search-notes(3), write-note(3), ...). The MCP server serves the same pages as memory://man resources.

bm man list                       # every page with its one-line summary
bm man search-notes               # print a page as Markdown
bm man "grep(1)"
bm man apropos "conflict resolution"
bm man install                    # install man pages, then try `man bm`

Wiki navigation commands

New in v0.24. bm wiki generates deterministic navigation pages for a local project: a root and per-folder index.md, plus log.md with the 25 most recent changes. Local and cloud produce the same bytes. A hand-written index.md or log.md is never overwritten; it is reported as a conflict instead.

bm wiki status
bm wiki validate --project research
bm wiki rebuild --dry-run
bm wiki rebuild --all

OKF export commands

New in v0.24. Export a local project as a static OKF v0.2-compatible bundle, or check an existing bundle.

bm okf export ~/exports/research-okf --project research
bm okf export ~/exports/research-okf --project research --replace
bm okf check ~/exports/research-okf
bm okf check ~/exports/research-okf --json

bm okf export DESTINATION --project NAME keeps concept frontmatter, categorized observations, and relative asset paths. It rewrites wikilinks to standard Markdown links, resolved the way the graph resolves them, and records the original relation types in a bm.okf_export extension. It also generates per-folder index.md files and a dated root log.md from the accepted-write journal. The export is staged beside the destination and validated before publishing. It refuses to overwrite an existing destination without --replace, and it restores the previous bundle if publication fails. The destination must be outside the source project, and cloud projects must be pulled locally first.

bm okf check BUNDLE_PATH reports per-file, per-rule diagnostics and exits nonzero on any violation. Both commands accept --json. See bm man okf-export for the full rules.

Agent host install commands

New in v0.24. bm install installs the Basic Memory plugin or package into an agent host. None of these commands touch the Basic Memory database.

bm install codex
bm install claude-code --scope project
bm install tau --dry-run
bm install pi --local

All four accept --dry-run to preview the plan and --yes to approve it without a prompt. Codex and Claude Code installs delegate to the host's own plugin CLI and accept --source to use a different marketplace Git source or local repo.

Retrieval inspection commands

Read-only diagnostics for search, new in v0.23. When a note doesn't come back for a query you expected it to, bm inspect chunks answers "is this note indexed, embedded, and current?" and bm inspect query answers "what did retrieval actually do with my query?".

bm inspect chunks

Show how the retrieval index decomposes one note into search rows and vector chunks. Accepts the same identifiers as read_note: a title, permalink, or memory:// URL.

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

The output shows the note's entity, observation, and relation search rows with the vector chunks each row produced, plus a readiness summary and a per-chunk status:

A freshness state (fresh, not_indexed, index_behind_rows, rows_behind_file, or unknown) distinguishes a chunking problem from an indexing-lag problem, with the checksum or fingerprint evidence for any non-fresh state.

bm inspect query

Run a search and trace its execution: every retrieval stage — matching, hydration, filtering, fusion, reranking, and the final page window — that produced the result page. The trace is captured by the same call that returns the results, so it reflects the actual execution rather than a reconstruction, and ordinary searches are unaffected.

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

The output shows the engine identity (vector index, embedding model, fusion formula, minimum similarity, reranker status), a stage table with in/out/dropped counts and timings, and the ranked results with final scores and rerank movement (Δ).

Configuration commands

bm config list

List every scalar setting with its effective value and source. Environment overrides are marked with the exact BASIC_MEMORY_* variable.

bm config list
bm config list --json

bm config get

Show one effective value and report any environment override:

bm config get reranker_enabled
bm config get milvus_uri

bm config set

Validate a value through the same config model used at startup, then write it to config.json:

bm config set reranker_enabled true
bm config set cli_output_style plain

Invalid keys or values exit nonzero without changing the config file. If an environment variable overrides the file value, the command writes the value but warns that the environment still wins. bm config set default_project rejects an unknown project and accepts a project's display name.

bm config unset

Remove a setting from config.json:

bm config unset reranker_enabled

The effective value then falls back to an environment override when one exists, otherwise to the built-in default.

list, get, set, and unset mask secret values and redact credentials embedded in URLs. Structured fields such as projects are managed by their dedicated command groups and do not appear as writable scalar settings.

Harness hook commands

bm hook is the lifecycle front door used by the Basic Memory Claude Code and Codex plugins. See Harness Capture for event behavior, settings, and retention.

# 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

Project management

bm project list

List projects from local config and (when available) cloud.

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

bm project info

Display detailed information and statistics about a project. Shows an htop-inspired compact dashboard with horizontal bar charts for note types, embedding coverage bars, and colored status dots.

bm project info main
bm project info main --json

bm project add

Add a new project. A local project is indexed before the command returns, so its notes are searchable immediately and the command shows embedding progress. Pass --no-wait to register a large directory now and index it later with bm project index.

# Local project (indexed before returning)
bm project add research ~/Documents/research

# Register now, index later
bm project add archive ~/Documents/archive --no-wait
bm project index archive

# 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

Under BASIC_MEMORY_PROJECT_ROOT, a project name whose permalink contains / (such as Research/2026) is refused, so every project stays a single top-level directory under the shared root.

bm project index

Index a project's files so its notes become searchable. Builds the search index and the embeddings. Same as bm reindex --project NAME.

bm project index research

Use it after bm project add --no-wait, or after fixing permissions on a directory the file watcher could not read.

bm project remove

Remove a project. What happens to files depends on where the project lives.

# Stop tracking a local project; files stay on disk
bm project remove research

# Remove a local project and delete its files
bm project remove research --delete-notes

# Remove a cloud project (always deletes its cloud files; asks to confirm)
bm project remove research --cloud

# Also delete the local sync directory, without a prompt
bm project remove research --cloud --delete-local-files --yes

Local projects: removing one stops tracking it. Its files stay on disk unless you pass --delete-notes.

Cloud projects: removing one always deletes its files from cloud storage. There is no longer a way to keep them. The command warns that the files can be recovered only from a cloud snapshot (bm cloud snapshot list) and asks for confirmation. Cloud deletion is accepted asynchronously: a background job purges the objects under the project's storage prefix, then completes the hard delete. Existing snapshots follow their own retention lifecycle. The local routing entry is removed too, so you can add the name again. A cloud-only project removed without --cloud is still treated as cloud-routed.

bm project default

Set the default project used as fallback when no project is specified.

bm project default main

bm project move

Update a local project's configured filesystem path. This changes configuration only — move the files to the new path yourself (Basic Memory does not move them).

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

bm project ls

List files in a project directory.

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

Routing modes (per project)

Route specific projects through cloud while keeping others local:

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

Cloud commands

Authentication and status

bm cloud login
bm cloud status
bm cloud logout

API keys

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

Setup and upload

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

Sync

# 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

# 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

push/pull are additive (never delete on the destination) and abort on conflicts by default, git-style. They are the supported sync workflow on both Personal and Team workspaces. On Team workspaces they run over the cloud's permissioned WebDAV API, with no bm cloud setup required and access checked per project. prune performs only ignore-based remote cleanup and asks for confirmation unless you pass --yes. For local index cleanup, use bm prune. See the Cloud Sync guide for details.

Public shares

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

All share commands accept --workspace to route by workspace slug, display name, or tenant ID. revoke confirms before deletion unless --force is set.

Snapshots

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>

Restore

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

Workspaces

# 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

See Teams for working with shared team workspaces.

Promo controls

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

Schema commands

Tools for defining, validating, and evolving note structure. See Schema System for concepts and workflow.

bm schema validate

Validate notes against their schema definition. Pass a note type to validate all notes of that type, a specific file path to validate one note, or omit to validate all notes that have schemas.

# 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

bm schema infer

Analyze existing notes of a type and suggest a schema based on common observation categories, relation types, and frontmatter fields. Fields present in 95%+ of notes become required; fields above the threshold become optional.

# 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

bm schema diff

Compare a schema definition against actual note usage to detect drift. Shows new fields appearing, old fields disappearing, and cardinality changes.

# 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

Tool commands (CLI wrapper for MCP tools)

Command group: bm tool (singular). This provides CLI access to the same MCP tools that AI assistants use, useful for scripting, debugging, and quick operations from the terminal.

Search, read, context, and activity commands use Rich tables, panels, trees, or Markdown when stdout is a TTY. Output precedence is:

1. --json for raw machine-readable JSON.
2. --plain for undecorated human-readable text.
3. Non-TTY output defaults to JSON, preserving piped and redirected scripts.
4. TTY output follows cli_output_style (rich by default, or plain).

--json and --plain are mutually exclusive. Set the interactive default with bm config set cli_output_style plain.

Exit status follows the tool result. Reading a note that does not exist exits with status 1 in every output mode, and JSON output carries error: "NOTE_NOT_FOUND". A refused write-note or a failed or refused edit-note prints the error and exits 1; for write-note, the JSON payload still goes to stdout. Before v0.24, a missing note exited 0 with null fields, so scripts should check the exit status.

bm tool write-note

# 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

# Replace it only if it is still the revision you read
bm tool write-note --title "API Notes" --folder specs --content "..." --overwrite --expected-checksum <checksum>

bm tool read-note

bm tool read-note "specs/api-notes"
bm tool read-note my-note --frontmatter
bm tool read-note my-note --json
bm tool read-note my-note --start-line 120 --end-line 180 --plain

A line-range read returns numbered lines plus the next range to read. A start line past the end of the note is an error. Line numbers from bm grep -C can be passed straight in.

bm tool edit-note

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

As of v0.24, replace_section fails when the exact heading is not in the note, instead of appending a duplicate section. Give a heading such as ## Open items #urgent in full, or use append to create a new section on purpose.

bm tool delete-note

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

bm tool search-notes

# 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

# Identifiers and metadata only, without note bodies
bm tool search-notes "api" --compact

bm tool build-context

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

bm tool recent-activity

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

Schema tool commands

These are CLI wrappers around the schema MCP tools with JSON output:

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

Import commands

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

bm import document

Extract a PDF, Word (.docx), PowerPoint (.pptx), or CSV file that is already stored inside a project into a sidecar Markdown note. New in v0.24.

# Install the extractors: [documents] for Word/PowerPoint, [pdf] for PDF
uv tool install "basic-memory[documents,pdf]"

# Paths are relative to the project root, not your current directory
bm import document reports/q3-review.pdf
bm import document decks/roadmap.pptx --project research

The command indexes the project, extracts the file, and writes <file>.<ext>.md next to it, plus a run note under document-ingestion-runs/. CSV needs no extra and renders a bounded preview. Re-running is a no-op while the source is unchanged, and the command refuses to overwrite a hand-written or enriched note at the sidecar path.

Notes on defaults

• If --project is omitted, Basic Memory falls back to default_project when configured.
• Most bm tool subcommands accept --project-id (the project's external UUID from bm project list --json) to disambiguate same-named projects across cloud workspaces.
• --local and --cloud flags are available on most commands for routing overrides.
• BASIC_MEMORY_* environment variables override config.json for the current process only. As of v0.24 they are no longer written into config.json when a command saves config.

Related pages

• What's new in v0.24
• Upgrade to v0.24
• Configuration
• MCP Tools Reference
• Cloud Guide
• Schema System
• Semantic Search