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

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.

```bash theme={null}
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={null}
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.

<Warning>Give each independently running Entity its own workspace. Sharing one directory makes these file paths collide.</Warning>

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:

```dotenv theme={null}
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={null}
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.