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

# Bot workspace, inbox and memory

> What a bot keeps between runs. Its persistent files, the bot-to-bot inbox, and its memory, and how to read each one over REST.


A run is short; a bot is not. Three things carry over from one run to the next: the files it writes, the messages other bots left for it, and what it remembers.

## Workspace files

The file tools (`read_file`, `write_file`, `edit_file`, `list_files`, `search_files`, `delete_file`) work on a virtual workspace. The `workspace` key says how long it lives:

| `workspace` | Files |
|---|---|
| `bot` | Kept across runs. The default for a saved bot. |
| `run` | Start clean each run. |

A bot that takes screenshots with `browser` finds them under `/shots/` in the same workspace.

### Read them

`GET /v1/workflows/{id}/workspace-files` lists the persistent files, newest first, up to the 1,000 newest (`truncated` is `true` when there are more). `GET /v1/workflows/{id}/workspace-files/download?path=` returns one file as raw bytes with its stored content type and `Content-Disposition: attachment`. Both are owner-only.

```bash
curl -s https://api.plungeai.com/v1/workflows/<bot id>/workspace-files \
  -H "Authorization: Bearer $PLUNGE_API_KEY"

curl -s -o report.md "https://api.plungeai.com/v1/workflows/<bot id>/workspace-files/download?path=notes/report.md" \
  -H "Authorization: Bearer $PLUNGE_API_KEY"
```

| Status and code | When |
|---|---|
| `400 invalid_path` | The path has a `..` segment, a backslash, a control character, an absolute path outside `/ws`, or an encoded form of any of these. |
| `404 file_not_found` | The path is not a file the listing shows. |
| `413 file_too_large` | The file is over 20 MB. |

The CLI is `ocean-cli workflows files <id> [--download <path> --out <file>]`. A run's own deliverables (spreadsheets, documents, decks) are listed per execution by `GET /v1/executions/{id}/files`.

## Inbox

When another bot sends a message with `message_bot`, the text is queued in the receiver's inbox and the receiver wakes. At the start of its next run the bot reads the queue as lines of the form `[MESSAGE from <bot>] <text>`, or `[MESSAGE from <bot> in <group>] <text>` for a group message, and the queue is cleared.

- A message waits up to 7 days.
- Eight relays end a chain, so two bots cannot loop forever.

`GET /v1/workflows/{id}/inbox` shows what is queued, newest first. It is read-only and owner-only. See [Bot to bot and groups](/bots/bot-to-bot-and-groups).

## Memory

A bot keeps durable facts with the `memory` tool and searches its past work with `recall` and `recall_history`.

- **`memory`** applies a batch of `operations` (`add`, `replace`, `remove`) to the `user` or `memory` target in one call. `read` and `forget {query}` are single calls of their own; `forget` purges every entry containing the text.
- **Whose memory.** A bot uses the memory of the user who runs it; `memory_owner` is refused at save. A bot's own namespace (`<owner>:bot:<id>`) is wiped when the bot is deleted.
- **Account memory over REST.** `GET /v1/memory/recall`, `POST /v1/memory/remember` and `POST /v1/memory/forget` read and write the facts every bot and agent you run can recall. `GET /v1/memory/runs?q=` searches your past runs (full text once the platform owner has enabled the index, a plain substring match until then), and `GET /v1/memory/runs/{id}` returns one stored result.
- **Weekly consolidation (opt-in, default off).** With `memory_consolidate: weekly` in the bot's `bot-config` block, Studio creates a second job, `<bot> · memory consolidation`, that runs on Sundays at 03:00. It replays the owner's recent runs through the memory review and records `reviewed N episodes`. With no key set there is no job, so nothing runs.

## Steering a running bot

`POST /v1/executions/{id}/steer` queues a message the loop reads at its next turn. A finished run answers `409 execution_finished`. `POST /v1/executions/{id}/followup` messages a run in flight the same way, and starts a new turn once the run has finished.