> ## 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.

# Observer

> A hidden recorder that captures every command and file op as timestamped events, backed by a pluggable store. Powers command history.

## What It Does

Every workspace has one **Observer**: a hidden recorder that logs each top-level
command and its file ops as timestamp-ordered events. It owns no mount and has no
endpoint of its own, features like command history are just *views* over its
events. Nested evals (`$(...)`, `eval`, `source`, `xargs`) run without recording,
so only real top-level commands land.

```mermaid theme={null}
flowchart TD
    Exec["ws.execute(cmd)"] --> Obs[Observer]
    Obs --> Store[("ObserverStore<br/>RAM · Disk · Redis")]
    Store --> Hist["history builtin<br/>(calling session)"]
    Store --> File["/.bash_history<br/>(all sessions)"]
```

## Storage backends

The Observer holds a storage-agnostic `ObserverStore`. RAM is the default; swap it
to persist events across daemon restarts. The store is chosen at construction; there
is no runtime API to change it.

<CodeGroup>
  ```python Python theme={null}
  from mirage import Workspace, MountMode
  from mirage.resource.ram import RAMResource
  from mirage.observe.disk_store import DiskObserverStore
  from mirage.observe.redis_store import RedisObserverStore

  # RAM (default), nothing to configure
  ws = Workspace({"/data": RAMResource()}, mode=MountMode.WRITE)

  # Persist to disk
  ws = Workspace({"/data": RAMResource()}, mode=MountMode.WRITE,
                 observe=DiskObserverStore("/var/mirage/history"))

  # Persist to Redis
  ws = Workspace({"/data": RAMResource()}, mode=MountMode.WRITE,
                 observe=RedisObserverStore("redis://localhost:6379/0"))
  ```

  ```typescript TypeScript theme={null}
  import { Workspace, RAMResource } from '@struktoai/mirage-core'
  import { DiskObserverStore, RedisObserverStore } from '@struktoai/mirage-node'

  // RAM (default), nothing to configure
  const ws = new Workspace({ '/data': new RAMResource() })

  // Persist to disk
  const wsDisk = new Workspace(
    { '/data': new RAMResource() },
    { observe: new DiskObserverStore('/var/mirage/history') },
  )

  // Persist to Redis
  const wsRedis = new Workspace(
    { '/data': new RAMResource() },
    { observe: new RedisObserverStore({ url: 'redis://localhost:6379/0' }) },
  )
  ```
</CodeGroup>

## Supported: command history

The Observer powers a GNU-bash-compatible history, exposed two ways over the same
events:

| Surface                | Scope           | Notes                                                        |
| ---------------------- | --------------- | ------------------------------------------------------------ |
| `history` builtin      | calling session | GNU flags `-c -d -a -n -r -w -s -p` and a count arg          |
| `/.bash_history` mount | all sessions    | read-only, GNU histfile format (`#<epoch>` then the command) |

Because `/.bash_history` is a real read-only mount, the ordinary file commands work
on it directly:

```bash theme={null}
history 5
tail -n 6 /.bash_history
grep cat /.bash_history
```

The format is GNU bash (`#<epoch>`), not zsh (`: <ts>:<dur>;<cmd>`).

## Snapshots

History is part of the workspace state: the Observer's command, clear, and delete
events are captured into a [snapshot](/home/snapshot) and restored on load, so a
restored workspace replays with the same history. The `/.bash_history` view mount
itself is not stored, it is a live projection rebuilt from the events.