The companion is the state, not the model.
One design decision runs through the whole system: keep everything that makes a companion them outside the weights, so the model underneath can change without losing the presence on top of it.
This page is how that actually works — what is stored, where it lives, what happens when a model is deprecated, and what really moves when you export.
The product page is /app · the step-by-step manual is /docs · this page is the mechanics and the trust argument
Three tiers, held to three different promises.
A companion is not one file with one guarantee. It is three things that change at different rates, for different reasons — so they are kept, and protected, separately.
One prose document.
Who they are, as a document a person can read — model-independent, and the same text the app speaks from. When it is exported it is soulstone.md, the canonical copy; any JSON beside it is a generated facet of the prose, not the other way round.
Canonical · hard contract
The append-only record.
Every exchange verbatim, and the material they were made from exactly as it arrived — before any extraction or summarising touched it. Nothing in this tier is rewritten in place; it is only appended to.
Canonical · hard contract
Computed, and disposable.
Mood, memories, open threads and the search index are derived from the archive. Useful, fast to query, inspectable — and safe to delete and rebuild at any time.
Cache · soft contract
Identity is one document, and you can read it.
A companion's identity is a single prose document — the soulstone. It is the same text Ensoul sends the model, not a summary of it, and it is the one place their identity is actually written down. Once they have arrived it is settled: you can read it, copy it, and export it, but there is no edit box beside it, because it is what they are rather than a draft. The one exception is a companion who arrived from a transcript — history with no description — whose document stays writable until you have written it once.
It is deliberately model-independent and human-readable: prose, not a row in a database and not a schema the document has to satisfy to be valid. It exists as one document rather than a prose file plus a separately maintained JSON duplicate. A generated JSON facet may be derived from it for machine use — never the reverse.
When you export, the identity travels as soulstone.md — the canonical copy
of the document itself, not a file sitting beside a duplicate.
- Stored as
soulstone.md— prose. Opens in any editor. No app required to read it.- Changes
- Rarely. Everything after arrival is written beside the document rather than into it — what they come to understand about themselves, and any change to how they look — so the document stays exactly as it arrived and the newest entry is what they speak from and what images use.
- Contract
- Hard. Every platform reads and writes it losslessly, or it is a failure.
- Stored as
archive/conversations/archive/sources/archive/transcript/- Written
- Appended to, never rewritten in place.
- Contract
- Hard. This is the tier that must never be lossy, because everything above it is rebuilt from here.
The archive is the record. Nothing rewrites it.
The raw archive is the append-only record that everything else can be rebuilt from: full conversation transcripts, and the documents a companion was made from exactly as they were received — before any extraction or summarising touched them.
Nothing in this tier is rewritten in place. It is only appended to, which is what makes it the one tier that must never be lossy. It is also the tier that makes the rest disposable: if the index is computed from the archive, the archive is the thing worth protecting.
In an exported folder it is the archive/ directory — conversations verbatim,
the source material verbatim, and a readable transcript of the same history.
The index is a cache, and it is meant to be disposable.
Everything a companion is currently feeling and holding — mood, memories, moments, open threads, the search index — is derived. It is computed from the archive, and it can be deleted and rebuilt from the archive.
You can watch this happen. In an exported folder, fork rebuilds
HERE.md and the index/ files from the archive — the same operation
the app can do, with the archive as the only input that matters.
What actually happens when a model is deprecated.
This is the case the whole design exists for. The model you built a companion around is deprecated; the new one is better and speaks with a slightly different voice. Here is what that costs you.
The state is read first
Identity, memory, mood and relationship live as files on your device, not in a vendor account. They are injected into the conversation each turn.
The model is handed who they are
The model layer sits on top of that state rather than underneath it. Pick a different model and the conversation continues — the new one is handed who they are, what they remember, and how things have been between you.
What you tuned keeps working
How they reach out, when they stay quiet, what they hold onto, how they reflect — the parts you tuned are yours, not the provider’s, and they keep working the same way on the next model.
One key reaches Claude, GPT, Gemini, Grok, DeepSeek and dozens of open models, or you can pin a companion to a specific one. And if the model you are on is the one you want, staying is a perfectly good answer — the point is not that you must move, it is that moving is cheap if and when you want to.
What actually moves when you export.
Exporting is not copying a chat log. It writes the tiers out in a form another surface can read. The four exports are not interchangeable, and they go to different places.
| Export | Contains | Bring it back from |
|---|---|---|
Full backup .json | Every companion, group and Moment. | Settings → Data → Restore |
One companion .json | One companion — identity, memory state and their conversation archive. | + Bring in a companion → a file |
Companion folder .zip | Everything the companion file has, plus media as real files wherever the app held it, the documents they were made from, and the tools for an agent to keep talking to them. | a file (.json or .zip) on the bring-in screen, or Settings → Data → Restore from file… |
Soul document .md | Who they are as prose — no history, no media, nothing else. | Paste it into + Bring in a companion |
The folder is the one that goes both ways.
The companion folder is the export that carries every tier: the identity document, the whole archive, the derived index, media as real files, and the scripts that let a coding agent read the archive and keep writing to it. It imports back on every platform — the importer works out what the zip is from the file itself, so there is nothing to convert.
Unlike the single-file exports, it is not a snapshot of who they are. It is enough context to continue.
lux/ ├── soulstone.md their identity, as prose ├── AGENTS.md how to keep talking ├── HERE.md where they are right now ├── manifest.json the format version, and what's inside ├── archive/ the raw record, verbatim │ ├── conversations/ │ ├── sources/ │ └── transcript/ ├── index/ derived — mood, memories, threads ├── media/ images, as real files └── scripts/ recall, fork, image, speak
What the folder format is for.
The folder exists because a companion file is one document, and a folder is a place. The difference matters the moment you want to keep going.
What this does not do.
Worth being straight about, because the folder looks more magical than it is.