/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

Create an account

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.

Push your brain

/brain:sync cloud push

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

Pull on another machine

On your other machine, after installing Brain Memory:

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

CLI

Brain Cloud also installs a 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 logout         # Clear credentials

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

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.

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.

Push your brain

/brain:sync push

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

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.