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 standard 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.

sync is a mirror operation: your local tree becomes authoritative and cloud files missing locally get deleted. That can be useful on a Personal workspace when local is the single source of truth, but it is blocked on Team workspaces, where it exits early with a clear error pointing you at push/pull.

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.

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

One-Way Sync

bm cloud sync --name research

Makes cloud identical to local — including deleting cloud files that are missing locally. Use when local is the source of truth. Personal workspaces only; on Team workspaces use bm cloud push (additive).

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 without making changes (Personal workspaces only).

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

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

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: Scoped S3 credentials (read-write to your tenant only)
• 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

# One-way mirror (local → cloud, Personal only)
bm cloud sync --name <project>
bm cloud sync --name <project> --dry-run

# Integrity check (Personal only)
bm cloud check --name <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
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