Learning NemoClaw

10 · Workspace Files — The Agent's Persistent Self

Source: the nemoclaw-user-workspace skill.

Every other doc in this set is about plumbing — how OpenClaw, OpenShell, and NemoClaw fit together. This doc is about the thing the plumbing is for: the agent has state. A persona, a user model, memory. That state lives in a specific set of Markdown files inside the sandbox, and losing it is the single worst outcome of a mis-clicked destroy.

The six files

All of them live at /sandbox/.openclaw/workspace/ inside the sandbox. Note that's a hidden directory (.openclaw) — the files are not at /sandbox/SOUL.md, and that trips up newcomers who try to grab them from the wrong path.

File What it controls
SOUL.md Core personality, tone, behavioral rules
USER.md Preferences, context, and facts the agent has learned about you
IDENTITY.md Agent name, creature type, emoji, self-presentation
AGENTS.md Multi-agent coordination, memory conventions, safety guidelines
MEMORY.md Curated long-term memory, distilled from daily notes
memory/YYYY-MM-DD.md Daily note files for session continuity

Directory layout:

/sandbox/.openclaw/workspace/
├── SOUL.md
├── USER.md
├── IDENTITY.md
├── AGENTS.md
├── MEMORY.md
└── memory/
    ├── 2026-03-18.md
    ├── 2026-03-19.md
    └── ...

The agent reads these at the start of every session. That's why editing USER.md mid-conversation doesn't immediately take effect — the agent already loaded its view. Start a new session and it re-reads.

Persistence truth table — the part you must internalize

Event Workspace files
Sandbox restart (reboot, gateway restart, nemoclaw onboard --resume) ✅ Preserved — the sandbox PVC retains its data
nemoclaw <name> destroy ❌ Gone — PVC deleted, no recovery
nemoclaw onboard that recreates the sandbox ❌ Gone — same wipe as destroy under the hood

The two "gone" cases are irrecoverable without a prior backup. The first time you learn this the hard way will hurt. Don't learn it the hard way.

When you don't need to back up:

When you must back up first:

Backup and restore

Two paths: raw OpenShell primitives (portable, scriptable, verbose) or the convenience script the NemoClaw repo ships (what you'll use 95% of the time).

Path 1 — manual via openshell sandbox download/upload

Backup:

SANDBOX=my-assistant
BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP_DIR"

openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/SOUL.md     "$BACKUP_DIR/"
openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/USER.md     "$BACKUP_DIR/"
openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/IDENTITY.md "$BACKUP_DIR/"
openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/AGENTS.md   "$BACKUP_DIR/"
openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/MEMORY.md   "$BACKUP_DIR/"
openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/memory/     "$BACKUP_DIR/memory/"

Restore: symmetric — openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/SOUL.md" /sandbox/.openclaw/workspace/ for each file, and the memory/ subdir as a whole.

Don't forget the memory/ directory. It's where daily notes live, and it's easy to miss because it's not one of the capitalized top-level files.

Path 2 — the convenience script

The NemoClaw repo ships scripts/backup-workspace.sh which does all six items in one call:

./scripts/backup-workspace.sh backup  my-assistant
# → Backup saved to /home/you/.nemoclaw/backups/20260320-120000/ (6 items)

./scripts/backup-workspace.sh restore my-assistant                  # restore latest
./scripts/backup-workspace.sh restore my-assistant 20260320-120000  # restore specific

Backups always land at ~/.nemoclaw/backups/YYYYMMDD-HHMMSS/. Each run creates a new directory, so you get a natural rollback history.

Verifying a backup

ls ~/.nemoclaw/backups/20260320-120000/
# Expected:
# AGENTS.md  IDENTITY.md  MEMORY.md  SOUL.md  USER.md  memory/

Six entries. If you're missing one, the restore won't fully rehydrate the agent — the missing file will come back empty and the agent will behave as though it had never learned whatever was in that file.

Editing workspace files

Three ways, from least to most invasive:

  1. Ask the agent. "Remember that I'm on Pacific time" or "update your USER.md to note I prefer concise answers" — this is the natural path. The agent edits the file in-place. Least friction, takes effect on next session load.
  2. Connect and edit directly.
    nemoclaw my-assistant connect
sandbox$ vim /sandbox/.openclaw/workspace/USER.md
    Useful for bulk changes, bootstrapping from a template, or fixing something the agent got wrong.
  3. Upload from the host.
    openshell sandbox upload my-assistant ./my-curated-SOUL.md /sandbox/.openclaw/workspace/SOUL.md
    For version-controlling your agent's persona in a git repo on your host and pushing updates.

The one-paragraph rule

The sandbox is disposable. The workspace is not. Treat /sandbox/.openclaw/workspace/ as the only thing in the sandbox you actually care about keeping. Everything else — installed packages, config, the image itself — can be recreated from a nemoclaw onboard. The workspace is the only thing that holds what you've taught your agent and what your agent has learned about you. Back it up before any destructive operation, and consider treating your backups directory as something worth including in your normal backup hygiene.

Cross-references

← Back to 00-INDEX.md