Local & Cloud Routing

Basic Memory is a knowledge base that you and your AI share. By default, your notes live on your computer. With Basic Memory Cloud, you can also store notes in the cloud — accessible from any device. Routing lets you choose where each project lives.

How Routing Works

When Basic Memory runs on your computer, it decides where to handle each request based on your settings:

• Local mode — Files and database stay on your machine. No network requests. This is the default.
• Cloud mode — Requests are forwarded to your Basic Memory Cloud instance. Notes are stored in the cloud and accessible from any device.

You use the same commands and your AI uses the same tools either way — the only difference is where your notes are stored.

Routing Levels

Routing decisions follow a priority order — the most specific level wins:

Examples:

• Global cloud mode is active, but bm project set-local research keeps the research project on your machine.
• You're in local-only mode, but bm project set-cloud shared-notes routes just that project through cloud.
• You need a quick cloud check: bm search_notes --cloud "meeting notes" overrides everything for that one call.

Setting Up Cloud Routing

Save an API Key

API keys are the simplest way to enable cloud routing for specific projects.

# Save a key you created in the web app
bm cloud api-key save bmc_your_key_here

# Or create a new key from the CLI (requires being logged in via `bm cloud login`)
bm cloud api-key create "my-laptop"

See API Keys for details on creating and managing keys.

Route a Project to Cloud

# Route a specific project through cloud
bm project set-cloud research

After this, all MCP tool calls for the research project go through your cloud instance.

Check Routing Status

# See which projects are cloud-routed
bm cloud status

Revert to Local

# Switch a project back to local
bm project set-local research

The project returns to local mode immediately. Your cloud data remains in the cloud — this only changes where new requests are handled.

Common Setups

All Local (Default)

No configuration needed. Every project runs on your machine. This is how Basic Memory works out of the box.

All Cloud

Log in and everything routes through cloud:

bm cloud login

All projects use your cloud instance. Use bm cloud logout to return to local-only.

Hybrid (Local + Cloud)

This is the most popular setup — keep private notes on your computer while sharing specific projects across devices.

# Save your API key for per-project routing
bm cloud api-key save bmc_your_key_here

# Route shared projects to cloud
bm project set-cloud shared-notes
bm project set-cloud team-wiki

# Personal projects stay local (no action needed — local is the default)

This is useful when you want to:

• Keep sensitive or personal projects on your machine
• Share specific projects across devices
• Collaborate on cloud projects while working locally on others

Gradual Migration

Start local and move projects to cloud one at a time:

# 1. Start with everything local (default)

# 2. Upload a project to cloud
bm cloud upload ~/my-notes --project my-notes --create-project

# 3. Route that project to cloud
bm cloud api-key save bmc_your_key_here
bm project set-cloud my-notes

# 4. Repeat for other projects as needed

Authentication

Cloud-routed projects need credentials. Basic Memory supports two methods:

Both methods work for any cloud-routed project. API keys are preferred for hybrid setups because they don't require opening a browser.

See API Keys for detailed setup instructions.

How It Works Under the Hood

• Local mode — Requests are handled directly on your machine with no network involved.
• Cloud mode — Requests are forwarded to cloud.basicmemory.com using your credentials (API key or login token). The cloud instance processes the request and returns the result.

In both cases, the same tools and commands work identically. The only difference is where the work happens.