KeiSeiKit-1.0/docs/USB-BRAIN-GUIDE.md

USB Exobrain — Step-by-Step Test Recipe

Put a KeiSeiKit "brain" on a portable USB drive, mount it into Claude Code (and Cursor / Continue / Zed if installed), verify MCP tools, unplug — verify clean detach.

This top-level document holds prerequisites, the shared filesystem warning, the TOC, and platform-agnostic troubleshooting. Step-by-step walkthroughs live in the three platform sub-documents.

Platform walkthroughs

• macOS walkthrough — /Volumes/<LABEL>, APFS recommended, Gatekeeper / xattr handling.
• Linux walkthrough — /media/$USER/<LABEL>, ext4 recommended, umount / optional systemd-udev auto-attach.
• Windows walkthrough — drive letter, NTFS recommended, Dismount-Volume / PowerShell.

---

0. Prerequisites (all platforms)

On the host:

• KeiSeiKit installed: ./install.sh --profile=full ran successfully, cargo test -p keisei shows 32/32 pass (v0.22).
• keisei CLI on PATH: ls ~/.claude/agents/_primitives/_rust/target/release/keisei returns the binary. Symlink into ~/.local/bin/ or %USERPROFILE%\bin as convenient.
• At least one supported client installed (Claude Code / Cursor / Continue / Zed) — keisei auto-detects all four.
• A USB stick or flash card physically attached and mounted by the OS.

On the USB drive:

• Free space: ~500 MB recommended (5 mcp-server binaries × ~90 MB each + room for memory/artifacts SQLite).
• Filesystem — see the warning below.

---

⚠️ Filesystem warning — exFAT / FAT32 are NOT safe for multi-client attach

SQLite WAL mode (used by kei-memory, kei-artifact, kei-social-store inside a brain) requires a filesystem with reliable shared-memory mmap. exFAT and FAT32 do NOT provide this, and keisei mount (multi-client fan-out) WILL corrupt the memory DBs if the brain lives on one of those filesystems.

Since v0.22 keisei itself prints an advisory on stderr when it detects an exFAT / FAT32 root at load time (via statfs(2) on macOS + Linux; Windows returns Unknown pending GetVolumeInformationW). The warning is non-blocking — single-client keisei attach on exFAT is still a supported path.

• On exFAT / FAT32: use the brain with ONE client at a time (keisei attach --scope=user). Do NOT run keisei mount.
• For reliable multi-client use, format the stick as APFS (macOS), ext4 (Linux), or NTFS (Windows). exFAT is fine for single-client or read-only cross-platform transport.
• If you already ran keisei mount on an exFAT brain and see SQLite errors, see "SQLite corruption on mount-attach" in Troubleshooting below.

---

Brain safety invariants (all platforms)

The following load-time checks fire regardless of OS. They prevent the most common misuse and attack patterns:

• Name regex — brain.name must match ^[a-z][a-z0-9_-]{0,63}$ (lowercase letter start, 1-64 chars, word chars + hyphen).
• Relative paths — every [paths.*] entry must be relative; no absolute paths, no .. components. Canonical form must live under the brain root.
• Symlink reject — the brain root itself cannot be a symlink. Pass the resolved path; this closes a USB→host pivot surface.
• Manifest size cap — manifest.toml is bounded at 64 KiB.
• Schema — schema_version ∈ {1, 2}. v1 uses single-string mcp_server; v2 uses per-platform map.

---

Platform-agnostic troubleshooting

"BrainNotFound" on attach

• Check <BRAIN>/manifest.toml exists.
• Pass an absolute path to keisei attach, not a relative one.

"PathEscape" on attach

• Every [paths.*] entry must be relative and resolve inside the brain root. No ../, no absolute paths.

"BrainIsSymlink" on attach

• The brain root is a symlink. Pass the resolved path instead — keisei refuses symlink roots to prevent accidental host-dir pivot via a crafted USB.

"NoPlatformBinary" on first use

• Your platform's binary isn't in bin/. Check std::env::consts::{OS, ARCH} on your host — the expected filename is kei-mcp-server-<os-renamed>-<arch-renamed> where macos→darwin, x86_64→x64, aarch64→arm64.

"NameConflict" on attach

• An MCP server with the same name already exists in the client's config. Either rename your brain (name in manifest.toml) or remove the existing entry manually.

SQLite corruption on mount-attach

• kei-memory / kei-artifact / kei-social-store databases show "disk image is malformed" or "database is locked" after keisei mount on a USB drive.
• Root cause: the brain lives on exFAT or FAT32, which don't reliably support SQLite WAL shared-memory mmap. Multi-client attach corrupts the DB.
• Fix:
  1. Copy the brain dir to an APFS (macOS) / ext4 (Linux) / NTFS (Windows) volume.
  2. Re-attach via keisei attach <new-path> or keisei mount <new-path>.
  3. For single-client use on the same exFAT drive, restrict to keisei attach --scope=user. Do NOT use keisei mount.

Filesystem-warning advisory not appearing

• keisei prints the exFAT/FAT32 warning to stderr (not stdout). Shells that redirect stderr away will hide it.
• Windows detect_fs_warning returns Unknown in v0.22 — format as NTFS manually.

---

What this tests end-to-end

1. Portable brain — works from a USB drive, no installer needed on the brain itself.
2. Per-platform dispatch — schema v2 picks the right binary for the host OS+arch.
3. Multi-client fan-out — keisei mount attaches to every detected client in one call.
4. Clean detach — zero residue in host configs, preserves unrelated MCP servers.
5. Safety gates — path confinement, name regex, symlink rejection, manifest size bound, filesystem-type advisory (v0.22).
6. Schema v1 compat — an older v1 brain with a single-string mcp_server still works.

If the walkthrough for your platform passes end-to-end, the v0.22 exobrain is production-ready for single-user workflows on that platform.

For shared-brain scenarios (team members all mounting the same brain over git / S3) see the kei-store backend docs — keisei attach s3://my-bucket/brain/ requires --features s3 at install.