Migration from local PLUR

Two common migration scenarios:

1. You have local engrams in ~/.plur/ and want to publish a subset to your team’s Enterprise instance.
2. The team has been collecting engrams individually and wants to consolidate into a shared scope.

Both follow the same pattern: export → review → import.

1. Connect your local PLUR to Enterprise

First, register the Enterprise server as a remote store from your local CLI:

plur stores add \
  --name acme \
  --url https://plur.your-org.com \
  --token plur_sk_...

The token is an API key issued from /me/api-keys on the Enterprise server. After this, your local PLUR can read from and write to scopes you have access to on acme.

2. Decide what to migrate

Not every local engram belongs in a shared scope. The principle: migrate what generalises, keep what’s personal.

Good migration candidates:

• “How we deploy” — applicable across the team.
• “Naming conventions in this codebase” — applicable across the team.
• Architecture decisions for projects others touch.

Bad migration candidates:

• “I prefer Vim over Emacs” — personal, belongs in user:.
• “Always summarise terse” — your communication preference.
• One-off corrections to your own habits.

List candidates with:

plur list --scope global --status active --json | jq '.[] | {id, statement, domain}'

Mark the ones to migrate (mentally or in a scratchpad).

3. Export as a pack

Bundle the engrams into a Knowledge Pack — this is the migration unit:

plur packs export \
  --scope global \
  --ids ENG-...,ENG-...,ENG-... \
  --out ./team-migration-2026-05-25 \
  --version 1.0.0 \
  --target-scope group:acme/platform

The --target-scope is the scope they’ll land under once imported. For platform team conventions, that’s typically group:acme/platform.

Review the pack:

plur packs preview ./team-migration-2026-05-25

You’ll see the engrams that will move, with their statements, types, and target scope. Adjust the source set and re-export until it looks right.

4. Import into Enterprise

plur packs install ./team-migration-2026-05-25 --store acme

Engrams land at group:acme/platform (the target scope from the pack manifest). The Enterprise server’s permission check ensures you have write rights to that scope; if you don’t, the install rejects with 403.

Conflicts (same id already present on the server) are flagged for review — install never silently overwrites.

5. Verify

From any team member’s machine with the same acme store registered:

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

The migrated engrams should appear. Recall on the team member’s local PLUR is fully local for global and project:* scopes; for group:acme/* it hits the Enterprise server.

Choosing the right scope

Original local scope	Likely target
global (rules you applied everywhere)	group:org/team or org:acme if widely shared
project:myapp	project:myapp mirrored on Enterprise (if the project is shared) or leave local
user:gregor	Don’t migrate — personal scope stays local.

If you’re not sure, default to a narrower scope (group: over org:). Widening later is easy; narrowing after the fact is hard because people have already learned to rely on the broader scope.

Reverse migration

If you want to pull team engrams into your local PLUR (for offline work, for instance):

plur packs export --scope group:acme/platform --out ./team-snapshot --version snapshot --store acme
plur packs install ./team-snapshot

This installs the team’s engrams into your local store under group:acme/platform — your local PLUR will use them in recall even without network. Periodic re-export keeps the local copy fresh.

What you don’t migrate

• Episodes — these are timeline records, not portable knowledge. They stay local. Episode export is a separate feature, used mostly for incident retrospectives.
• Activation history — packs carry the engram, not its access history. Activation re-accumulates from real use on the new server.
• Pinning — Enterprise admins decide what to pin. Pinning is a server-side flag, not part of the engram body.

Rolling back

A pack install is auditable and reversible:

plur packs uninstall team-migration-2026-05-25 --store acme

This retires the engrams that came from the pack (history preserved). If the migration turns out to be wrong, you can roll back and re-export with corrections.