Skip to content

01.cloud-guide.md

Latest commit

 

History

History
307 lines (219 loc) · 10.6 KB

01.cloud-guide.md

File metadata and controls

307 lines (219 loc) · 10.6 KB
Raw
title Basic Memory Cloud
description Cloud remote MCP setup, web editor, CLI tools, and snapshots for 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.

::note{icon="i-lucide-cloud"} Why use Basic Memory Cloud?

  • Access from any device
  • Easily import your data
  • 2-minute setup
  • Local sync optional
  • OAuth authentication ::

Setup with Claude

Open the Claude Directory, search for Basic Memory Cloud, and select Install. Complete the Basic Memory authorization flow, then ask Claude to list your Basic Memory projects.

The published remote connector works across Claude web, desktop, mobile, Cowork, and Claude Code.

::tip For the directory walkthrough and manual custom-connector fallback, see the Claude Desktop Integration guide. ::

Setup with ChatGPT

Open Basic Memory Cloud in ChatGPT, select Connect, and complete the Basic Memory authorization flow. Select Try in chat to start a conversation with the app enabled.

For the full Plugin-directory walkthrough, managed-workspace notes, and manual custom MCP fallback, see the ChatGPT Integration guide.

::note For clients or advanced setups that require a server URL, the Basic Memory Cloud remote MCP endpoint remains:

https://cloud.basicmemory.com/mcp

::

Web App

Browse, edit, and collaborate on your cloud notes directly in your browser at app.basicmemory.com.

Key features:

  • Edit notes - A rich editor, plain Markdown source mode, and a read-only preview with clickable wiki links
  • Collaborate with AI - Connect an agent and watch it write alongside you in the same note
  • Import data - Bring in project ZIPs, Claude or ChatGPT exports, or memory-json from Settings → Import
  • Manage projects - Create, switch between, and manage projects
  • Upload folders as ZIP - Zip a folder and import it into any writable project — no CLI needed
  • Download archives - Export projects as zip files for backup

::tip For the complete web app guide including editing modes, drafts, AI collaboration, importing, and project management, see the Web App Guide. ::

Command Line Tools

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

Requirements: an up-to-date Basic Memory CLI (bm update). See Local Installation for installation.

::note{icon="i-lucide-info"} Why use the CLI?

  • Manage multiple projects from terminal
  • Upload entire folders to cloud
  • Sync local files with push and pull
  • Automate workflows with scripts ::

Quick Start

# Authenticate — OAuth in the browser, validates your subscription
bm cloud login

# Check the connection: cloud host, API key status, OAuth token status
bm cloud status

# List projects across your workspaces
bm project list

# Create a cloud project (--cloud is required; add --default to make it the default)
bm project add my-new-project --cloud

bm cloud login authenticates the CLI — it does not change project routing or start syncing files. Projects stay local unless you route them through cloud with bm project set-cloud <name>; revert with bm project set-local <name> --local-path <path>. See Local & Cloud Routing for the full routing model.

If you log in without an active subscription, you'll see "Active subscription required" — subscribe at basicmemory.com/subscribe.

bm cloud logout removes your OAuth tokens. A saved API key is not removed — it keeps working for cloud-routed projects, so delete it separately if you need to revoke access.

::tip The full command walkthrough — sign-in options, API keys, workspaces, routing, sync, and snapshots — lives on the Cloud CLI page. ::

Remove a Cloud Project and Its Data

Cloud project removal keeps note files by default. Use --delete-notes when you also want to purge the project's active cloud storage:

::warning If the project has a configured local sync directory, --cloud --delete-notes also removes that local directory. Back up any local files you need before running the destructive command. Deletion is irreversible for active project storage; existing point-in-time snapshots may still contain historical copies until those snapshots are deleted or expire. ::

# Stop tracking the project, but retain its cloud files
bm project remove research --cloud

# Remove the project and purge every object under its cloud storage prefix
bm project remove research --cloud --delete-notes

Keep the explicit --cloud flag on the destructive --delete-notes command so the CLI also removes any configured local sync directory. Omitting --cloud from a cloud-routed project still purges hosted storage, but leaves the local sync copy intact. Hosted deletion is asynchronous: the project is hidden from cloud workspace operations when deletion is accepted, then a background job removes its database rows. A local routing or sync configuration entry can still appear as a config-only row in the combined bm project list; that does not mean the hosted project remains. With --delete-notes, the background job also removes indexed and unindexed objects under the project's exact storage prefix.

The MCP delete_project tool provides the same hosted-storage purge with delete_notes=true. It does not remove a configured local sync directory; use the explicit CLI command above when you need to delete both copies. The MCP response reports the pending deletion status and background job ID.

Upload Files to Cloud

::note{icon="i-lucide-upload"} No CLI needed for one-off uploads. In the web app, Settings → Import → Project ZIP imports a zipped folder into any writable project — pick the team and target project, optionally a destination folder, and upload (ZIPs up to 100MB; markdown files are indexed automatically). The Activity view tracks the job after it starts. ::

For scripted or repeated uploads, use bm cloud upload from the CLI:

# 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 web app and for AI conversations.

::tip To edit both locally and in cloud, sync with push/pull — see the Cloud Sync Guide. ::

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 snapshot contents
bm cloud snapshot browse snap_abc123 --prefix notes/

# Restore a file from a snapshot
bm cloud restore notes/example.md --snapshot snap_abc123

::tip For complete snapshot management including restore procedures and best practices, see the Cloud Snapshots Guide. ::

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

Prefer the browser? Zip your ~/basic-memory folder and import it via Settings → Import → Project ZIP — no CLI required.

Use when:

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

Option 2: Local File Sync (Hybrid Workflow)

Set up sync to work both locally and in cloud:

# Login and setup sync
bm cloud login
bm cloud setup

# Add your existing project as a cloud project with a local sync path
bm project add main --cloud --local-path ~/basic-memory

# First push (preview, then upload your local files)
bm cloud push --name main --dry-run
bm cloud push --name main

# Ongoing: pull cloud changes down, push local changes up
bm cloud pull --name main
bm cloud push --name main

Use when:

  • You want to edit both locally (Obsidian, VS Code) and in cloud
  • Need offline access
  • Want changes to flow both ways

::note{icon="i-lucide-info"} Both methods preserve all your notes, relations, and tags. Choose based on whether you want cloud-only or hybrid local+cloud workflow. See the Cloud Sync Guide for detailed sync configuration. ::

Moving between cloud workspaces

If your notes already live in one cloud workspace (say, your personal one) and you want to bring them into a team workspace — or vice versa — see Copy Content Between Workspaces for the project ZIP, single-note, MCP, and local-sync recipes.

Next Steps

:::card-group ::card

title: Local & Cloud Routing icon: i-lucide-route to: /cloud/routing

Run some projects locally and others in the cloud. ::

::card

title: Cloud Sync Guide icon: i-lucide-refresh-cw to: /cloud/cloud-sync

Sync local files with push and pull. ::

::card

title: CLI Reference icon: i-lucide-terminal to: /reference/cli-reference

Complete CLI command reference. ::

::card

title: MCP Tools Reference icon: i-lucide-wrench to: /reference/mcp-tools-reference

All available MCP tools for AI assistants. :: :::