Share knowledge across tenants with Packs

The shape of the problem

You run one product over many tenants. Every tenant needs the same base of knowledge, your platform's runbooks, taxonomies and instincts, defined once. Every tenant also needs a private layer of its own: its own data, under its own encryption key, with its own memory policy. A single shared brain cannot do this, because the key and the policy are properties of the whole brain, not of a scope. Give each tenant its own brain and you get the private layer but lose the shared top, and re-seeding the base into thousands of brains by hand is a non-starter.

The pattern: keep the base in its own brain and publish it as a plaintext Pack. Give each tenant its own brain with its own key and policy, and mount the Pack underneath in reference mode. The base is stored once and read live by every tenant; each tenant's private writes stay sealed in its own brain. Update the base once and every tenant sees the new version. This is the scale case, the one Sentryx is built on: a small non-secret base under thousands of encrypted tenants.

        base brain (plaintext, non-secret)
                    |
              POST .../publish
                    v
            Pack  platform-runbooks  v2     <-- stored ONCE
              /         |          \
   reference mount  reference     reference
        |              |              |
   brn_acme        brn_globex     brn_initech     <-- each its own DEK + policy
   /shared (RO base)  /shared       /shared
   /acme   (private)  /globex       /initech

Step 1 — Publish the base brain as a plaintext Pack

Put your shared knowledge in a dedicated base brain (brn_base below) and curate it like any other: write reference docs and policies at its scopes, let it learn if you want. The base is not secret, it is the same for every tenant, so publish it with encryption_at_publish: "none". A reference mount requires a plaintext Pack.

curl https://api.fightclub.pro/v1/brains/brn_base/publish \
  -H "Authorization: Bearer $RINGSIDE_KEY" \
  -d '{ "name": "platform-runbooks", "slug": "platform-runbooks",
        "encryption_at_publish": "none", "notes": "initial base" }'

Note the pack_id. If the snapshot is large (over 1,000 entries) the call returns status: "building"; poll GET /v1/packs/{packId} until the version reads ready before any tenant mounts it.

Step 2 — Provision a tenant brain and mount the Pack

For each tenant, create a brain with its own encryption and its own memory policy, then mount the base Pack in reference mode. Set the shared taxonomy as the tenant brain's memory_policy at creation so its own learning is shaped the same way the base is. Embedding model and dimensions must match the Pack, so create the tenant brain with the same embedding_model you published the base with, or the mount is rejected with 422 embedding_model_mismatch.

curl https://api.fightclub.pro/v1/brains \
  -H "Authorization: Bearer $RINGSIDE_KEY" \
  -d '{ "name": "Acme tenant brain",
        "encryption": "standard",
        "embedding_model": "openai/text-embedding-3-small",
        "memory_policy": {
          "type_taxonomy": [
            { "type": "procedure", "tier": "A", "weight": 1.4 },
            { "type": "gotcha",    "tier": "A", "weight": 1.3 },
            { "type": "fact",      "tier": "B", "weight": 1.0 }
          ],
          "learn_mode": "autonomous"
        } }'
# -> { "id": "brn_acme...", "object": "brain", "encryption": "standard", ... }

The scope_map rebases the whole Pack under /shared, leaving the tenant's own scopes (/acme, /acme/q3, ...) free for private writes. A reference mount is status: "ready" immediately, so the very next recall composes both layers. Repeat this step per tenant: each call is one brain plus one mount, and nothing about the base is copied.

Step 3 — Write and recall

Write the tenant's private memory to its own scopes as usual: every PUT /entries and every observe lands in the brain's native layer, never in the Pack. Recall composes the two in one ranked pass with no extra parameters. Pass explain: true to see which store each hit came from.

# private write to the tenant's own scope
curl -X PUT https://api.fightclub.pro/v1/brains/brn_acme/entries \
  -H "Authorization: Bearer $RINGSIDE_KEY" \
  -d '{ "scope": "/acme", "class": "memory", "type": "gotcha",
        "title": "Acme CDN", "body": "Acme rollback must flush the CDN cache first." }'

# recall sees the tenant's private memory AND the shared base, ranked together
curl https://api.fightclub.pro/v1/brains/brn_acme/recall \
  -H "Authorization: Bearer $RINGSIDE_KEY" \
  -d '{ "scope": "/acme", "query": "how do we roll back a failed deploy",
        "explain": true }'

The tenant's site-specific gotcha shadows or outranks the generic base procedure when they share scope and entity, so an agent acting on the recall gets the override before the default. The base is evergreen-scored (no recency or usage decay) under its own frozen tiers, while the tenant's memory ages and reinforces normally.

Step 4 — Update the base once, for everyone

When the shared knowledge changes, edit the base brain and publish again. Each publish mints a new immutable version.

curl https://api.fightclub.pro/v1/brains/brn_base/publish \
  -H "Authorization: Bearer $RINGSIDE_KEY" \
  -d '{ "notes": "Q3 runbook refresh" }'
# -> { "pack_id": "pack_7f3a2c...", "version": 2, "status": "ready", ... }

Mounts are pinned by default, so a tenant keeps reading the exact version it was mounted against until you move it. You have two ways to roll tenants forward:

• ·Set follow_latest: true on a mount and a new publish re-points it instantly to the new version, with no per-tenant rewrite. Good for tenants you want always on the current base.
• ·Or leave mounts pinned and move them deliberately with PATCH /v1/brains/{id}/mounts/{mountId} and { "version": 2 }. Good when you want to validate a new base on a few tenants before the fleet.

# opt a tenant into auto-updates
curl -X PATCH https://api.fightclub.pro/v1/brains/brn_acme/mounts/mnt_44c1 \
  -H "Authorization: Bearer $RINGSIDE_KEY" \
  -d '{ "follow_latest": true }'

# or move a pinned tenant to v2 on your schedule
curl -X PATCH https://api.fightclub.pro/v1/brains/brn_globex/mounts/mnt_77ab \
  -H "Authorization: Bearer $RINGSIDE_KEY" \
  -d '{ "version": 2 }'

Either way the base is rewritten exactly once, as one Pack version. For a reference mount the re-point is a metadata change, so even a fleet of thousands costs one publish plus cheap re-points, never a per-tenant re-seed.

Reseller and multi-level layering

A reseller sits between the platform and its own clients: platform knowledge at the bottom, the reseller's own shared layer in the middle, each client's private memory on top. Which design you use turns on one question, and getting it wrong is where people assume a three-level chain works when it does not. The question: do the reseller's clients need their own encryption key or their own memory policy?

Clients as scopes (the common case, supported today)

If the reseller's clients can share the reseller's key and policy, you do not need a brain per client. Give the reseller one brain, mount the platform Pack under it once, and use scopes for its clients: platform knowledge at the mounted base, reseller-wide knowledge at the reseller root, per-client memory under sub-scopes. Scope inheritance gives the shared top within one brain; the Pack mount adds the platform layer beneath all of it. This is still only two layers (the platform Pack plus the one reseller brain), so it composes today.

# one reseller brain, platform Pack mounted under /platform
curl https://api.fightclub.pro/v1/brains/brn_reseller/mounts \
  -H "Authorization: Bearer $RINGSIDE_KEY" \
  -d '{ "pack_id": "pack_7f3a2c", "mode": "reference",
        "scope_map": { "/": "/platform" } }'

# reseller-wide note at the root; per-client memory under sub-scopes
curl -X PUT https://api.fightclub.pro/v1/brains/brn_reseller/entries \
  -H "Authorization: Bearer $RINGSIDE_KEY" \
  -d '{ "scope": "/", "class": "policy", "title": "House style",
        "body": "All client comms go out in the reseller brand voice." }'

# recall for one client sees: client scope + reseller root + platform base
curl https://api.fightclub.pro/v1/brains/brn_reseller/recall \
  -H "Authorization: Bearer $RINGSIDE_KEY" \
  -d '{ "scope": "/clients/dunder", "query": "deploy rollback policy" }'

Clients as their own brains: a known v1 limit

When a client genuinely needs its own DEK or its own memory_policy, it must be its own brain, not a scope. That client now needs three layers composed at recall: the platform base, the reseller's shared layer, and its own private memory. That is two distinct shared layers under one brain, and v1 cannot stack two live shared layers. Two rules combine to prevent it. Publish snapshots only the publishing brain's own native rows, never the bases it itself mounts, so a reseller cannot reference-mount the platform Pack, add its layer, and republish the union (the new Pack would contain only the reseller's own rows). And a brain may hold at most one reference mount, so a client cannot reference-mount the platform Pack and a reseller Pack at the same time. Mounting only the platform Pack from the client brain gives platform plus the client's own memory but loses the reseller's shared layer, which is the trap.

The encryption split

The whole pattern rests on putting encryption where it earns its keep: on the private layer, not the shared base.

The base is plaintext and non-secret

It is your runbooks and instincts, identical for every tenant, published with encryption_at_publish=none so it can be read live by reference mounts. Sealing it under each tenant's key would buy zero security and cost one full copy per tenant.

The private layer is sealed per tenant

Each tenant brain has its own DEK and its own memory_policy. Its server topology, procedures and gotchas live here, sealed under its own key, untouched by the shared base.

Real secrets live in a secret store

Raw credentials, keys and tokens never belong in a brain or a Pack at all. Publish refuses content that matches a secret pattern (422 secret_detected). Keep secrets in a real secret store and reference them from your application, not from memory.

Recap

1. 01Curate a non-secret base brain and publish it as a plaintext Pack (encryption_at_publish: "none").
2. 02Per tenant: create a brain with its own encryption, matching embedding model, and the shared taxonomy as its memory_policy.
3. 03Mount the Pack in reference mode with a scope_map that tucks the base under /shared (or /platform).
4. 04Write private memory to the tenant's own scopes; recall composes both layers automatically.
5. 05Update the base by re-publishing; roll tenants forward with follow_latest or a deliberate PATCH.