BM(1)

NAME
bm - local-first knowledge base for humans and AI agents

SYNOPSIS
bm COMMAND [ARGS]...
basic-memory COMMAND [ARGS]...

DESCRIPTION
bm manages Basic Memory projects: plain markdown files that form a knowledge graph. Files are the source of truth; SQLite provides indexing and full-text search; the same operations are exposed to AI agents over the Model Context Protocol (MCP) and to humans and scripts through this CLI.

Notes use semantic markdown: observations (- [category] text #tag) and relations (- relation_type [[Target]]) become queryable graph structure. Projects route independently to the local API or to Basic Memory Cloud.

COMMANDS
Knowledge operations:

bm tool
    CLI access to the MCP tools (write-note, read-note, search-notes, build-context, ...). These emit JSON and are the scriptable surface.

bm status
    Show sync status between files and the database.

bm reindex
    Index local file changes and rebuild search/embeddings. This is the manual sync trigger when no MCP server is running.

bm doctor
    Run end-to-end file/database consistency checks.

bm orphans
    List entities with no relations in the knowledge graph.

bm format
    Run configured formatters over note files.

Projects and schemas:

bm project
    Add, remove, list projects; set the default; flip a project between local and cloud routing.

bm schema
    List, validate, infer, and drift-check Picoschema note-type contracts.

Data and cloud:

bm import
    Import from ChatGPT, Claude, or memory.json exports. Imports write files; run bm reindex afterwards.

bm cloud
    Authenticate, sync (push/pull/sync/bisync), snapshots, and team workspace administration.

Infrastructure:

bm mcp
    Run the MCP server (hosts the live file watcher).

bm man
    Manage these man pages (bm man install).

bm reset
    Drop and recreate the database (destructive).

Most commands accept --project NAME to target a project and --local/--cloud to override routing.

EXAMPLES
Write and find a note from the shell:

    echo "# Standup notes" | bm tool write-note \
        --title "Standup" --folder notes
    bm tool search-notes "standup"

Pick up files created outside the tools:

    bm status            # shows pending changes
    bm reindex           # indexes them

FILES

~/.basic-memory/config.json
    Projects, default project, per-project routing modes, cloud settings.

~/.basic-memory/memory.db
    SQLite index (derived; safe to rebuild with bm reindex).

ENVIRONMENT

BASIC_MEMORY_FORCE_LOCAL
    Force local routing regardless of cloud mode.

BASIC_MEMORY_LOG_LEVEL
    Logging verbosity (e.g. DEBUG).

SEE ALSO
Full manual (machine-readable, agent-traversable): the manual Basic Memory project — see docs/manual-pages.md in the repository. Documentation: https://docs.basicmemory.com

For AI agents: the complete tool reference lives in the manual project as section-3 pages (write-note(3), search-notes(3), ...), queryable via search_notes with metadata_filters={"type": "manpage"}.

BUGS
https://github.com/basicmachines-co/basic-memory/issues

AUTHORS
Basic Machines (https://basicmachines.co)