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

# Files

> Read and write the files in an agent's workspace and its persistent memory.

Every agent has a workspace in its sandbox, shared by all its sessions, and a memory the harness keeps across conversations. Both live on the sandbox's disk and survive sleep. You can read and write them from your backend at any time.

## The workspace

The workspace root is `/home/user/workspace` in the sandbox. File paths in the API are relative to it, and so is each session's `cwd`: a session created with `cwd: "repos/web"` runs its harness in `/home/user/workspace/repos/web`.

```go Go theme={null}
entry, err := agent.Files.Write(ctx, "repos/web/TODO.md", []byte("- fix the flaky test\n"))
if err != nil {
	return err
}
fmt.Println(entry.Path, entry.Size)

data, err := agent.Files.Read(ctx, "repos/web/TODO.md")
if err != nil {
	return err
}
fmt.Println(string(data))

entries, err := agent.Files.List(ctx, paddock.FileList{Dir: "repos/web", Recursive: true})
if err != nil {
	return err
}
for _, e := range entries {
	fmt.Println(e.Type, e.Path, e.Size, e.ModifiedAt)
}

err = agent.Files.Delete(ctx, "repos/web/build", paddock.FileDelete{Recursive: true})
```

```python Python theme={null}
entry = agent.files.write("repos/web/TODO.md", b"- fix the flaky test\n")
print(entry.path, entry.size)

data = agent.files.read("repos/web/TODO.md")
print(data.decode())

for e in agent.files.list("repos/web", recursive=True).data:
    print(e.type, e.path, e.size, e.modified_at)

agent.files.delete("repos/web/build", recursive=True)
```

```ts TypeScript theme={null}
const entry = await agent.files.write("repos/web/TODO.md", "- fix the flaky test\n");
console.log(entry.path, entry.size);

const data = await agent.files.read("repos/web/TODO.md");
console.log(new TextDecoder().decode(data));

const { data: entries } = await agent.files.list("repos/web", { recursive: true });
for (const e of entries) console.log(e.type, e.path, e.size, e.modifiedAt);

await agent.files.delete("repos/web/build", { recursive: true });
```

| Operation | Meaning |
| - | - |
| `files.list(dir?)` | The entries under `dir` (default the root), each a `path`, `type` (`file` or `directory`), `size`, and `modifiedAt`; `recursive` lists the whole tree |
| `files.read(path)` | The file's bytes |
| `files.write(path, data)` | Creates missing parent directories and replaces an existing file; returns its entry |
| `files.delete(path)` | Deletes a file; a directory needs `recursive` |

## Memory

Memory is what the harness keeps across conversations: text files the agent writes as it works and reads at the start of each conversation. Each session's instruction file (`CLAUDE.md` for Claude Code, `AGENTS.md` for Codex) names the memory directory and includes its `MEMORY.md`, up to 32 KiB; the harness reads any other memory file itself when it needs it. Memory is the agent's data, never configuration: a new agent starts with none.

```go Go theme={null}
_, err := agent.Memory.Write(ctx, "MEMORY.md", "The team deploys on Thursdays.\n")
if err != nil {
	return err
}
text, err := agent.Memory.Read(ctx, "MEMORY.md")
if err != nil {
	return err
}
fmt.Println(text)
```

```python Python theme={null}
agent.memory.write("MEMORY.md", "The team deploys on Thursdays.\n")
print(agent.memory.read("MEMORY.md"))
```

```ts TypeScript theme={null}
await agent.memory.write("MEMORY.md", "The team deploys on Thursdays.\n");
console.log(await agent.memory.read("MEMORY.md"));
```

Memory paths are relative to the agent's memory directory. `memory.list()`, `read`, `write`, and `delete` work like their file counterparts, on text.

## Rules

| Rule | Meaning |
| - | - |
| Paths | Relative to their root; a path that escapes it is `400` |
| Waking | A file or memory operation on a sleeping agent wakes it and waits. If the agent is not awake within 30 seconds, it fails with `503 unavailable`; retrying is safe |
| Size | One read or write is at most 100 MB |
| Sharing | Files are shared by all the agent's sessions and their running turns. paddock does not lock them |
| Timeouts | The SDKs allow file and memory requests 10 minutes instead of the usual 60 seconds |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.