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/<Entity name>/. The display name in the declaration determines the default directory; do not assume the YAML filename is the directory name.

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:

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 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:

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:

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 and the verify and recover commands for this mode. Do not treat an arbitrary cache directory as the only authoritative copy.