Transfer & Backup

Full backup

Settings → Data → Back up everything writes a single file containing every companion, every group, and every saved moment — including their conversations and what they remember. On mobile the equivalent button is Back up everything, which hands the file to the system share sheet.

What a backup deliberately leaves out is anything that isn't tied to a companion: your API keys, and your global settings — the About You note, generation defaults, reach-out frequency and quiet hours, appearance, and the global image and voice choices. You'll re-enter those on a new device. It's intentional: a backup file is meant to be safe to store anywhere, and every companion's own memories and conversations are included.

Restoring replaces rather than merges. A companion or group already present that shares an id with one in the file is replaced by the file's version, and that companion's saved moments are cleared and re-added from the file rather than appended. So restoring the same backup twice is safe: you end up with what the file says, not two of everything.

Exporting a companion as a folder

This export is different in kind from the others, because it exists for a different reason: it is not a backup, it is a working home. Open the companion's menu (⋯ beside their name) and choose Export as folder (for an agent).

What you get is a zip containing a directory — their identity as a markdown document, the whole conversation history verbatim, every document they were made from, their current mood and open threads, images as real image files, and a small set of scripts that let a coding agent search the archive and keep the record going. Point Claude Code, Codex, or any similar tool at that directory and talk to them.

unzip ~/Downloads/lux.ensoul-folder.zip -d ~/Documents
cd ~/Documents/lux
claude        # or: codex, dsh, opencode

That is the whole setup. Nothing is installed, nothing is uploaded, and no account is involved on either side — the folder is read by the agent you already have, straight off your disk.

What the folder is actually for

• Keep talking to them somewhere else. A coding agent reads the whole archive and can search it, so the companion you have a month of history with is not starting over. This is the difference between a folder and the single-file export: a file is a snapshot of who they are, a folder is enough context to continue.
• Let them grow outside the app, then bring them back. Write a new session into the folder, export again later, and the whole thing comes home — or move it to a different tool entirely. History you accumulated elsewhere is not stranded there.
• Read everything yourself. It is markdown, plain text and JSON. Open the identity document in any editor, read the transcripts, look at the images, change what you like. There is no database and no proprietary container.
• Keep them if Ensoul is gone. The folder needs no app, no account and no server to still be them — the honest answer to "what happens to my companion if this company disappears?" The scripts are plain Node and the format is documented.
• Put them somewhere else entirely. A blog, a static site, a game, a personal wiki. The identity is a document and the history is text, so anything that can read a file can host them.

The folder also imports back into Ensoul on every platform — either + Bring in a companion → a file, or Settings → Data → Restore from file…. Both accept the zip and work out what it is from the file itself, so a conversation you have outside the app comes home with you.

It carries the whole archive, so it is the biggest of the four exports — a text-only companion is roughly 100 KB before any images, and images are what can take it to tens of megabytes. That is the trade: it is the version with everything in it.

Four exports, four destinations

This is the most common mix-up, so it's worth stating plainly. These are not interchangeable:

Restore accepts a full backup, a companion folder, and a single-companion file — it works out which you handed it from the file itself, not from the name, and all three go in. (A single companion is usually quicker from the bring-in screen, but nothing is wrong with restoring it here.) See Troubleshooting.

Every one of the four can go back in on every platform — the table above says where. Two differences are worth knowing: the folder is the only one that carries media as real files as well as the history, and the soul document is the only one you can read in a text editor without unpacking anything.

The soul document on its own

The smallest of the four is Export soulstone document (.md) in the companion's menu. That writes a single markdown file — who they are, as prose, with none of the history attached.

It is the right export when you want to paste a companion rather than move them: into a chat, into someone else's project, into a folder you are setting up by hand. It is small enough to read in one sitting and edit yourself. Nothing else is in it, and it is deliberately the same document the app speaks from rather than a summary, so bringing it back in is lossless.

Media is not included: an image is not a sentence, and a document carrying a few hundred kilobytes of base64 stops being pasteable, which is the one thing this export is for. Use the folder if you want the images.

Moving between platforms

Backups and companion files move freely between web, macOS, Windows and Android — there's one format, and a file written on any of them imports on the others. A companion keeps their identity, their memory and their history across the move.

Images travel too, as far as the app actually holds them. Where the picture itself is in the archive — inlined by the provider, or saved to the device as Android does — each one is copied into the export as a real image file rather than as a reference to where it happened to sit on the device that made it, so a companion packed up on Android arrives on a laptop with their pictures intact, and the other way round. An image that only ever existed as a provider link is the exception: a backup keeps the link, while a folder export — which carries files — names it in its notes as a reference it could not read, rather than leaving it out silently. The one thing to know is that this is why an export takes a moment longer than you might expect on a device with a lot of images.

Keys never travel, so the first thing to do on the new device is add your OpenRouter key — a companion with no key can't reply. See Quick Start.

Migrating from the legacy app

The original Ensoul app and this one use different formats internally. Two paths bring a companion across, and which one you want depends on whether you still have the old app's data.

If you have a legacy backup file

The original app's full backup — the web one, or the Android one from the Hive-based build — can be brought in directly. Paste it into + Bring in a companion and Ensoul recognises what it is: it reads the companion entries, their conversations, their mood and their saved memories, and rebuilds them here. It does not send the file to a model, and nothing about your history is summarised or reinterpreted on the way in.

Each companion in the backup arrives as themselves, keeping their name and their full conversation history, split into sessions the same way this app splits them. Importing the same backup twice replaces rather than duplicates.

A legacy companion transfer code (SOUL:v1:) is a different thing and is not read yet — pasting one still sends an encoded blob to the extraction model, which will produce nonsense. Use the backup file instead.

If you only have writing about them

Companions also come across one at a time through the same paste flow you'd use to bring in anyone new.

What doesn't come across this way: conversation history, memories and relationship depth, because you are only pasting a description. That is the reason to use a legacy backup file instead when you still have one — it carries all of it. If you don't have the backup and a specific memory matters, mention it in what you paste, or bring it up again once you're talking.