/brain:sync

Sync your brain across devices using Brain Cloud, Git remote push/pull, or file-based export/import.

Usage

/brain:sync [subcommand]

Cloud Sync (Brain Cloud):

cloud login — Authenticate via device code flow
cloud push — Upload ~/.brain/ to Brain Cloud
cloud pull — Download from Brain Cloud
cloud status — Show connection info
cloud logout — Clear stored credentials

Git Sync:

setup <url> — Configure a Git remote for syncing
push — Push local changes to the remote
pull — Pull remote changes to local
status — Show sync state (remote URL, ahead/behind counts)
export [path] — Export the brain to a portable file
import <path> — Import a brain from a portable file
disconnect — Remove sync configuration

Brain Cloud Sync

The easiest way to sync — no Git setup required. Push your brain to Brain Cloud and pull it on any device.

Setup

undefined

Create an account

undefined

Log in from your terminal

/brain:sync cloud login

This starts a device code flow — open the displayed URL in your browser and approve the login.

undefined

Push your brain

/brain:sync cloud push

Your entire ~/.brain/ directory is packed into a tar.gz archive and uploaded.

undefined

Pull on another machine

On your other machine, after installing Brain Memory:

/brain:sync cloud login
/brain:sync cloud pull

CLI

Brain Cloud is also reachable via the brain cloud CLI for use outside of agent sessions:

brain cloud login          # Authenticate
brain cloud push           # Upload ~/.brain/
brain cloud pull           # Download to ~/.brain/
brain cloud status         # Show connection info
brain cloud brains         # List the account's brains
brain cloud use <name>     # Sync with another brain
brain cloud logout         # Clear credentials

Several Brains

An account can hold more than one brain, for example one per project, created on the Brains page of the dashboard. brain cloud login links the account's first brain unless you name another:

brain cloud login --brain "Work"     # link "Work", creating it if no brain has that name
brain cloud brains                   # * marks the brain this device syncs with
brain cloud use Work                 # switch; add --create to make a new one

Names match ignoring case. Switching changes only which brain this device syncs with: ~/.brain/ is left as it is. Run brain cloud pull to load the brain you switched to. A push into a brain that already holds memories this device has not pulled is refused, so one brain's memories never land on top of another's by accident.

In Claude.ai and other MCP hosts, ask the agent which brains you have (brain_status) and to switch (brain_use). The connector remembers your choice for later sessions. Use the same brain on both sides, or memories saved in one will not show up in the other.

When a Push Is Refused

A push names the archive it started from. If another device pushed since you last pulled, the store refuses the upload and nothing is overwritten:

Error: The store has changes you have not pulled, so nothing was uploaded.

Run brain cloud pull, then brain cloud push again. brain cloud push --force uploads anyway and replaces what the store holds; the store keeps a snapshot of what it replaced, so brain restore --from cloud can undo it.

A Self-Hosted Store

brain cloud also talks to a store you run yourself with brain-store. Log in with the token its operator issued instead of the device code flow:

pbpaste | brain cloud login --api-url https://store.example.com --token-stdin

--token TOKEN and the BRAIN_STORE_TOKEN environment variable also work. The CLI refuses to send a token over plain HTTP to another host unless you pass --allow-http.

Cloud State

Cloud credentials are stored locally at ~/.brain/.cloud/config.json and never pushed to any remote.

Git Remote Sync

For users who prefer to self-host or want version history. Uses your existing Git/SSH authentication — no additional credentials needed.

Setup

undefined

Create a private repository

Create a private Git repository on your preferred hosting service:

gh repo create brain-data --private

You can use GitHub, GitLab, Codeberg, or any self-hosted Git server.

undefined

Configure the remote

/brain:sync setup git@github.com:you/brain-data.git

This initializes a hidden Git repository inside ~/.brain/.sync/repo/ and sets the remote URL. Your brain files remain in their original locations.

undefined

Push your brain

/brain:sync push

Commits all current brain files and pushes to the remote repository.

undefined

Pull on another machine

On your other machine, after installing Brain Memory:

/brain:sync setup git@github.com:you/brain-data.git
/brain:sync pull

Push

/brain:sync push

Stages all changes in ~/.brain/, creates a commit with a timestamp, and pushes to the configured remote. Only changed files are transferred.

Pull

/brain:sync pull

Fetches from the remote and merges changes into your local brain. If there are conflicts (rare — usually happens when two machines modify the same memory), the agent will prompt you to resolve them.

Export / Import

For one-off transfers without setting up a Git remote.

Export

/brain:sync export

Packs the entire ~/.brain/ directory into a single file. The output file is saved to a location you specify (or a default like ~/brain-export-<timestamp>.tar.gz).

Import

/brain:sync import <path>

Imports a previously exported brain file. Supports two modes:

Merge mode (default) — Only imports files that are newer than existing ones. Existing memories that were modified more recently on the local machine are preserved.
Overwrite mode — Replaces all local brain files with the imported ones.

/brain:sync import ~/brain-export-20260215.tar.gz
/brain:sync import ~/brain-export-20260215.tar.gz --overwrite

Encryption

Both Git sync and export/import support optional AES-256-GCM encryption with a user-provided passphrase.

Enabling Encryption

When setting up sync:

/brain:sync setup git@github.com:you/brain-data.git --encrypt

The agent will prompt for a passphrase. All files are encrypted before committing to the remote. You will need the same passphrase to pull on another machine.

For exports:

/brain:sync export --encrypt

And when importing an encrypted file:

/brain:sync import ~/brain-export-encrypted.tar.gz

The agent will prompt for the passphrase.

warning

If you enable encryption, you must remember your passphrase. There is no recovery mechanism. Without the passphrase, encrypted data cannot be decrypted.

Sync State

Sync configuration and state are stored in ~/.brain/.sync/:

~/.brain/.sync/
├── config.json          # Remote URL, encryption flag
└── repo/                # Hidden git repo for sync

This directory is local-only and is never pushed to the remote.

Key Features

Feature	Description
Brain Cloud	One-command sync via `cloud push` / `cloud pull` — no Git required
Non-interactive push	Push executes immediately — no confirmation step. Pull/import still confirm before overwriting.
Manual sync	No background watchers, no auto-sync. You control when data moves.
Optional encryption	AES-256-GCM with user-provided passphrase (Git sync and export)
Merge mode	Import only newer files, preserving local changes
Zero dependencies	Uses Node.js built-in `https` and `crypto`, and the system `git` and `tar` binaries
Any Git host	Git sync works with GitHub, GitLab, Codeberg, or self-hosted servers

tip

For most users, Brain Cloud is the easiest option — sign up, log in, push. Use Git sync if you want version history and full self-hosting. Use export/import for air-gapped or one-off transfers.

info

Sync is always manual by design. Your brain data never leaves your machine unless you explicitly push or export.