Migrating local → Enterprise

You’ve been running local PLUR. Your team just stood up Enterprise. This guide walks the move — what to migrate, what to keep local, and how the two coexist.

The mental model

You don’t replace local PLUR with Enterprise. You add Enterprise as a remote store. Your local PLUR keeps working; new shared scopes show up alongside personal ones. Most of your engrams stay local.

~/.plur/           ← still your local store, untouched
  + remote store "acme" → https://plur.your-org.com
    └─ scopes: group:acme/* , org:acme , (and project: scopes the team shares)

A recall in a project with shared scope visible to you returns local engrams and server engrams, ranked together.

Step 1 — connect

Get an API key from your Enterprise server’s /me/api-keys (see Authentication). Then:

plur init-remote --url https://plur.your-org.com --token plur_ent_...

This registers the remote store and discovers the scopes your account can write to (you can also pass --scopes explicitly, or run plur stores discover --register later). From inside an agent session, the MCP tools plur_stores_add and plur_scopes_discover do the same thing.

Verify:

plur stores list

You should see the remote store and the scopes it serves.

Step 2 — decide what to migrate

The principle: migrate what generalises, keep what’s personal.

Local engram	Where it should go
”Always validate input at API boundaries”	`org:acme` or `global` (depending on scope)
“Our deploys go through Caddy”	`group:acme/platform`
”I prefer terse responses”	Stays local in `user:gregor`
”Project X uses old auth lib”	`project:x` (mirror on Enterprise if the project is shared)

Don’t migrate everything in one go. Start with one scope — usually org:acme or group:acme/<your-team> — and 10–20 engrams. See how it lands.

Step 3 — export as a pack

The pack is a convenient review unit — filter by scope, domain, tags, or type:

plur packs export acme-onboarding \
  --scope project:my-app \
  --domain platform \
  --output ./acme-onboarding

Export runs a privacy scan and flags anything that looks like a secret or personal detail before it leaves your store. Review:

plur packs preview ./acme-onboarding

You’ll see the statements and types. Prune until it looks right.

Step 4 — import into Enterprise

Bulk-import the reviewed engrams via the server’s REST API — each engram in the pack’s engrams.yaml becomes a POST /api/v1/engrams with the team scope you’re targeting:

curl -X POST https://plur.your-org.com/api/v1/engrams \
  -H "Authorization: Bearer plur_ent_..." \
  -H "Content-Type: application/json" \
  -d '{"statement": "...", "type": "procedural", "scope": "group:acme/platform"}'

The server checks that you have write access to group:acme/platform; without it you get 403 and need an admin to grant access. For a handful of engrams, it’s often simpler to have your agent re-save them with plur_learn and the target scope — once the remote store is registered, writes to team scopes route to the server automatically.

Step 5 — verify with a teammate

Have someone else on your team — already connected to acme — run:

plur recall "deploy" --scope group:acme/platform

The engrams you just migrated should appear in their results. If they don’t, double-check the scope you wrote them to matches a scope they can read.

After migration

Future engrams

New engrams you want to share with the team go directly to Enterprise — no need to do the local-then-export dance. plur init-remote writes the remote connection into your project’s .plur.yaml; with a team scope set, hooks route corrections to the Enterprise server automatically:

scope:  group:acme/platform
domain: platform
# remote_url / remote_token written by plur init-remote

Local stays local

Your global, project:*, and user:* engrams keep living in ~/.plur/. Sync them across your own machines with plur sync (git remote) as before. The two systems don’t interfere.

Reverse migration

Team scopes live on the server, so reading them needs connectivity. If you want a local snapshot of specific team knowledge for offline work, recall the engrams you need and re-save the essentials into a local scope — or ask an admin for a pack export from the server. There’s no automatic offline mirror today.

Common pitfalls

Migrating too eagerly. Resist the urge to push your whole local store. 90% of personal engrams belong in user: and add noise to a shared scope.
Wrong target scope. Easier to widen later than narrow — start with group: rather than org:.
Forgetting hook config. Without .plur.yaml, new corrections still go to ~/.plur/. Update each project’s .plur.yaml after migration.
Pinning local engrams. pinned: true is per-store — it doesn’t transfer with the content. Re-pin on the server side after migration if an engram must always load.

When to move everything

You don’t. Side-by-side is the supported model: the local store stays the substrate for personal memory and offline work, and Enterprise serves the shared scopes. There is no local-less cutover mode — and you wouldn’t want one, because it would take your personal memory offline with the network.