Basic Memory Cloud

Cloud authentication, setup, and mount commands for Basic Memory Cloud

Basic Memory Cloud provides hosted cloud sync for multi-device workflows. Currently in invite-only beta. Sign up for an invite at the Basic Memory website.

Cloud features require an active Basic Memory subscription. Subscribe here.

Basic Memory Cloud requires version v0.15.2 or later of the Basic Memory CLI tools. See the install and upgrade instructions on the Getting Started page.

You can use the shorter command alias bm instead of basic-memory for all CLI commands (e.g., bm cloud login instead of basic-memory cloud login).

Quick Start

Authenticate

bm cloud login

Opens browser for OAuth 2.1 authentication, then displays an authorization code.

Check Status

bm cloud status

View your authentication status, subscription, and cloud project information.

List Projects

bm project list

Shows all your cloud projects with their paths and default status.

Authentication

Basic Memory uses JWT-based cloud authentication with OAuth 2.1 and automatic subscription validation.

Authenticate with Basic Memory Cloud:

bm cloud login

What happens:

Opens browser to OAuth authorization page
Handles PKCE challenge/response automatically
Validates active subscription status
Stores JWT token in ~/.basic-memory/basic-memory-cloud.json
Token automatically refreshed when needed

Browser Confirmation Code

Terminal

In the terminal, the same code will be displayed. Confirm the codes match and press the Confirm button on the web page.

 bm cloud login
Initiating authentication...

🔐 Authentication Required

To authenticate, please visit:
https://eloquent-lotus-05.authkit.app/device

And enter this code: XXX-XXX

Or for one-click access, visit:
https://eloquent-lotus-05.authkit.app/device?user_code=XXX-XXX

Opening browser automatically...

Waiting for you to complete authentication in your browser...

After you login and confirm via the web browser, your auth token will be saved locally.

✅ Successfully authenticated with Basic Memory Cloud!
Verifying subscription access...
✓ Cloud mode enabled
All CLI commands now work against https://cloud.basicmemory.com
✓ Tokens saved to ~/.basic-memory/basic-memory-cloud.json

Important: After bm cloud login, CLI tools access cloud endpoints instead of local MCP. Commands like bm project list show cloud projects, and bm tool [name] invokes tools in the cloud. Use the same CLI commands for both local and cloud projects.

If no subscription:

Active subscription required
Subscribe at: https://basicmemory.com/subscribe

Check Authentication Status

View current authentication and cloud status:

bm cloud status

Output shows:

Authentication status (logged in/out)
Subscription status (active/expired)
Last sync time
Cloud project count
Tenant information
Sync directory configuration

Logout

Clear authentication session:

bm cloud logout

Removes ~/.basic-memory/basic-memory-cloud.json and clears cached credentials. All cloud commands will require re-authentication.

Manage Cloud Projects from the command line

Creating Projects

Create a new project

# In cloud mode - creates cloud project
bm project add my-new-project

# Create and set as default
bm project add my-new-project --default

List Projects

bm project list
           Basic Memory Projects
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Name ┃ Path                   ┃ Default ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ main │ /app/data/basic-memory │ ✓       │
└──────┴────────────────────────┴─────────┘

Other project management commands are available. See bm project --help.

Upload files to Cloud Projects

You can directly upload local files or directories to cloud projects using bm cloud upload. This is useful for:

Migrating existing local projects to the cloud
Quickly uploading specific files or directories
One-time bulk uploads without setting up sync

Basic Usage:

# Upload a directory to existing project
bm cloud upload ~/my-notes --project research

# Upload a single file
bm cloud upload important-doc.md --project research

Create Project On-the-Fly:

If the target project doesn’t exist yet, use --create-project:

# Upload and create project in one step
bm cloud upload ~/local-project --project new-research --create-project

Skip Automatic Sync:

By default, the command syncs the project after upload to index the files. To skip this:

# Upload without triggering sync
bm cloud upload ~/bulk-data --project archives --no-sync

File Filtering:

The upload command respects .bmignore and .gitignore patterns, automatically excluding:

Hidden files (.git, .DS_Store)
Build artifacts (node_modules, __pycache__)
Database files (*.db, *.db-wal)
Environment files (.env)

To customize what gets uploaded, edit ~/.basic-memory/.bmignore.

Complete Example:

# 1. Login to cloud
bm cloud login

# 2. Upload local project (creates project if needed)
bm cloud upload ~/specs --project specs --create-project

# 3. Verify upload
bm project list

Example Output:

bm cloud upload --project specs --create-project specs
Creating cloud project 'specs'...
✓ Created project 'specs'
Uploading /Users/phernandez/dev/basicmachines/basic-memory/specs to project 'specs'...
Found 21 file(s) to upload
Uploading SPEC-8 TigrisFS Integration.md (1/21)
Uploading SPEC-14 Cloud Git Versioning & GitHub Backup.md (2/21)
Uploading SPEC-9 Signed Header Tenant Information.md (3/21)
Uploading SPEC-12 OpenTelemetry Observability.md (4/21)
Uploading SPEC-15 Configuration Persistence via Tigris for Cloud Tenants.md (5/21)
Uploading SPEC-3 Agent Definitions.md (6/21)
Uploading SPEC-9 Multi-Project Bidirectional Sync Architecture.md (7/21)
Uploading SPEC-5 CLI Cloud Upload via WebDAV.md (8/21)
Uploading SPEC-13 CLI Authentication with Subscription Validation.md (9/21)
Uploading SPEC-17 Semantic Search with ChromaDB.md (10/21)
Uploading SPEC-14- Cloud Git Versioning & GitHub Backup.md (11/21)
Uploading SPEC-9-1 Follow-Ups- Conflict, Sync, and Observability.md (12/21)
Uploading SPEC-10 Unified Deployment Workflow and Event Tracking.md (13/21)
Uploading SPEC-4 Notes Web UI Component Architecture.md (14/21)
Uploading SPEC-7 POC to spike Tigris Turso for local access to cloud data.md (15/21)
Uploading SPEC-2 Slash Commands Reference.md (16/21)
Uploading SPEC-18 AI Memory Management Tool.md (17/21)
Uploading SPEC-1 Specification-Driven Development Process.md (18/21)
Uploading SPEC-11 Basic Memory API Performance Optimization.md (19/21)
Uploading SPEC-6 Explicit Project Parameter Architecture.md (20/21)
Uploading SPEC-16 MCP Cloud Service Consolidation.md (21/21)
✓ Upload complete: 21 file(s) (363.9 KB)
✅ Successfully uploaded to 'specs'
Syncing project 'specs'...
✓ Filesystem sync initiated for project 'specs'

After sync completes, the notes are available in the Notes Web UI and for AI conversations.

Notes Web UI

CLI Reference - Complete CLI command reference
Getting Started - Initial setup and configuration
MCP Tools Reference - Multi-project workflows
What’s New - v0.15.0 release notes

Basic Memory Cloud

Quick Start

Authenticate

Check Status

List Projects

Authentication

Login to Cloud

Check Authentication Status

Logout

Manage Cloud Projects from the command line

Creating Projects

List Projects

Upload files to Cloud Projects

Related Documentation