CLI Reference

Complete command line reference for Basic Memory including auth, import, project management, and tool commands

Core Commands

cloud

Manage cloud authentication and synchronization. Requires active subscription.

Authentication Commands

cloud login

Authenticate with Basic Memory Cloud using OAuth 2.1 flow.

# Authenticate with cloud service
basic-memory cloud login

Opens browser for authentication, validates subscription, and stores JWT token in ~/.basic-memory/cloud_auth.json.

What happens:

• Opens OAuth authorization in browser
• Validates active subscription
• Stores JWT token locally
• Auto-refreshes token when needed

Error cases:

• No subscription: Shows subscribe URL
• Network error: Retries with exponential backoff
• Invalid credentials: Prompts to try again

cloud logout

Clear authentication session and credentials.

# Logout and clear credentials
basic-memory cloud logout

Removes stored credentials from ~/.basic-memory/cloud_auth.json. Requires re-authentication for cloud commands.

cloud status

Check authentication, subscription, and sync status.

# View cloud status
basic-memory cloud status

Shows:

• Authentication status (logged in/out)
• Subscription status (active/expired)
• Last sync time
• Mount status (if mounted)
• Cloud project count
• Tenant information

Sync Commands

cloud bisync-setup

One-time setup for bidirectional cloud synchronization.

# Setup with default directory
basic-memory cloud bisync-setup

# Custom sync directory
basic-memory cloud bisync-setup --dir ~/my-sync-folder

What happens:

1. Checks for/installs rclone
2. Generates scoped S3 credentials
3. Configures rclone remote
4. Creates local sync directory
5. Performs initial baseline sync

Configuration saved to:

• ~/.basic-memory/config.json - sync_dir path
• ~/.config/rclone/rclone.conf - remote credentials
• ~/.basic-memory/bisync-state/{tenant_id}/ - sync state

cloud bisync

Bidirectional synchronization with cloud storage.

# Basic sync (uses 'balanced' profile)
basic-memory cloud bisync

# Choose sync profile
basic-memory cloud bisync --profile safe      # Keep both versions on conflict
basic-memory cloud bisync --profile balanced  # Use newer file (default)
basic-memory cloud bisync --profile fast      # Optimized for speed

# Dry run (preview changes)
basic-memory cloud bisync --dry-run

# Force resync (rebuild baseline)
basic-memory cloud bisync --resync

# Verbose output
basic-memory cloud bisync --verbose

Sync Profiles:

Automatically discovers and registers new local projects with cloud before syncing.

Mount Commands

cloud mount

Mount cloud storage as local filesystem using rclone.

# Basic mount (default: ~/basic-memory-cloud)
basic-memory cloud mount

# Custom mount point
basic-memory cloud mount --mount-point ~/my-cloud-mount

# Background mode
basic-memory cloud mount --daemon

# Read-only mount
basic-memory cloud mount --read-only

# With verbose logging
basic-memory cloud mount --verbose

Provides direct access to cloud files without local sync. Network connection required.

What happens:

1. Authenticates with cloud
2. Generates scoped S3 credentials
3. Configures rclone remote
4. Mounts cloud bucket via FUSE
5. Makes files accessible at mount point

Platform requirements:

• macOS: macFUSE (brew install --cask macfuse)
• Linux: FUSE (usually pre-installed)
• Windows: WinFsp (https://winfsp.dev/)

cloud unmount

Unmount cloud storage.

# Unmount default location
basic-memory cloud unmount

# Unmount custom location
basic-memory cloud unmount --mount-point ~/my-cloud-mount

# Force unmount (if busy)
basic-memory cloud unmount --force

Flushes pending writes and cleanly unmounts the FUSE filesystem.

Integrity Commands

cloud check

Verify integrity of cloud storage.

basic-memory cloud check

Validates checksums and file consistency between local and cloud, detecting:

• Corrupted files
• Missing files
• Sync drift

import

Imports external knowledge sources with support for project targeting:

# Claude conversations
basic-memory import claude conversations

# Claude projects
basic-memory import claude projects

# ChatGPT history
basic-memory import chatgpt

# Memory JSON format
basic-memory import memory-json /path/to/memory.json

# Import to specific project
basic-memory --project=work import claude conversations

status

Shows system status information:

# Basic status check
basic-memory status

# Detailed status
basic-memory status --verbose

# JSON output
basic-memory status --json

project

Manage multiple projects with the new unified database architecture. Projects can now be switched instantly during conversations without restart.

# List all configured projects with status
basic-memory project list

# Create a new project
basic-memory project add work ~/work-basic-memory

# Create a project using an existing directory (like an Obsidian vault)
basic-memory project add notes ~/Documents/MyObsidianVault

# Set the default project
basic-memory project default work

# Remove a project (doesn't delete files)
basic-memory project remove personal

# Show detailed project statistics
basic-memory project info

Using Projects in Commands

All commands support the --project flag to specify which project to use:

# Run MCP server for a specific project
basic-memory --project=personal mcp

tools

Direct access to MCP tools via CLI with new editing and file management capabilities:

# Create notes
basic-memory tool write-note --title "My Note" --content "Content here"

# Search notes
basic-memory tool search-notes --query "authentication"

help

The full list of commands and help for each can be viewed with the --help argument.

basic-memory --help

Using stdin with Basic Memory’s write_note Tool

The write-note tool supports reading content from standard input (stdin), allowing for more flexible workflows when creating or updating notes in your Basic Memory knowledge base.

Use Cases

This feature is particularly useful for:

1. Piping output from other commands directly into Basic Memory notes
2. Creating notes with multi-line content without having to escape quotes or special characters
3. Integrating with AI assistants like Claude Code that can generate content and pipe it to Basic Memory
4. Processing text data from files or other sources

Basic Usage

Method 1: Using a Pipe

You can pipe content from another command into write_note:

# Pipe output of a command into a new note
echo "# My Note\n\nThis is a test note" | basic-memory tool write-note \
--title "Test Note" --folder "notes"

# Pipe output of a file into a new note
cat README.md | basic-memory tool write-note --title "Project README" --folder "documentation"

# Process text through other tools before saving as a note
cat data.txt | grep "important" | basic-memory tool write-note --title "Important Data" --folder "data"

Method 2: Using Heredoc Syntax

For multi-line content, you can use heredoc syntax:

# Create a note with heredoc
cat << EOF | basic-memory tool write_note --title "Project Ideas" --folder "projects"
# Project Ideas for Q2

## AI Integration
- Improve recommendation engine
- Add semantic search to product catalog

## Infrastructure
- Migrate to Kubernetes
- Implement CI/CD pipeline
EOF

Method 3: Input Redirection

You can redirect input from a file:

# Create a note from file content
basic-memory tool write-note --title "Meeting Notes" --folder "meetings" < meeting_notes.md

Integration with Claude Code

This feature works well with Claude Code in the terminal:

CLI

In a Claude Code session, let Claude know he can use the basic-memory tools, then he can execute them via the cli:

echo "# Test Note from Claude\n\nThis is a test note created by Claude to test the stdin functionality." | basic-memory tool write-note --title "Claude Test Note" --folder "test" --tags "test" --tags "claude"

# Stable releases
pip install basic-memory

# Beta/pre-releases
pip install basic-memory --pre

# Latest development builds (auto-published)
pip install basic-memory --pre --force-reinstall

# Check current version
basic-memory --version

Troubleshooting Common Issues

Import Errors

If import fails:

1. Check that the source file is in the correct format
2. Verify permissions on the target directory
3. Use —verbose flag for detailed error information

Status Issues

If status shows problems:

1. Note any unresolved relations or warnings
2. Restart your MCP Client (e.g. Claude Desktop)
3. Check file permissions if database access errors occur
4. If the errors continue please contact us and we will fix it