Skip to main content
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

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

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