Skip to main content
Glama

basic-memory

cloud-cli.md15.8 kB
# Basic Memory Cloud CLI Guide The Basic Memory Cloud CLI provides seamless integration between local and cloud knowledge bases using a **cloud mode toggle**. When cloud mode is enabled, all your regular `bm` commands work transparently with the cloud instead of locally. ## Overview The cloud CLI enables you to: - **Toggle cloud mode** with `bm cloud login` / `bm cloud logout` - **Use regular commands in cloud mode**: `bm project`, `bm sync`, `bm tool` all work with cloud - **Bidirectional sync** with rclone bisync (recommended for most users) - **Direct file access** via rclone mount (alternative workflow) - **Integrity verification** with `bm cloud check` - **Automatic project creation** from local directories ## Prerequisites Before using Basic Memory Cloud, you need: - **Active Subscription**: An active Basic Memory Cloud subscription is required to access cloud features - **Subscribe**: Visit [https://basicmemory.com/subscribe](https://basicmemory.com/subscribe) to sign up If you attempt to log in without an active subscription, you'll receive a "Subscription Required" error with a link to subscribe. ## The Cloud Mode Paradigm Basic Memory Cloud follows the **Dropbox/iCloud model** - a single cloud space containing all your projects, not per-project connections. **How it works:** - One login per machine: `bm cloud login` - One sync directory: `~/basic-memory-cloud-sync/` (all projects) - Projects are folders within your cloud space - All regular commands work in cloud mode **Why this model:** - ✅ Single set of credentials (not N per project) - ✅ One rclone process (not N processes) - ✅ Familiar pattern (like Dropbox) - ✅ Simple operations (setup once, sync anytime) - ✅ Natural scaling (add projects = add folders) ## Quick Start ### 1. Enable Cloud Mode Authenticate and enable cloud mode for all commands: ```bash bm cloud login ``` This command will: 1. Open your browser to the Basic Memory Cloud authentication page 2. Prompt you to authorize the CLI application 3. Store your authentication token locally 4. **Enable cloud mode** - all CLI commands now work against cloud ### 2. Set Up Sync Set up bidirectional file synchronization: ```bash bm cloud setup ``` This will: 1. Install rclone automatically (if needed) 2. Configure sync credentials 3. Create `~/basic-memory-cloud-sync/` directory 4. Establish initial sync baseline **Alternative:** Use `bm cloud setup --mount` to set up mount instead of sync. ### 3. Verify Setup Check that everything is working: ```bash bm cloud status ``` You should see: - `Mode: Cloud (enabled)` - `Cloud instance is healthy` - Bisync status showing `✓ Initialized` ### 4. Start Using Cloud Now all your regular commands work with the cloud: ```bash # List cloud projects bm project list # Create cloud project bm project add "my-research" # Use MCP tools on cloud bm tool write-note --title "Hello" --folder "my-research" --content "Test" # Sync with cloud bm sync # Watch mode for continuous sync bm sync --watch ``` ### 5. Disable Cloud Mode Return to local mode: ```bash bm cloud logout ``` All commands now work locally again. ## Working with Cloud Projects **Important:** When cloud mode is enabled, use regular `bm project` commands (not `bm cloud project`). ### Listing Projects View all projects (cloud projects when cloud mode is enabled): ```bash # In cloud mode - lists cloud projects bm project list # In local mode - lists local projects bm project list ``` ### Creating Projects Create a new project (creates on cloud when cloud mode is enabled): ```bash # In cloud mode - creates cloud project bm project add my-new-project # Create and set as default bm project add my-new-project --default ``` ### Automatic Project Creation **New in SPEC-9:** Projects are automatically created when you create local directories! ```bash # Create a local directory in your sync folder mkdir ~/basic-memory-cloud-sync/new-project echo "# Notes" > ~/basic-memory-cloud-sync/new-project/readme.md # Sync - automatically creates cloud project bm sync # Verify - project now exists on cloud bm project list ``` This Dropbox-like workflow means you don't need to manually coordinate projects between local and cloud. ## File Synchronization ### The `bm sync` Command (Cloud Mode Aware) The `bm sync` command automatically adapts based on cloud mode: **In local mode:** ```bash bm sync # Indexes local files into database ``` **In cloud mode:** ```bash bm sync # Runs bisync + indexes files bm sync --watch # Continuous sync every 60 seconds bm sync --interval 30 # Custom interval ``` The same command works everywhere - no need to remember different commands for local vs cloud! ## Bidirectional Sync (bisync) - Recommended Bidirectional sync is the **recommended approach** for most users. It provides: - ✅ Offline access to all files - ✅ Automatic bidirectional synchronization - ✅ Conflict detection and resolution - ✅ Works with any editor or tool - ✅ Background watch mode ### Setup Set up bisync (runs automatically if you used `bm cloud setup`): ```bash bm cloud setup ``` Or set up with custom directory: ```bash bm cloud setup --dir ~/my-sync-folder ``` ### Running Sync Use the cloud-aware `bm sync` command: ```bash # Manual sync bm sync # Watch mode (continuous sync) bm sync --watch # Custom interval (30 seconds) bm sync --watch --interval 30 ``` ### Bisync Profiles Bisync supports three conflict resolution strategies with different safety levels: | Profile | Conflict Resolution | Max Deletes | Use Case | |---------|-------------------|-------------|----------| | **balanced** | newer | 25 | Default, recommended for most users | | **safe** | none | 10 | Keep both versions on conflict | | **fast** | newer | 50 | Rapid iteration, higher delete tolerance | **Profile Details:** - **safe**: - Conflict resolution: `none` (creates `.conflict` files for both versions) - Max delete: 10 files per sync - Best for: Critical data where you want manual conflict resolution - **balanced** (default): - Conflict resolution: `newer` (auto-resolve to most recent file) - Max delete: 25 files per sync - Best for: General use with automatic conflict handling - **fast**: - Conflict resolution: `newer` (auto-resolve to most recent file) - Max delete: 50 files per sync - Best for: Rapid development iteration with less restrictive safety checks **How to Select a Profile:** The default profile (`balanced`) is used automatically with `bm sync`: ```bash # Uses balanced profile (default) bm sync ``` For advanced control, use `bm cloud bisync` with the `--profile` flag: ```bash # Use safe mode bm cloud bisync --profile safe # Use fast mode bm cloud bisync --profile fast # Preview changes with specific profile bm cloud bisync --profile safe --dry-run ``` **Check Available Profiles:** ```bash bm cloud status ``` This shows all available profiles with their settings. **Current Limitations:** - Profiles are hardcoded and cannot be customized - No config file option to change default profile - Profile settings (max_delete, conflict_resolve) cannot be modified without code changes - Profile selection only available via `bm cloud bisync --profile` (advanced command) ### Establishing New Baseline If you need to force a complete resync: ```bash bm cloud bisync --resync ``` **Warning:** This overwrites the sync state. Use only when recovering from errors. ### Checking Sync Status View current sync status: ```bash bm cloud status ``` This shows: - Cloud mode status - Instance health - Sync directory location - Last sync time - Available bisync profiles ### Verifying Sync Integrity Check that local and cloud files match: ```bash # Full integrity check bm cloud check # Faster one-way check bm cloud check --one-way ``` This uses `rclone check` to verify files match without transferring data. ### Working with Bisync Create and edit files in `~/basic-memory-cloud-sync/`: ```bash # Create a new note echo "# My Research" > ~/basic-memory-cloud-sync/my-project/notes.md # Edit with your favorite editor code ~/basic-memory-cloud-sync/my-project/ # Sync changes to cloud bm sync ``` In watch mode, changes sync automatically: ```bash # Start watch mode bm sync --watch # Edit files - they sync automatically every 60 seconds code ~/basic-memory-cloud-sync/my-project/ ``` ### Filter Configuration Bisync uses `.bmignore` patterns from `~/.basic-memory/.bmignore`: ```bash # View current ignore patterns cat ~/.basic-memory/.bmignore # Edit ignore patterns code ~/.basic-memory/.bmignore ``` Example `.bmignore`: ```gitignore # This file is used by 'bm cloud bisync' and file sync # Patterns use standard gitignore-style syntax # Hidden files (files starting with dot) - .* # Basic Memory internal files - memory.db/** - memory.db-shm/** - memory.db-wal/** - config.json/** # Version control - .git/** # Python - __pycache__/** - *.pyc - .venv/** # Node.js - node_modules/** ``` **Key points:** - ✅ **Global configuration** - One ignore file for all projects - ✅ **rclone filter syntax** - Patterns with `- ` prefix - ✅ **Automatic creation** - Created with defaults on first use - ✅ **Shared patterns** - Same patterns used by sync service ## NFS Mount (Direct Access) - Alternative NFS mount provides direct file system access as an alternative to bisync. Use this if you prefer mounting files like a network drive. ### Setup Set up mount instead of bisync: ```bash bm cloud setup --mount ``` ### Mounting Files Mount your cloud files: ```bash # Mount with default settings bm cloud mount # Mount with specific profile bm cloud mount --profile fast ``` #### Mount Profiles - **balanced** (default): Balanced caching for general use - **streaming**: Optimized for large files - **fast**: Minimal verification for rapid access ### Checking Mount Status View current mount status: ```bash bm cloud status --mount ``` ### Unmounting Files Unmount when done: ```bash bm cloud unmount ``` ### Working with Mounted Files Once mounted, files appear at `~/basic-memory-cloud/`: ```bash # List cloud files ls ~/basic-memory-cloud/ # Edit with your favorite editor code ~/basic-memory-cloud/my-project/ # Changes are immediately synced to cloud echo "# Notes" > ~/basic-memory-cloud/my-project/readme.md ``` **Note:** Changes are written through to cloud immediately. There's no "sync" step needed. ## Instance Management ### Health Check Check if your cloud instance is healthy: ```bash bm cloud status ``` This shows: - Cloud mode enabled/disabled - Instance health status - Instance version - Sync or mount status ## Troubleshooting ### Authentication Issues **Problem**: "Authentication failed" or "Invalid token" **Solution**: Re-authenticate: ```bash bm cloud logout bm cloud login ``` ### Subscription Issues **Problem**: "Subscription Required" error when logging in **Solution**: You need an active Basic Memory Cloud subscription to use cloud features. 1. Visit the subscribe URL shown in the error message 2. Sign up for a subscription 3. Once your subscription is active, run `bm cloud login` again **Problem**: "Subscription Required" error for existing user **Solution**: Your subscription may have expired or been cancelled. 1. Check your subscription status at [https://basicmemory.com/account](https://basicmemory.com/account) 2. Renew your subscription if needed 3. Run `bm cloud login` again Note: Access is immediately restored when your subscription becomes active. ### Sync Issues **Problem**: "Bisync not initialized" **Solution**: Run setup or initialize with resync: ```bash bm cloud setup # or bm cloud bisync --resync ``` **Problem**: "Too many deletes" error **Solution**: Bisync detected many deletions (safety check). Review changes and use a higher delete limit profile or force resync: ```bash bm cloud bisync --profile fast # Higher delete limit # or bm cloud bisync --resync # Force baseline ``` **Problem**: Conflicts detected **Solution**: Bisync found files changed in both locations. Check sync directory for `.conflict` files: ```bash ls ~/basic-memory-cloud-sync/**/*.conflict ``` Resolve conflicts manually, then sync again. ### Connection Issues **Problem**: "Cannot connect to cloud instance" **Solution**: Check cloud status: ```bash bm cloud status ``` If instance is down, wait a few minutes and retry. If problem persists, contact support. ### Mount Issues **Problem**: "Mount point is busy" **Solution**: Unmount and remount: ```bash bm cloud unmount bm cloud mount ``` **Problem**: "Permission denied" when accessing mounted files **Solution**: Check mount status and remount: ```bash bm cloud status --mount bm cloud unmount bm cloud mount ``` ## Security - **Authentication**: OAuth 2.1 with PKCE flow - **Tokens**: Stored securely in `~/.basic-memory/auth/token` - **Transport**: All data encrypted in transit (HTTPS) - **Credentials**: Scoped S3 credentials for sync/mount (read-write access to your tenant only) - **Isolation**: Your data is isolated from other tenants - **Ignore patterns**: Sensitive files (`.env`, credentials) automatically excluded ## Command Reference ### Cloud Mode Management ```bash bm cloud login # Authenticate and enable cloud mode bm cloud logout # Disable cloud mode bm cloud status # Check cloud mode and sync status bm cloud status --mount # Check cloud mode and mount status ``` ### Setup ```bash bm cloud setup # Setup bisync (default, recommended) bm cloud setup --mount # Setup mount (alternative) bm cloud setup --dir ~/sync # Custom sync directory ``` ### Project Management (Cloud Mode Aware) When cloud mode is enabled, these commands work with cloud: ```bash bm project list # List projects bm project add <name> # Create project bm project add <name> --default # Create and set as default bm project rm <name> # Delete project bm project set-default <name> # Set default project ``` ### File Synchronization ```bash bm sync # Sync files (local or cloud depending on mode) bm sync --watch # Continuous sync (cloud mode only) bm sync --interval 30 # Custom interval for watch mode # Advanced bisync commands bm cloud bisync # Run bisync manually bm cloud bisync --profile safe # Use specific profile bm cloud bisync --dry-run # Preview changes bm cloud bisync --resync # Force new baseline bm cloud bisync --watch # Continuous sync bm cloud bisync --verbose # Show detailed output # Integrity verification bm cloud check # Full integrity check bm cloud check --one-way # Faster one-way check ``` ### Direct File Access (Mount) ```bash bm cloud mount # Mount cloud files bm cloud mount --profile fast # Use specific profile bm cloud unmount # Unmount files ``` ## Summary Basic Memory Cloud provides two workflows: ### Recommended: Bidirectional Sync (bisync) 1. `bm cloud login` - Authenticate once 2. `bm cloud setup` - Configure sync once 3. `bm sync` - Sync anytime (or use `--watch`) 4. Work in `~/basic-memory-cloud-sync/` 5. Changes sync bidirectionally ### Alternative: Direct Mount 1. `bm cloud login` - Authenticate once 2. `bm cloud setup --mount` - Configure mount once 3. `bm cloud mount` - Mount when needed 4. Work in `~/basic-memory-cloud/` 5. Changes write through immediately Both approaches work seamlessly with cloud mode - all your regular `bm` commands work with either workflow!

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/basicmachines-co/basic-memory'

If you have feedback or need assistance with the MCP directory API, please join our Discord server