Team vault sync (R2 / S3 / GCS)

Share ~/.ClawQL memory notes across your team via a centralized object-storage bucket. Cloudflare R2 is the default provider because Cloudflare is in the bundled default stack.

Team overview (Helm deploy, observability, verification): getting-started-for-teams.md.

What syncs

Quick start (R2)

1. Create an R2 bucket in Cloudflare (e.g. acme-clawql-team).
2. Create R2 S3 API credentials (Manage R2 API tokens → Create API token with Object Read & Write).
3. Configure sync:

clawql sync init --interactive
# provider: r2 (default)
# bucket: acme-clawql-team
# prefix: teams/engineering/

export CLAWQL_R2_ACCOUNT_ID="<cloudflare-account-id>"
export CLAWQL_SYNC_ACCESS_KEY_ID="<r2-access-key>"
export CLAWQL_SYNC_SECRET_ACCESS_KEY="<r2-secret>"

Or store credentials in the local vault (loaded at MCP/CLI startup):

clawql secrets set r2AccessKeyId
clawql secrets set r2SecretAccessKey
clawql secrets set cloudflareAccountId

4. Push your notes:

clawql sync push

5. Teammates pull:

clawql sync init --bucket acme-clawql-team --prefix teams/engineering/
clawql sync pull
clawql doctor

Quick start (S3)

1. Create an S3 bucket (e.g. acme-clawql-team) and an IAM user with s3:GetObject, s3:PutObject, s3:ListBucket on that bucket.
2. Configure sync:

clawql sync init --provider s3 --bucket acme-clawql-team --prefix teams/engineering/

export CLAWQL_AWS_ACCESS_KEY_ID="<iam-access-key>"
export CLAWQL_AWS_SECRET_ACCESS_KEY="<iam-secret>"
export CLAWQL_AWS_REGION="us-east-1"   # or CLAWQL_SYNC_REGION

Or store credentials in the local vault:

clawql secrets set awsAccessKeyId
clawql secrets set awsSecretAccessKey

3. Push and pull as with R2 (clawql sync push, clawql sync pull).

Quick start (GCS)

Google Cloud Storage uses the S3-compatible interoperability API (HMAC keys), not the native GCS JSON API — same @aws-sdk/client-s3 client as R2 and S3.

1. Create a GCS bucket (e.g. acme-clawql-team) in your GCP project.
2. Enable interoperability: Cloud Storage → Settings → Interoperability → Create a key for a service account (or user HMAC key).
3. Configure sync:

clawql sync init --provider gcs --bucket acme-clawql-team --prefix teams/engineering/
# interactive: provider accepts gcs or gcp

export CLAWQL_GCS_HMAC_ACCESS_ID="<hmac-access-id>"
export CLAWQL_GCS_HMAC_SECRET="<hmac-secret>"
# endpoint defaults to https://storage.googleapis.com (path-style)

Or store credentials in the local vault:

clawql secrets set gcsHmacAccessId
clawql secrets set gcsHmacSecret

4. Push your notes:

clawql sync push

5. Teammates pull:

clawql sync init --provider gcs --bucket acme-clawql-team --prefix teams/engineering/
clawql sync pull
clawql doctor

Helm: set teamSync.provider: gcs — the chart injects CLAWQL_SYNC_ENDPOINT=https://storage.googleapis.com. Put gcsHmacAccessId and gcsHmacSecret in the provider secret (via envFromSecret).

Commands

Providers

Environment

Config file: ~/.ClawQL/sync.json — safe to commit bucket/prefix in team docs; never put secrets there.

Auto sync (MCP runtime)

When the MCP server runs with sync configured, enable automatic background sync:

Auto sync logs to stderr ([clawql-mcp] team sync auto-push/...). Failures are non-fatal — ingest/recall still succeed.

Local dev example:

export CLAWQL_SYNC_AUTO=1
export CLAWQL_SYNC_AUTO_PULL=1
npx clawql-mcp-http

Helm (charts/clawql-mcp)

Enable team bucket sync for in-cluster MCP pods:

teamSync:
  enabled: true
  provider: r2
  bucket: acme-clawql-team
  prefix: teams/production/
  autoPush: true
  autoPushDebounceMs: 30000
  autoPull: true
  autoPullMinMs: 60000
  autoPullOnStart: true
  r2:
    accountId: '<cloudflare-account-id>' # or cloudflareAccountId in provider secret

Credentials stay in Vault / envFromSecret — add r2AccessKeyId, r2SecretAccessKey, and cloudflareAccountId to secret/clawql/providers (same keys as local vault).

GCS example:

teamSync:
  enabled: true
  provider: gcs
  bucket: acme-clawql-team
  prefix: teams/production/
  autoPush: true
  autoPull: true

Store gcsHmacAccessId and gcsHmacSecret in the provider secret. The chart sets CLAWQL_SYNC_ENDPOINT=https://storage.googleapis.com automatically.

helm upgrade --install clawql ./charts/clawql-mcp \
  --set envFromSecret=clawql-provider-env \
  --set teamSync.enabled=true \
  --set teamSync.provider=gcs \
  --set teamSync.bucket=acme-clawql-team \
  --set teamSync.prefix=teams/production/ \
  --set teamSync.autoPush=true \
  --set teamSync.autoPull=true

Template smoke: make helm-team-sync-template-tests.

After pull

• Run clawql doctor or trigger memory_recall with CLAWQL_MEMORY_DB_SYNC_ON_RECALL=1 to refresh memory.db from new Markdown.
• Conflicts: if two teammates edit the same note, sync status lists conflicts; use sync push --force or sync pull --force deliberately.

Related

• Local provider vault
• Memory / Obsidian
• Cloudflare provider (API execute, not sync)