basic-memory

# Cloud Mount Commands **Status**: New Feature **PR**: #306 **Requires**: Active subscription, rclone installation ## What's New v0.15.0 introduces cloud mount commands that let you access cloud storage as a local filesystem using rclone mount. This provides direct file access for browsing, editing, and working with cloud files. ## Quick Start ### Mount Cloud Storage ```bash # Mount cloud storage at ~/basic-memory-cloud bm cloud mount # Storage now accessible as local directory ls ~/basic-memory-cloud cd ~/basic-memory-cloud/my-project vim notes.md ``` ### Unmount ```bash # Unmount when done bm cloud unmount ``` ## How It Works ### rclone Mount Basic Memory uses rclone to mount your cloud bucket as a FUSE filesystem: ``` Cloud Storage (S3) rclone mount Local Filesystem ┌─────────────────┐ ┌──────────────────┐ │ s3://bucket/ │ <───────────> │ ~/basic-memory- │ │ tenant-id/ │ (FUSE filesystem) │ cloud/ │ │ ├── project-a/│ │ ├── project-a/ │ │ ├── project-b/│ │ ├── project-b/ │ │ └── notes/ │ │ └── notes/ │ └─────────────────┘ └──────────────────┘ ``` ### Mount vs Bisync | Feature | Mount | Bisync | |---------|-------|--------| | **Access** | Direct cloud access | Synced local copy | | **Latency** | Network dependent | Instant (local files) | | **Offline** | Requires connection | Works offline | | **Storage** | No local storage | Uses local disk | | **Use Case** | Quick access, browsing | Primary workflow, offline work | **Key difference:** Mount directory (`~/basic-memory-cloud`) and bisync directory (`~/basic-memory-cloud-sync`) must be **different locations**. ## Commands ### bm cloud mount Mount cloud storage to local filesystem. ```bash # Basic mount (default: ~/basic-memory-cloud) bm cloud mount # Custom mount point bm cloud mount --mount-point ~/my-cloud-mount # Background mode bm cloud mount --daemon # With verbose logging bm cloud mount --verbose ``` **What happens:** 1. Authenticates with cloud (uses stored JWT) 2. Generates scoped S3 credentials 3. Configures rclone remote 4. Mounts cloud bucket via FUSE 5. Makes files accessible at mount point ### bm cloud unmount Unmount cloud storage. ```bash # Unmount default location bm cloud unmount # Unmount custom location bm cloud unmount --mount-point ~/my-cloud-mount # Force unmount (if busy) bm cloud unmount --force ``` **What happens:** 1. Flushes pending writes 2. Unmounts FUSE filesystem 3. Cleans up mount point ### bm cloud status Check mount status. ```bash bm cloud status ``` **Shows:** ``` Cloud Mount Status ┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Property ┃ Value ┃ ┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ Status │ ✓ Mounted │ │ Mount Point │ ~/basic-memory-cloud │ │ Remote │ s3://bucket/tenant-id │ │ Read/Write │ Yes │ └────────────────┴────────────────────────────┘ ``` ## Mount Point Structure ### Default Layout ```bash ~/basic-memory-cloud/ # Mount point (configurable) ├── project-a/ # Cloud projects visible as directories │ ├── notes/ │ │ └── meeting-notes.md │ └── ideas/ │ └── brainstorming.md ├── project-b/ │ └── documents/ └── shared-notes/ ``` ### Important: Separate from Bisync **Mount point:** `~/basic-memory-cloud` (direct cloud access) **Bisync directory:** `~/basic-memory-cloud-sync` (synced local copy) **These MUST be different directories:** ```bash # ✓ Correct - different directories MOUNT: ~/basic-memory-cloud BISYNC: ~/basic-memory-cloud-sync # ✗ Wrong - same directory (will error) MOUNT: ~/basic-memory-cloud BISYNC: ~/basic-memory-cloud ``` ## Usage Workflows ### Quick File Access ```bash # Mount bm cloud mount # Browse files ls ~/basic-memory-cloud cd ~/basic-memory-cloud/work-project # View a file cat ideas/new-feature.md # Edit directly vim notes/meeting.md # Unmount when done bm cloud unmount ``` ### Read-Only Browsing ```bash # Mount for reading bm cloud mount # Search for files grep -r "authentication" ~/basic-memory-cloud # View recent files find ~/basic-memory-cloud -type f -mtime -7 # Unmount bm cloud unmount ``` ### Working with Obsidian ```bash # Mount cloud storage bm cloud mount # Open mount point in Obsidian # Obsidian vault: ~/basic-memory-cloud/my-project # Work directly on cloud files # Changes saved immediately to cloud # Unmount when done (close Obsidian first) bm cloud unmount ``` ### Temporary Access on Another Device ```bash # Device B (no local sync setup) bm cloud login bm cloud mount # Access files directly cd ~/basic-memory-cloud vim project/notes.md # Unmount and logout bm cloud unmount bm cloud logout ``` ## Performance Considerations ### Network Latency Mount performance depends on network: - **Local network:** Fast, near-native performance - **Remote/internet:** Slower, noticeable latency - **Offline:** Not accessible (returns errors) ### Caching rclone provides some caching: ```bash # Mount with enhanced caching rclone mount basic-memory-remote:bucket ~/basic-memory-cloud \ --vfs-cache-mode writes \ --vfs-write-back 5s ``` ### When to Use Mount vs Bisync **Use Mount for:** - Quick file access - Temporary access on other devices - Read-only browsing - Low disk space situations **Use Bisync for:** - Primary workflow - Offline access - Better performance - Regular file operations ## Mount Options ### Foreground vs Daemon **Foreground (default):** ```bash bm cloud mount # Runs in foreground, shows logs # Ctrl+C to unmount ``` **Daemon (background):** ```bash bm cloud mount --daemon # Runs in background # Use 'bm cloud unmount' to stop ``` ### Read-Only Mount ```bash # Mount as read-only bm cloud mount --read-only # Prevents accidental changes # Good for browsing/searching ``` ### Custom Mount Point ```bash # Use different directory bm cloud mount --mount-point ~/cloud-kb # Files at ~/cloud-kb/ ls ~/cloud-kb ``` ## Troubleshooting ### Mount Failed **Problem:** Can't mount cloud storage ```bash $ bm cloud mount Error: mount failed: transport endpoint not connected ``` **Solutions:** 1. Check authentication: `bm cloud login` 2. Verify rclone installed: `which rclone` 3. Check mount point exists: `mkdir -p ~/basic-memory-cloud` 4. Ensure not already mounted: `bm cloud unmount` ### Directory Busy **Problem:** Can't unmount, directory in use ```bash $ bm cloud unmount Error: device is busy ``` **Solutions:** ```bash # Check what's using it lsof | grep basic-memory-cloud # Close applications using mount # cd out of mount directory cd ~ # Force unmount bm cloud unmount --force # Or use system unmount umount -f ~/basic-memory-cloud ``` ### Permission Denied **Problem:** Can't access mounted files ```bash $ ls ~/basic-memory-cloud Permission denied ``` **Solutions:** 1. Check credentials: `bm cloud login` 2. Verify subscription: `bm cloud status` 3. Remount: `bm cloud unmount && bm cloud mount` ### Slow Performance **Problem:** Files load slowly **Solutions:** 1. Use bisync for regular work instead 2. Enable write caching (advanced) 3. Check network connection 4. Consider local-first workflow ### Conflicts with Bisync **Problem:** Trying to use same directory ```bash $ bm cloud mount --mount-point ~/basic-memory-cloud-sync Error: Cannot use bisync directory for mount ``` **Solution:** Use different directories ```bash MOUNT: ~/basic-memory-cloud BISYNC: ~/basic-memory-cloud-sync ``` ## Advanced Usage ### Manual rclone Mount For advanced users, mount directly: ```bash # List configured remotes rclone listremotes # Manual mount with options rclone mount basic-memory-{tenant-id}:{bucket} ~/mount-point \ --vfs-cache-mode full \ --vfs-cache-max-age 1h \ --daemon # Unmount fusermount -u ~/mount-point # Linux umount ~/mount-point # macOS ``` ### Mount with Specific Options ```bash # Read-only with caching rclone mount remote:bucket ~/mount \ --read-only \ --vfs-cache-mode full # Write-back for better performance rclone mount remote:bucket ~/mount \ --vfs-cache-mode writes \ --vfs-write-back 30s ``` ## Platform-Specific Notes ### macOS **Requires:** macFUSE ```bash # Install macFUSE brew install --cask macfuse # Mount bm cloud mount ``` **Unmount:** ```bash # Basic bm cloud unmount # Or system unmount umount ~/basic-memory-cloud ``` ### Linux **Requires:** FUSE ```bash # Install FUSE (usually pre-installed) sudo apt-get install fuse # Debian/Ubuntu sudo yum install fuse # RHEL/CentOS # Mount bm cloud mount ``` **Unmount:** ```bash # Basic bm cloud unmount # Or system unmount fusermount -u ~/basic-memory-cloud ``` ### Windows **Requires:** WinFsp ```bash # Install WinFsp from https://winfsp.dev/ # Mount bm cloud mount # Mounted as drive letter (e.g., Z:) dir Z:\ ``` ## Security ### Credentials - Mount uses scoped S3 credentials (tenant-isolated) - Credentials expire after session - No plain-text secrets stored ### File Access - All traffic encrypted (HTTPS/TLS) - Same permissions as cloud API - Respects tenant isolation ### Unmount on Logout ```bash # Good practice: unmount before logout bm cloud unmount bm cloud logout ``` ## See Also - `cloud-bisync.md` - Bidirectional sync (recommended for primary workflow) - `cloud-authentication.md` - Required authentication setup - `cloud-mode-usage.md` - Using CLI tools with cloud - rclone documentation - Advanced mount options