npm package: @membox-cloud/membox
Description: Zero-knowledge encrypted memory sync for [OpenClaw](https://openclaw.ai).
Latest version: 0.1.48

# @membox-cloud/membox

Zero-knowledge encrypted memory sync for [OpenClaw](https://openclaw.ai).

Keep your local Markdown memory (`MEMORY.md`, `memory/YYYY-MM-DD.md`) as the source of truth, with an encrypted cloud backup for sync, recovery, and multi-device support.

## Install

```bash
openclaw plugins install @membox-cloud/membox
```

Optional skill install from ClawHub:

```bash
clawhub install membox-cloud-sync
```

## Prerequisites

- OpenClaw >= 2026.2.14
- A [membox.cloud](https://membox.cloud) account (GitHub, Google, or email login)

## Agent UX Boundary

When an agent is helping a user inside a live OpenClaw conversation, treat first-time Membox install as a two-phase flow:

1. If the current runtime does not yet expose `membox_*` tools, install the plugin and optional skill, explain that a Gateway restart or fresh session is required, then stop at that boundary.
2. Start a fresh OpenClaw session after the restart so the new tools are actually loaded.
3. Only after the current runtime can already call `membox_setup_start` should the agent send the browser authorization link.

Do not promise or fabricate a device-authorization link before the current runtime has loaded the Membox tools. Before the restart happens, send a clear handoff message that the runtime is about to reload, the current conversation may stop at that boundary, and after reconnect the user only needs a short follow-up such as "continue" or "now what". If `membox_*` tools are already visible, skip restart and go directly to `membox_setup_start`. In the fresh session after restart, the user should not need an exact phrase such as "continue Membox setup"; short follow-up cues like "continue", "now what", or "that previous setup" should be enough for the agent to resume pending Membox state. Once the fresh runtime can see `membox_*` tools, do not ask whether install succeeded; acknowledge the handoff and continue setup.

## Quick Start

### 1. Setup

```bash
openclaw membox setup
```

This will:
- Start device authorization via `membox.cloud`
- Prompt for a vault passphrase (never sent to server)
- Create a new account master key for first-device setup, or request trusted-device approval for an existing vault
- Generate recovery materials on first-device setup
- Run initial upload or pull depending on whether the vault already exists

**Save the recovery code** displayed at the end. Without it and your passphrase, encrypted data cannot be recovered.

### 2. Sync

```bash
openclaw membox sync
```

Upload local changes to the encrypted cloud replica.

### 3. Pull

```bash
openclaw membox pull
openclaw membox pull --preview
```

Download remote changes. Use `--preview` to inspect before applying.

### 4. Status

```bash
openclaw membox status
```

Show vault state, sync cursor, and device info.

### 5. Restore

```bash
openclaw membox restore
```

Restore access on a new device with your recovery bundle and recovery code.

### 6. Trusted-device approval

On an existing unlocked device:

```bash
openclaw membox grants approve-pending
```

Approve pending new-device requests and transfer the encrypted account master key.

## CLI Commands

| Command | Description |
|---------|-------------|
| `membox setup` | Initial setup and device authorization |
| `membox unlock` | Unlock vault for the current session |
| `membox restore` | Restore vault access from the recovery bundle |
| `membox logout` | Clear the current local binding before switching accounts |
| `membox sync` | Upload local changes to cloud |
| `membox pull` | Download remote changes |
| `membox status` | Show vault status |
| `membox grants approve-pending` | Approve pending trusted-device requests |
| `membox pause` | Pause automatic sync |
| `membox resume` | Resume automatic sync |

## Agent Tools

The plugin also registers LLM-callable tools:

- `membox_status` - Check vault status
- `membox_sync` - Trigger sync
- `membox_setup_start` - Begin setup flow
- `membox_setup_poll` - Poll pending browser authorization
- `membox_setup_finish` - Finish setup from local passphrase and recovery-code files
- `membox_unlock` - Unlock the vault from a local passphrase file
- `membox_unlock_secret_enable` - Explicitly opt this machine into managed local auto-unlock
- `membox_unlock_secret_disable` - Disable the managed local auto-unlock secret
- `membox_grants_approve_pending` - Approve trusted-device requests
- `membox_pull` - Preview or apply remote changes
- `membox_restore` - Restore with local recovery-code and passphrase files
- `membox_logout` - Clear the current local binding before switching accounts

Security note:

- Secret-bearing tools read from local files so the model does not need the vault passphrase or recovery code inline.
- First-device tool-only setup should always provide a local `recovery_code_output_file` so the recovery code never needs to travel through the model.
- Setup and restore now persist device secrets in a local passphrase-encrypted bundle, so published npm installs do not depend on native `keytar`.
- Managed unlock is explicit opt-in. When enabled, the passphrase is kept only on the local machine, using the platform keychain when available or a private local fallback file when it is not.
- On Unix-like systems, passphrase and recovery-code files should be private, for example `chmod 600 /path/to/file`.
- Agent-driven setup should send `verification_uri_complete` only after the current runtime already has the Membox tools loaded. If install just happened, continue in a fresh session after restart instead of trying to keep the same reply alive.
- When an agent updates local memory content, it should report the local file-write result first and the cloud sync result second. If sync is blocked, say the local write already succeeded before describing the unlock or auth follow-up.

## Configuration

In your OpenClaw plugin config:

```json
{
  "serverUrl": "https://membox.cloud"
}
```

The default server is `https://membox.cloud`. Override with `serverUrl` for self-hosted deployments.

## Account Switching

If you want this machine to sign into a different Membox account, run:

```bash
openclaw membox logout
```

That clears the local Membox binding on this machine and tries to revoke the current remote device too. It does not delete local `MEMORY.md` / `memory/` files, and it does not clear the OpenClaw browser's login cookies. If you want a different GitHub, Google, or Membox identity on the next setup, sign out in that browser first or use an incognito window before authorizing again.

## Local Development

Run the following commands from the repository root:

```bash
source ./scripts/dev-env.sh
pnpm --filter @membox-cloud/membox build
openclaw plugins install -l ./apps/openclaw-plugin
openclaw plugins doctor
```

The plugin's `serverUrl` is environment-driven in local development. Source `scripts/dev-env.sh` in every terminal where you run `openclaw membox ...`, or it will fall back to the default production URL.

For local verification, all plugin debug logs can be redirected into the repository `./logs/` directory by exporting `MEMBOX_LOG_FILE` before starting OpenClaw.

For end-to-end diagnostics across plugin + API:

```bash
export MEMBOX_LOG_FILE="$PWD/logs/plugin-debug.log"
export MEMBOX_SERVER_LOG_FILE="$PWD/logs/api-debug.log"
```

When a repro is complete, collect a safe debug bundle with:

```bash
bash scripts/collect-membox-debug.sh
```

The bundle includes safe state snapshots, plugin/API logs, and OpenClaw command output. It intentionally excludes raw refresh tokens, device private keys, and vault secret bundles.

For a full manual validation flow, see `./MANUAL-DUAL-DEVICE-CHECKLIST.md`.

For an agent-first install + pairing flow, see `./AGENT-WORKFLOW.md` and run `bash scripts/install-membox-agent-stack.sh` from the repository root.

For release, production rollout, and final human-owned checks, see `./RELEASE-CHECKLIST.md`.

## Security Model

- **Zero-knowledge**: encryption/decryption happens locally. The server never sees plaintext.
- **Key hierarchy**: `passphrase -> URK -> AMK -> DEK`
  - URK (User Root Key): derived from passphrase via Argon2id
  - AMK (Account Master Key): random, wrapped by URK
  - DEK (Data Encryption Key): per-object, wrapped by AMK
- **Recovery**: recovery code + passphrase can restore AMK on a new device
- **Device approval**: existing devices can grant key material to new devices via Ed25519-signed encrypted grants

## Known Limitations

- Requires a reachable Membox API endpoint
- No selective file sync (all memory files are included)
- Conflict resolution strategies: `local-wins`, `remote-wins`, `conflict-copy`
- Auto-sync interval is not yet configurable

## License

Private - see repository for details.