@membox-cloud/membox

Zero-knowledge encrypted memory sync for OpenClaw.

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

openclaw plugins install @membox-cloud/membox

Optional skill install from ClawHub:

clawhub install membox-cloud-sync

Prerequisites

• OpenClaw >= 2026.2.14
• A 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. 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.

Quick Start

1. Setup

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

openclaw membox sync

Upload local changes to the encrypted cloud replica.

3. Pull

openclaw membox pull
openclaw membox pull --preview

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

4. Status

openclaw membox status

Show vault state, sync cursor, and device info.

5. Restore

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:

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 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

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.

Configuration

In your OpenClaw plugin config:

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

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

Local Development

Run the following commands from the repository root:

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:

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 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.