Skip to main content

​
Introduction

Basic Memory Cloud extends the local-first experience with cross-device synchronization, cloud storage, and multi-platform support. Cloud features are optional and require an active subscription.
The local-first open-source workflow continues as always. Cloud is an optional enhancement for users who need multi-device access.

​
Key Benefits

​
Cross-Device Access

  • Sync your knowledge graph across desktop, web, and mobile
  • Work seamlessly from any device
  • Real-time synchronization keeps everything in sync

​
Bidirectional Sync

  • Two-way sync between local files and cloud storage
  • Conflict resolution with integrity verification
  • Mount cloud storage for direct file access

​
Project Management

  • Create and manage projects in the cloud
  • Toggle individual projects between local and cloud modes
  • Per-project sync configuration

​
Secure Storage

  • JWT-based authentication with subscription validation
  • Encrypted cloud storage with Tigris Object Storage
  • Automatic snapshot management for data protection

​
Cloud Architecture

Basic Memory Cloud uses:
  • Authentication: OAuth 2.0 via WorkOS AuthKit with JWT tokens
  • Storage: Tigris Object Storage (S3-compatible)
  • Sync: rclone bisync for bidirectional synchronization
  • API: RESTful API with subscription-based access control

​
Getting Started

1

Sign Up

Create an account at basicmemory.com with a 7-day free trial.Use promo code BMFOSS for 20% off for 3 months (OSS contributors).
2

Authenticate

basic-memory cloud login
This opens your browser for OAuth authentication and stores tokens locally.
3

Setup Sync

basic-memory cloud setup
Installs rclone and configures cloud credentials for file synchronization.
4

Configure Projects

Add a project with cloud sync:
basic-memory project add research --cloud --local-path ~/Documents/research
Or configure sync for an existing project:
basic-memory cloud sync-setup research ~/Documents/research
5

Sync

Run your first bidirectional sync:
# Preview changes (recommended)
basic-memory cloud bisync --name research --resync --dry-run

# Perform the sync
basic-memory cloud bisync --name research --resync

​
Subscription Requirements

All cloud features require an active subscription. The CLI will prompt you to subscribe when attempting to use cloud features without a valid subscription.

​
What Requires a Subscription

  • Cloud authentication and API access
  • Bidirectional file synchronization
  • Cloud project management
  • Snapshot creation and restoration
  • Cloud workspace access

​
What Remains Free

  • Local-only Basic Memory usage
  • All MCP tools with local projects
  • Local file synchronization
  • Local database operations
  • Importing from Claude/ChatGPT

​
Cloud vs Local Mode

You can mix local and cloud projects in the same configuration:
FeatureLocal ModeCloud Mode
File StorageLocal filesystemLocal + Cloud (synced)
MCP AccessLocal API (stdio)Local API (stdio)
CLI RoutingLocal APICloud API (when set)
AuthenticationNone requiredAPI key or OAuth
SubscriptionNot requiredRequired
SyncOptional watch modeBidirectional bisync

​
Per-Project Routing

Individual projects can be routed through the cloud while others stay local: 
# Save API key (create via web app or CLI)
bm cloud api-key save bmc_abc123...

# Set specific project to cloud mode
bm project set-cloud research

# Revert to local mode
bm project set-local research

# List projects with routing info
bm project list

​
Command Overview

​
Authentication Commands

bm cloud login          # Authenticate with OAuth
bm cloud logout         # Remove OAuth tokens
bm cloud status         # Check auth and health

​
Sync Commands

bm cloud sync --name <project>           # One-way: local → cloud
bm cloud bisync --name <project>         # Two-way: local ↔ cloud
bm cloud check --name <project>          # Verify integrity
bm cloud sync-setup <name> <local-path>  # Configure sync

​
Project Management

bm project list                    # List all projects
bm project add <name> --cloud      # Add cloud project
bm project set-cloud <name>        # Enable cloud routing
bm project set-local <name>        # Disable cloud routing

​
Snapshot Management

bm cloud snapshot create "description"  # Create snapshot
bm cloud snapshot list                  # List snapshots
bm cloud snapshot show <id>             # Show snapshot details
bm cloud restore <path> --snapshot <id> # Restore files

​
Workspace Management

bm cloud workspace list               # List workspaces
bm cloud workspace set-default <name> # Set default workspace

​
Next Steps

Authentication Setup

Learn how to authenticate with Basic Memory Cloud

Bidirectional Sync

Set up two-way synchronization between local and cloud

Project Management

Manage cloud projects and routing configuration

CLI Reference

Complete CLI command reference

​
Telemetry

Basic Memory collects minimal, anonymous usage events for cloud conversion funnel analysis: What we collect:
  • Cloud promo impressions and login attempts
  • Promo opt-out events
What we do NOT collect:
  • File contents, note titles, or knowledge base data
  • Personally identifiable information (PII)
  • IP addresses or fingerprinting data
  • Per-command or per-tool-call tracking
Opt out by setting: 
export BASIC_MEMORY_NO_PROMOS=1
This disables both promo messages and all telemetry events.

Build docs developers (and LLMs) love

Get started for freeTalk to us