Bot workspace, inbox and memory

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:

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.

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"

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.

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.