Agent Storage: files your agents keep between runs
Agent Storage gives each Nebula agent its own persistent files. Learn how agents keep notes, state and reports between runs and move files to any device.
Agents you create in Nebula each have their own Agent Storage: a persistent set of files that survives across runs, threads and devices. Ask an agent to keep something for next time, such as notes, state between scheduled runs or a generated report, and it saves it there and finds it again later.
Market Analyst, keep each week's competitor pricing table so you can tell me what changed next Monday.
Saved this week's table as pricing/2026-10-26.csv in my storage. Next Monday I'll compare the new prices against it and list every change.
What agents keep in storage
Storage belongs to the agent, not to a channel or a device. Whatever channel runs the agent and whichever device it works on, it opens the same files. Nothing else in Nebula writes to them.
| Keep | Example |
|---|---|
| Working notes | What a research agent has already checked, so it doesn't repeat itself |
| State between scheduled runs | The last invoice number a weekly job processed |
| Generated reports | Each month's summary, kept so the next one can compare |
| Caches and datasets | A cleaned customer list it reuses instead of rebuilding |
Agents are told to keep it findable: a short README.md at the top saying what each folder holds, files grouped by purpose (state/, reports/, cache/), and anything stale deleted.
Everyone who runs an agent shares its files
An agent's storage isn't split per person. Everyone who can run the agent reads and writes the same files, so anything you ask it to keep, the other people who use it can read and change through it.
Don't ask an agent to store passwords, tokens or one person's private details unless everyone who uses that agent should have them. Keep account access in Connections and sign-ins in a password manager.
How an agent reaches its storage
Each agent comes with the agent-storage skill, which tells it when and how to use its storage. You don't need to set anything up. The agent picks one of two ways in, depending on the file.
For small text files up to 256 KiB, such as notes, JSON state or Markdown. In a task's activity log these show as List Stored Files, Read Stored File, Store File and Delete Stored File. Storing a file replaces the whole file at that path.
For binary or large files, up to 100 MiB each, and files the agent makes or uses on a device. The agent installs the small nebula-storage command-line tool on the device it's working on (it needs only Python 3), then moves files in and out:
nebula-storage ls [PREFIX] # list stored files
nebula-storage get PATH [DEST|-] # download a stored file
nebula-storage put SRC|- PATH # upload a file, replacing PATH
nebula-storage rm PATH # delete a stored fileIt works only inside commands the agent runs. A terminal you open on the same device can't use it.
Paths are relative to the agent's storage, separated by /, like reports/2026-10.csv.
Ask an agent to use its storage
Mention storage when you want something kept, or ask the agent what it already has. For example:
- "Save the cleaned lead list to your storage so tomorrow's run starts from it."
- "What's in your storage? Delete anything older than this quarter."
- "Put the exported dashboard PDF from the device into your storage as reports/october.pdf."
Common questions
Unsure what an agent has kept? Ask it, or ask Nebula. For anything else, email support@nebula.gg.
Related
Put Nebula to work
Get Nebula on your computer or phone, then create your first channel and set its goal.
Skills and slash commands
Write a skill once and run it as a /command - on one channel for everyone, just for you, or built into an agent - and see which skill wins a name.
Models: defaults, custom endpoints and local models
Choose the default model for your Nebula workspace or a channel's tasks, add models from a catalog or your own endpoint, or run one on this computer.