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:

• Toggle cloud mode - All regular bm commands work with cloud when enabled
• 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 shared Team workspaces
• Bidirectional sync - Keep local and cloud in sync with rclone bisync (Personal workspaces)
• Offline access - Work locally, sync when ready

Personal vs Team Workspaces

sync and bisync are mirror operations: one tree becomes authoritative and files missing on the other side get deleted. That is correct for a Personal workspace (one user, one source of truth) but unsafe on a shared Team bucket, where it could delete a teammate's files. On Team workspaces these commands exit early with a clear error and point you at push/pull.

push and pull are additive (they never delete on the destination), so they are safe on both Personal and Team workspaces.

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 Getting Started 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 locally (when cloud mode is disabled)

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 project add research --local-path ~/Documents/research
bm project add work --local-path ~/work-notes
bm project add temp  # No local sync

# Now you can sync individually (after initial --resync):
bm cloud bisync --name research
bm cloud bisync --name work
# temp stays cloud-only

What happens under the covers:

• Config stores cloud_projects dict mapping project names to local paths
• Each project gets its own bisync state in ~/.basic-memory/bisync-state/{project}/
• Rclone syncs using single remote: basic-memory-cloud
• Projects can live anywhere on your filesystem

Quick Start

1. Enable Cloud Mode

Authenticate and enable cloud mode:

bm cloud login

What this does:

1. Opens browser to Basic Memory Cloud authentication page
2. Stores authentication token
3. Enables cloud mode - all CLI commands now work against cloud
4. Validates your subscription status

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 single rclone remote: basic-memory-cloud

3. Add Projects with Sync

Create projects with optional local sync paths:

# Create cloud project without local sync
bm project add research

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

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

4. Sync Your Project

Establish the initial sync baseline. Always preview with --dry-run first:

# Step 1: Preview the initial sync
bm cloud bisync --name research --resync --dry-run

# Step 2: If all looks good, run the actual sync
bm cloud bisync --name research --resync

5. Subsequent Syncs

After the first sync, just run bisync without --resync:

bm cloud bisync --name research

What happens:

1. Rclone compares local and cloud states
2. Syncs changes in both directions
3. Auto-resolves conflicts (newer file wins)
4. Basic Memory reindexes all changed files
5. Updates last_sync timestamp in config

6. Verify Setup

bm cloud status

You should see:

• Mode: Cloud (enabled)
• Cloud instance is healthy

File Synchronization

Understanding the Sync Commands

If you collaborate on a shared Team workspace, use push/pull. If you are the only writer (a Personal workspace), the mirror commands sync/bisync give you a single source of truth.

Team Workspaces: 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

Two-Way Sync (Recommended)

# First time - establish baseline
bm cloud bisync --name research --resync

# Subsequent syncs
bm cloud bisync --name research

Conflict resolution: When the same file is edited both locally and in cloud, the newer file wins (based on modification time).

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 bisync --name research --dry-run

Shows what would change without actually syncing.

Verify Integrity

bm cloud check --name research

Compares file checksums without making changes.

Multiple Projects

Syncing Multiple Projects

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

# Establish baselines
bm cloud bisync --name research --resync
bm cloud bisync --name work --resync
bm cloud bisync --name personal --resync

# Daily workflow: sync everything
bm cloud bisync --name research
bm cloud bisync --name work
bm cloud bisync --name personal

Mixed Usage

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

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

# Sync only the configured ones
bm cloud bisync --name research
bm cloud bisync --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:

# Version control
.git/**

# Python
__pycache__/**
*.pyc
.venv/**

# Node.js
node_modules/**

# Basic Memory internals
memory.db/**
memory.db-shm/**
memory.db-wal/**

# OS files
.DS_Store/**

# Environment files
.env/**

Troubleshooting

Authentication Issues

Problem: Authentication failed or Invalid token

Solution:

bm cloud logout
bm cloud login

First Bisync Requires --resync

Problem: Bisync fails on first run

Solution:

bm cloud bisync --name research --resync

This establishes the initial baseline state.

Empty Directory Issues

Problem: "Empty prior Path1 listing. Cannot sync to an empty directory"

Solution: Add at least one file before running --resync:

echo "# Research Notes" > ~/Documents/research/README.md
bm cloud bisync --name research --resync

Bisync State Corruption

Problem: Bisync fails with errors about corrupted state

Solution:

bm cloud bisync-reset research
bm cloud bisync --name research --resync

Too Many Deletes

Problem: "max delete limit (25) exceeded"

Solution: Review what's being deleted, then force resync if correct:

bm cloud bisync --name research --dry-run
bm cloud bisync --name research --resync

Project Not Configured for Sync

Problem: "Project has no local_sync_path configured"

Solution:

bm cloud sync-setup research ~/Documents/research
bm cloud bisync --name research --resync

Disable Cloud Mode

Return to local mode:

bm cloud logout

All bm commands now work with local projects.

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 Management

bm project list                           # List cloud projects
bm project add <name>                     # Create cloud project (no sync)
bm project add <name> --local-path <path> # Create with local sync
bm cloud sync-setup <name> <path>       # Add sync to existing project
bm project rm <name>                      # Delete project

File Synchronization

# Two-way sync (recommended)
bm cloud bisync --name <project>          # After first --resync
bm cloud bisync --name <project> --resync # First time / force baseline
bm cloud bisync --name <project> --dry-run
bm cloud bisync --name <project> --verbose

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

# Integrity check
bm cloud check --name <project>

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

Summary

Basic Memory Cloud uses project-scoped sync:

1. Enable cloud mode - bm cloud login
2. Install rclone - bm cloud setup
3. Add projects with sync - bm project add research --local-path ~/Documents/research
4. Preview first sync - bm cloud bisync --name research --resync --dry-run
5. Establish baseline - bm cloud bisync --name research --resync
6. Daily workflow - bm cloud bisync --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 (max delete limits, conflict resolution)
• Full offline access (work locally, sync when ready)

Next Steps