Basic Memory Cloud

Basic Memory Cloud provides hosted MCP access with no local installation required. Bring your knowledge to the cloud - all your existing notes, connections, and context accessible from anywhere.

Setup with Claude

Basic Memory Cloud uses Remote MCP to connect to AI assistants. The connection URL is:

https://cloud.basicmemory.com/mcp

Setup with ChatGPT

For detailed ChatGPT setup instructions, see the ChatGPT Integration guide.

Web Editor

Edit and manage your cloud notes directly in your browser at app.basicmemory.com/notes.

Key features:

• View and Edit Notes - Browse and edit with a rich markdown editor
• Import Conversations - Import ChatGPT, Claude, or JSON data
• Manage Projects - Create, switch between, and manage projects
• Upload Files - Bulk upload markdown files and directories
• Download Archives - Export projects as zip files for backup

Command Line Tools

The CLI tools are optional but enable advanced features like project management, file upload, and bidirectional sync.

Requirements: Basic Memory CLI v0.16.0 or later. See Getting Started for installation.

Quick Start

# 1. Authenticate
bm cloud login

# 2. Check Status
bm cloud status

# 3. List Projects
bm project list

Authentication

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

Login to Cloud

bm cloud login

What happens:

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

A confirmation code will be displayed in both the browser and terminal. Confirm the codes match and press the Confirm button on the web page.

After login:

✅ 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

If no subscription:

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

Check Status

bm cloud status

Shows: authentication status, subscription status, last sync time, cloud project count, tenant information, and sync directory configuration.

Logout

bm cloud logout

Removes ~/.basic-memory/basic-memory-cloud.json and clears cached credentials.

Project Management

# Create a new cloud project
bm project add my-new-project

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

# List all cloud projects
bm project list

Example output:

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

Upload Files to Cloud

Upload local files or directories to cloud projects using bm cloud upload:

# 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

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

# 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)

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

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

Cloud Snapshots

Basic Memory Cloud includes point-in-time snapshots for backup and recovery. Create manual snapshots before major changes, or rely on automatic daily backups.

Key features:

• Create unlimited manual snapshots
• Automatic daily snapshots
• Browse historical versions
• Restore individual files or folders

# Create a snapshot before major changes
bm cloud snapshot create "Before reorganization"

# List all snapshots
bm cloud snapshot list

# Browse and restore files
bm cloud snapshot browse snap_abc123

Migrating to Cloud

Already using Basic Memory locally? You have two options:

Option 1: One-Time Upload (Fastest)

Upload your existing local project to cloud:

# Login first
bm cloud login

# Upload entire project
bm cloud upload ~/basic-memory --project main --create-project

Use when:

• You want to move to cloud-only
• One-time migration is sufficient
• Don't need ongoing local-cloud sync

Option 2: Bidirectional Sync (Hybrid Workflow)

Set up sync to work both locally and in cloud:

# Login and setup sync
bm cloud login
bm cloud setup

# Add existing project with sync enabled
bm project add main --local-path ~/basic-memory

# Initial sync (resync creates baseline)
bm project bisync --name main --resync --dry-run  # preview first
bm project bisync --name main --resync             # establish baseline

# Ongoing sync (run after local or cloud changes)
bm project bisync --name main

Use when:

• You want to edit both locally (Obsidian, VS Code) and in cloud
• Need offline access
• Want automatic bidirectional sync

Next Steps