> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bumbleagi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Persistence

> Volume, Postgres, and data durability on Railway.

Hybrid Railway deployments have three persistence layers:

| Layer                            | What it stores                                                     | Durability                   |
| -------------------------------- | ------------------------------------------------------------------ | ---------------------------- |
| **Postgres**                     | Episodic memory, relationships, beliefs, entity state, automations | Durable                      |
| **Railway volume** (`/app/data`) | `knowledge.md`, `journal.md`, soma checkpoint, workspace files     | Durable (survives redeploy)  |
| **Container disk**               | Code, configs, logs                                                | Ephemeral (lost on redeploy) |

## Volume setup

The volume is not optional. Without it, `knowledge.md`, `journal.md`, and soma state are destroyed on every container redeploy.

```bash theme={null}
railway service bumblebee-worker
railway volume add --mount-path /app/data
railway variable set BUMBLEBEE_EXECUTION_WORKSPACE_DIR=/app/data
railway redeploy --service bumblebee-worker --yes
```

`BUMBLEBEE_EXECUTION_WORKSPACE_DIR` redirects knowledge, journal, and soma paths onto the volume. Without it, those files land on the ephemeral container disk under `~/.bumblebee`.

## First startup

If no `knowledge.md` exists at the configured path, the entity writes a minimal template automatically. No manual seeding required for a fresh deploy.

## Postgres

Set `DATABASE_URL` on the Railway service:

```env theme={null}
DATABASE_URL=postgresql://user:pass@host:5432/bumblebee
```

When set, all structured memory (episodes, relationships, beliefs, automations, reminders) uses Postgres instead of SQLite. Schema migrations run automatically on startup.

## Seeding knowledge

To pre-populate `knowledge.md` on a fresh volume:

```bash theme={null}
railway ssh --service bumblebee-worker
cat > /app/data/entities/canary/knowledge.md << 'EOF'
## [locked] about yourself
You are Canary, the first entity on Bumblebee.
EOF
```

## Backup and restore

```bash theme={null}
# Backup
railway ssh --service bumblebee-worker
tar czf /tmp/backup.tar.gz /app/data/entities/

# Restore
railway ssh --service bumblebee-worker
tar xzf /tmp/backup.tar.gz -C /
```

For Postgres, use `pg_dump` / `pg_restore` via the Railway database service.

## S3-compatible attachment storage

In local mode, images and audio from chats are saved to disk. On ephemeral cloud disks, those files disappear on redeploy. For hybrid deployments, use S3-compatible object storage:

```env theme={null}
BUMBLEBEE_ATTACHMENTS_BACKEND=object_s3_compat
BUMBLEBEE_S3_ENDPOINT_URL=https://...
BUMBLEBEE_S3_BUCKET=bumblebee-attachments
BUMBLEBEE_S3_ACCESS_KEY=...
BUMBLEBEE_S3_SECRET_KEY=...
```

<Tip>The setup wizard (`bumblebee setup`) prompts for S3 configuration on the hybrid path. Any S3-compatible API works — Cloudflare R2, Backblaze B2, MinIO, AWS S3.</Tip>

## Troubleshooting

| Symptom                    | Cause                                                    | Fix                                      |
| -------------------------- | -------------------------------------------------------- | ---------------------------------------- |
| Knowledge lost on redeploy | No volume or `BUMBLEBEE_EXECUTION_WORKSPACE_DIR` not set | Add volume and set the env var           |
| Soma state resets          | Soma checkpoint on ephemeral disk                        | Ensure workspace dir points to volume    |
| Entity can't write files   | Workspace dir doesn't exist                              | Verify volume mount path matches env var |