v0.22.0

v0.22.0 makes cloud sync safe for teams. New bm cloud push and bm cloud pull commands transfer changes additively — they never delete files on the destination — so you can collaborate on a shared Team workspace without risking a teammate's work. The release also brings search improvements, more capable bm tool and bm status commands, and a long list of MCP tool and embedding reliability fixes.

v0.22.1 patch

A follow-up patch to v0.22.0 focused on first-run reliability:

• Fresh installs no longer get stuck when the projects table is empty — Basic Memory now routes you to project setup and promotes your first project to the default automatically.
• Sync skips projects without a valid local path and ignores stale projects left in the database but missing from your config.
• MCP qualified project routes resolve workspace display names and tenant ids correctly.
• search_notes comma-splits note_types, entity_types, and categories, matching how tags already behave.
• write_note gains a workspace parameter for parity with edit_note.
• Faster CLI startup — heavy imports are deferred out of the command path.

Full details in the changelog.

Team-Safe Push and Pull

push and pull model git push / git pull: additive, conflict-aware transfers that work on both Personal and Team workspaces.

# Fetch cloud changes into your local directory
bm cloud pull --name research

# Upload your local changes to the cloud
bm cloud push --name research

# Preview either direction first
bm cloud pull --name research --dry-run

If a file differs on both sides, the command aborts and lists the conflicts — like a rejected git push. Re-run with --on-conflict to choose what survives:

Each Team workspace gets its own scoped rclone remote, so credentials and sync state stay isolated per workspace.

Mirror commands are now Personal-only

bm cloud sync and bm cloud bisync are mirror operations — one side becomes authoritative and missing files get deleted on the other. That's correct for a Personal workspace with a single writer, but unsafe on a shared Team bucket. On Team workspaces these commands now exit early with a clear error and point you at push/pull instead.

See the Cloud Sync guide for details.

Search Improvements

• Observation category filter — narrow search results to specific observation categories like [decision] or [fact].
• Comma-separated tags just work — tags="alpha,beta" and the tag:alpha,beta shorthand now split and match consistently everywhere.
• note_types filter is case-insensitive, so Task and task find the same notes.

CLI Improvements

• bm status --wait --timeout 60 — block until sync completes, handy for scripting.
• bm tool write-note --type — set the note type at creation time.
• bm tool delete-note — delete notes from the command line.
• bm tool commands align with MCP behavior — consistent error exit codes, overwrite handling, and defaults across the CLI wrappers and the MCP tools they mirror.

Experimental: LiteLLM Embeddings

Semantic search can now use a LiteLLM-backed embedding provider, opening the door to hosted embedding models beyond the built-in FastEmbed. This is experimental — expect the configuration surface to evolve.

Embedding reliability also improved across the board: FastEmbed vectors are L2-normalized for correct similarity scoring with custom models, corrupt model caches self-heal, and a single embedding provider is reused per process.

Reliability Fixes

A large round of MCP tool fixes:

• build_context resolves observations by the same permalink the search index uses, and truncated observation permalinks no longer collide.
• edit_note recovers when a file exists on disk but isn't indexed yet.
• move_note resolves memory:// URLs, no longer falsely rejects same-project moves, and no longer reports false success across project boundaries.
• read_note accepts page/page_size like its sibling tools.
• recent_activity shows the correct project, and navigation pagination is validated.
• bm cloud setup no longer overwrites an existing rclone remote.

Upgrading

No breaking changes. Upgrade as usual:

uv tool upgrade basic-memory
# or
brew upgrade basic-memory

Full details in the changelog.