Cloud Sync Guide

The Basic Memory Cloud CLI provides seamless integration between local and cloud knowledge bases using project-scoped synchronization. Each project can optionally sync with the cloud, giving you fine-grained control over what syncs and where.

Overview

The cloud CLI enables you to:

• Per-project routing - Route individual projects through cloud with bm project set-cloud; the rest stay local
• Project-scoped sync - Each project independently manages its sync configuration
• Explicit operations - Sync only what you want, when you want
• Team-safe push/pull - Additive, git-style transfers that work on Personal and Team workspaces alike
• Offline access - Work locally, sync when ready

The sync commands

push and pull are the supported sync workflow. They are additive — they never delete files on the destination — and conflict-aware, so they are safe everywhere, including shared Team workspaces where a mirror operation could delete a teammate's files.

Prerequisites

Before using Basic Memory Cloud sync, you need:

• Active Subscription: An active Basic Memory Cloud subscription
• Subscribe: Visit basicmemory.com/subscribe
• Basic Memory CLI: See Install Basic Memory locally for installation

When to Use Sync

Architecture: Project-Scoped Sync

How It Works

Projects can exist in three states:

1. Cloud-only - Project exists on cloud, no local copy
2. Cloud + Local (synced) - Project has a local working directory that syncs
3. Local-only - Project exists only on your machine (the default for bm project add)

Example:

# You have 3 projects on cloud:
# - research: wants local sync at ~/Documents/research
# - work: wants local sync at ~/work-notes
# - temp: cloud-only, no local sync needed

bm cloud sync-setup research ~/Documents/research
bm cloud sync-setup work ~/work-notes
# temp needs no setup — it stays cloud-only

# Now you can sync individually:
bm cloud pull --name research
bm cloud pull --name work

What happens under the covers:

• Config stores each project as an entry with a local_sync_path in ~/.basic-memory/config.json
• Rclone transfers files using a tenant-scoped remote per workspace (basic-memory-cloud for your Personal workspace)
• Projects can live anywhere on your filesystem

Quick Start

1. Sign in to Cloud

Authenticate the CLI:

bm cloud login

What this does:

1. Opens browser to Basic Memory Cloud authentication page
2. Stores authentication token
3. Validates your subscription status

Login doesn't change project routing or start syncing — projects stay local unless you route or sync them explicitly.

2. Set Up Sync

Install rclone and configure credentials:

bm cloud setup

What this does:

1. Installs rclone automatically (if needed)
2. Fetches your tenant information from cloud
3. Generates scoped S3 credentials for sync
4. Configures a tenant-scoped rclone remote for the workspace (basic-memory-cloud for your Personal workspace)

3. Add Projects with Sync

Create projects with optional local sync paths:

# Create cloud project without local sync
bm project add research --cloud

# Create cloud project WITH local sync
bm project add research --cloud --local-path ~/Documents/research

# Or configure sync for an existing cloud project
bm cloud sync-setup research ~/Documents/research

4. Pull the Project Down

Fetch the cloud copy into your local directory. Preview with --dry-run first:

# Step 1: Preview what would transfer
bm cloud pull --name research --dry-run

# Step 2: Fetch cloud files into your local directory
bm cloud pull --name research

pull is additive — it fetches new and changed files without deleting anything local.

5. Daily Workflow

Pull before you start, edit locally, push when you're done:

# Fetch changes made in the web app, by MCP tools, or by teammates
bm cloud pull --name research

# ... edit files locally ...

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

What happens on push:

1. New and changed local files transfer to cloud
2. If a file differs on both sides, the command aborts and lists the conflicts
3. The cloud instance detects the new files and reindexes them automatically

6. Verify Setup

bm cloud status

You should see:

• OAuth: token valid
• Cloud connected

File Synchronization

Understanding the Sync Commands

Push and Pull (Additive, Git-Style)

push and pull model git push / git pull:

# Preview what would transfer
bm cloud pull --name research --dry-run

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

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

Both commands are additive — they never delete files on the destination. New and changed files transfer; if any file differs on both sides, the command aborts and lists the conflicts, like a rejected git push.

The transport depends on the workspace, but the commands and flags are identical. Personal-workspace transfers run through the tenant-scoped rclone remote configured by bm cloud setup. Team-workspace transfers (v0.23+) run over the cloud's WebDAV API, where each request is checked against your access to that project — members with read access can pull, members with edit access can push, and no bm cloud setup is needed.

Resolving conflicts: re-run with --on-conflict to choose what survives. The value names what is kept, so it reads the same in both directions:

# A teammate edited notes you also changed locally — pull reports a conflict:
bm cloud pull --name research
# pull aborted: 1 file(s) differ between local and cloud.

# Take the cloud version:
bm cloud pull --name research --on-conflict keep-cloud

# Or keep both copies to merge by hand:
bm cloud pull --name research --on-conflict keep-both

Deprecated mirror commands

bm cloud sync (one-way mirror: make cloud identical to local, deleting cloud files missing locally), bm cloud bisync (bidirectional mirror), and bm cloud bisync-reset are deprecated as of v0.24. They still run on Personal workspaces and print a deprecation notice each time; on Team workspaces they exit with the notice. Use pull and push instead:

push never deletes cloud files. To remove cloud files that match a newly added .bmignore pattern, use bm cloud prune (below). To delete individual notes, delete them in the web app or with the bm_delete MCP tool.

Prune newly ignored cloud files

Use prune when you want only the .bmignore cleanup without a full mirror sync:

# Show the exact remote paths that match this machine's ignore file
bm cloud prune --name research --dry-run

# Show the paths again, then ask for confirmation before deletion
bm cloud prune --name research

# Skip the confirmation prompt after reviewing a dry run
bm cloud prune --name research --yes

prune can run without a configured local sync directory because it inspects remote paths against ~/.basic-memory/.bmignore. It is Personal-workspace-only and permanently deletes only the exact paths shown in its preview.

Preview Changes (Dry Run)

bm cloud pull --name research --dry-run
bm cloud push --name research --dry-run

Shows what would transfer without actually syncing.

Verify Integrity

bm cloud check --name research

Compares file checksums against the Personal-workspace mirror remote without making changes. This is a legacy command tied to the deprecated mirror workflow; bm cloud pull --dry-run and bm cloud push --dry-run are the preferred way to preview differences on any workspace.

Multiple Projects

Syncing Multiple Projects

# Setup multiple projects
bm project add research --cloud --local-path ~/Documents/research
bm project add work --cloud --local-path ~/work-notes
bm project add personal --cloud --local-path ~/personal

# Daily workflow: pull, edit, push
bm cloud pull --name research
bm cloud pull --name work
bm cloud pull --name personal

# ... edit locally ...

bm cloud push --name research
bm cloud push --name work
bm cloud push --name personal

Mixed Usage

# Projects with sync
bm project add research --cloud --local-path ~/Documents/research
bm project add work --cloud --local-path ~/work

# Cloud-only projects
bm project add archive --cloud
bm project add temp-notes --cloud

# Sync only the configured ones
bm cloud pull --name research
bm cloud pull --name work
# archive and temp-notes stay cloud-only

Filter Configuration

Understanding .bmignore

Basic Memory uses .bmignore for global ignore patterns (similar to .gitignore).

Location: ~/.basic-memory/.bmignore

Default patterns:

# Hidden files and version control
.*
.git

# Python
__pycache__
*.pyc
.venv

# Node.js
node_modules

# Basic Memory internals
*.db
*.db-shm
*.db-wal
config.json

# Editors and OS files
.obsidian
.DS_Store
*.tmp

Patterns follow .gitignore escaping: \#*# matches files that start with #, and a backslash keeps leading or trailing whitespace. Emacs autosave files (#note.md#) are never indexed.

Troubleshooting

Authentication Issues

Problem: Authentication failed or Invalid token

Solution:

bm cloud logout
bm cloud login

Push or Pull Reports Conflicts

Problem: "pull aborted: N file(s) differ between local and cloud"

Solution: This is the conflict guard working as intended. Preview the differences, then choose what survives:

bm cloud pull --name research --dry-run
bm cloud pull --name research --on-conflict keep-both

Project Not Configured for Sync

Problem: "Error: Project 'research' has no local sync path configured"

Solution:

bm cloud sync-setup research ~/Documents/research
bm cloud pull --name research

Workspace Is Not Set Up for Sync

Problem: "Workspace '...' is not set up for sync."

Solution: A Personal workspace's rclone remote hasn't been provisioned yet:

bm cloud setup

Team workspaces never need bm cloud setup — their push/pull run over the permissioned WebDAV API, so this error only appears on the Personal path.

Sign out

bm cloud logout

Logout removes your stored OAuth tokens (a saved API key survives and keeps routing cloud projects). It doesn't change project routing — to route a project locally again, use bm project set-local <name> --local-path <path>.

Security

• Authentication: OAuth 2.1 with PKCE flow
• Tokens: Stored securely in ~/.basic-memory/basic-memory-cloud.json
• Transport: All data encrypted in transit (HTTPS)
• Credentials: Personal transfers use scoped S3 credentials (read-write to your tenant only); Team transfers use your OAuth session over WebDAV with per-project access checks
• Isolation: Your data isolated from other tenants
• Ignore patterns: Sensitive files excluded via .bmignore

Command Reference

Cloud Mode Management

bm cloud login              # Authenticate and enable cloud mode
bm cloud logout             # Disable cloud mode
bm cloud status             # Check cloud mode and instance health

Setup

bm cloud setup              # Install rclone and configure credentials

Project Setup

bm project add <name> --cloud                     # Create cloud project (no sync)
bm project add <name> --cloud --local-path <path> # Create with local sync
bm cloud sync-setup <name> <path>                 # Add sync to an existing cloud project

Full project and auth commands (list, remove, login, status): CLI Reference.

File Synchronization

# Standard workflow (Personal + Team)
bm cloud pull --name <project>            # Fetch cloud changes (additive)
bm cloud push --name <project>            # Upload local changes (additive)
bm cloud pull --name <project> --dry-run
bm cloud push --name <project> --dry-run
bm cloud pull --name <project> --on-conflict keep-both

# Targeted deletion of cloud files matching ~/.basic-memory/.bmignore
bm cloud prune --name <project> --dry-run
bm cloud prune --name <project>

# Legacy integrity check (Personal only; prefer pull/push --dry-run)
bm cloud check --name <project>

# Deprecated (v0.24) — use pull/push instead
# bm cloud sync --name <project>
# bm cloud bisync --name <project>
# bm cloud bisync-reset <project>

# List remote files
bm project ls --name <project>

Summary

Basic Memory Cloud uses project-scoped sync:

1. Sign in - bm cloud login
2. Install rclone - bm cloud setup (Personal workspaces; Team push/pull needs no setup)
3. Add projects with sync - bm project add research --cloud --local-path ~/Documents/research
4. Preview the first pull - bm cloud pull --name research --dry-run
5. Pull the project down - bm cloud pull --name research
6. Daily workflow - pull, edit locally, then bm cloud push --name research

Key benefits:

• Each project independently syncs (or doesn't)
• Projects can live anywhere on disk
• Explicit sync operations (no magic)
• Safe by design (additive transfers, conflict guard)
• Full offline access (work locally, sync when ready)

Next Steps