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

# RAM

> Use an in-memory Mirage filesystem for temporary files, tests, examples, and writable agent scratch space.

The RAM resource exposes an in-memory filesystem mounted at some prefix
such as `/data/`. All data lives in process memory and is lost on exit.

No setup or credentials required.

## Config

```python theme={null}
from mirage import MountMode, Workspace
from mirage.resource.ram import RAMResource

resource = RAMResource()
ws = Workspace({"/data": resource}, mode=MountMode.WRITE)
```

No configuration object needed - `RAMResource()` takes no arguments.

## Filesystem Layout

The RAM filesystem starts empty. Files and directories are created
on demand via commands like `touch`, `mkdir`, `tee`, `cp`, etc.

```text theme={null}
/data/
  notes.txt
  config.json
  reports/
    q1.csv
    q2.csv
  uploads/
    image.png
```

Paths are normalized with a leading `/`. The root directory `/` always
exists.

## Cache

The RAM resource uses `IndexCacheStore` with `index_ttl = 0` (no
expiry). Since all data is in-memory, the index is always fresh,
no network calls or stale cache concerns.

## Example

```python theme={null}
import asyncio

from mirage import MountMode, Workspace
from mirage.resource.ram import RAMResource

resource = RAMResource()


async def main() -> None:
    ws = Workspace({"/data": resource}, mode=MountMode.WRITE)

    # Create files
    await ws.execute('echo "hello world" | tee /data/hello.txt')
    await ws.execute('echo \'{"name": "alice", "age": 30}\' | tee /data/user.json')
    await ws.execute("mkdir /data/reports")
    await ws.execute('echo "revenue,100" | tee /data/reports/q1.csv')

    # Read
    r = await ws.execute("cat /data/hello.txt")
    print(await r.stdout_str())

    # List
    r = await ws.execute("ls /data/")
    print(await r.stdout_str())

    # Query JSON
    r = await ws.execute('jq ".name" /data/user.json')
    print(await r.stdout_str())

    # Search
    r = await ws.execute("grep hello /data/hello.txt")
    print(await r.stdout_str())

    # Tree
    r = await ws.execute("tree /data/")
    print(await r.stdout_str())

    # File info
    r = await ws.execute("stat /data/hello.txt")
    print(await r.stdout_str())

    # Copy, move, remove
    await ws.execute("cp /data/hello.txt /data/hello_copy.txt")
    await ws.execute("mv /data/hello_copy.txt /data/renamed.txt")
    await ws.execute("rm /data/renamed.txt")


if __name__ == "__main__":
    asyncio.run(main())
```

## Shell Commands

The RAM resource supports the full set of shell commands since it
handles real file content (text, binary, JSON, CSV, etc.):

### Read Commands

| Command         | Notes                                      |
| --------------- | ------------------------------------------ |
| `cat`           | Read file content                          |
| `head` / `tail` | First/last N lines                         |
| `grep` / `rg`   | Pattern search (file or directory level)   |
| `jq`            | Query JSON fields                          |
| `wc`            | Line/word/byte counts                      |
| `stat`          | File metadata (name, size, type, modified) |
| `find`          | Recursive search with `-name`, `-maxdepth` |
| `tree`          | Directory tree view                        |
| `nl`            | Number lines                               |
| `du`            | Disk usage summary                         |
| `file`          | Detect file type                           |
| `strings`       | Extract printable strings from binary      |
| `xxd`           | Hex dump                                   |
| `md5`           | MD5 checksum                               |
| `sha256sum`     | SHA-256 checksum                           |

### Text Processing

| Command    | Notes                                       |
| ---------- | ------------------------------------------- |
| `awk`      | Pattern scanning and processing             |
| `sed`      | Stream editor                               |
| `tr`       | Translate or delete characters              |
| `sort`     | Sort lines                                  |
| `uniq`     | Remove duplicate lines                      |
| `cut`      | Extract fields/columns                      |
| `join`     | Join lines on a common field                |
| `paste`    | Merge lines side by side                    |
| `column`   | Columnate output                            |
| `fold`     | Wrap lines to a specified width             |
| `expand`   | Convert tabs to spaces                      |
| `unexpand` | Convert spaces to tabs                      |
| `fmt`      | Simple text formatter                       |
| `rev`      | Reverse lines                               |
| `tac`      | Concatenate and print in reverse            |
| `look`     | Display lines beginning with a given string |
| `shuf`     | Shuffle lines                               |
| `tsort`    | Topological sort                            |
| `comm`     | Compare two sorted files                    |
| `cmp`      | Compare two files byte by byte              |
| `diff`     | Compare files line by line                  |
| `patch`    | Apply a diff patch                          |
| `iconv`    | Character encoding conversion               |

### File Operations

| Command  | Notes                                 |
| -------- | ------------------------------------- |
| `cp`     | Copy files                            |
| `mv`     | Move/rename files                     |
| `rm`     | Remove files                          |
| `mkdir`  | Create directories                    |
| `touch`  | Create empty file or update timestamp |
| `ln`     | Create symbolic links                 |
| `tee`    | Write stdin to file and stdout        |
| `mktemp` | Create temporary file                 |
| `split`  | Split file into pieces                |
| `csplit` | Split file by context                 |

### Path Utilities

| Command    | Notes                      |
| ---------- | -------------------------- |
| `basename` | Strip directory from path  |
| `dirname`  | Strip filename from path   |
| `realpath` | Resolve path               |
| `readlink` | Print symbolic link target |
| `ls`       | List directory contents    |

### Compression

| Command  | Notes                 |
| -------- | --------------------- |
| `gzip`   | Compress files        |
| `gunzip` | Decompress gzip files |
| `zip`    | Create zip archives   |
| `unzip`  | Extract zip archives  |
| `tar`    | Archive files         |
| `zcat`   | Cat compressed files  |
| `zgrep`  | Grep compressed files |

### Encoding

| Command  | Notes                |
| -------- | -------------------- |
| `base64` | Base64 encode/decode |

### Data Format Support

Commands with format-specific variants for structured data files:

| Format  | Extension  | Variants                                       |
| ------- | ---------- | ---------------------------------------------- |
| Parquet | `.parquet` | cat, head, tail, wc, stat, cut, grep, ls, file |
| Feather | `.feather` | cat, head, tail, wc, stat, cut, grep, ls, file |
| ORC     | `.orc`     | cat, head, tail, wc, stat, cut, grep, ls, file |
| HDF5    | `.hdf5`    | cat, head, tail, wc, stat, cut, grep, ls, file |

These variants auto-detect the format by extension and convert to
tabular text (CSV) for processing.

## Use Cases

* **Testing**: Fast filesystem for unit tests without I/O
* **Staging**: Temporary data area during pipelines
* **Prototyping**: Develop against a filesystem before switching to S3/disk
* **Caching**: In-process data exchange between commands
* **Ephemeral workspaces**: Create, process, discard - no cleanup needed