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

# Files

> Read and write files in session storage. Scoped file operations for data persistence.

Files capability provides session-scoped file storage. Read, write, and manage files during agent execution without external storage services.

## Key Features

* **Session-Scoped Storage** - Files persist within a conversation/execution
* **Read/Write Operations** - Full file I/O access
* **No External Dependency** - Built-in, no configuration needed
* **Automatic Cleanup** - Files deleted when session ends
* **Per-File Limit** - Up to 10MB per file

## How to Enable

Files is automatically available on all agents and gateways. No configuration needed.

## Usage Examples

### Write a File

```python theme={null}
# Write JSON to file
import json
data = {"name": "Alice", "age": 30}
with open("/tmp/user.json", "w") as f:
    json.dump(data, f)
print("File written")
```

### Read a File

```python theme={null}
# Read and parse JSON
import json
with open("/tmp/user.json", "r") as f:
    data = json.load(f)
print(data["name"])
```

### Append to File

```python theme={null}
# Append log entry
with open("/tmp/log.txt", "a") as f:
    f.write("Event: User login\n")
```

### List Files

```bash theme={null}
ls -la /tmp/
```

## File Operations

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Write
    with open("/tmp/file.txt", "w") as f:
        f.write("content")

    # Read
    with open("/tmp/file.txt", "r") as f:
        content = f.read()

    # Append
    with open("/tmp/file.txt", "a") as f:
        f.write("more content")

    # Delete
    import os
    os.remove("/tmp/file.txt")
    ```
  </Tab>

  <Tab title="Bash">
    ```bash theme={null}
    # Write
    echo "content" > /tmp/file.txt

    # Read
    cat /tmp/file.txt

    # Append
    echo "more" >> /tmp/file.txt

    # Delete
    rm /tmp/file.txt
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const fs = require("fs");

    // Write
    fs.writeFileSync("/tmp/file.txt", "content");

    // Read
    const content = fs.readFileSync("/tmp/file.txt", "utf8");

    // Append
    fs.appendFileSync("/tmp/file.txt", "more");

    // Delete
    fs.unlinkSync("/tmp/file.txt");
    ```
  </Tab>
</Tabs>

## File Paths

### Default Location

Use `/tmp/` for session-scoped files:

```
/tmp/data.json
/tmp/results.csv
/tmp/script.py
```

### Limitations

* Cannot write outside `/tmp/`
* Cannot access system directories
* Session-isolated (each execution has separate storage)

## File Scopes

### Session Files

Files written during agent execution, available within the same session.

```
- Agent conversation 1
  - /tmp/analysis.json (available throughout conversation)

- Agent conversation 2
  - /tmp/analysis.json (different file, not shared)
```

### Persistent Storage

For data that needs to persist beyond a session, use:

* Knowledge Retrieval (vector index)
* External storage (HTTP Client to upload)
* Workflow state (between runs)

## Common Recipes

### Store Structured Data

```python theme={null}
import json
results = {
    "queries": ["search1", "search2"],
    "found": 5,
    "timestamp": "2025-03-20"
}
with open("/tmp/results.json", "w") as f:
    json.dump(results, f, indent=2)
```

### Process CSV

```python theme={null}
import csv
with open("/tmp/data.csv", "w") as f:
    writer = csv.writer(f)
    writer.writerow(["name", "age"])
    writer.writerow(["Alice", 30])
    writer.writerow(["Bob", 25])
```

### Generate Reports

```python theme={null}
report = """
# Analysis Report
Generated: 2025-03-20

## Summary
- Total items: 100
- Processed: 95
- Errors: 5
"""
with open("/tmp/report.md", "w") as f:
    f.write(report)
```

### Cache Results

```python theme={null}
import json
import os

cache_file = "/tmp/cache.json"
if os.path.exists(cache_file):
    with open(cache_file, "r") as f:
        cache = json.load(f)
else:
    cache = {}
    # Build cache
    with open(cache_file, "w") as f:
        json.dump(cache, f)
```

## Resource Limits

| Limit              | Value | Notes                    |
| ------------------ | ----- | ------------------------ |
| Per-File Size      | 10MB  | All scopes               |
| Files per Scope    | 100   | Per scope                |
| Agent Home Storage | 50MB  | Persistent agent storage |

## Cost

For current pricing details, see [Pricing](https://noorle.com/pricing/).

## Limitations

* **Session-scoped only** - Files deleted when session ends
* **No sharing** - Each session has isolated storage
* **System directories restricted** - Only `/tmp/` accessible
* **No real-time sync** - For persistence, export to external storage

## Best Practices

### Use Descriptive Names

```python theme={null}
# Good
/tmp/user_analysis_2025-03-20.json

# Bad
/tmp/data.json
```

### Clean Up Large Files

```python theme={null}
import os
if os.path.exists("/tmp/large_file.bin"):
    os.remove("/tmp/large_file.bin")
```

### Handle Missing Files

```python theme={null}
import os
if os.path.exists("/tmp/file.txt"):
    with open("/tmp/file.txt", "r") as f:
        content = f.read()
else:
    content = "File not found"
```

### Use Appropriate Formats

* **JSON** for structured data
* **CSV** for tabular data
* **Plain text** for logs
* **Markdown** for reports

## Troubleshooting

### "File Not Found"

File was in different session or manually deleted. Create new file.

### "Permission Denied"

Can only write to `/tmp/`. Cannot write to system directories.

### "Disk Full"

Exceeded storage limit. Delete large files or break into smaller sessions.

### Data Lost After Session

Expected behavior. Use HTTP Client to upload results, or save to Knowledge base.

## Persistence Strategies

### For Short-term (single session)

Use Files capability directly.

### For Long-term

1. Export to external storage via HTTP Client
2. Save to Knowledge base
3. Store in workflow execution context

### For Shared Data

1. Use HTTP Client to upload to shared service
2. Create connector to external database
3. Use workflow outputs

## Next Steps

* [Code Runner - Process Data](/use/capabilities/code-runner)
* [Sandbox - Complex Operations](/use/capabilities/sandbox)
* [HTTP Client - Upload Results](/use/capabilities/http-client)