> ## Documentation Index > Fetch the complete documentation index at: https://docs.ngram.space/llms.txt > Use this file to discover all available pages before exploring further. # Keep the Entity intact > Understand which state lives in the database, on disk, and inside a portable Entity. A database backup alone is not a complete Entity backup. ngram stores structured memory in a database and keeps readable knowledge, journals, body checkpoints, and workspace artifacts on disk. ## Storage map | State | Default location or backend | | -------------------------------------------------------- | ---------------------------------------------------------------------- | | Episodes, beliefs, relationships, reminders, automations | SQLite `memory.db`, or Postgres when `DATABASE_URL` is configured | | Curated knowledge | `knowledge.md` | | Journal | `journal.md` | | Body checkpoints | `soma/` | | Relationship document mirrors | `relationships/` | | Autonomous activity transcript | `autonomy_transcript.md` | | Projects, learned procedures, self-model | Entity files such as `projects.json`, `skills/`, and `self_model.json` | | Attachments | Local disk or configured S3-compatible object storage | | Inference pause | `.inference-paused`, beside the journal | | Blender projects and revisions | `.ngram/blender/` inside the selected execution workspace | | Spatial creation worlds and program state | Browser storage for the Spatial origin; export through Objects | For a conventional local Entity, most state defaults to `~/.ngram/entities//`. The display name in the declaration determines the default directory; do not assume the YAML filename is the directory name. ```bash theme={"theme":"github-light-default"} uv run ngram status rook ``` Use the reported paths when backing up or troubleshooting. ## Persistent workspace `NGRAM_EXECUTION_WORKSPACE_DIR` redirects knowledge, journal, soma, relationship documents, session todos, and the default autonomy transcript to a shared workspace root. For example, a worker with a volume mounted at `/app/data` can use: ```dotenv theme={"theme":"github-light-default"} NGRAM_EXECUTION_WORKSPACE_DIR=/app/data ``` The files are directly under that root: `/app/data/knowledge.md`, `/app/data/journal.md`, and `/app/data/soma/`. Do not invent an additional `entities/rook/` directory unless you explicitly configure it as the workspace. Give each independently running Entity its own workspace. Sharing one directory makes these file paths collide. This variable does not redirect every path. SQLite, projects, skills, and logs may still resolve through the Entity's home directory. The Railway entrypoint also places `HOME` and caches on the mounted volume. Keep that entrypoint when using the supplied deployment configuration, or configure all remaining paths yourself. ## Spatial artifacts Back up the execution workspace's `.ngram/blender/` directory to preserve editable projects, published `.blend` and GLB revisions, and script history. A Python worker restart can reopen the last published checkpoint; it cannot recover changes that were never published. Keep a portable Blender executable on durable storage or install it as part of the execution-host image. The Spatial world library is separate browser state. An Objects export stores the world and program source/state with asset references; it does not embed the referenced Blender/GLB files. Restore both browser documents and their artifacts when moving to another machine. Loopback hostnames, ports, and browsers each affect which origin's saved scene is available. [Figment packages](/spatial/figments#publish-and-share) are self-contained exports for individual interactive assemblies. They include model assets, behavior, physics, grips and optional editable Blender source. Published versions and binary assets live in IndexedDB, separate from the active world checkpoint. Export `.figment.json` files for backups; clearing site data removes this library, and an ordinary world JSON does not include its binary assets. ## Postgres and attachments Set `DATABASE_URL` through your hosting platform's private variables. ngram chooses the Postgres backend when that value is present for a conventional Entity. The `hybrid_railway` profile requires it. A volume remains necessary for disk state even with Postgres. Protect both the database and the mounted files in your backup plan. For object-backed attachments, configure: ```dotenv theme={"theme":"github-light-default"} NGRAM_ATTACHMENTS_BACKEND=object_s3_compat NGRAM_S3_BUCKET=ngram-attachments ``` Supply `NGRAM_S3_ENDPOINT_URL`, `NGRAM_S3_ACCESS_KEY`, and `NGRAM_S3_SECRET_KEY` privately for your object-storage service. Restrict the credentials to the intended bucket. Object storage does not replace the Entity database or workspace volume. ## Export and verify The portable format packages Entity state with an integrity manifest: ```bash theme={"theme":"github-light-default"} uv run ngram export rook exports/rook.ngram uv run ngram verify exports/rook.ngram ``` Treat the archive as private: it can contain conversations, relationships, journals, and attached files. Integrity verification detects structural or content mismatches; it is not encryption or a malware scan. For a production backup, pause inference and stop other writers before taking coordinated database and filesystem snapshots. Test restoration into an isolated location before depending on the backup. ## Live portable Entities An opened `.ngram` Entity has a canonical container and a derived runtime cache. Its database routing differs from a conventional YAML Entity: the live container uses its local cache database even if `DATABASE_URL` is set. Use the [portable Entity workflow](/build/portable-inference) and the `verify` and `recover` commands for this mode. Do not treat an arbitrary cache directory as the only authoritative copy.