Skip to main content

​
Overview

Basic Memory supports multiple projects with flexible routing between local and cloud modes. Each project can be independently configured to:
  • Run entirely local (no cloud dependency)
  • Route CLI commands through the cloud API
  • Sync files bidirectionally with cloud storage
  • Use different cloud workspaces
MCP tools (via stdio transport) always use local routing, allowing simultaneous use of local Claude Desktop and cloud-based clients.

​
Project Concepts

​
Project Modes

Each project has a routing mode that determines which API it uses:
ModeCLI RoutingMCP (stdio)File StorageRequires Cloud
LOCALLocal APILocal APILocal onlyNo
CLOUDCloud APILocal APILocal + Cloud (synced)Yes

​
Project Paths

  • Local path: Where files are stored on your filesystem (~/basic-memory/research)
  • Cloud path: The project’s path in cloud storage (/research)
  • Sync path: Local directory for bidirectional sync (can differ from local path)

​
Workspaces

Cloud workspaces organize projects by tenant:
  • Personal workspace: Your individual account workspace
  • Organization workspace: Shared workspace for team collaboration
Each workspace has its own projects and subscription.

​
Listing Projects

View all local and cloud projects: 
bm project list
Example output: 
                    Basic Memory Projects                     
┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┓
┃ Name    ┃ Local Path         ┃ Cloud Path  ┃ CLI Route ┃ Sync  ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━┩
│ main    │ ~/basic-memory     │             │ local     │       │
│ research│ ~/docs/research    │ /research   │ cloud     │ ✓     │
│ work    │ ~/work             │             │ local     │       │
└─────────┴────────────────────┴─────────────┴───────────┴───────┘

​
Filtering Output

# Show only local projects
bm project list --local

# Show only cloud projects
bm project list --cloud

# Show projects from specific workspace
bm project list --workspace "Personal"

# JSON output for scripting
bm project list --json

​
Creating Projects

​
Local Project

Create a project that runs entirely local: 
bm project add notes ~/Documents/notes

​
Cloud Project with Sync

Create a project with cloud routing and sync: 
bm project add research --cloud --local-path ~/Documents/research
This command:
  1. Creates the project in the cloud
  2. Creates the project in local database
  3. Configures sync path
  4. Sets routing mode to cloud
Cloud project creation requires authentication. Run bm cloud login first if you haven’t already.

​
Project Routing

​
Set Cloud Mode

Route a project’s CLI commands through the cloud API: 
bm project set-cloud research
What changes:
  • CLI commands for this project use cloud API
  • Requires API key or OAuth authentication
  • Enables cloud features (search, stats, etc.)
What stays local:
  • MCP tools (via stdio transport)
  • File storage (unless sync is configured)
  • Database (unless explicitly using cloud)

​
Set Local Mode

Revert a project to local-only routing: 
bm project set-local research
What changes:
  • CLI commands use local API
  • No cloud authentication required
  • Limited to local features

​
Routing Flags

Override routing for a single command: 
# Force local routing
bm project info research --local

# Force cloud routing  
bm project info research --cloud
Routing flags are useful for testing or when you want to query both local and cloud states.

​
Project Information

Get detailed information about a project: 
bm project info research
Example output: 
Project: research
  Path: ~/Documents/research
  Mode: cloud
  Entities: 1,247
  Relations: 3,891
  Last Modified: 2026-02-27 14:32:10
  
Sync Configuration:
  Local Path: ~/Documents/research
  Bisync Initialized: Yes
  Last Sync: 2026-02-28 09:15:43

​
Routing Status

Check which API a project uses: 
bm project list | grep research
Look at the “CLI Route” column:
  • local - Using local API
  • cloud - Using cloud API
  • local (flag) - Forced local via --local flag
  • cloud (flag) - Forced cloud via --cloud flag

​
Sync Configuration

​
Configure Sync for Existing Project

Set up bidirectional sync for a project: 
bm cloud sync-setup research ~/Documents/research
This:
  1. Verifies the project exists in the cloud
  2. Creates the local directory
  3. Updates project config with sync path
  4. Prepares for first bisync

​
View Sync Status

bm project info research
Look for:
  • Bisync Initialized: Whether baseline sync has been established
  • Last Sync: Timestamp of last successful sync
  • Local Path: Where files are stored locally

​
Remove Sync Configuration

To stop syncing a project (keeps cloud and local data): 
# Edit config manually
vim ~/.basic-memory/config.yaml

# Remove or modify the project's local_sync_path field
Removing sync configuration doesn’t delete any files. It only stops future syncs. Files remain in both local and cloud.

​
Default Project

Set a project as the default for MCP operations: 
bm project default research
The default project is used by MCP tools when no project is explicitly specified.

​
View Default Project

bm project info
Or look for the “Default” column in bm project list output.

​
Workspace Management

Workspaces are only relevant for cloud projects. Local projects don’t use workspaces.

​
List Workspaces

View available cloud workspaces: 
bm cloud workspace list
Example output: 
              Available Workspaces               
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┓
┃ Name        ┃ Type       ┃ Role  ┃ Tenant ID ┃ Default ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━┩
│ Personal    │ personal   │ owner │ 11111...  │ [X]     │
│ Acme Corp   │ org        │ admin │ 22222...  │         │
└─────────────┴────────────┴───────┴───────────┴─────────┘

​
Set Default Workspace

bm cloud workspace set-default "Personal"
Or use the tenant ID: 
bm cloud workspace set-default 11111111-1111-1111-1111-111111111111
The default workspace is used when listing cloud projects without specifying --workspace.

​
Per-Command Workspace

Query a specific workspace: 
bm project list --cloud --workspace "Acme Corp"

​
Multi-Device Workflows

​
Scenario: Desktop and Laptop

On Desktop: 
# Initial setup
bm cloud login
bm cloud setup
bm project add research --cloud --local-path ~/Documents/research
bm cloud bisync --name research --resync

# Work on files...

# Sync before stopping work
bm cloud bisync --name research
On Laptop: 
# Initial setup
bm cloud login
bm cloud setup
bm cloud sync-setup research ~/Documents/research
bm cloud bisync --name research --resync

# Work on files...

# Sync regularly
bm cloud bisync --name research

​
Scenario: Mixed Local and Cloud Projects

# Personal notes stay local-only
bm project add notes ~/Documents/notes

# Research syncs to cloud
bm project add research --cloud --local-path ~/Documents/research
bm project set-cloud research

# Work projects stay local for now
bm project add work ~/Documents/work

# Later, enable cloud for work project
bm project set-cloud work
bm cloud sync-setup work ~/Documents/work

​
Advanced Configuration

​
Manual Config Editing

Project configuration lives in ~/.basic-memory/config.yaml: 
default_project: research
projects:
  main:
    path: /Users/you/basic-memory
    mode: local
    
  research:
    path: /Users/you/Documents/research
    local_sync_path: /Users/you/Documents/research
    mode: cloud
    bisync_initialized: true
    last_sync: '2026-02-28T09:15:43'
Key fields:
  • path: Local filesystem path
  • local_sync_path: Sync directory (can differ from path)
  • mode: Routing mode (local or cloud)
  • bisync_initialized: Whether baseline sync exists
  • last_sync: Timestamp of last successful sync

​
Environment Variables

Control routing behavior:
VariableEffect
BASIC_MEMORY_FORCE_LOCAL=trueForce local routing for all commands
BASIC_MEMORY_FORCE_CLOUD=trueForce cloud routing for all commands
BASIC_MEMORY_EXPLICIT_ROUTING=trueMark routing as explicit
Example: 
# Test local API while project is in cloud mode
BASIC_MEMORY_FORCE_LOCAL=true bm status

​
Snapshot Integration

Cloud projects support snapshots for backup and rollback.

​
Create Snapshot

Snapshot your project’s cloud state: 
bm cloud snapshot create "before major refactor"

​
List Snapshots

bm cloud snapshot list

​
Restore from Snapshot

Restore specific files or entire project: 
# Restore specific file
bm cloud restore /research/notes/important.md --snapshot snap_abc123

# Restore entire project directory
bm cloud restore /research/ --snapshot snap_abc123
After restoring from a snapshot, run bisync --resync to establish a new baseline:
bm cloud bisync --name research --resync

​
Snapshot Best Practices

  • Before major changes: Create snapshot before refactoring or bulk edits
  • Daily snapshots: Automate daily snapshots via cron or scheduled task
  • Pre-sync snapshots: Snapshot before risky sync operations
  • Descriptive names: Use clear descriptions for easy identification

​
Troubleshooting

​
Project Not Found

# Verify project exists locally
bm project list --local

# Verify project exists in cloud
bm cloud list --cloud

# Re-create if missing
bm project add myproject --cloud --local-path ~/path

​
Cloud Routing Fails

# Check authentication
bm cloud status

# Verify API key is set (for cloud projects)
bm cloud status

# Re-authenticate if needed
bm cloud login

​
Sync Path Mismatch

# Check current configuration
bm project info research

# Reconfigure sync path
bm cloud sync-setup research ~/correct/path

​
Bisync State Issues

# Reset bisync state
bm cloud bisync-reset research

# Re-establish baseline
bm cloud bisync --name research --resync

​
Wrong Workspace

# List available workspaces
bm cloud workspace list

# Set correct default workspace
bm cloud workspace set-default "Correct Workspace"

# Or use --workspace flag
bm project list --cloud --workspace "Correct Workspace"

​
Next Steps

Bidirectional Sync

Learn about syncing files between local and cloud

Authentication

Set up cloud credentials and API keys

CLI Reference

Complete CLI command reference

Build docs developers (and LLMs) love

Get started for freeTalk to us