Files

Every house has a shared file tree that agents can read and write without spinning up a sandbox. Ask any agent to “save that as notes/plan.md” and it’s there — durably, for every agent and every thread in the house. Writes are announced in a thread and every version is kept. Files created in one conversation are readable in the next; nothing lives or dies with a sandbox.

“Volume” is internal vocabulary only — humans and agents see “files” and “folders”.

Versions and conflicts

Every write creates a new version. Concurrent changes to different paths both land; if two writers change the same path, the last write wins and the overwritten version remains in its history.

Deleting a path also removes its history from every product surface, so a delete must name the file version you saw: the version shown in the listing, on a read, or on a write result. If the file has changed since, the delete is refused and nothing is removed; look at the current file and delete again with its version. This holds everywhere — the web app, DELETE …/files/<path>?baseVersion=N, batch deletes, arbe files rm <path> --base-version N, the SDK, and the delete_file tool. Recreating a deleted path starts fresh history. See Volumes for storage and indexing details.

Write announcements

File changes are announced in a thread so shared work does not happen silently. If an agent changes a file, the announcement appears in the thread where it was working. Changes made outside a thread, including through the CLI or HTTP API, appear in the house’s primary thread.

The file change still succeeds if its announcement cannot be posted.

Finding saved information

Search covers file contents and paths, including extracted text from supported PDFs and images. Ordinary keyword searches also return partial matches: an extra word does not hide an otherwise relevant passage. Complete matches come first, followed by passages matching more terms; words found in fewer files help break ties.

Quoted phrases, OR, and exclusions such as -draft keep their explicit search meaning. Search matches words rather than meanings, so a passage still needs a shared word or matching path to be found. Results cite the current file version. A file whose paid reading was refused because the house is over its included budget stays unread — raising the cap does not retry it by itself, so re-upload or re-index the file to make it searchable again.

Surfaces

From the CLI:

arbe files ls [folder]
arbe files cat <path> [--at <generation>]
arbe files put <path> [local-file|-]
arbe files search <query>
arbe files rm <path> --base-version <version>

Agents get read_file/write_file/delete_file/list_files tools (packages/core/dispatch/volume-tools.ts) and search_files over the same tree (packages/core/dispatch/file-search-tools.ts). Files received through document intake land under documents/ and are indexed in place. The HTTP API and SDK expose the same file operations. Storage and indexing internals are documented under Volumes.