Cloud Sync Guide

Guide to syncing your local Basic Memory projects with Basic Memory Cloud

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
Bidirectional sync - Keep local and cloud in sync with rclone bisync
Offline access - Work locally, sync when ready

Prerequisites

Before using Basic Memory Cloud sync, you need:

Active Subscription: An active Basic Memory Cloud subscription is required to access cloud features
Subscribe: Visit https://basicmemory.com/subscribe to sign up
Basic Memory CLI: Cloud sync requires the CLI. See Local Installation for installation steps.

If you attempt to log in without an active subscription, you’ll receive a “Subscription Required” error with a link to subscribe.

Why Use Sync?

When to use sync:

Sync is designed for hybrid workflows where you want to edit files locally (in tools like Obsidian or VS Code) while keeping cloud in sync.

Use sync when:

You want to edit notes locally in your preferred editor
You need bidirectional sync (changes flow both ways automatically)
You’re working with large knowledge bases
You want offline access with periodic syncing

Alternatives to sync:

If you don’t need local editing, you can work directly in the cloud:

Web Editor: Upload and edit files in the Basic Memory Cloud web interface
MCP Tools Only: Use AI assistants (Claude, ChatGPT) to manage notes entirely in cloud via MCP tools

Sync is optional - choose the workflow that fits your needs.

Architecture: Project-Scoped Sync

How It Works

Projects can exist in three states:

Cloud-only - Project exists on cloud, no local copy
Cloud + Local (synced) - Project has a local working directory that syncs
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 project bisync --name research
bm project 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, not forced into sync directory

Quick Start

1. Enable Cloud Mode

Authenticate and enable cloud mode:

bm cloud login

What this does:

Opens browser to Basic Memory Cloud authentication page
Stores authentication token in ~/.basic-memory/auth/token
Enables cloud mode - all CLI commands now work against cloud
Validates your subscription status

Result: All bm project, bm tools commands now work with cloud.

2. Set Up Sync

Install rclone and configure credentials:

bm cloud setup

What this does:

Installs rclone automatically (if needed)
Fetches your tenant information from cloud
Generates scoped S3 credentials for sync
Configures single rclone remote: basic-memory-cloud

Result: You’re ready to sync projects. No sync directories created yet - those come with project setup.

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 project sync-setup research ~/Documents/research

What happens under the covers:

When you add a project with --local-path:

Project created on cloud at /app/data/research
Local path stored in config: cloud_projects.research.local_path = "~/Documents/research"
Local directory created if it doesn’t exist
Bisync state directory created at ~/.basic-memory/bisync-state/research/

Result: Project is ready to sync, but no files synced yet.

4. Sync Your Project

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

# Step 1: Preview the initial sync (recommended)
bm project bisync --name research --resync --dry-run

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

What happens under the covers:

Rclone reads from ~/Documents/research (local)
Connects to basic-memory-cloud:bucket-name/app/data/research (remote)
Creates bisync state files in ~/.basic-memory/bisync-state/research/
Syncs files bidirectionally with settings:
- conflict_resolve=newer (most recent wins)
- max_delete=25 (safety limit)
- Respects .bmignore patterns

Result: Local and cloud are in sync. Baseline established.

Why --resync? This is an rclone requirement for the first bisync run. It establishes the initial state that future syncs will compare against. After the first sync, never use --resync unless you need to force a new baseline.

See: rclone bisync documentation

5. Subsequent Syncs

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

bm project bisync --name research

What happens:

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

Result: Changes flow both ways - edit locally or in cloud, both stay in sync.

Reindexing after sync: Basic Memory automatically reindexes all synced changes to update the knowledge graph. For large changes (many files), this may take a few moments to complete.

6. Verify Setup

Check status:

bm cloud status

You should see:

Mode: Cloud (enabled)
Cloud instance is healthy
Instructions for project sync commands

Working with Projects

Understanding Project Commands

Key concept: When cloud mode is enabled, use regular bm project commands (not bm cloud project).

# In cloud mode:
bm project list              # Lists cloud projects
bm project add research      # Creates cloud project

# In local mode:
bm project list              # Lists local projects
bm project add research ~/Documents/research  # Creates local project

Creating Projects

Use case 1: Cloud-only project (no local sync)

bm project add temp-notes

What this does:

Creates project on cloud at /app/data/temp-notes
No local directory created
No sync configuration

Result: Project exists on cloud, accessible via MCP tools, but no local copy.

Use case 2: Cloud project with local sync

bm project add research --local-path ~/Documents/research

What this does:

Creates project on cloud at /app/data/research
Creates local directory ~/Documents/research
Stores sync config in ~/.basic-memory/config.json
Prepares for bisync (but doesn’t sync yet)

Result: Project ready to sync. Run bm project bisync --name research --resync to establish baseline.

Use case 3: Add sync to existing cloud project

# Project already exists on cloud
bm project sync-setup research ~/Documents/research

What this does:

Updates existing project’s sync configuration
Creates local directory
Prepares for bisync

Result: Existing cloud project now has local sync path. Run bisync to pull files down.

Listing Projects

View all projects:

bm project list

What you see:

All projects in cloud (when cloud mode enabled)
Default project marked
Project paths shown

File Synchronization

Understanding the Sync Commands

There are three sync-related commands:

bm project sync - One-way: local → cloud (make cloud match local)
bm project bisync - Two-way: local ↔ cloud (recommended)
bm project check - Verify files match (no changes)

One-Way Sync: Local → Cloud

Use case: You made changes locally and want to push to cloud (overwrite cloud).

bm project sync --name research

What happens:

Reads files from ~/Documents/research (local)
Uses rclone sync to make cloud identical to local
Respects .bmignore patterns
Shows progress bar

Result: Cloud now matches local exactly. Any cloud-only changes are overwritten.

When to use:

You know local is the source of truth
You want to force cloud to match local
You don’t care about cloud changes

Two-Way Sync: Local ↔ Cloud (Recommended)

Use case: You edit files both locally and in cloud UI, want both to stay in sync.

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

# Subsequent syncs
bm project bisync --name research

What happens:

Compares local and cloud states using bisync metadata
Syncs changes in both directions
Auto-resolves conflicts (newer file wins)
Detects excessive deletes and fails safely (max 25 files)

Conflict resolution example:

# Edit locally
echo "Local change" > ~/Documents/research/notes.md

# Edit same file in cloud UI
# Cloud now has: "Cloud change"

# Run bisync
bm project bisync --name research

# Result: Newer file wins (based on modification time)
# If cloud was more recent, cloud version kept
# If local was more recent, local version kept

When to use:

Default workflow for most users
You edit in multiple places
You want automatic conflict resolution

Verify Sync Integrity

Use case: Check if local and cloud match without making changes.

bm project check --name research

What happens:

Compares file checksums between local and cloud
Reports differences
No files transferred

Result: Shows which files differ. Run bisync to sync them.

# One-way check (faster)
bm project check --name research --one-way

Preview Changes (Dry Run)

Use case: See what would change without actually syncing.

bm project bisync --name research --dry-run

What happens:

Runs bisync logic
Shows what would be transferred/deleted
No actual changes made

Result: Safe preview of sync operations.

Advanced: List Remote Files

Use case: See what files exist on cloud without syncing.

# List all files in project
bm project ls --name research

# List files in subdirectory
bm project ls --name research --path subfolder

What happens:

Connects to cloud via rclone
Lists files in remote project path
No files transferred

Result: See cloud file listing.

Multiple Projects

Syncing Multiple Projects

Use case: You have several projects with local sync, want to sync all at once.

# 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 project bisync --name research --resync
bm project bisync --name work --resync
bm project bisync --name personal --resync

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

Mixed Usage

Use case: Some projects sync, some stay cloud-only.

# 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 project bisync --name research
bm project bisync --name work

# Archive and temp-notes stay cloud-only

Result: Fine-grained control over what syncs.

Disable Cloud Mode

Return to local mode:

bm cloud logout

What this does:

Disables cloud mode in config
All commands now work locally
Auth token remains (can re-enable with login)

Result: All bm commands work with local projects again.

Filter Configuration

Understanding .bmignore

The problem: You don’t want to sync everything (e.g., .git, node_modules, database files).

The solution: .bmignore file with gitignore-style patterns.

Basic Memory already respects .gitignore files in your projects. See Controlling What Gets Indexed for details. Use .bmignore when you need a global ignore list that applies across all your projects.

Location: ~/.basic-memory/.bmignore

Default patterns:

# Version control
.git/**

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

# Node.js
node_modules/**

# Basic Memory internals
memory.db/**
memory.db-shm/**
memory.db-wal/**
config.json/**
watch-status.json/**
.bmignore.rclone/**

# OS files
.DS_Store/**
Thumbs.db/**

# Environment files
.env/**
.env.local/**

How it works:

On first sync, .bmignore created with defaults
Patterns converted to rclone filter format (.bmignore.rclone)
Rclone uses filters during sync
Same patterns used by all projects

Customizing:

# Edit patterns
code ~/.basic-memory/.bmignore

# Add custom patterns
echo "*.tmp/**" >> ~/.basic-memory/.bmignore

# Next sync uses updated patterns
bm project bisync --name research

Troubleshooting

Authentication Issues

Subscription Issues

Bisync Initialization

Explanation: Bisync needs a baseline state before it can sync changes.

Solution:

bm project bisync --name research --resync

What this does:

Establishes initial sync state
Creates baseline in ~/.basic-memory/bisync-state/research/
Syncs all files bidirectionally

Result: Future syncs work without --resync.

Empty Directory Issues

Explanation: Rclone bisync doesn’t work well with completely empty directories. It needs at least one file to establish a baseline.

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

# Create a placeholder file
echo "# Research Notes" > ~/Documents/research/README.md

# Now run bisync
bm project bisync --name research --resync

Why this happens: Bisync creates listing files that track the state of each side. When both directories are completely empty, these listing files are considered invalid by rclone.

Best practice: Always have at least one file (like a README.md) in your project directory before setting up sync.

Bisync State Corruption

Explanation: Sometimes bisync state can become inconsistent (e.g., after mixing dry-run and actual runs, or after manual file operations).

Solution: Clear bisync state and re-establish baseline:

# Clear bisync state
bm project bisync-reset research

# Re-establish baseline
bm project bisync --name research --resync

What this does:

Removes all bisync metadata from ~/.basic-memory/bisync-state/research/
Forces fresh baseline on next --resync
Safe operation (doesn’t touch your files)

Note: This command also runs automatically when you remove a project to clean up state directories.

Too Many Deletes

Explanation: Bisync detected you’re about to delete more than 25 files. This is a safety check to prevent accidents.

Solution 1: Review what you’re deleting, then force resync:

# Check what would be deleted
bm project bisync --name research --dry-run

# If correct, establish new baseline
bm project bisync --name research --resync

Solution 2: Use one-way sync if you know local is correct:

bm project sync --name research

Project Not Configured for Sync

Connection Issues

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 automatically 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

When cloud mode is enabled:

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 project sync-setup <name> <path>       # Add sync to existing project
bm project rm <name>                      # Delete project

File Synchronization

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

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

# Integrity check
bm project check --name <project>
bm project check --name <project> --one-way

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

Summary

Basic Memory Cloud uses project-scoped sync:

Enable cloud mode - bm cloud login
Install rclone - bm cloud setup
Add projects with sync - bm project add research --local-path ~/Documents/research
Preview first sync - bm project bisync --name research --resync --dry-run
Establish baseline - bm project bisync --name research --resync
Daily workflow - bm project 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

Cloud Setup Guide

Learn about Basic Memory Cloud features and setup

CLI Reference

Complete CLI command reference

Obsidian Integration

Use cloud sync with Obsidian

VS Code Integration

Use cloud sync with VS Code