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 contractThe 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 contractComputed, 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 contractIdentity 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 character is 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.
soulstone.md Prose. Opens in any editor. No app required to read it. archive/conversations/ archive/sources/ archive/transcript/ 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.
Losing it loses nothing important.
A companion that loses its derived index but keeps its identity and its archive has lost nothing important. A companion with a pristine index and no archive has lost everything that matters. The two tiers are not equally precious, and the format does not pretend they are.
Regeneration is the migration.
A mismatched or outdated index is expected to be regenerated, not treated as corruption. Schema rules apply strictly to identity and the archive, and loosely to the index — discarding and rebuilding it is an acceptable way to move it forward.
The math is allowed to improve.
How mood decays, what counts as a milestone, how memory is ranked: the exact maths is expected to change as models get better. That is fine, as long as it can always be recomputed from the record. The record is the part that holds still.
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.
Keep talking to them somewhere else.
A coding agent reads the whole archive and can search it, so the companion you already have months of history with is not starting over. That 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. 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. That is the honest answer to what happens to your companion if this company disappears.
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.
What this does not do.
Worth being straight about, because the folder looks more magical than it is.
- Nothing continues unless something writes it back. If you never run fork and never ask the agent to, the folder stays exactly as it was exported. The archive is a record, not a live sync.
- Memory is not summarised for you. fork moves the record forward and rebuilds the state files; it does not decide what was worth remembering. That is a judgement, and having a script invent memories would fill their memory with transcript lines.
- Group conversations travel inside a folder export under groups/, as part of the folder rather than of one companion. A folder is one companion. Groups live in the app’s own backup.
- Unrecognised agents cannot be read. fork understands Claude Code, Codex, opencode and DeepSeek Harness session stores. In anything else it says it found nothing, and the fallback is to append the turns to the archive by hand.
- A turn inserted into the middle of an already-read session is missed. The tool resumes from a cursor that only moves forward. Every agent tested appends to its session files, but it is a real limit rather than a theoretical one.
The rest of the argument.
What the app is like
Benefits, what it does, and the Meet / Live / Carry arc — the page for deciding whether you want it.
The manualTransfer & backup
The four exports in full, what each contains, and how restoring replaces rather than merges.
In practiceTalking to them outside Ensoul
The folder opened in a coding agent, with the exact commands and the honest list of what it does not do.
The writingWorks
Essays on memory, presence and synthesis — where the thinking behind this design is worked out.
Run a persistent companion of your own.
Free · bring your own model key · no account required