botrun-msync — Git-backed Memory Sync CLI for Agents

bms manages persistent memory for AI agents across ephemeral VMs. Memories are stored as files in Git repos (GitHub / GitLab), and bms handles the git plumbing — clone, sync, and scope management. Agents read/write memory files directly using their own tools.

Install

npx botrun-msync --help

Quick Start

# 1. Add a memory scope (bind token via env var name)
npx botrun-msync config add-scope my-notes \
  --repo github.com/your-org/agent-memory \
  --token-env MY_GITHUB_TOKEN \
  --description "My personal notes" \
  --access readwrite

# 2. Set the token
export MY_GITHUB_TOKEN=ghp_xxxxx

# 3. Clone the repo
npx botrun-msync memory init

# 4. Agent reads/writes files at the local path...

# 5. Push changes back
npx botrun-msync memory sync

Concepts

Scope

A scope is a logical name that maps to a git repo. Each agent can have multiple scopes pointing to different repos.

npx botrun-msync config add-scope my-notes \
  --repo github.com/org/my-memory \
  --token-env BMS_TOKEN_NOTES \
  --description "Personal research notes" \
  --access readwrite

Multi-Repo Architecture

Different scopes can point to different repos. Permissions are controlled by Git provider tokens — not by bms. Each scope binds to its own token via --token-env, enabling per-repo permission control.

# Director agent setup:
# Read-write token for personal repo
npx botrun-msync config add-scope director \
  --repo github.com/org/director-memory \
  --token-env BMS_TOKEN_DIRECTOR \
  --description "Director personal research" \
  --access readwrite

# Read-only token for team repos
npx botrun-msync config add-scope team1 \
  --repo github.com/org/team1-memory \
  --token-env BMS_TOKEN_TEAMS \
  --description "Team 1 memory" \
  --access readonly

npx botrun-msync config add-scope team2 \
  --repo github.com/org/team2-memory \
  --token-env BMS_TOKEN_TEAMS \
  --description "Team 2 memory" \
  --access readonly

Create separate GitHub Fine-grained PATs with different permissions:

• BMS_TOKEN_DIRECTOR → Contents: Read and write (only director-memory repo)
• BMS_TOKEN_TEAMS → Contents: Read-only (only team1-memory + team2-memory repos)

This way, even if a user modifies the config, they can't write to repos their token doesn't allow.

Config

Config 與 Data 分離

config.json（scope 定義）和 data（clone 下來的 repo）可以放在不同位置：

• config.json — 集中管理，預設 /workspace/.botrun/bms/config.json
• data — 跟著使用場景走，由 memory init 決定位置，預設 $PWD/data/

/workspace/.botrun/bms/config.json     ← scope 定義 + data_path 指向

/your/project/data/            ← data 跟著專案走
├── my-notes/                  ← git clone of my-notes scope
├── team1/                     ← git clone of team1 scope
└── team2/                     ← git clone of team2 scope

Config File

預設路徑：/workspace/.botrun/bms/config.json

覆蓋方式：

npx botrun-msync --config-path /path/to/config.json memory init    # CLI option
BMS_CONFIG=/path/to/config.json npx botrun-msync memory init        # env var

Priority: --config-path > BMS_CONFIG > /workspace/.botrun/bms/config.json

{
  "data_path": "/your/project/data",
  "scopes": {
    "my-notes": {
      "repo": "github.com/org/member1-memory",
      "token_env": "BMS_TOKEN_NOTES",
      "description": "Personal research notes",
      "access": "readwrite"
    },
    "team1": {
      "repo": "github.com/org/team1-memory",
      "branch": "dev",
      "token_env": "BMS_TOKEN_TEAMS",
      "description": "Team 1 memory",
      "access": "readonly"
    }
  }
}

| Field | Required | Description | |-------|----------|-------------| | data_path | no | Absolute path to data directory. Written by memory init | | scopes | yes | Scope definitions (see below) |

Scope fields:

| Field | Required | Description | |-------|----------|-------------| | repo | yes | Git repo URL (without https://) | | branch | no | Git branch to use. Omit = repo default branch | | token_env | no | Env var name for this scope's token (for per-repo permission control) | | description | no | Description for agent context | | access | no | Access hint for agent: readwrite or readonly (default: readwrite) | | provider | no | github or gitlab. Auto-detected from URL |

Config Commands

npx botrun-msync config add-scope <name> --repo <url> [--branch <branch>] [--token-env <envVar>] [--description <text>] [--access <mode>]
npx botrun-msync config remove-scope <name>
npx botrun-msync config set-data-path <path>
npx botrun-msync config show

Environment Variables

| Variable | Purpose | |----------|---------| | BMS_CONFIG | Config file path (default: /workspace/.botrun/bms/config.json) |

Each scope's token is configured via --token-env, which points to an environment variable name. There are no global token variables — every scope must declare its own.

Memory Commands

npx botrun-msync memory init [--data-path <path>]

Clones all configured scope repos. Writes data_path to config.json.

Data path priority: --data-path > config data_path > $PWD/data/

{
  "scopes": {
    "my-notes": { "local": "/your/project/data/my-notes" },
    "team1": { "local": "/your/project/data/team1" }
  }
}

npx botrun-msync memory scopes

Lists all scopes with their repo, description, access, and local filesystem path.

{
  "scopes": {
    "my-notes": {
      "repo": "github.com/org/member1-memory",
      "description": "Personal research notes",
      "access": "readwrite",
      "local": "/your/project/data/my-notes"
    },
    "team1": {
      "repo": "github.com/org/team1-memory",
      "description": "Team 1 memory",
      "access": "readonly",
      "local": "/your/project/data/team1"
    }
  }
}

npx botrun-msync memory sync

Commits and pushes all changed memory files back to remote repos.

{
  "synced": ["my-notes"],
  "skipped": ["team1"]
}

JSON Output

All commands output structured JSON, including --help:

npx botrun-msync --help
npx botrun-msync config --help
npx botrun-msync memory --help

Agent Lifecycle

VM starts
  → npx botrun-msync memory init          # clone repos to data/
  → agent reads/writes files     # using native tools (Read, Write, grep)
  → npx botrun-msync memory sync          # push changes
VM destroyed

Development

npm install
npm test

License

MIT