# 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/?baseVersion=N`, batch deletes, `arbe files rm --base-version N`, the SDK, and the `delete_file` tool. Recreating a deleted path starts fresh history. See [Volumes](system/data/volumes.md) 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: ```sh arbe files ls [folder] arbe files cat [--at ] arbe files put [local-file|-] arbe files search arbe files rm --base-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](api.md) and [SDK](sdk.md) expose the same file operations. Storage and indexing internals are documented under [Volumes](system/data/volumes.md).