| name | passport-bootstrap |
| description | Use when the user installs mnemo-mcp on a fresh machine and wants to restore prior memory state from S3 or Google Drive (Phase 2 passport sync). Triggers on phrases like "set up mnemo on this machine", "restore my memory passport", "import passport", "bootstrap mnemo", or when the user says they got a new laptop / VM and wants their memories back. |
| argument-hint | [backend: s3 | gdrive] |
Passport Bootstrap
Restore an encrypted memory passport from a configured backend so a
fresh mnemo-mcp install picks up the user's full memory history.
When to Use
Trigger on explicit signals:
- "set up mnemo on this machine"
- "restore my passport" / "import my memory passport"
- "bootstrap mnemo on this laptop / VM"
- New-machine context: "I just installed mnemo on a new device"
- Recovery context: "I lost my memories, can you restore from S3?"
Do NOT trigger when the user is on an already-configured machine
(check config(action="status") first - if total_memories > 0,
ask before importing because import LWW-merges and may NOT overwrite
local rows newer than the bundle).
Workflow
Step 1: Detect configured backend
Call config(action="status") and inspect the response. The default
backend is the first entry of SYNC_BACKEND env (defaults to
gdrive). If both s3 and gdrive are configured, ask the user
which one to import from. If neither is configured, stop and tell the
user they need to run the relay form first
(config(action="setup_start") in HTTP mode, or set
SYNC_S3_BUCKET + GOOGLE_DRIVE_CLIENT_ID env vars in stdio mode).
Step 2: Confirm passphrase
The bundle is AES-256-GCM-encrypted with an Argon2id-derived key from
the user's passphrase. The MCP server needs the RAW passphrase to
decrypt - the Argon2id hash stored in config.enc is verification-
only.
In stdio mode: instruct the user to set SYNC_PASSPHRASE env var
before running mnemo-mcp (or to relaunch with the env exported).
In HTTP mode: prompt the user to submit the relay form's passphrase
field again (the raw value is held in process memory only and is
cleared on restart - it is NEVER persisted).
Step 3: Import the bundle
Call config(action="import_passport", key="<backend>") where
<backend> is s3 or gdrive. The server pulls the latest bundle
from the chosen backend, decrypts with the supplied passphrase, and
applies each row via last-write-wins per row (local rows newer than
the bundle row are preserved + an audit row is written to
sync_overrides).
Step 4: Verify
After the response lands, call config(action="status") again and
confirm total_memories matches expectations. If the response from
step 3 reports inserted > 0 but total_memories did not move,
something else is wrong (caller should escalate, not silently
proceed).
Failure Modes
- "SYNC_PASSPHRASE not set" -> Step 2 was skipped. Re-prompt for
the passphrase, do NOT pick a default value.
- "Passphrase mismatch or tampered bundle" -> wrong passphrase,
OR the bundle was modified at rest. Generic message by design (no
passphrase oracle). Tell the user to double-check the passphrase;
if confirmed correct, the bundle may need re-upload from a clean
source.
- "no_passport" -> the backend bucket / folder is empty. Either
the user has never run
config(action="sync_now") from another
machine, or the bucket name in the relay form was wrong. Ask them
to verify on the source machine.
KeyError on backend name -> backend isn't registered. Means
SYNC_S3_BUCKET is empty (for s3) or the gdrive token is missing.
Run the relay form to populate.
Anti-Patterns
- Do NOT call
config(action="sync_now") before import - that would
push the empty local DB on top of the remote, deleting other
machines' state.
- Do NOT call
memory(action="import", data=...) - that imports
Phase 1 JSONL files, NOT Phase 2 encrypted passport bundles.
- Do NOT proceed silently when the user supplied no passphrase.
Importing yields cryptic "Passphrase mismatch" errors instead of
the cleaner "passphrase missing" pre-flight check.
